CEM Component Reference

Status: Phase 4 MVP reference for @epa-wg/cem-components.

This document describes all 55 canonical XHTML/CEM-ML components. It pairs with conventions.md, accessibility.md, component-mvp.md, and the passive/payload completion contract. Components load from individual XHTML resources or the generated bundle through cem-elements. The legacy JavaScript installer and package entry are retired.

Capability caveat: source templates and their owning declarations carry intrinsic behavior metadata. Fragment imports inherit it, so ordinary consumers need only tag and src. Preserve the metadata when copying a template; explicit importer values override it, and capability="" suppresses it. A component can still render while losing required runtime behavior when the capability is removed or replaced. See the capability names and ownership rules and the form demo.

Authoring Contract

• The normative source/layout/testing contract is the declarative UI principle: one src/components/<cem-tag>/<cem-tag>.xhtml CEM-ML declaration whose <template id="<cem-tag>" type="text/cem-ml"> is reusable as <declaration-url>#<cem-tag>, containing its declaration-owned <style> node with CEM UI --cem-* tokens, installed once per declaration, and one colocated CSF Next <cem-tag>.stories.ts module containing all component unit assertions in async play functions from storybook/test. Its render functions return HTML strings and it loads its own raw XHTML declaration through the shared Storybook loader. Standalone component CSS and production JavaScript/TypeScript elsewhere in the package is forbidden; the story is the only development-only TypeScript exception and cannot implement behavior.
• The accepted CSS target compiles declaration styles with native @scope. Private rules use the tag root; public shared groups use declaration-owned scope="name"; projected roots retain slot="name"; and component-owned internals expose part="name". Per-instance CSS requires an explicit inert direct payload template. The complete target is normative in the CEM light-DOM CSS scope contract but MUST NOT be assumed implemented until its active migration gate passes.
• If CEM-ML lacks a concise required capability, hard-stop the component and implement the reusable capability in cem-elements before resuming. A behavior module, installer callback, story-local behavior, or app-local workaround is forbidden.
• Components render in light DOM through the <cem-element> substrate. Authors provide semantic fallback content first; the upgraded output keeps the same visible meaning.
• Component state is expressed through host attributes and ARIA attributes, not private CSS classes. Use disabled, aria-selected, aria-expanded, aria-busy, aria-invalid, and data-state according to the state matrix in docs/component-mvp.md.
• Component styling must use CEM token families from @epa-wg/cem-theme. The token families listed below are the allowed styling surface for the MVP; no component-specific color or spacing literals should be introduced.
• Examples live under ../examples. New and migrated component tests live only inside their colocated CSF Next Storybook module. Use cem-select as the proven pattern.

Production Gate

The current migration baseline and the proven XHTML/CSF Next contract remain verifiable when this command passes on the branch being promoted:

The aggregate gate includes:

Current legacy evidence locations follow. They keep the pre-migration package verifiable but are not valid locations or implementation patterns for new work:

The Phase 3 visual baseline is the inline Vitest snapshot produced by the headless Chromium project used on Linux CI. It records normalized visible HTML, geometry, and selected computed styles while removing runtime-generated data-cem-* identity/source-map attributes and inert data-island templates. Baseline updates therefore appear as reviewed source diffs. The accompanying PNG capture is a browser-paint smoke assertion and is not stored as a second, platform-sensitive golden file.

Handoff condition: Phase 4 component expansion can build on this primitive package after the aggregate verify gate is green and the promoted branch has no uncommitted gate changes. The handoff covers the MVP primitive declaration set, common static/form workflows, state and ARIA behavior, light-DOM rendering, event payload capture, and token-only style constraints.

Known deferrals remain outside the Phase 3.2 trigger:

• Edge/SSR processing fixtures for serialized data-island snapshots are Phase 3.5.
• @epa-wg/custom-element monorepo adoption is Phase 3.6.
• Full application behaviors such as dialog focus trapping, routed navigation, async data loading, and resource primitives are follow-up runtime/application work.
• Post-MVP controls including split actions, date ranges, date/time-zone integration, adapters and alternate calendar views, side-nav variants, breadcrumbs, and richer Additional menu/dropdown variants remain future expansion work.

Actions

Host visibility follows the shared native visibility convention.

