RFC: The future of missing.js

[geoffrey-eisenbarth]

missing.js

The goal of missing.js is to provide a comprehensive collection of common UI widgets and behaviors that:

• don’t expect the website author to use a particular framework or library,
• are small in terms of bandwidth,
• are headless (i.e. by default, they only contain minimal styling that's necessary for functionality) but have optional style sheets with default styling (e.g. missing.css),
• are implemented with simple and well documented code,
• have wide support, and
• have exemplary accessibility.

To that end, we are creating this discussion to:

1. create a ranked list of desired UI widgets,
2. determine naming conventions,
3. discuss css and js implementation details

Widget list

Below is a list of possible widgets we could implement:

ARIA APG Patterns (click to toggle)

• accordion: use <details name=foo>
• alert: partial support
  • use <output role=alert> for alerts (<output> has implicit role=status and is display: inline by default, so the author would need to change that)
  • use <output> for toasts (the implicit role=status implies aria-live=polite and aria-atomic=true, same caveat with default display value)
• alert dialog: partial support
  • use <dialog role=alertdialog> (<dialog> has implicit role=dialog)
• breadcrumb: partial support
  • js not required, author must 1) place it in <nav>, 2) provide accessible name, 3) set aria-current=page
  • an earlier proposal suggested implementing a crumb menu that shows other items on that level of the hierarchy.
• button: use <button>
• carousel: no support
• checkbox: use <input type=checkbox>
• combobox: no support
  • OpenUI explainer
  • future: support chip input c.f. franken ui)
