@adia-ai/a2ui-corpus 0.6.36 → 0.6.37

package/catalog-a2ui_0_9_rules.txt

@@ -95,6 +95,11 @@
 - For row/column layouts use <row-ui> / <col-ui>; for grid use <stack-ui>; block is for content-flow groupings.
 - Block-ui does not impose padding/gap by default — wrap in <section-ui> if you want chrome.
 
+## Blockquote
+- Use for pull-quotes, testimonials, or inline citations. Renders italic body text with a left rule indicator + optional em-dash attribution line.
+- Set [cite] for plain-string attribution; use [slot="cite"] for rich attribution (linked source, role pairing). Slot content overrides the [cite] prop when both are set.
+- Do NOT wrap blockquote-ui in a native <blockquote> element — that produces nested-blockquote semantics. The tag IS the blockquote.
+
 ## Breadcrumb
 - Canonical placement: render <breadcrumb-ui> inside <admin-topbar> for hierarchical page-context display. It is the topbar's heading region — typically preceded by a sidebar-toggle <button-ui icon="sidebar" variant="ghost" size="sm"> and followed by topbar actions in [slot="action"]. The host stamps role="navigation" + aria-label="Breadcrumb" automatically.
 - Child shape: each crumb is either an <a href> (ancestor link) or a plain <span> (terminal / non-link current page). The LAST child is the current page and MUST be a plain <span> — the component auto-applies aria-current="page" and disables pointer events on it. Optional first child may be an <icon-ui> (or <a> wrapping one with aria-label) for an app / home glyph.
@@ -193,6 +198,11 @@
 - 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.
 
+## ContextMenu
+- Use <context-menu-ui> for right-click menus on a target (table row, file item, canvas object). For button-triggered menus use <menu-ui>; for popover content that is not a menu use <popover-ui> directly.
+- Items are <menu-item-ui> children inside the default slot — same shape as <menu-ui> items.
+- Bind target via wrap (default-slot first non-menu-item-ui child) OR [for] selector. The selector form is useful for whole-table or whole-canvas menus where wrapping isn't practical.
+
 ## 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.
@@ -418,6 +428,12 @@
 - editable attribute enables drag-to-connect interactions; default is render-only.
 - For data-flow visualizations only — for general-purpose lines/shapes use raw SVG.
 
+## NumberFormat
+- Use for read-only numeric display with locale-aware formatting. For numeric INPUT use <input-ui type=number>; for KPI big-number display use <stat-ui>.
+- [number-style=currency] REQUIRES [currency] to be set to a valid ISO 4217 code. Without it the element renders nothing rather than producing malformed output.
+- [number-style=percent] treats the [value] as a fraction (0.5 → 50%). To display 50 as '50%' pass value=0.5 OR keep [number-style=decimal] and append '%' manually.
+- Compact notation auto-defaults maximumFractionDigits to 1. Override only when extra precision is needed (rare for compact display — defeats the purpose).
+
 ## OptionCard
 - Use <option-card-ui> for one-of-N choices where each option needs a heading + description, a leading icon, or both (onboarding personas, plan tiers, source pickers). Use <radio-ui> for dense forms with short labels and no descriptions. Use <segmented-ui> for compact horizontal single-select with short labels.
 - Group siblings by sharing the same [name] attribute — they auto-form a radiogroup. Form participation is implicit via UIFormElement: submits `name=value` with parent form. Wrap the group in <col-ui gap="2"> for default layout or <grid-ui> for [layout="tile"] hero pickers.
@@ -448,6 +464,11 @@
 - Inner shape inside a pane-ui is the conventional <header> + <section> + optional <footer> slot pattern. Headers carry [slot="action"] button clusters; sections hold the navigator tree, inspector form rows, or other primary content.
 - For a standalone resizable two-pane layout (no shell), nest panes directly inside a flex row — both with [side]-typed chrome — and the resize handle will live on the seam between them. For a non-resizable summary pane (a fixed-width detail rail), drop [resizable] and pane-ui collapses to a static container.
 