Dropdown and submenu surfaces use the opaque comfort palette with matching text, and Canvas/CanvasText in forced colors. Menu containers consume theme-owned --cem-menu-inset and --cem-menu-item-gap preferences with a nonzero floor for outside zebra/focus paint. At default stripe geometry, super-compact menus reserve 6px at the edge and 12px between items; inherited stripe/stroke overrides can increase those bounds. Controls retain zero super-compact padding/minima, and popup height follows content subject to the shared viewport boundary.

States: default, hover, focus-visible, active, disabled, pending, selected. The canonical cem-action declaration embeds its scoped styles for all five intents. cem-icon-button uses the same five variants in both button and link state styles, including persistent selection and pending feedback. Its additional navigation variant uses navigation colors for links and disclosure buttons. The contextual variant has unfilled resting and disabled states in every theme; disabled ink is muted. Hover, active, pending, focus and selection retain their theme feedback. Adjacent controls still require the theme's coupling guard. The action variants use paired CEM action tokens for default, enabled native-button hover and held native-button active states. Hover and active change only background/text color; they add no ARIA or active runtime state and exclude disabled buttons through :enabled. See the action hover contract and action active contract.

Action consumes the theme's --cem-action-<intent>-<state>-background and --cem-action-<intent>-<state>-text properties directly. Override these on a container or an individual host; removing an override restores the inherited theme value. The former private --_cem-action-* aliases are removed without compatibility aliases. No generic --cem-action-<state>-* family is introduced.

For cem-action and cem-icon-button, pending="true" reflects aria-busy="true" and shows the canonical 45-degree pending gradient with a seamless two-second loop. Colors come from the current intent's pending/active background pair and pending text. Destructive uses the theme's pending-stripe endpoint for a lighter stripe in light schemes and a darker stripe in dark schemes; its active button state remains unchanged. Pending paint takes precedence over hover/active and disabled paint. A disabled pending button keeps the gradient while native disabled semantics block activation and focus. Clearing pending while disabled restores disabled colors. Hover/focus preserve the continuous animation and zebra focus remains independent. Clearing pending restores interaction paint. Reduced motion freezes the gradient; forced colors use system colors and a static pending boundary. Pending preserves dimensions and activation; use disabled to block activation.

Inputs

cem-suggestions attaches a native suggestions list to one projected cem-field or cem-text-field. Enable local composition through the embedding runtime's localSuggestions: true policy. Use inert editor and options payload slots; optional option/group-label templates use type="text/cem-ml" and receive native suggestion/group parameters in their original namespace context. The field owns value, name, constraints, visible label, help and form submission. The attachment owns listbox/row IDs, group names, preview and status feedback.

The omitted profile, or explicit profile="listbox", supports filter="contains|prefix|none", filter-by="label|value|label value" (omit with none), require-selection, selection-message, options-state="ready|pending|failed", options-error, listbox label, and the five *-message feedback attributes shown in its gallery. Custom labels cannot hide the stored-value hint. Explicit native options/editor-for integration requires host-admitted sources and relationships; it conflicts with the matching local slot. Chromium input-protocol plays cover mouse/touch/pen taps, cancellation, wheel scrolling and composition settlement on both fields. Physical touch-pan, device IME, screen-reader interoperability and the broader composition matrix remain in the acceptance evidence and release record. The gallery maps all seven audited source intents, including native text fallback and explicit value/label edge cases. Its numeric examples demonstrate ordinary editing only. The property playground includes an explicit profile="native-datalist" example. This profile accepts text, search, tel, url, single-email and number inputs, retains their native roles and constraints, and consumes complete ungrouped local sources. It rejects custom filtering, selection proof, label templates and email multiple. The browser owns filtering and the picker; no custom popup or synthetic commit is installed. Actual numeric picker selection and device/AT acceptance remain pending in the acceptance record; typed numeric values are not picker-selection evidence.

cem-field and cem-text-field use canonical XHTML declarations and the shared form-control capability. See the field controls contract for attribute presence, host form ownership, reset and scoped indicators. Both single-line fields forward native range/step, length/pattern, editing hints and list bindings; see that contract for the full shared inventory. Live public value writes update submission/validity synchronously and preserve reset defaults. Explicit runtime recovery refuses entered passwords and password/one-time-code controls. After explicit clearing, the shared runtime can capture an empty credential control; it never clears a value to gain admission. Nonempty reset values/custom errors, file controls and other unsupported source/state contracts still block complete recovery. See the credential checkpoint policy.

