Gaia/Shared/Components
Contents
Overview
Gaia components mainly contains the web components used around gaia, which are included in shared/elements
The remote repository is used to host all components in development.
Gaia components follow the new Building Block style guide, which is located in MDN
Is Gaia Components Ready?
Here is the demo page of current gaia components.
Available components are listed below with readiness matrix.
Progress
Slide for current gaia component status at end of June.
Gaia adaption progress is tracked in bug 1002417 and pending due to wait for decisions of UX style refresh. Project Spark is using gaia-components as its main UI elements.
At this time we restart the gaia web component related work from UX review to make sure the component's UI/UX behavior is matching new UX style. We'll test other perspective such as RTL support, performance, accessibility, CSS naming & overall syntax check (and the cross browser support if possible).
To apply those work on real environment, we identify header, list, button as frequently used elements from spark project, initiate the first batch to improve their overall readiness state.
Fields to improve:
- UX: check if components are following the UX spec
- RTL: check syntax is RTL compatible
- Accessibility: check syntax is aria friendly and inherit from correct element
- CSS Animation: Apply smoother Animation from TV experience.
- Performance: create a set of performance evaluation tests to make sure the component readiness. Use raptor to check if it lag the current app
- Syntax check: add basic lint check, example, readme to improve the code maintenance
Web Component support status
- Firefox: Under flag: need enable dom.webcomponents.enabled in about:config
- FirefoxOS: permission needed: add "moz-extremely-unstable-and-will-change-webcomponents": {} permission in manifest.webapp's permissions section
Platform support issues are tracked in bug 811542
- :host-context() bug 1082060
- :host bug 992245
- ::content bug 992249
- ::shadow bug 1112251
Web Component Specs
- Web Components: http://w3c.github.io/webcomponents/explainer/
- Shadow DOM: http://w3c.github.io/webcomponents/spec/shadow/
- HTML Import: http://w3c.github.io/webcomponents/spec/imports/
- Custom Element: http://w3c.github.io/webcomponents/spec/custom/
Component Readiness Level
In Use
These elements already used in gaia
| Name | UX | RTL | Perf | Accessibility | Syntax | Cross | Preview | Meta Bugs |
|---|---|---|---|---|---|---|---|---|
| gaia-header | O | X | ? | O | O | O | O | x |
| gaia-icons | O | - | - | O | - | x | O | x |
| gaia-theme | O | - | - | - | ? | x | O | x |
| gaia-toast | O | ? | ? | O | ? | x | O | bug 1160022 |
| gaia-confirm* | O | ? | ? | ? | ? | x | x | bug 1160024 |
| gaia-subheader* | O | ? | ? | O | ? | x | x | x |
| gaia-switch* | O | ? | ? | O | ? | x | x | x} |
| gaia-radio* | O | ? | ? | O | ? | x | x | x |
| gaia-checkbox* | O | ? | ? | O | ? | x | x | x |
| gaia-menu* | O | ? | ? | O | ? | x | x | x |
- gaia-confirm, gaia-subheader, gaia-switch, gaia-radio, gaia-checkbox, gaia-menu are Building Block style component and now only located in gaia/shared/elements
- (try not mix gaia-subheader with gaia-sub-header, they are totally different)
Can Use
These elements UX is correct, encourage to be used in master to improve element quality and maintainance
| Name | UX | RTL | Perf | Accessibility | Syntax | Cross | Preview | Meta Bugs |
|---|---|---|---|---|---|---|---|---|
| gaia-button | X | O | ? | O | O | x | O | bug 1160032 |
| gaia-checkbox | O | ? | ? | O | ? | x | x | bug 1160021 |
| gaia-toolbar | O | ? | ? | O | ? | x | O | bug 1160018 |
| gaia-text-input | O | O | ? | O | ? | x | O | bug 1160012 |
| gaia-sub-header* | P | ? | ? | O | ? | ? | x | x |
- UX: gaia-sub-header 's slide menu part is not ready for use.
Not Ready But in Use
Spark already use some of components that can not pass UX review.
| Name | UX | RTL | Perf | Accessibility | Syntax | Cross | Preview | Meta Bugs |
|---|---|---|---|---|---|---|---|---|
| gaia-list | X | ? | ? | bug 1162152 | ? | x | O | bug 1160040 |
| gaia-progress | X | ? | ? | bug 1162159 | ? | x | O | bug 1160033 |
| gaia-switch | X | ? | ? | O | O | x | O | bug 1160036 |
| gaia-dialog | X | ? | ? | bug 1162184 | ? | x | x | bug 1160037 |
Not Ready
Others components are not ready yet (can not pass UX review), if you want to use them, please ni UX review first.
| Name | UX | RTL | Perf | Accessibility | Syntax | Cross | Preview | Meta Bugs |
|---|---|---|---|---|---|---|---|---|
| gaia-tabs | X | ? | ? | bug 1162170 | ? | x | X | bug 1160034 |
| gaia-slider | X | ? | ? | bug 1162175 | ? | x | x | bug 1160035 |
| gaia-picker | X | ? | ? | bug 1162186 | ? | x | O | bug 1160038 |
| gaia-value-selector | X | ? | ? | bug 1162188 | ? | x | O | bug 1160039 |
Utility
| Name | UX | RTL | Perf | Accessibility | Syntax | Cross | Preview | Meta Bugs |
|---|---|---|---|---|---|---|---|---|
| gaia-component | - | - | - | ? | O | O | x | x |
ChangeLog
- 2015/5/8 gaia-button change from Not Ready to Can Use state
- 2015/5/21 add `basic treatment` and `Not ready but in use` section
- 2015/5/26 gaia-icon accessibility is ready
- 2015/5/29 gaia-switch accessibility is ready
- 2015/10/30 Settings is migrated to gaia-radio*/gaia-checkbox*/gaia-switch* (with Building Block style)
Gaia Components Basic Treatments
Visual
The elements UX and visual should be follow the spec on MDN. Please contact Harly (hhsu@mozilla.com, UX) or Przemek (pabratowski@mozilla.com, UI) for provement.
RTL
There's theme-selector in each component's example page. Use it to check RTL support status and think about what can be supported by the component itself.
Make sure the style use `-moz-margin-start` instead of `margin-left`, and so on.
Syntax
Basic lint and unit test is required. Run `npm run lint` for link check, run `npm test` for unit test.
- Stop overriding component's CSS elements.
When you tempt to override component's style, DONT do it. Firstly you can double check with UX team if this new design is follow their convention. If so, opt in to a specific style configuration that defined inside of the component (eg. `<gaia-button circular>`)
- Icon related design
Read gaia icons accessibility for designing icon related syntax.
- Don't embed l10n directly into component
For l10n, don't embed l10n directly into component itself. l10n will work properly in the content elements. such as
<gaia-button> <span data-l10n-id="ok"/> </gaia-button>
Performance
Always measuring then improving.
You can compare the component created time by browse your FxOS device to `http://localhost:8000/test/stress.html` (run on local server). Make sure you measure the performance with real device. Or the result will be not really useful.
Accessibility
Most of accessibility(a11y) enhancements could be pre-defined by component. The component user could benefit from a11y automatically.
The component should inherit from proper native element, and add proper role of aria. http://rawgit.com/w3c/aria/master/aria/aria.html
For example, button should inherit from `HTMLButtonElement` and have `role=button` attribute.
The current name or state should be exposed to ScreenReader as well. For example, button should have `aria-checkd="true" aria-disabled="true"` when button is checked and disabled.
- use setAttribute to set aria attribute to host element but not inner element to prevent double trigger the related event.
PS: To enable Screen reader on FxOS device, tap up then down button trice. then tap up then down button trice again.
