@adia-ai/a2ui-corpus 0.6.32 → 0.6.34

package/catalog-a2ui_0_9_rules.txt

@@ -104,6 +104,10 @@
 - For navigation (route-change) use <nav-item-ui> or anchor; button-ui is for actions only.
 - For toggleable on/off state use <switch-ui>; for multi-select clusters use <toggle-group-ui> + <toggle-option-ui>.
 
+## CalendarGrid
+- Use <CalendarGrid> only as a substrate primitive composed inside a higher-level component (date-range picker, datetime picker, custom date affordance). For a full single-date input, use <CalendarPicker> — it adds a trigger button, popover surface, and form-association.
+- <CalendarGrid> is NOT form-associated. Its emitted `change` event is the sole signal to the parent — the parent owns the canonical value + form participation.
+
 ## CalendarPicker
 - Form-associated date input. Trigger button + popover calendar grid; emits ISO date string via change events.
 - Use for single-date input. For date ranges compose two pickers or use a dedicated range component.
@@ -173,12 +177,34 @@
 - For simple color swatches (read-only display) use <swatch-ui>; for hex/rgb text input use <color-input-ui>.
 - Output format defaults to oklch(); set format= to override (hex, rgb, hsl).
 
+## Combobox
+- Use <combobox-ui> for typeahead-filterable single-select with a constrained-choice value model. `value` MUST be one of `options[].value` unless `[free-text]` is set. For ≤ 4 options, use <segmented-ui> or <radio-ui> instead.
+- For free-form text entry with suggestions, use <autocomplete-input-ui> (SPEC-035) — combobox is constrained-choice. For button-first dropdowns where the trigger should be closed by default, use <select-ui searchable>.
+- Compose options via native <option> / <optgroup> children, OR set `.options` programmatically as an array of `{value, label, disabled?}` (grouped form: `{label, options:[…]}`). Setting `value` to a string not in `options` is invalid mid-state (free-text=false) and the validator should reject it.
+- `[creatable]` implies `[free-text]` and adds the "Create '{value}'" footer affordance + `create` event. Consumer wires the create event to a backend flow.
+- Multi-select goes through <multi-select-ui> (SPEC-040), not combobox. Combobox is single-select.
+
 ## Command
 - <command-ui> is the searchable PALETTE primitive (input + option list). For Cmd+K palettes, wrap it in <admin-command> at the shell tier — admin-command owns the native <dialog>, focus management, and the Cmd+K / Ctrl+K shortcut listener. command-ui is content-only and does NOT own the dialog or shortcut. Do NOT hand-roll a <dialog> + Cmd+K key listener.
 - Author items as native <option value data-icon data-shortcut> elements inside <optgroup label="…"> for grouped sections. The `select` event's detail.category mirrors the parent optgroup's label. Detail = { value, label, category }.
 - Decision rule vs adjacent surfaces. Use <menu-ui> for small NON-searchable popover menus (≤10 actions, triggered by a button). Use <modal-ui> for generic centered dialogs. Reach for <command-ui> only when you need a searchable, keyboard-navigable list of commands or destinations.
 - command-ui MAY render inline (no dialog) for embedded search panels, but the canonical AdiaUI admin pattern is exactly one <command-ui placeholder="…"> as the sole child of <admin-command> inside <admin-shell>. See site/index.html and playgrounds/admin-shell/ for production references.
 