Documentation page chrome uses the separate cem-gallery-page declaration. Its cem-playground-theme preference controls the page; production theme-switch examples and fixed variation themes keep their own scopes and storage keys.

States: default, hover, focus-visible, disabled, loading, expanded, invalid, required, readonly, checked, indeterminate.

cem-autocomplete is covered across every applicable input state. It supports free text by default and an explicit require-selection mode, contributes its string value through ElementInternals, keeps focus on the native input during listbox navigation, and accepts live declarative option replacement without replacing that input or mutating the committed value. Filtering, ranking, fetching, and debouncing remain application/CEM-QL concerns.

cem-timepicker is covered across its applicable input states while the direct authored text input remains the form and event owner. Values are empty or canonical HH:mm; typed syntax/range errors use native custom validity; generated intervals or direct options supply listbox choices. Option commits dispatch one input/change pair on that exact input. Date objects, seconds, time zones, locale adapters, and datepicker integration remain out of scope.

cem-datepicker is covered across its applicable input states while the direct authored text input remains the value, validation, event, reset, and form owner. Calendar navigation changes only a draft; Apply emits one native input/change pair when the canonical value changes, while Cancel, Escape, and backdrop dismissal remain silent. The Angular Material parity row stays partial because date ranges, adapters/filters, alternate year views, date/time-zone integration, Date/Temporal values, and locale-specific text parsing remain out of scope.

cem-slider retains native range-input form/event ownership for single and range values. It adds no tuple form value or custom event: each thumb serializes under its authored name and emits its own native input/change sequence. Parent bounds are normalized, range values cannot cross, and transient pointer or focus paint does not mutate component state or geometry.

Presence-only host busy projects exact data-state="loading" and aria-busy="true" markers to the same interactive control. It does not infer or perform asynchronous work, disable editing, create runtime state, or replace the control; label, value, focus, and dimensions remain stable. See the input loading contract.

Extra input indicators are state-specific. Resting fields, closed selects and unselected choices have no decorative shadow stack; native control boundaries remain. Checkbox, radio and switch labels stay clickable but never own the indicator. Their native inputs own focus, checked/mixed, invalid and pending feedback, so the label text is not enclosed in a second box.

When needed, the stack composes an invalid/pending anchor, an independent keyboard-focus stripe and an independent checked/mixed or open-popup stripe. A normal anchor has zero width. Invalid controls activate the boundary width; pending controls activate pending width; invalidity wins when both apply. Disabled controls do not acquire an invalid/pending anchor, but retain their native checked state and selection indicator. Pointer hover alone adds no extra shadow; it can recolor an already active invalid/pending indicator.

Field-like controls default to indicator="underline"; checkbox, radio and switch default to indicator="outline". These options describe active state feedback, not an always-visible decoration. Missing/unsupported values use the family default. The inherited --cem-input-indicator-appearance adapter still wins over the host attribute. Theme tokens remain generated and overridable. In forced colors, shadows are removed and native state plus system-color outlines preserve feedback. Focus and blur must preserve DOM, values and layout.

Action selection and disclosure

cem-action[selected] represents a persistent choice and draws the selected zebra independently of focus, hover, held :active, disabled and loading. Its container owns selection; clicking never toggles the attribute automatically. Use selectable on both selected and unselected members of a choice group. selected implies selectable. Both attributes are presence-only: remove them for false; selected="false" still means selected.

The native button exposes aria-pressed="true" when selected, "false" when selectable but unselected, and no aria-pressed for an ordinary command. Do not put aria-selected on an ordinary button; menus, tabs and list options retain their own role-specific selection contracts. Selection is an outline channel, not a required alternate fill. Combined selected/focus/pending cues must remain visible without changing dimensions. Forced colors uses an inset selection boundary and a separate focus/pending outline.

expanded="true|false" is retained as explicit forwarding to aria-expanded for an action reporting an associated disclosure's state. It does not open a panel or indicate selection, and is omitted from the standalone action playground. The disclosure owner supplies the behavior and panel association; cem-action forwards native invoker and relationship attributes to its exact button; see the command contract below.

