Gaia/Shared/Components

< Gaia‎ | Shared

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

  • 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

Web Component Specs

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.