+## PasswordStrength
+- Pair with <input-ui type=password> via a JS listener (input.addEventListener('input', e => meter.value = e.target.value)). The meter does NOT participate in form data — it is a display indicator.
+- The score is 0 (Weak) / 1 (Fair) / 2 (Good) / 3 (Strong). [min-score] sets the threshold for the `satisfied` boolean in score-change events. Use the boolean to gate a submit button.
+- Do NOT set value via setAttribute — value is JS-property only and never appears in rendered HTML (security: avoids leaking the password into the DOM).
+
 ## PipelineStatus
 - Single updating pipeline status indicator — status pill with optional progress bar.
 - stage + complete + message attributes drive the current display state.
@@ -457,7 +478,7 @@
 ## Popover
 - <popover-ui> wraps a focusable trigger (slot="trigger", typically <button-ui>) + arbitrary interactive content (slot="content"). Never put bare text in slot="trigger" — it must be focusable so keyboard users can open the popover.
 - Decision rule vs adjacent surfaces. (a) For a list of action items use <menu-ui> instead — menu-ui is the specialized popover with role=menu + roving tabindex. (b) For read-only hover hints use <tooltip-ui>. (c) For centered focus-trapping dialogs use <modal-ui>. (d) For edge-anchored multi-field forms use <drawer-ui>. popover-ui is the GENERAL anchored surface for everything else (inline forms, color pickers, theme panels, export menus with non-action content).
-- Use [placement="bottom-end"] for topbar overflow / settings buttons; [placement="bottom-start"] for inline form fields; top-* variants when trigger sits low in the viewport (statusbar). [gap] (default 4px) controls offset from anchor.
+- Placement convention (ADR-0034): default `bottom` centers under the trigger — correct for wide pickers (calendar, color, date-range, filter forms). Use `bottom-start` for trigger-width menus (action lists, listboxes, breadcrumb overflow — popover width ≈ trigger width). Use `bottom-end` only when the trigger sits at the right edge of a container by construction (toolbar spillover). Use `top-*` when the trigger sits low in the viewport (statusbar). [gap] (default 4px) sets offset from anchor.
 - [trigger="hover"] is for non-essential disclosure only — never use it for popovers containing inputs, destructive actions, or anything the user must interact with via keyboard. Default [trigger="click"] for everything interactive.
 - Do NOT nest <modal-ui> or <drawer-ui> inside slot="content"; popovers are non-modal anchored surfaces, not dialog hosts. Stacking dialog surfaces inside a popover breaks focus management.
 
@@ -471,6 +492,12 @@
 - For labeled task lists (multiple progress bars with row labels), use <progress-row-ui> instead.
 - Spinner variant (variant='spinner') for circular loading indicators; bar variant default for linear.
 
+## QRCode
+- Set [value] for URLs / share links / plain text. The built-in encoder covers byte-mode UTF-8 up to QR version 10 (~150 chars at ECC-M, more at lower ECC levels).
+- For data that exceeds version 10, switch to a higher ECC level downgrade ([error-correction=L]) OR use a BYO encoder and pass the precomputed [matrix].
+- When QR sits over a non-white surface, set [background] to a solid color. White-on-image QR backgrounds are unreliable for scanners — quiet-zone contrast against the dark cells is the load-bearing visual.
+- The [margin] (quiet zone) defaults to 4 cells per QR spec. Smaller margins may scan on some devices but not others; do not go below 2.
+
 ## Radio
 - Self-labeling widget — use the [label] attribute directly; do NOT wrap in <field-ui>. The widget renders its own label inline via CSS attr() pattern. For radio groups, the canonical pattern is a column of bare <radio-ui label='…'> elements sharing a [name=] — no field-ui wrapper around each radio.
 - Use the [name] attribute to group radios — exactly one is selected per name group; form-associated.
@@ -486,6 +513,11 @@
 - For thumbs-up/down agent feedback use <agent-feedback-bar-ui> instead — different semantics + visual.
 - max attribute sets the scale (default 5); allow-half attribute enables half-step granularity.
 