Action command invokers

The accepted interaction design governs new action wiring. The declaration consumes the shared action-command capability in cem-elements; no component-local behavior owns visibility.

Native commandfor, command, popovertarget, popovertargetaction, and interestfor forward unchanged to the produced button. aria-controls, aria-haspopup, aria-describedby, and aria-expanded also forward; explicit aria-expanded takes precedence over the existing expanded shorthand. Native commands target native owners, never an implicitly selected descendant of a custom host.

command-target="@name|#id" resolves an explicit CEM relationship. @name resolves only in the nearest interaction-scope against interaction-name; missing/duplicate names are diagnostics, with no ancestor fallback. Built-in commands resolve a declared native owner (part="surface") or a directly targeted native surface. Custom commands target the provider endpoint. Shared descriptor metadata may supply target/command/context defaults through interaction; surface and descriptor component lifecycles are delivered separately.

context-key is captured with the actual native source before browser command dispatch, available to shared surface capabilities through getCemActionInvocation. This transient metadata does not replace typed CEM context. The target owns popup/dialog state; button-selected business state is unchanged.

Conflicting native/CEM invocation routes are rejected rather than toggled twice. Missing targets rebind as the DOM changes. Submit/reset behavior remains native even when invalid surface wiring is diagnosed. cem-interaction-error bubbles from the invoker when no valid target exists. Existing controls and target IDs survive ordinary rerender.

This first delivery implements action-side wiring and native targets. Shared popup/dialog targets own session commands and their target-side lifecycle.

Layout

cem-workspace accepts slot="navigation-actions" for controls beside its navigation heading. The wrapping header owns spacing; the heading remains a separate h2, so interactive controls do not become part of its accessible name.

These six layout/content owners use canonical XHTML, declaration-scoped token CSS and stable public parts. See the layout/content contract for defaults, typography, responsive tracks and retained content state.

States: default, loading, empty. In v1, both explicit layout states are owned by cem-surface: busy projects pending loading and takes precedence over the settled empty state. Stacks and grids remain formatting-only; dividers are non-interactive separation tracks. cem-divider composes D0 color, D1 relationship spacing/inset, the D2 guard floor, and D5 line geometry as specified by the divider contract. See the layout loading and layout empty contracts.

Navigation

States: default, hover, focus-visible, active, disabled, selected, expanded. The public stylesheet implements hover and focus-visible on the actual nav links/buttons, collapsible disclosure button, and tab buttons—not their structural wrappers. Generated navigation-item pairs preserve current-link/selected-tab meaning and suppress enabled hover styling for native or ARIA-disabled owners. Existing D5 stroke/offset and zebra color semantics provide an external focus ring that coexists with hover and selection without changing geometry. Navigation active/current-active pairs provide native held feedback; disclosure release remains owned by its expanded contract. Forced colors use platform system colors. See the navigation hover contract and navigation focus-visible contract, the navigation active contract, and the navigation disabled contract. Native disabled buttons leave the tab order and use browser suppression; cem-tabs uses that native-disabled contract exclusively. Direct ARIA-disabled cem-nav owners remain keyboard-discoverable while host capture behavior prevents pointer, programmatic, Enter, and native-button Space activation before target/application bubble listeners or default action.

cem-paginator uses its native select and action buttons as the only hover, focus, active, and disabled owners; the landmark, range/actions group, and label remain structural. Render-only normalization does not rewrite invalid or out-of-range author attributes. Page-size changes preserve the first visible item, successful user requests emit one serializable cem-page, and boundary or globally disabled activation is suppressed. Existing theme semantics cover normal and forced colors without a CSS exception.

Content

States: default, hover, focus-visible, selected, loading, empty, checked.

cem-expansion additionally owns contextual active, disabled, and expanded states for its native header without turning content disclosure into navigation or selection. Multiple siblings are independent; exclusive accordion-group policy is not part of this contract.

cem-sort-header additionally owns contextual active, disabled, ascending, descending, and none states. Only its native button receives interaction paint; cem-table, the host, and the column-header wrapper remain structural. Existing theme semantics cover every binding, including forced colors, so no CSS exception is recorded.