+## DateRangePicker
+- DateRangePicker.value MUST be `{from, to}` with both ISO 8601 dates, OR null. Either side null is invalid mid-state and the validator should reject it (use `input` event for partial state).
+- DateRangePicker.value.to MUST be `>=` value.from lexicographically. Reversed ranges trigger `invalid` and do NOT commit.
+- When `comparison: true`, both `value` AND `compareValue` MUST be set on commit. If only one is set, the form participation emits the set one and omits the other.
+- presets array entries each require both `label` (string) and `range` (`{from, to}`). Empty preset arrays are valid (rail renders empty).
+- Use DateRangePicker for date ranges. Do NOT compose two adjacent `<calendar-picker-ui>` instances + JS synchronization — that is the pattern this primitive replaces.
+
+## DatetimePicker
+- `DatetimePicker.value` MUST be ISO 8601 datetime (`YYYY-MM-DDTHH:mm` or `YYYY-MM-DDTHH:mm:ss`) OR empty string. Date-only or time-only strings fire `invalid`.
+- `precision: "second"` requires the value to include seconds when set; missing seconds are coerced to `:00` on commit.
+- `min` and `max` MUST be parseable ISO 8601 datetimes if non-empty. If `value` falls outside, `invalid` fires and the value does not commit.
+- `hour-cycle` overrides the locale-derived cycle in the time pane. Set explicitly when the surface needs a specific cycle (cron editors, log queries, system surfaces).
+- Use DatetimePicker for combined date+time. Do NOT compose `<calendar-picker-ui>` + a free-form `<input-ui>` manually as an alternative — that is the pattern this primitive replaces.
+- Per ADR-0025 NEVER wrap a native `<input type="datetime-local">` — the calendar pane + time pane composition + ElementInternals together provide form participation.
+
 ## DemoToggle
 - Demo-page-only — toggles between live and code views in component documentation surfaces.
 - Do not use in apps/ — restrict to packages/web-components/components/*/<name>.html demo pages and docs surfaces.
@@ -283,6 +309,13 @@
 - Use only in dev/debug surfaces; not for product UI.
 - Place in a right-pane inside <editor-shell-ui>'s editor-sidebar slot for editor-style inspector layouts.
 
+## IntegrationCard
+- Use <integration-card-ui> for one tile in an integrations grid. Set `provider` and `name` — both are required for analytics keys and the accessible name. Set `description` so users don't have to look the integration up externally.
+- `status` MUST be one of `available | connected | error | pending | coming-soon`. The button label and variant are DERIVED from `status` — never slot a <button-ui> directly in the card body. Use the `actions` slot for an overflow <menu-ui> with secondary actions like Reauthenticate or Disconnect.
+- When `status="error"`, set `error-message` — otherwise the user sees a Retry button with no context. The message renders below the description in danger-text color.
+- `logo` accepts a URL (containing `/`, renders as <img>) or a registered icon name (renders as <icon-ui>). Don't mix — one provider gets one logo source.
+- Group integration cards in <grid-ui columns="auto-fit"> or use <integrations-page-ui> (SPEC-063) for the canonical Settings-panel grid. Never nest <card-ui> around an <integration-card-ui> — it IS a card variant.
+
 ## Kbd
 - Inline-only — content from innerHTML, typically one or two key labels.
 - In menu items, use the kbd= attribute on <menu-item-ui> instead of nesting <kbd-ui> directly.
@@ -293,6 +326,16 @@
 - When wrapping action affordances that visually mimic links (e.g. 'Forgot password?' that triggers a reset flow), prefer `<button-ui variant="ghost">` over a fake `<link-ui>` — the affordance is semantically a button, just visually understated.
 - For inline-sentence affordances ('I agree to the [Terms] and [Privacy]'), nest `<link-ui>` directly inside `<text-ui>` so it inherits the paragraph's font / size / line-height.
 
+## ListWindow
+- ListWindow.items MUST be an array of plain objects OR scalars. Functions / DOM nodes / Promises are invalid.
+- ListWindow.render cannot be expressed in A2UI JSON — declarative authoring MUST use a <template> child (or default <list-item-ui> for objects with a text field).
+- When items.length > 200, the validator SHOULD recommend ListWindow over List to keep the DOM tractable.
+- ListWindow MUST have a defined height (via parent layout or style="height:..."). An unbounded-height windowed list defeats the windowing math.
+- ListWindow.item-size SHOULD be set when item heights are known and constant — the fast-path is significantly cheaper.
+- Do NOT nest ListWindow inside another scroll container; double-scroll containers break the IntersectionObserver math. Use one scroll boundary.
+- Do NOT use ListWindow for short lists (< 50 items). The windowing overhead exceeds the cost of rendering all rows. Use List for short lists.
+- Do NOT use for tabular data — that is Table with virtualized rows.
+
 ## ListItem
 - Child of <list-ui> — one row of generic-list content.
 - For navigation lists use <nav-item-ui> inside <nav-ui>; for menu items use <menu-item-ui>; for tree rows use <tree-item-ui>.
@@ -474,6 +517,13 @@
 - For two-handle range selection use <range-ui> instead.
 - Step attribute controls increments; show-value enables an inline value label.
 
+## Spinner
+- Use <Spinner> for INDETERMINATE loading where the duration is unknown. For determinate progress (a known fraction complete), use <Progress> (linear) instead. For known-shape placeholder loading, use <Skeleton>.
+- When a Spinner is inside a Button, set tone="current" so it matches the button label color, and disable the button while the operation is in progress.
+- When overriding [label], use a present-progressive verb form ("Loading", "Saving", "Uploading"). Never use "Spin" or "Wait" — they describe the visual, not the operation.
+- Do not nest <Spinner> inside <Skeleton>; they are siblings (two different loading idioms), not parent/child.
+- Do not stack multiple sibling <Spinner>s in the same viewport region. Use one parent-level Spinner instead — multiple spinners add visual noise without extra information.
+
 ## Stack
 - Overlay/layer stacking container — children occupy the same area, stacked on the z-axis.
 - Use for overlapping content (image + overlay, badge-over-avatar, drop-shadow stacks).
@@ -566,6 +616,14 @@
 - Use [rows] to set initial height (default 3) and [resize] (vertical | horizontal | both | none; default vertical) to control user resize. Never substitute a native <textarea> just to get rows / resize.
 - Enter inserts a newline — <textarea-ui> does NOT emit a `submit` event. For Enter-to-send multi-line composers, use <chat-input-ui submit-on-enter> inside <chat-composer>, not textarea-ui.
 
+## TimePicker
+- `<time-picker-ui>` is the canonical standalone time-of-day picker. Per ADR-0025 NEVER wrap a native `<input type="time">` — segments are contenteditable spans + ElementInternals provides form participation.
+- `value` MUST be ISO 8601 time `HH:mm` or `HH:mm:ss` (24-hour), or empty string. Localized formats (e.g. "9:30 AM") are not accepted; display formatting is derived from `hour-cycle` regardless of how the value is stored.
+- `step` is in seconds. 60 = minute precision (default); 900 = 15-minute precision (meeting-time common); 1 = second precision (requires `precision="second"`).
+- `precision="second"` exposes the seconds segment AND emits `HH:mm:ss`. Default `precision="minute"` emits `HH:mm`.
+- `hour-cycle` overrides locale-derived behavior. Set explicitly (`h12` / `h23`) when the surface needs a specific cycle (cron editors, log queries, system surfaces).
+- For datetime selection use `<datetime-picker-ui>` (SPEC-038) — it composes this primitive as its time pane.
+
 ## TimelineItem
 - Child of <timeline-ui> — one chronological event with timestamp + content + optional icon dot.
 - Different from <stepper-item-ui> (process steps with completion state) — timeline-item is event history.
@@ -671,6 +729,31 @@
 - Different from primitive <chat-thread-ui>: chat-thread (no -ui suffix) is the module-tier shell-aware version with scroll-on-new-message + load-more + empty-state coordination.
 - Hosts message blocks (typically agent/user message rows) as default-slot children; <chat-empty> goes as first child for the empty state.
 
+## DateRangeSelector
+- DateRangeSelector MUST sit inside a toolbar context — typically a
+Row inside DashboardLayout.slot=toolbar, or directly inside
+AdminPageHeader.slot=action. Do NOT place it as a freestanding
+block primitive at page top-level.
+
+- ONLY ONE DateRangeSelector with broadcast="document" per page.
+Secondary instances on the same page MUST use broadcast="self"
+or broadcast="none". Two document-broadcasters race for the
+data-range-* attributes on <html> and produce flicker.
+
+- `presets` MUST be a comma-separated subset of the documented value
+enum (today, 7d, 30d, 90d, qtd, ytd, custom). Unknown keys are
+ignored at runtime; the chip-row renders only recognized keys.
+
+- When value="custom", from/to MUST be ISO-8601 dates supplied
+either declaratively (from + to attributes) or imperatively via
+setRange("custom", from, to). Without a custom from/to, the
+composite falls back to the prior resolved range.
+
+- For form participation, set [name]. Without [name], the composite
+emits range-change events only and does NOT participate in form
+submission. With [name], FormData carries the value "{from}:{to}".
+
+
 ## EditorCanvasEmpty
 - editor-canvas-empty is the bespoke empty-state slot for <editor-canvas>. Place as the first child of <editor-canvas>; visibility is automatic via the [empty] reflected attribute.
 - CSS-only — no JS module needed in shell HTML imports.
@@ -710,6 +793,21 @@
 - Different from <admin-topbar> (admin-shell chrome) — editor-toolbar has [full-screen] state + editor-specific [data-toolbar-action] event bubbling.
 - Place full-screen toggle buttons inside the toolbar with [data-toolbar-action="toggle-full-screen"]; host reflects [full-screen] up to <editor-shell>.
 
+## ConfirmDialog
+- ConfirmDialog is for NON-destructive yes/no questions ("Save changes?", "Switch theme?", "Apply preset?"). For irreversible destructive operations (delete, drop, deploy to prod) use AlertDialog instead — its danger chrome + role="alertdialog" + typed-name speed-bump are the WAI-APG pattern for that case.
+- Default focus lands on Cancel by default — this is intentional (WAI guidance: the least-destructive action is the default). Do NOT add autofocus to the confirm button or override the focus model.
+- The confirm button is primary-toned by default. Use [confirm-variant="ghost"] only when both options are roughly equivalent in weight (e.g. "Apply preset" vs "Keep current" where neither is strictly preferred).
+- Do NOT model the cancel option as a "Discard" action — if cancel means "lose data", the operation is destructive and belongs in AlertDialog. ConfirmDialog's cancel is a no-op return-to-prior- state semantically.
+- Reflect dialog visibility via the [open] boolean attribute on the ConfirmDialog host (open=true / open=false). Do NOT toggle [hidden], CSS display, or wrap in a sibling visibility container — the inner <modal-ui> owns the native <dialog> lifecycle.
+
+## OnboardingChecklist
+- OnboardingChecklist MUST have a non-empty `items` array. Empty items renders an empty card.
+- Each item MUST have a unique `id` within the list — used as the storage key + event detail.
+- `storageKey` SHOULD be namespaced per product (e.g. `myapp:onboarding:v1`) to avoid cross-app collisions.
+- Items SHOULD number 3 to 8. Fewer than 3 is not worth a checklist; more than 8 should split into stages.
+- Use for the "card of optional setup tasks" case. For horizontal multi-screen wizards use <step-progress-ui>; for generic to-do lists compose <list-ui> + <check-ui> directly.
+- Do not nest two <onboarding-checklist-ui> with the same `storageKey` — they will clobber each other.
+
 ## A2UIRoot
 - Mount point for an A2UI-rendered composition. Hosts the runtime-emitted DOM tree.
 - Different from <gen-root> (which is for the generative-UI lane with LLM-driven streaming).