• dialog (modal): use <dialog>
• disclosure (show/hide): use <details>
• feed: no support
• grid: no support (see Adobe's impl)
• landmarks: use <aside>, <footer>, <header>, <main>, <nav>, <section aria-label>, <form>, and <search>
• link: use <a>
• listbox: no support
• menu, menu-item, menu-button: no support
• menu-bar, menuitem-radio, menuitem-checkbox: no support
• meter: use <meter>
• radio group: use <input type=radio name=foo>
• slider: use <input type=range>
• multithumb-slider: no support
• spinbutton: no support
• switch: partial support
  • use <input type=checkbox role=switch>
  • Requires significant CSS in order to style as a switch (except for Safari)
• table: use <table>
• tabs: no support
• toolbar: no support
• tooltip: no support
  • See also toggle tips
• tree view: no support
• treegrid: no support
• window splitter: no support

Non-APG Patterns (click to toggle)

• screen-reader-text
• input masking
• data table
• multi-select checkbox
• scrollspy
• avatar
• fly-out navigation menus
• scroll-box element (internals.role = region, tabindex = 0, overflow: auto)
• close button (for .titlebar in alerts, dialogs, etc)
• toggle button group
  • a series of toggle buttons, e.g. bold/italic/underline or flush-left/flush-right/centered/justified
  • Can be exclusive or multi-selectable.
• card link
  • an <article> where clicking anywhere on the article (that isn’t itself clickable) activates a certain link or button or other action.
  • This can be implemented in css (see “card pseudo element hack”), but a JS implementation would be composable with other components e.g. a gridlist with cards could activate the cards.
• mobile-nav expander
  • can this be done framework agnostic?
• calendar/date/time widgets
  • is <input type=date|time|datetime-local> sufficient?
  • support non-Gregorian calendars, localization support
  • date range picker (e.g. booking a hotel)
• color picker
  • is <input type=color> sufficient?
  • support light-dark() (composite widget of two color pickers)
• progress bar
  • is <progress> sufficient?
  • support displaying percentage values
  • support listening for standardized update events
• bibliography (low priority bc bibhtml does a wonderful job)
• hover preview
  • a card that appears when an element is hovered, showing a snippet of information from the linked page.
  • Most existing implementations seem to be exclusive to visual usage – is it impossible to make this accessible?
• overflow
  • A row of items, such that any element that doesn’t fit in the row and would cause it to wrap or overflow will be moved into a separate container (the pane). The pane would usually be the body of a disclosure.
  • TBD: Is it OK to require items to be direct children of the overflow? Otherwise, how should wrappers behave when their descendant items are moved into the pane?
  • Should we duplicate wrappers in the pane? Should we remove them from the overflow when all their children are moved into the pane (and vice versa)?

Guidelines

1. Components should mutate their child elements as little as possible. They should be able to initialize themselves when the children have already been mutated (i.e. if a live DOM tree is stringified and restored, such as during htmx history restoration).

2. Components should emit events liberally for interactions performed on them, so that their behavior can be hooked into.

3. Shadow DOM should only be used to set styles that are strictly required for functionality

   • Avoids problems in integrating with other libraries (particularly htmx)
   • Allows authors to write their own style sheets (CSS custom properties should be used internally to allow authors to override them)
   • Custom elements are display: inline by default, (e.g. set :host { display: block; } for tabpanels).

4. Common behaviors should be abstracted into composable mixins.

5. Accessibility guidelines must be strictly followed when available. If the component does not have explicit guidelines, careful consideration should be taken based on guidelines for similar components.

Implementation

Thanks to deniz, we have two great utility functions: behavior() and tag(). The first one allows us to hook custom functionality into elements matching a given selector (e.g. role=menu), and the second one reduces a lot of boilerplate involved in custom elements.

• Are there situations that work better as a behavior() than a tag()?
  • behavior() needs to be re-initialized for dynamically created elements: this happens for free with tag() (however, it might be possible for behavior() to be extended to cover this).
  • tag() provides access to the ElementInternals API, requiring significantly less author markup.
  • behavior() doesn't require dash-separated names and can be hooked directly into any selector, making it compatible with existing CSS libraries.
  • tag() requires dash-separated names, making it incompatible with existing CSS libraries.
• What should our custom element prefix(es) be?
  • <aria-foo> works well with APG patterns: <aria-tooltip>, <aria-carousel>, <aria-tree-view|grid>, <aria-window-splitter>, but maybe feels out of place for non-APG patterns: <aria-input-mask> / <aria-scroll-box>.
  • We could simplify to <a-tablist>, <a-menubar> (maybe follow English grammar with <an-alert>), making non-APG patterns such as <an-input-mask> and <a-scroll-box> feel less out of place.
  • Not all custom elements have to have the same prefix, we could distinguish between APG patterns and other widgets this way
  • We could use some prefix related to "missing": <missing-menu-bar>, <missing-input-mask>
    • Is this too long?
    • It kind of reads as if the menu bar is physically missing, as opposed to supporting the library's name

Common behaviors

There are a few recurring behaviors utilized in accessible widgets. These should be developed in a composable way in order to make creation of compound widgets more efficient. Some of the behaviors are getting native implementations (such as invoker buttons and anchor positioning), but it'll be awhile before they're available across our support target.

• Focus group: Add keyboard support for moving focus among a list or grid of focusable elements with a roving tabindex. (see: open-ui explainer)

• Focus selector: Add support for selecting an element when it is focused. ARIA roles that require "selection follows focus" include role=tree|listbox|tab

• Hot keys: Add keyboard shortcuts to an element, e.g. Escape to close a menu, moving focus to the next item in a menu whose label begins with a given printable character, and other non-standard keyboard navigation (feeds).

• Invoker button: Polyfill for the commandfor and command attributes. Needed for menus and toolbars. (see: open-ui explainer)

• Anchor positioning: Polyfill for the upcoming CSS anchor positioning. Needed for menus, tooltips, and combobox.

• Dynamic ID / ARIA linking / ARIA validating: many widgets require unique ids and linkage via aria-labelledby / aria-describedby etc. This could possibly automatically handle setting those attributes and/or logging errors to console when markup does not specify required ARIA links. See ARIA Naming Role Guidance

• Light dismiss: "Closes" the component when the user clicks outside the element. What it means to “close” is defined by the child component.

• Reorderable: Allow a component’s children to be reordered by clicking and dragging. Needs research to figure out if this is possible to implement generically, or needs to be implemented within specific components.

Next steps

• Create an un-ranked second draft of the widget list:
  • Suggestions/additions and opinions needed
• Determine a naming convention for custom elements:
  • Current candidates are <aria-foo>, <a|an-foo>, <missing-foo>
  • Do we want a single prefix for all widgets or should we distinguish the APG patterns?
  • Suggestions and opinions needed
• Chose five widgets to start with that are:
  • in high demand,
  • sufficiently complex to stress test the framework, and
  • utilize multiple behaviors mentioned in the previous section.
• Put together demo pages for the widgets to finalize markup and provide a manual test during development.
• Create the necessary base behaviors for the initial five widgets
• Create the initial five widgets and then re-assess.

[geoffrey-eisenbarth]

Initial widgets to implement

In order to build a sufficiently robust framework, we should start with implementations of the following patterns:

• tabs: requires focus group and select follows focus
• toolbar: requires focus group, focusability of disabled controls (EDIT: this seems to just be a matter of styling [aria-disabled=true] and does not require any behavior changes unless we want to exclude [aria-disabled=true] values from being submitted by a FACE).
• feed: requires hotkeys support for unconventional keyboard navigation
• listbox: form-associated, multiple selection, grouped options, recommended type-ahead
• menu, menu-item, menu-button: requires focus group, popover API, anchor positioning polyfill
• menu-bar, menuitem-radio, menuitem-checkbox: form-associated, possibly requires commandfor polyfill

[geoffrey-eisenbarth]

Managing state

The following table summarizes the potential ARIA states a widget could assume. A few things to note:

• All of the pseudo-classes require using form associated custom elements (FACE), but presence of a pseudo-class does not imply the role should be a FACE (see: tab has aria-selected, but should not be a FACE because it's navigational / presentational).

• For the "disabled but focusable" pattern we have to 1) set [aria-disabled="true"], 2) not use [disabled] / el.disabled, and 3) prevent any interaction using preventDefault and style based on [aria-disabled="true"].