cem-tree additionally owns contextual active, disabled, and expanded states on exact treeitem buttons. Selection and loading are projected application facts; activation never mutates selection or starts resource work. Structural item/group wrappers own hierarchy layout only. The completed generic content interaction family and the dedicated forced-colors gate cover every state, so no component CSS exception is recorded.

In v1, content:loading is owned only by cem-card[busy]; lists, tables, and media previews neither infer nor inherit it. Authors retain last-known content during refresh or provide visible loading text plus layout-preserving cem-skeleton payload for initial loading. See the content loading contract.

Feedback

States: default, focus-visible, loading, expanded, invalid, indeterminate.

The tooltip contract defines native trigger ownership, independent focus/hover interest, touch preservation, description cleanup and shared placement. The same owner supplies description and visible presentation.

cem-progress-spinner is the distinct circular owner; linear cem-progress does not change shape to satisfy it. Missing value means indeterminate, and live value/max changes retain the same SVG and geometry. D0 progress colors, D2c progress geometry, and D7 cycle/easing tokens cover its stylesheet. Forced colors use GrayText for the remaining track and Highlight for the indicator; reduced motion leaves a static incomplete arc. See the progress spinner contract.

The native dialog contract defines commands, explicit modal mode, cancelable closing, focus restoration and retained/disposed bodies. The feedback/status declaration contract covers retained message owners, explicit urgency, native progress, shared circular preparation and inert skeletons.

The feedback focus contract covers actual native focus owners and forced colors. Sheets remain separate regions.

Action dimensions

size selects a theme minimum visible height: small 2.5rem, medium 3rem, large 4rem, x-large 6rem. Omit/remove it to inherit container geometry, including data-cem-size. Width and flex/grid stretch remain CSS layout concerns. The native button reserves at least --cem-coupling-zone-min in both axes; compact profiles use a transparent hit border and clip paint to the padding box. This border is not a visible intent outline. Zebra marks the complete target. Keep at least --cem-coupling-guard-min between neighboring targets. See the dimension decision.

Action contrast modes

Contrast-light/dark collapse action fills to the surface and use surface ink. Intent appears in the contour; hover and active increase its thickness without changing layout. Keyboard zebra remains independent. Loading animates a masked zebra contour, including while disabled, with a flat surface behind the label. Reduced motion freezes that contour; forced colors uses a static system outline. Ordinary light/dark/native modes retain pending background gradients. Both the contrast state values and contour tokens are generated from canonical theme docs.

Canonical command components

cem-icon-button and cem-menu-item load from their individual XHTML declarations or components.xhtml#<tag>. Both expose their native button as part="control"; icon-button also exposes the decorative glyph as part="icon".

Icon-button uses the action variants primary (default), explicit, contextual, alternate and destructive in both modes. It supports action bend classes and native button/form attributes. Native clicks update the pressed (icon-button) or selected (menu-item) event slice; these are event records, not persistent selected/toggle state. Menu navigation and popup ownership remain the containing menu's responsibility. Default slot content is supported by both controls. Boolean disabled presence includes disabled="false".

Each component has a matching property playground under playgrounds/, covering all listed attributes and showing its canonical source.

Persistent and nested menus

cem-menu loads from components/cem-menu/cem-menu.xhtml#cem-menu. Its default slot preserves links, buttons and cem-menu-item controls in a wrapping flex container. direction="row|column" defaults to row and justify="start|end" defaults to start. aria-label and aria-labelledby label the layout container; hidden uses presence. dir inherits normally. Arbitrary content receives no item paint.

The shared composite leaves --cem-inset-control around its items, floored at --cem-coupling-guard-min. The --cem-gap-related between items is floored at twice that guard, leaving room for both a selected item and its focused neighbor's zebra indicators. This applies to row, column and nested popup menus, including projected cem-action controls. Inherited spacing overrides apply without changing each item's own control padding.

keyboard="native|menu" defaults to native. Native mode keeps ordinary Tab navigation. Menu mode exposes a row menubar or column menu with one enabled roving stop. Arrows follow orientation and RTL; Home/End and case-insensitive typeahead skip disabled and hidden controls. Enter/Space retain native control activation. Empty or all-disabled menus have no roving stop.