+## RelativeTime
+- Use for displaying a single timestamp as a relative phrase. Self-updates on a tick so the rendered text stays current; no parent re-render required.
+- Set [datetime] to an ISO 8601 string. Empty datetime renders nothing — do not stamp a relative-time-ui element until you have a timestamp value.
+- [update-interval=0] freezes the render (no tick). Use for historical timestamps that will never become 'just now' (audit-log rows, version-history entries from days+ ago).
+
 ## RichText
 - Rich-text display + editor primitive. Renders paragraphs, lists, headings, and inline formatting; contenteditable when editable= is set.
 - Different from <text-ui> (single semantic block) — richtext handles multi-paragraph + inline marks.
@@ -532,10 +564,14 @@
 - Compose multiple <skeleton-ui> blocks to mock the actual content shape (card-skeleton, row-skeleton, etc.).
 - For post-load empty states use <empty-state-ui> instead; skeleton is pre-load only.
 
+## SkipNav
+- Place as the FIRST focusable element on the page — inside <body> before any nav / shell chrome. Otherwise keyboard users still tab through the nav before hitting the skip link.
+- Target [#main] (or whatever id wraps the routed content). The target element should have tabindex="-1" so focus lands on it after the link is activated (otherwise focus may move to nothing perceptible).
+
 ## Slider
-- Single-handle slider for selecting one value in a range. Form-associated; emits numeric change events.
-- For two-handle range selection use <range-ui> instead.
-- Step attribute controls increments; show-value enables an inline value label.
+- Default mode is single-handle. Form-associated; emits numeric change events with detail.value.
+- For two-handle range selection (price filters, date ranges, audio range gates), set [dual] and use [lower-value]/[upper-value] instead of [value]. Form-data submits as "<lower>,<upper>" under [name]; change event detail carries {lower, upper}. Do NOT use <range-ui> — that primitive is a draggable numeric field, not a two-thumb range slider.
+- [step] controls increments for both single and dual modes. Constraint: in dual mode, [lower-value] ≤ [upper-value] is enforced on each setter; reversed values clamp to equal.
 
 ## 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>.
@@ -667,6 +703,12 @@
 - Typically posted into <feed-ui> via UIFeed.post(...); for inline persistent alerts use <alert-ui> instead.
 - Variant maps to severity (info, success, warn, error); same tokens as <alert-ui>.
 
+## TableOfContents
+- Use for in-page section navigation. Pair with a sticky container in an aside / right rail for the docs-site outline pattern.
+- Default scans the toc-ui's parent for h2/h3 headings. Set [target] to a CSS selector for a specific container; set [headings] to a comma-separated tag list (e.g. h1,h2,h3) for different depth coverage.
+- Headings missing an [id] receive an auto-generated slug from their text content. Existing ids are preserved.
+- Smooth-scroll on click is handled by the global `scroll-behavior: smooth` in resets.css (gated by prefers-reduced-motion). Do NOT add per-toc-ui smooth-scroll JS — the global wins.
+
 ## ToggleGroup
 - Multi-select button cluster — hosts <toggle-option-ui> children, each independently toggleable.
 - Different from <segmented-ui> (single-select) — toggle-group emits a SET of active values.
@@ -718,6 +760,10 @@
 - Multiple attribute enables multi-file selection; accept= constrains file types.
 - For agent chat attachments use <chat-composer-ui>'s built-in upload affordance instead.
 
+## VisuallyHidden
+- Wrap text that screen readers need but sighted users do not — icon-only-button labels, contextual disambiguation ("Edit profile" inside a row whose visible button just says "Edit").
+- Distinct from [hidden] / display:none (hides from EVERYONE) and from aria-label (replaces visible text). Use <visually-hidden-ui> when both visible AND invisible text need to coexist on the same element.
+
 ## BillingOverview
 - BillingOverview.account is REQUIRED. The composite is meaningless without an account snapshot; emitting BillingOverview with null account and no data-stream-src renders the empty state.
 - account.status MUST be one of `active` | `trialing` | `past_due` | `canceled` | `paused`. Unknown values render neutral chrome.