@exponential-at/ui 0.0.0-stage → 0.1.0

package/catalog/a11y.json

@@ -0,0 +1,668 @@
+{
+  "$comment": "Round 1 (docs/round-1-contract.md §6): the ACCESSIBILITY contract every renderer keeps. `roles` = the MACHINE-READABLE role vocabulary (ARIA names, plus `text` = static text and `hidden` = out of the accessibility tree; SwiftUI traits / Compose semantics / AccessKit roles map from them), used by every `role` here and by the expanded tree's `accessibility.role`. `components` = per component its `role` (one of `roles`: the role of the component's main accessible object), `notes` (prose: composite parts, states, which strings name it) and the KEYBOARD expectations, one line per key group (arrows flip in RTL; a roving tab stop = one Tab stop for the group, arrows move inside it). Every component is listed (round1.test.ts gates it). `commands` = what a HOST may ask of a surface at runtime. `rules` = what holds for every component. Round 2 (docs/round-2-contract.md): Resizable, `scrollToIndex`, sections, the per-node direction rule. Append-only; docs/components.generated.json carries each component's entry.",
+  "roles": [
+    "alert",
+    "alertdialog",
+    "banner",
+    "button",
+    "checkbox",
+    "combobox",
+    "dialog",
+    "document",
+    "form",
+    "group",
+    "heading",
+    "hidden",
+    "img",
+    "link",
+    "list",
+    "listitem",
+    "main",
+    "menu",
+    "meter",
+    "navigation",
+    "none",
+    "progressbar",
+    "radio",
+    "radiogroup",
+    "region",
+    "separator",
+    "slider",
+    "spinbutton",
+    "status",
+    "switch",
+    "tablist",
+    "table",
+    "text",
+    "textbox",
+    "tooltip",
+    "tree",
+    "treeitem"
+  ],
+  "rules": [
+    "Every interactive node is reachable by Tab in reading order (tree order; a node's resolved `direction` flips its rows) and shows a focus ring only for keyboard focus (`:focus-visible`, recipe state `focus`).",
+    "A field's label, description and every error are linked to it (aria-labelledby / aria-describedby, contentDescription, accessibilityLabel/Hint); an error has the id `<node id>.error`.",
+    "`visible: false` removes the node from the accessibility tree; `visibility: hidden` hides it too; `display: none` likewise.",
+    "Icon-only buttons and standalone Icons take their `label` (or `accessibility.label`) as the accessible name; decorative icons are hidden.",
+    "`accessibility.label`/`description` on any node override the computed name/description.",
+    "Animations honour reduced motion: with `prefers-reduced-motion: reduce` transitions run at 0 ms, the Spinner/Skeleton shimmer stops and every style `animation` shows its rest keyframe.",
+    "Text and accessible names follow the NODE's direction (an inner `direction` box included): reading order, `textAlign` start/end and the bidi paragraph direction."
+  ],
+  "commands": {
+    "focus": {
+      "args": [
+        "id"
+      ],
+      "description": "Moves keyboard focus to the node with this id (the first focusable descendant of a non-focusable node); ignored when it is not rendered."
+    },
+    "announce": {
+      "args": [
+        "text",
+        "live"
+      ],
+      "description": "Speaks the text through the platform's live region (`polite` waits, `assertive` interrupts) without showing anything."
+    },
+    "scrollIntoView": {
+      "args": [
+        "id"
+      ],
+      "description": "Scrolls the nearest scrolling ancestor (List, ScrollArea, the surface) so the node is visible."
+    },
+    "scrollToIndex": {
+      "args": [
+        "id",
+        "index",
+        "align"
+      ],
+      "description": "Scrolls the List or Table `id` so its item (data index, before any local sort) is in view: `align` start | center | end | nearest (default), the pinned section header subtracted; a windowed list renders it first (src/list.ts scrollOffsetForIndex)."
+    }
+  },
+  "components": {
+    "Box": {
+      "role": "none",
+      "notes": "group (button when pressable). A pressable Box is a button.",
+      "keys": [
+        "Enter, Space: press (pressable only)"
+      ]
+    },
+    "Stack": {
+      "role": "none",
+      "notes": "none (layout only)",
+      "keys": []
+    },
+    "Grid": {
+      "role": "none",
+      "notes": "none (layout only)",
+      "keys": []
+    },
+    "Card": {
+      "role": "group",
+      "notes": "group labelled by its title",
+      "keys": []
+    },
+    "Separator": {
+      "role": "separator",
+      "notes": "separator",
+      "keys": []
+    },
+    "ScrollArea": {
+      "role": "region",
+      "notes": "region (scrollable, focusable when it overflows)",
+      "keys": [
+        "Arrow keys, PageUp/PageDown, Home/End scroll while focused"
+      ]
+    },
+    "Section": {
+      "role": "group",
+      "notes": "group; the header a heading (level 3) with the caption and count in its name, or a button with aria-expanded when collapsible; the rows a list (a tree when `tree`) of listitems",
+      "keys": [
+        "Enter, Space: fold when collapsible"
+      ]
+    },
+    "Group": {
+      "role": "group",
+      "notes": "group labelled by its title, described by its footer",
+      "keys": []
+    },
+    "Heading": {
+      "role": "heading",
+      "notes": "heading (level from h1–h4)",
+      "keys": []
+    },
+    "Kbd": {
+      "role": "text",
+      "notes": "text (the shortcut spelled out)",
+      "keys": []
+    },
+    "Label": {
+      "role": "text",
+      "notes": "label of the control named by `for`",
+      "keys": [
+        "Pressing it focuses that control"
+      ]
+    },
+    "Badge": {
+      "role": "text",
+      "notes": "text (status)",
+      "keys": []
+    },
+    "Alert": {
+      "role": "alert",
+      "notes": "alert for warning/error, status otherwise. alert for warning/error, status otherwise ($a11y).",
+      "keys": []
+    },
+    "EmptyState": {
+      "role": "status",
+      "notes": "status; the action = button",
+      "keys": [
+        "Enter, Space on the action"
+      ]
+    },
+    "Progress": {
+      "role": "progressbar",
+      "notes": "progressbar (valuenow/valuemax, labelled by its label)",
+      "keys": []
+    },
+    "Meter": {
+      "role": "meter",
+      "notes": "meter (value of max, labelled by its label)",
+      "keys": []
+    },
+    "Sparkline": {
+      "role": "img",
+      "notes": "img with a generated summary (first, last, min, max). The Chart painter names it with `sparklineSummary` (first, last, min, max).",
+      "keys": []
+    },
+    "List": {
+      "role": "list",
+      "notes": "list; each item a listitem with its position in the WHOLE list (aria-setsize/posinset, also when windowed); a section header is a heading (level 3) and stays first in reading order while pinned",
+      "keys": [
+        "Tab moves through the rows' controls; the list itself is one scroll region"
+      ]
+    },
+    "Resizable": {
+      "role": "group",
+      "notes": "group; each handle a focusable separator (aria-orientation = the line's, valuenow = the size of the panel before it, valuemin/max = its limits, controls = that panel), named `$string.resize`",
+      "keys": [
+        "Arrow keys on a handle: move it on screen by 10 points (Left/Right horizontal, Up/Down vertical; rtl: ArrowRight shrinks the first panel)",
+        "Home / End: the panel before the handle to its min / max",
+        "Enter: collapse or reopen a collapsible panel"
+      ]
+    },
+    "Text": {
+      "role": "text",
+      "notes": "text (a live region when `live` is not off)",
+      "keys": []
+    },
+    "Markdown": {
+      "role": "document",
+      "notes": "document fragment (headings, lists, links, tables keep their roles)",
+      "keys": [
+        "Tab moves through the links"
+      ]
+    },
+    "CodeBlock": {
+      "role": "region",
+      "notes": "region (code), copy = button",
+      "keys": [
+        "Tab reaches the copy button; Enter, Space: copy and announce `copied`"
+      ]
+    },
+    "Image": {
+      "role": "img",
+      "notes": "img (alt = name; decorative when alt is empty)",
+      "keys": []
+    },
+    "Icon": {
+      "role": "img",
+      "notes": "img when labelled, hidden otherwise",
+      "keys": []
+    },
+    "Video": {
+      "role": "group",
+      "notes": "video with the platform's controls",
+      "keys": [
+        "Space: play/pause; ArrowLeft/ArrowRight: seek 5 s"
+      ]
+    },
+    "AudioPlayer": {
+      "role": "group",
+      "notes": "audio with the platform's controls",
+      "keys": [
+        "Space: play/pause; ArrowLeft/ArrowRight: seek 5 s"
+      ]
+    },
+    "Avatar": {
+      "role": "img",
+      "notes": "img (name)",
+      "keys": []
+    },
+    "Carousel": {
+      "role": "region",
+      "notes": "region, roledescription carousel; each page a group `page i of n`",
+      "keys": [
+        "ArrowLeft/ArrowRight: previous/next page while focus is inside",
+        "Home/End: first/last page"
+      ]
+    },
+    "Tabs": {
+      "role": "tablist",
+      "notes": "tablist / tab / tabpanel",
+      "keys": [
+        "Roving tab stop on the tabs",
+        "ArrowLeft/ArrowRight: previous/next tab, activating it (wraps)",
+        "Home/End: first/last tab",
+        "Tab: into the active panel",
+        "Each close glyph (labelled `closeTab`, revealed by keyboard focus too) is a button after its tab; the + button (labelled `newTab`) follows the last tab"
+      ]
+    },
+    "Segmented": {
+      "role": "radiogroup",
+      "notes": "radiogroup (single) or toolbar of toggle buttons (multiple); `bar` = navigation of buttons, the selected one aria-current=page",
+      "keys": [
+        "Roving tab stop",
+        "ArrowLeft/ArrowRight (ArrowUp/ArrowDown): move focus (wraps)",
+        "Home/End: first/last",
+        "Space, Enter: toggle the focused item"
+      ]
+    },
+    "Accordion": {
+      "role": "group",
+      "notes": "headers = buttons with aria-expanded controlling regions",
+      "keys": [
+        "Enter, Space: toggle the focused section",
+        "ArrowDown/ArrowUp: next/previous header",
+        "Home/End: first/last header"
+      ]
+    },
+    "Dialog": {
+      "role": "dialog",
+      "notes": "dialog (modal)",
+      "keys": [
+        "Opening moves focus to the first focusable child (else the dialog)",
+        "Tab cycles inside the dialog (focus trap)",
+        "Escape: close when dismissible",
+        "Closing returns focus to the trigger"
+      ]
+    },
+    "Drawer": {
+      "role": "dialog",
+      "notes": "dialog (modal)",
+      "keys": [
+        "As Dialog; a swipe toward the edge closes when dragToDismiss"
+      ]
+    },
+    "DockCard": {
+      "role": "button",
+      "notes": "trigger = button named `label: title` ($a11y); the sheet is a Drawer (dialog, modal).",
+      "keys": [
+        "Enter, Space: open the sheet",
+        "As Drawer once open"
+      ]
+    },
+    "Popover": {
+      "role": "dialog",
+      "notes": "dialog (non-modal)",
+      "keys": [
+        "Enter, Space on the trigger: open",
+        "Escape: close and return focus to the trigger",
+        "openOn hover also opens on trigger focus"
+      ]
+    },
+    "Tooltip": {
+      "role": "tooltip",
+      "notes": "tooltip describing its anchor",
+      "keys": [
+        "Shows on hover AND keyboard focus of the anchor (after the platform delay); Escape hides"
+      ]
+    },
+    "Menu": {
+      "role": "menu",
+      "notes": "menu / menuitem / menuitemcheckbox / group / separator; `openOn: contextmenu` opens at the pointer",
+      "keys": [
+        "Enter, Space, ArrowDown on the trigger: open on the first item; ArrowUp: open on the last",
+        "Shift+F10 or the Menu key on the focused child (contextmenu): open at the child",
+        "ArrowDown/ArrowUp: next/previous item (wraps, skips disabled)",
+        "Home/End: first/last item",
+        "Enter, Space: run the item (a checkbox item toggles and stays open)",
+        "ArrowRight on a submenu: open it; ArrowLeft or Escape inside: close it",
+        "A searchable submenu opens with its filter input focused: typing filters, ArrowDown/ArrowUp move the active row, Enter picks it, ArrowLeft with the caret at the start or Escape closes it",
+        "Escape: close and return focus to the trigger",
+        "Typing a letter: the next item starting with it"
+      ]
+    },
+    "Toast": {
+      "role": "status",
+      "notes": "status (polite); alert (assertive) for type error",
+      "keys": [
+        "Never takes focus on appear; Tab reaches its action and close",
+        "Escape on a focused toast: dismiss",
+        "Hover or focus pauses the duration timer"
+      ]
+    },
+    "Ring": {
+      "role": "progressbar",
+      "notes": "progressbar (value 0..1 as percent)",
+      "keys": []
+    },
+    "Spinner": {
+      "role": "progressbar",
+      "notes": "progressbar (indeterminate) labelled `loading` by default",
+      "keys": []
+    },
+    "Skeleton": {
+      "role": "hidden",
+      "notes": "hidden (the parent announces busy)",
+      "keys": []
+    },
+    "Table": {
+      "role": "table",
+      "notes": "table (grid when selectable): columnheader with aria-sort, row with aria-selected",
+      "keys": [
+        "Enter, Space on a sortable header: cycle the sort (asc, desc)",
+        "Space on a row checkbox: toggle the row; on the header checkbox: select all",
+        "Enter on a focused row: rowPress",
+        "Tab moves through headers, checkboxes and cell controls"
+      ]
+    },
+    "Chart": {
+      "role": "img",
+      "notes": "img with a generated summary (kind, series, ranges); a data table fallback for screen readers. The painter names it with `chartSummary` (series, min, max) and offers a data table fallback.",
+      "keys": [
+        "ArrowLeft/ArrowRight while focused: move the tooltip between categories"
+      ]
+    },
+    "Button": {
+      "role": "button",
+      "notes": "button (aria-busy while loading)",
+      "keys": [
+        "Enter, Space: press",
+        "A `submit` button submits the enclosing Form"
+      ]
+    },
+    "Link": {
+      "role": "link",
+      "notes": "link",
+      "keys": [
+        "Enter: open / press"
+      ]
+    },
+    "Toggle": {
+      "role": "button",
+      "notes": "button with aria-pressed",
+      "keys": [
+        "Enter, Space: toggle"
+      ]
+    },
+    "Form": {
+      "role": "form",
+      "notes": "form",
+      "keys": [
+        "Enter in a single-line field: submit",
+        "A failed submit focuses the first invalid field and announces `invalidFields`"
+      ]
+    },
+    "Input": {
+      "role": "textbox",
+      "notes": "textbox",
+      "keys": [
+        "Enter: submit (fires `submit`, submits the Form)"
+      ]
+    },
+    "Textarea": {
+      "role": "textbox",
+      "notes": "textbox (multiline)",
+      "keys": [
+        "Enter: newline"
+      ]
+    },
+    "NumberField": {
+      "role": "spinbutton",
+      "notes": "spinbutton (valuemin/valuemax/valuenow)",
+      "keys": [
+        "ArrowUp/ArrowDown: ± step (Shift: ×10)",
+        "PageUp/PageDown: ± 10 steps",
+        "Home/End: min/max",
+        "Enter or blur: commit and clamp"
+      ]
+    },
+    "Checkbox": {
+      "role": "checkbox",
+      "notes": "checkbox",
+      "keys": [
+        "Space: toggle"
+      ]
+    },
+    "Radio": {
+      "role": "radiogroup",
+      "notes": "radiogroup / radio",
+      "keys": [
+        "Roving tab stop on the checked option",
+        "ArrowDown/ArrowRight: next option, selecting it (wraps)",
+        "ArrowUp/ArrowLeft: previous option"
+      ]
+    },
+    "ChoiceTiles": {
+      "role": "radiogroup",
+      "notes": "radiogroup of radio tiles (single) or a group of checkbox tiles (multiple); the picture is decorative, the label names the tile",
+      "keys": [
+        "Roving tab stop on the picked tile (the first when none)",
+        "ArrowRight/ArrowLeft, ArrowDown/ArrowUp: move focus (wraps); single: picks",
+        "Space, Enter: toggle the focused tile"
+      ]
+    },
+    "Switch": {
+      "role": "switch",
+      "notes": "switch; the label (and description) first, the switch at the end; the whole row toggles",
+      "keys": [
+        "Space, Enter: toggle"
+      ]
+    },
+    "Slider": {
+      "role": "slider",
+      "notes": "slider",
+      "keys": [
+        "ArrowRight/ArrowUp: + step; ArrowLeft/ArrowDown: - step",
+        "PageUp/PageDown: ± 10 steps",
+        "Home/End: min/max"
+      ]
+    },
+    "Select": {
+      "role": "combobox",
+      "notes": "combobox + listbox / option",
+      "keys": [
+        "Enter, Space, ArrowDown: open on the selected option",
+        "ArrowDown/ArrowUp: move the active option; Home/End: first/last",
+        "Enter: choose (multiple: toggle and stay open)",
+        "Escape: close without change",
+        "Typing: jump to the next matching option; with `searchable`, typing filters, focus stays in the search field and arrows move the active option (aria-activedescendant)"
+      ]
+    },
+    "SearchList": {
+      "role": "combobox",
+      "notes": "combobox (the input) controlling a listbox of options; the highlighted row = aria-activedescendant, the count a polite status",
+      "keys": [
+        "Focus stays in the input",
+        "ArrowDown/ArrowUp: move the highlighted row (no wrap, no animation)",
+        "Enter or Tab: pick the highlighted row (fires `select`)",
+        "Typing: filters; the top row is highlighted again"
+      ]
+    },
+    "ChipInput": {
+      "role": "textbox",
+      "notes": "textbox with a list of removable chips",
+      "keys": [
+        "Enter or comma: add the typed entry",
+        "Backspace in an empty field: focus the last chip, again: remove it",
+        "ArrowLeft/ArrowRight: move between chips; Delete, Backspace: remove the focused chip",
+        "ArrowDown: open the suggestions (as Select)"
+      ]
+    },
+    "DatePicker": {
+      "role": "combobox",
+      "notes": "combobox opening a dialog with a grid of days",
+      "keys": [
+        "Enter, Space, ArrowDown: open on the selected (else today's) day",
+        "Arrow keys: ± 1 day / ± 1 week",
+        "PageUp/PageDown: previous/next month (Shift: year)",
+        "Home/End: start/end of the week (locale week start)",
+        "Enter, Space: choose; Escape: close"
+      ]
+    },
+    "DateRangePicker": {
+      "role": "combobox",
+      "notes": "as DatePicker; the second choice ends the range",
+      "keys": [
+        "As DatePicker; the first Enter sets the start, the second the end"
+      ]
+    },
+    "TimePicker": {
+      "role": "combobox",
+      "notes": "combobox + listbox",
+      "keys": [
+        "As Select; typing `HH:mm` into the field commits on Enter or blur"
+      ]
+    },
+    "FileUpload": {
+      "role": "button",
+      "notes": "button (the drop zone) + a list of files with remove buttons",
+      "keys": [
+        "Enter, Space on the drop zone: open the file picker",
+        "Tab reaches each file's remove button"
+      ]
+    },
+    "Composer": {
+      "role": "textbox",
+      "notes": "textbox (multiline) + send button",
+      "keys": [
+        "Enter: submit; Shift+Enter: newline",
+        "Escape while busy: stop"
+      ]
+    },
+    "TreeGuides": {
+      "role": "hidden",
+      "notes": "hidden (decorative; a Row part)",
+      "keys": []
+    },
+    "Unknown": {
+      "role": "group",
+      "notes": "group labelled `unknownComponent`",
+      "keys": []
+    },
+    "Collapsible": {
+      "role": "group",
+      "notes": "trigger = button with aria-expanded. The trigger is a button with aria-expanded = open ($a11y).",
+      "keys": [
+        "Enter, Space: toggle"
+      ]
+    },
+    "Pagination": {
+      "role": "navigation",
+      "notes": "navigation of two buttons and a status. Labelled `pagination`; previous/next buttons and a status labelled `pageOf` ($a11y).",
+      "keys": [
+        "Enter, Space on previous/next"
+      ]
+    },
+    "Breadcrumb": {
+      "role": "navigation",
+      "notes": "navigation (breadcrumb); the last item aria-current=page. Labelled `breadcrumb`; the last item aria-current=page ($a11y).",
+      "keys": [
+        "Tab through the links; Enter: select"
+      ]
+    },
+    "Stepper": {
+      "role": "list",
+      "notes": "list; the current step aria-current=step. Each step a listitem labelled `stepDone`/`stepCurrent`/`stepUpcoming`; the current one aria-current=step ($a11y).",
+      "keys": []
+    },
+    "Rating": {
+      "role": "group",
+      "notes": "A group of star buttons: each labelled `ratingStar` (\"3 of 5\"), the chosen one aria-pressed; read-only stars leave the tree and the group is an img labelled `ratingValue` ($a11y).",
+      "keys": [
+        "Tab through the stars; Enter, Space: rate"
+      ]
+    },
+    "AlertDialog": {
+      "role": "alertdialog",
+      "notes": "alertdialog. The cancel button takes focus on open (`autoFocus`, $a11y).",
+      "keys": [
+        "Opening focuses the cancel button",
+        "Escape: cancel; clicks outside are ignored"
+      ]
+    },
+    "Sidebar": {
+      "role": "none",
+      "notes": "navigation landmark (the sidebar slot) beside main. Layout only; its `sidebar` part is a navigation landmark, its `main` part the main landmark ($a11y).",
+      "keys": []
+    },
+    "AppBar": {
+      "role": "banner",
+      "notes": "banner (heading level 1 = the title). The title is heading level 1; the back button is labelled `back` ($a11y).",
+      "keys": [
+        "Enter, Space on back"
+      ]
+    },
+    "Row": {
+      "role": "button",
+      "notes": "button (aria-selected when selected) when pressable, a group of its texts otherwise ($a11y); the guides are decorative",
+      "keys": [
+        "Enter, Space: press (pressable only)"
+      ]
+    },
+    "Trace": {
+      "role": "none",
+      "notes": "Layout only: a column of TraceItem lines.",
+      "keys": []
+    },
+    "TraceItem": {
+      "role": "group",
+      "notes": "A collapsible line is a button with aria-expanded = open ($a11y); a plain line is text; the icon is decorative.",
+      "keys": [
+        "Enter, Space: toggle (collapsible only)"
+      ]
+    },
+    "Chip": {
+      "role": "button",
+      "notes": "button with aria-pressed (= selected) when pressable, text otherwise ($a11y); remove = button labelled `remove`",
+      "keys": [
+        "Enter, Space: press; Delete, Backspace: remove when removable"
+      ]
+    },
+    "Page": {
+      "role": "none",
+      "notes": "Layout only: its header is the AppBar (banner, the title heading level 1), its body the main landmark ($a11y).",
+      "keys": [
+        "Enter, Space on back"
+      ]
+    },
+    "Toolbar": {
+      "role": "group",
+      "notes": "group of controls in reading order; the trailing action last",
+      "keys": []
+    },
+    "SplitView": {
+      "role": "none",
+      "notes": "Layout only: the `list` part is a navigation landmark, the `detail` part the main landmark; the phone back button is labelled `back` ($a11y).",
+      "keys": [
+        "Enter, Space on back"
+      ]
+    },
+    "FieldGroup": {
+      "role": "group",
+      "notes": "group of fields; each field keeps its own label",
+      "keys": []
+    },
+    "FormActions": {
+      "role": "group",
+      "notes": "group: Cancel, then the submit (the last in focus order)",
+      "keys": [
+        "Enter, Space on a button"
+      ]
+    },
+    "StatTile": {
+      "role": "group",
+      "notes": "group labelled by its label; the sparkline is an img with the generated summary",
+      "keys": []
+    }
+  }
+}