Place a nested cem-menu slot="submenu" directly inside a cem-menu-item. Submenus require root menu mode, inherit that behavior, default to columns and open below row triggers or beside column triggers, flipping/clamping to the viewport. Owners remain buttons even when href is supplied. Leaf href items render native anchors; disabled leaves omit href and suppress activation. Opening focuses the panel's first enabled item. Escape closes the nearest panel and restores the trigger. Tab, outside activation and leaf activation dismiss open chains without a focus trap; only one sibling panel remains open. Runtime IDs link controls, trigger names and panels. Roots remain persistent.

Shared composite-menu and action-control capabilities own browser behavior in cem-elements. Dropdown composition supplies separately triggered root popups; context menus, checkbox/radio items and lazy loading are deferred.

Legacy source audit: Material menu (version in this repository) maps Default, Vertical, Horizontal, scoped and inline styling, wrap menu and wrap menu right to the canonical gallery's Default, Vertical, Horizontal, Scoped token overrides, Token overrides, Wrapping and End alignment examples respectively. Customization now uses the consumed contextual action and inset tokens. No external menu assets are needed.

Dropdown and nested menu composition

cem-dropdown loads from components/cem-dropdown/cem-dropdown.xhtml#cem-dropdown. label supplies fallback trigger text (Dropdown); aria-label names it separately. The base slot overrides the fallback native button: supply a direct native button, link or focusable trigger. With trigger-for, the declared external trigger owns activation and the fallback button is omitted. The default slot accepts arbitrary HTML or a menu. open="false" closes; other values open, including the source's default visible state. Use explicit open="false" for an initially closed interactive dropdown. disabled and hidden use presence; dir and class inherit normally.

The panel height follows its content, including menu item spacing. There is no fixed row-count cap. The shared popup controller constrains the panel to the viewport or declared boundary; vertical scrolling appears only when the content exceeds that available height.

The trigger toggles on native click/Enter/Space; ArrowDown opens and focuses the first enabled panel control. Escape restores trigger focus. Tab, focus leaving the component and outside activation dismiss without a trap. Geometry flips and clamps within the viewport when opened or resized. Like the legacy source, the dropdown uses a relative host and an absolute panel at z-index: 1, with square top corners. Initially open panels retain the CSS position below their triggers, including offscreen examples. Scrolling moves the panel with its trigger, including beyond the viewport edge. The declaration consumes existing action, control, bend, typography, focus and elevation tokens instead of defining component-specific shadow/height/width aliases.

Place cem-menu direction="column" keyboard="menu" in the default slot. Nested menu-item submenu slots keep their existing composition. Both capabilities consume the shared popup controller. The nearest menu handles Escape first; only when its submenu chain is closed does the outer dropdown handle Escape. Leaf menu activation dispatches shared popup dismissal, closing the complete chain. Popup wrappers and menu navigation retain separate ownership; no gallery or component JavaScript implements their behavior.

Source audit: dropdown 0.0.39 maps HTML in dropdown, Menu in dropdown and Hide dropdown dynamically to the same-named canonical gallery examples. The source's external image is replaced with the shipped custom-element SVG asset. The source's label becomes a native button so its existing keyboard focus also supports keyboard activation.

External declaration aliases inherit their intrinsic source capabilities: composite-menu for cem-menu, action-control for cem-menu-item, and popup for cem-dropdown. Use <cem-element tag="cem-menu" src="…#cem-menu"> without repeating the capability. Preserve source metadata when copying templates; explicit importer overrides can disable the keyboard or popup behavior described here. The metadata ownership rules apply to all three.

In a single-choice menu, cem-action and cem-icon-button with control-role="menuitemradio" map their container-owned selected state to aria-checked and the same selected zebra outline. Other selectable buttons continue to expose aria-pressed. The theme switch uses icon buttons so its Unicode sun/moon glyphs use cem-icon sizing separately from the choice labels. Its choices use align="start"; both icon components support logical inline alignment independently of row/column direction, with center as the default.

cem-text kind="project|resource|output" applies canonical resource identity paint without adding interaction or headings; variant="caption" keeps UI typography. Use it inside projected headings so its own declaration owns the text styling. Interactive tree rows keep their own selected/hover/disabled paint precedence. cem-app-bar appearance="compact" uses canonical control padding, contextual adjacency, and an inherited margin-free public title slot root. The default app bar appearance and projected title descendants remain consumer-owned.