State	Values	Required Roles	JS Property	HTML Attribute	Pseudo-Class	Reflective
aria-busy	true, false	global
aria-checked	false, mixed, true, undefined	checkbox, menuitemcheckbox, menuitemradio, option, radio, switch	.defaultChecked .checked	[checked] None	:checked :checked	True N/A
aria-current	page, step, location, date, time, true, false	global
aria-disabled	true, false	application, button, composite, gridcell, group, input, link, menuitem, scrollbar, separator, tab	.disabled	[disabled]	:disabled	True
aria-expanded	false, true, undefined	application, button, checkbox, combobox, gridcell, link, listbox, menuitem, row, rowheader, tab, treeitem	.open .showPopover()	[open] None	:open (caniuse) :popover-open	True, N/A
aria-grabbed	false, true, undefined	global
aria-hidden	false, true, undefined	global	.hidden	[hidden]		True
aria-invalid	grammar, false, spelling, true	application, checkbox, combobox, gridcell, listbox, radiogroup, slider, spinbutton, textbox, tree	internals.setValidity()		:invalid
aria-pressed	false, mixed, true, undefined	button
aria-selected	false, true, undefined	gridcell, option, row, tab	.defaultSelected .selected	[selected] None	:checked :checked	True N/A

How can we best provide authors the ability to monitor, change, and style widget state?

Answer: Use ElementInternals to set roles, properties and default state and change state using [aria-${state}] attributes. The attribute values override ElementInternals so e.g. we can set el.internals.ariaSelected = false for all <aria-tab> and then set [aria-selected="true"] on the active one when appropriate.

• All changes in state should emit events: simply add aria-${state} to observedAttributes
• Exposes state and allows state to be remembered when DOM tree is stringified (in contrast to ElementInternals.states)
• Elements can initialize themselves in the attributeChangedCallback(), which is run before connectedCallback()
• It's an existing and robust standard
• Built in IDL / content attribute reflection (and avoids the issue with [selected] and [checked] attributes not being reflective. EDIT: Actually those attributes ARE reflected, but as .defaultSelected and .defaultChecked, but point still stands)
• Easy and familiar styling hooks, no need for authors to learn new attributes (in contrast to ElementInternals.states and :state())
• Helps promote good ARIA to authors
• Use FACE when appropriate in order to expose pseudo-classes for styling

[geoffrey-eisenbarth]

Alternatives

A list of similar (but not) libraries that may be helpful by ways of compare/contrast:

• Ariakit
• FrankenUI
• Adobe React Aria
• Vaadin (and their multi-select combobox)
• Quiet UI

[geoffrey-eisenbarth]

When it comes time to finalize docs / demos, make sure to specify all the default ARIA properties set in ElementInternals, as well as supported ARIA states/properties.