@slotted/react 0.0.0-stage → 0.1.0-beta.0

package/dist/docs/listbox.json

@@ -0,0 +1,811 @@
+{
+  "family": "listbox",
+  "ui": "listbox",
+  "binding": "react",
+  "catalog": {
+    "group": "Forms",
+    "summary": "List of options for single or multiple choice."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "plain",
+      "framed"
+    ],
+    "selectionMode": [
+      "none",
+      "single",
+      "multiple"
+    ],
+    "selectionBehavior": [
+      "toggle",
+      "replace"
+    ],
+    "orientation": [
+      "vertical",
+      "horizontal"
+    ],
+    "focusMode": [
+      "auto",
+      "roving",
+      "activedescendant"
+    ],
+    "indicator": [
+      "check",
+      "none"
+    ],
+    "loop": [
+      true,
+      false
+    ],
+    "typeahead": [
+      true,
+      false
+    ],
+    "selectOnFocus": [
+      true,
+      false
+    ],
+    "navigateDisabled": [
+      true,
+      false
+    ],
+    "disallowEmptySelection": [
+      true,
+      false
+    ],
+    "disallowSelectAll": [
+      true,
+      false
+    ],
+    "virtual": [
+      true,
+      false
+    ],
+    "disabled": [
+      true,
+      false
+    ]
+  },
+  "members": {
+    "listbox": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "md",
+        "variant": "framed",
+        "selectionMode": "single",
+        "selectionBehavior": "toggle",
+        "orientation": "vertical",
+        "focusMode": "auto",
+        "indicator": "check",
+        "loop": false,
+        "typeahead": true,
+        "selectOnFocus": false,
+        "navigateDisabled": false,
+        "disallowEmptySelection": false,
+        "disallowSelectAll": false,
+        "virtual": false,
+        "disabled": false,
+        "loading": false,
+        "hasMore": false,
+        "rows": 7,
+        "columns": 1,
+        "itemSize": 36,
+        "sectionSize": 28,
+        "overscan": 4,
+        "loadMoreThreshold": 0,
+        "typeaheadTimeout": 500,
+        "pageSize": 10
+      },
+      "capabilities": [
+        "selection",
+        "current",
+        "virtualization",
+        "appearance",
+        "size",
+        "orientation",
+        "arrangement",
+        "disabled",
+        "loading",
+        "readOnly",
+        "required",
+        "invalid",
+        "content",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "selected",
+        "current",
+        "disabled",
+        "loading",
+        "readonly",
+        "invalid",
+        "required"
+      ],
+      "parts": [
+        "root",
+        "canvas",
+        "group",
+        "group-label",
+        "option",
+        "indicator",
+        "icon",
+        "label",
+        "description",
+        "meta",
+        "empty",
+        "loader"
+      ]
+    }
+  },
+  "docs": {
+    "listbox": {
+      "imports": {
+        "source": "import {\n  Listbox,\n  ListboxDefaultsProvider,\n  ListboxDescription,\n  ListboxEmpty,\n  ListboxGroup,\n  ListboxIcon,\n  ListboxIndicator,\n  ListboxLabel,\n  ListboxLoader,\n  ListboxMeta,\n  ListboxOption,\n} from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "required": true,
+          "purpose": "The listbox itself, not a wrapper around one. It carries role=\"listbox\", data-ui=\"listbox\" and every axis, it is the scroll container, and it is the one tab stop the whole set has."
+        },
+        {
+          "part": "canvas",
+          "element": "div with role=\"presentation\"",
+          "required": false,
+          "purpose": "Only while the set is windowed. It holds the whole list block size so the scrollbar is the length of the data, and starts the rendered slice at the offset the engine returned. The role is what keeps the options owned by the listbox."
+        },
+        {
+          "part": "group",
+          "element": "div with role=\"group\"",
+          "required": false,
+          "purpose": "A run of options with a name. The pattern requires the name, so the group carries aria-labelledby to its own label, or aria-label when the label row is scrolled out of a window."
+        },
+        {
+          "part": "group-label",
+          "element": "div",
+          "required": false,
+          "purpose": "The group name a reader hears when they land inside it."
+        },
+        {
+          "part": "option",
+          "element": "div with role=\"option\"",
+          "required": true,
+          "purpose": "One choice. It carries data-key, aria-selected, data-selected, data-current and, when the collection is one the family was handed, aria-setsize and aria-posinset."
+        },
+        {
+          "part": "indicator",
+          "element": "span",
+          "required": false,
+          "purpose": "The mark that says an option is chosen, drawn from the glyph scale. Its column is reserved whether or not the mark is painted, so the list does not shift sideways as one option is chosen."
+        },
+        {
+          "part": "icon",
+          "element": "span",
+          "required": false,
+          "purpose": "The option own artwork, in the same column the mark uses and never beside it: an Icon holding a Glyph, or an element of the page own. No stylesheet fills it."
+        },
+        {
+          "part": "label",
+          "element": "span",
+          "required": true,
+          "purpose": "The option primary text, and the only one of the three columns that gives way."
+        },
+        {
+          "part": "description",
+          "element": "span",
+          "required": false,
+          "purpose": "A second line under the label, for what the label cannot say on its own."
+        },
+        {
+          "part": "meta",
+          "element": "span",
+          "required": false,
+          "purpose": "The value beside the name — a count, a price, a status word. Menu calls the same column shortcut, because a menu third column holds a key binding."
+        },
+        {
+          "part": "empty",
+          "element": "div",
+          "required": false,
+          "purpose": "What the listbox says when it holds nothing. Inside the listbox, so a reader hears the message rather than \"listbox, zero items\" and then silence."
+        },
+        {
+          "part": "loader",
+          "element": "div with role=\"option\"",
+          "required": false,
+          "purpose": "The row at the end of a page that has not arrived. It is an option by role because a listbox owns nothing else, and disabled because it is not a choice."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "string | readonly string[] | null, or string",
+          "defaultValue": "—",
+          "appliesTo": "Listbox, ListboxOption",
+          "description": "On the listbox: the chosen key, or the set of them; present means controlled, for the life of the component. On an option: the key it chooses, which is what the listbox value holds"
+        },
+        {
+          "name": "defaultValue",
+          "type": "string | readonly string[] | null",
+          "defaultValue": "—",
+          "appliesTo": "Listbox",
+          "description": "What an uncontrolled listbox starts from, read once"
+        },
+        {
+          "name": "activeKey",
+          "type": "string | null",
+          "defaultValue": "—",
+          "appliesTo": "Listbox",
+          "description": "Which option the keyboard is on. Present means controlled"
+        },
+        {
+          "name": "defaultActiveKey",
+          "type": "string | null",
+          "defaultValue": "—",
+          "appliesTo": "Listbox",
+          "description": "Where the keyboard starts, read once"
+        },
+        {
+          "name": "selectionMode",
+          "type": "'none' | 'single' | 'multiple'",
+          "defaultValue": "single",
+          "appliesTo": "Listbox",
+          "description": "How many options may be chosen. multiple writes aria-multiselectable"
+        },
+        {
+          "name": "selectionBehavior",
+          "type": "'toggle' | 'replace'",
+          "defaultValue": "toggle",
+          "appliesTo": "Listbox",
+          "description": "toggle is the model the pattern recommends; replace is the desktop one, where a plain press replaces"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "Listbox",
+          "description": "The type and control geometry step. Defaults to the Field around it before the provider"
+        },
+        {
+          "name": "variant",
+          "type": "'plain' | 'framed'",
+          "defaultValue": "framed",
+          "appliesTo": "Listbox",
+          "description": "framed is the standalone control; plain is what a layer already frames"
+        },
+        {
+          "name": "orientation",
+          "type": "'vertical' | 'horizontal'",
+          "defaultValue": "vertical",
+          "appliesTo": "Listbox",
+          "description": "Which axis the arrows move along. horizontal is mirrored in a right-to-left document"
+        },
+        {
+          "name": "focusMode",
+          "type": "'auto' | 'roving' | 'activedescendant'",
+          "defaultValue": "auto",
+          "appliesTo": "Listbox",
+          "description": "auto answers activedescendant whenever the set is windowed, because a roving tab stop cannot survive a recycled row"
+        },
+        {
+          "name": "indicator",
+          "type": "'check' | 'none'",
+          "defaultValue": "check",
+          "appliesTo": "Listbox",
+          "description": "Whether a chosen option draws a mark as well as its ground and its ink"
+        },
+        {
+          "name": "loop",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Listbox",
+          "description": "Whether the arrows wrap past the ends"
+        },
+        {
+          "name": "typeahead",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Listbox",
+          "description": "Whether printable characters move the highlight"
+        },
+        {
+          "name": "typeaheadTimeout",
+          "type": "number",
+          "defaultValue": "500",
+          "appliesTo": "Listbox",
+          "description": "Milliseconds of silence before a new typeahead sequence begins"
+        },
+        {
+          "name": "selectOnFocus",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Listbox",
+          "description": "Whether moving the highlight also chooses. The pattern names the accessibility cost, so the default is the safe one"
+        },
+        {
+          "name": "navigateDisabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Listbox",
+          "description": "Whether the arrows land on a disabled option, which the pattern allows where discoverability matters"
+        },
+        {
+          "name": "disallowEmptySelection",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Listbox",
+          "description": "Refuses the press that would leave nothing chosen"
+        },
+        {
+          "name": "disallowSelectAll",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Listbox",
+          "description": "Refuses the select-all accelerator"
+        },
+        {
+          "name": "rows",
+          "type": "number",
+          "defaultValue": "7",
+          "appliesTo": "Listbox",
+          "description": "How many options tall the box is before it scrolls. <select size> under another name"
+        },
+        {
+          "name": "columns",
+          "type": "number",
+          "defaultValue": "1",
+          "appliesTo": "Listbox",
+          "description": "How many options across. The arrows step by this number down a column"
+        },
+        {
+          "name": "pageSize",
+          "type": "number",
+          "defaultValue": "10",
+          "appliesTo": "Listbox",
+          "description": "How far PageUp and PageDown travel"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Listbox, ListboxOption",
+          "description": "On the listbox, unstated it defers to the Field and stated it wins, and every option inherits it. On an option it is aria-disabled and never the native attribute, so the option keeps its place in the set"
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Listbox",
+          "description": "Every option stays reachable and every change is refused. Writes aria-readonly"
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Listbox",
+          "description": "Writes aria-required. The Field owns the message"
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Listbox",
+          "description": "Writes aria-invalid and turns the edge and the ring"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Listbox",
+          "description": "Writes aria-busy, which ARIA asks of a container whose options have not arrived"
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "Listbox",
+          "description": "Submits one hidden input per chosen key, so a bare form carries the set"
+        },
+        {
+          "name": "items",
+          "type": "readonly T[]",
+          "defaultValue": "—",
+          "appliesTo": "Listbox",
+          "description": "The whole collection. Without it the collection is read from the rendered options"
+        },
+        {
+          "name": "sections",
+          "type": "readonly ListboxSection<T>[]",
+          "defaultValue": "—",
+          "appliesTo": "Listbox",
+          "description": "A grouped collection. Mutually exclusive with items"
+        },
+        {
+          "name": "getKey",
+          "type": "(item: T) => string",
+          "defaultValue": "—",
+          "appliesTo": "Listbox",
+          "description": "The identity that survives a reorder. It is a string, so no comparator is needed"
+        },
+        {
+          "name": "getLabel",
+          "type": "(item: T) => string",
+          "defaultValue": "—",
+          "appliesTo": "Listbox",
+          "description": "What typeahead matches and what a reader hears"
+        },
+        {
+          "name": "isItemDisabled",
+          "type": "(item: T) => boolean",
+          "defaultValue": "—",
+          "appliesTo": "Listbox",
+          "description": "Whether one item refuses to be chosen"
+        },
+        {
+          "name": "renderOption",
+          "type": "(item: T) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Listbox",
+          "description": "The content of one option. The family renders the option around it"
+        },
+        {
+          "name": "totalCount",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "Listbox",
+          "description": "How large the whole set is when only part of it has loaded. Writes aria-setsize"
+        },
+        {
+          "name": "virtual",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Listbox",
+          "description": "Renders only the options the viewport covers, plus the pinned ones"
+        },
+        {
+          "name": "itemSize",
+          "type": "number",
+          "defaultValue": "36",
+          "appliesTo": "Listbox",
+          "description": "The block size of one option. Required whenever virtual is set"
+        },
+        {
+          "name": "sectionSize",
+          "type": "number",
+          "defaultValue": "28",
+          "appliesTo": "Listbox",
+          "description": "The block size of a group label row. Defaults to itemSize"
+        },
+        {
+          "name": "overscan",
+          "type": "number",
+          "defaultValue": "4",
+          "appliesTo": "Listbox",
+          "description": "Options rendered either side of the viewport"
+        },
+        {
+          "name": "hasMore",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Listbox",
+          "description": "Whether the consumer has another page to give"
+        },
+        {
+          "name": "loadMoreThreshold",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "Listbox",
+          "description": "How many options before the end the request goes out"
+        },
+        {
+          "name": "emptyContent",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Listbox",
+          "description": "What a handed collection shows when it holds nothing"
+        },
+        {
+          "name": "loaderContent",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Listbox",
+          "description": "What the row at the end of an unfinished page says"
+        },
+        {
+          "name": "textValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "ListboxOption",
+          "description": "What typeahead matches, when the visible text is not it"
+        },
+        {
+          "name": "label",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "ListboxGroup",
+          "description": "The group accessible name, which the pattern requires of every group"
+        }
+      ],
+      "composition": [
+        {
+          "name": "ListboxDefaultsProvider",
+          "type": "{ size, variant, selectionMode, … }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "Sets nineteen axes once for every listbox under it. An explicit prop still wins"
+        },
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Listbox, ListboxOption, ListboxGroup, ListboxEmpty, ListboxLoader",
+          "description": "Renders the part into another element, keeping every attribute and handler it was given"
+        },
+        {
+          "name": "handleRef",
+          "type": "Ref<ListboxHandle>",
+          "defaultValue": "—",
+          "appliesTo": "Listbox",
+          "description": "focus(), scrollToKey(key, align) and getActiveKey() — the three actions no prop can express"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Reaches the native element; each part extends its own element props"
+        },
+        {
+          "name": "aria-label / aria-labelledby",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "Listbox",
+          "description": "The listbox own name. The pattern requires one when it is not part of another widget"
+        },
+        {
+          "name": "onKeyDown / onFocus / onBlur / onClick",
+          "type": "handler",
+          "defaultValue": "—",
+          "appliesTo": "Listbox, ListboxOption",
+          "description": "Runs before the family own, and preventDefault() stops the family from answering"
+        }
+      ],
+      "events": [
+        {
+          "name": "onValueChange",
+          "payload": "(value: string | readonly string[] | null, request: ChangeRequest)",
+          "when": "Before the selection moves. The value is one key in single and none, and the set in multiple. The request carries the value it replaces, the reason — pointer, keyboard, select, clear or programmatic — the originating event, and cancel()."
+        },
+        {
+          "name": "onActiveKeyChange",
+          "payload": "(key: string | null, request: ChangeRequest)",
+          "when": "Before the option the keyboard is on moves. Reasons: pointer, keyboard, programmatic. It is a value of its own, because the pattern makes focus and selection two things."
+        },
+        {
+          "name": "onLoadMore",
+          "payload": "()",
+          "when": "Once the rendered window has come within loadMoreThreshold options of the end of what has been loaded, and only while hasMore is true and loading is false."
+        }
+      ],
+      "accessibility": [
+        "The pattern is https://www.w3.org/WAI/ARIA/apg/patterns/listbox/, read on 4 September 2026 from the rendered page and from the pattern source in w3c/aria-practices, so the optional keys and both selection models come from the source rather than from the summary. The root carries role=\"listbox\", every option carries role=\"option\", and a group carries role=\"group\" with the accessible name the pattern requires of it.",
+        "Selection is aria-selected on every selectable option, true or false and never absent, and aria-checked on none of them: the pattern forbids a listbox that carries both. A chosen option says so three ways — a tinted ground, a start-edge bar and a mark — because under forced colours the ground becomes Canvas and a family that spoke only in colour would say nothing in the mode that needs it most.",
+        "There is one tab stop for the whole set. Under the roving model it lives on the active option, and under aria-activedescendant it lives on the root; focusMode=\"auto\" chooses the second whenever the set is windowed, because an element carrying tabindex=\"0\" that is recycled out of the DOM takes focus to the body with it. The active option is pinned into the rendered window for the same reason: a property naming an id that is not in the document leaves a reader operating a widget with no focused option.",
+        "aria-setsize and aria-posinset are written on every option of a collection the family was handed and on none written as children. That is the pattern condition — the pair is required when the complete set is not in the DOM — and with children the whole set is in the DOM and the platform counts it.",
+        "A disabled option carries aria-disabled rather than the native attribute, so it keeps its place in the set and can still be reached when navigateDisabled says discoverability matters more. readonly keeps every option reachable and refuses every change; disabled outranks selected, so a chosen option that is disabled keeps its mark and loses the ground that said it was yours to change.",
+        "Keyboard: Tab in and out, arrows along the axis, Home and End, PageUp and PageDown, Space and Enter to choose, Shift with an arrow to move and toggle, Shift+Space for a range, Control+Shift+Home or End to select to an end, Control+A to select everything and again to clear, Control with an arrow to move without choosing under the alternative model, and printable characters for typeahead — where a space is a character once a sequence is open, which is what makes an option named in two words reachable."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-control-border-color",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-gap-lg",
+    "--slotted-control-gap-md",
+    "--slotted-control-gap-sm",
+    "--slotted-control-height-lg",
+    "--slotted-control-height-md",
+    "--slotted-control-height-sm",
+    "--slotted-control-icon-size-lg",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-control-invalid-edge-width",
+    "--slotted-control-padding-inline-lg",
+    "--slotted-control-padding-inline-md",
+    "--slotted-control-padding-inline-sm",
+    "--slotted-control-radius",
+    "--slotted-control-shadow",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-background",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-loop",
+    "--slotted-duration-short",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-color-invalid",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-family-sans",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-semibold",
+    "--slotted-line-height-md",
+    "--slotted-line-height-sm",
+    "--slotted-listbox-border-color",
+    "--slotted-listbox-columns",
+    "--slotted-listbox-group-border-color",
+    "--slotted-listbox-highlight",
+    "--slotted-listbox-highlight-active",
+    "--slotted-listbox-measure",
+    "--slotted-listbox-option-radius",
+    "--slotted-listbox-padding-block",
+    "--slotted-listbox-padding-inline",
+    "--slotted-listbox-radius",
+    "--slotted-listbox-rows",
+    "--slotted-listbox-selected-surface",
+    "--slotted-listbox-selected-text",
+    "--slotted-listbox-shadow",
+    "--slotted-listbox-surface",
+    "--slotted-listbox-text",
+    "--slotted-listbox-text-muted",
+    "--slotted-radius-md",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-space-5",
+    "--slotted-space-6",
+    "--slotted-surface",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-subtle-active",
+    "--slotted-tone-accent-subtle-hover",
+    "--slotted-tone-accent-surface",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One listbox with every axis on it, driven by the controls under the canvas. Arrow through it, hold Shift, and watch the ring and the bar say two different things.",
+      "language": "tsx",
+      "source": "<Listbox aria-label=\"Region\" defaultValue=\"europe\">\n  {regions.map((region) => (\n    <ListboxOption key={region.id} value={region.id}>\n      <ListboxIndicator />\n      <ListboxLabel>{region.name}</ListboxLabel>\n      <ListboxMeta>{region.count}</ListboxMeta>\n    </ListboxOption>\n  ))}\n</Listbox>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "selection",
+      "title": "One choice, several, or none",
+      "note": "Three listboxes side by side. The multi-select one writes aria-multiselectable; the read-only one refuses every change and still lets the arrows through.",
+      "language": "tsx",
+      "source": "<Listbox aria-label=\"Contents\" selectionMode=\"multiple\" defaultValue={['cheese']}>\n  {fillings.map((filling) => (\n    <ListboxOption key={filling} value={filling}>\n      <ListboxIndicator />\n      <ListboxLabel>{filling}</ListboxLabel>\n    </ListboxOption>\n  ))}\n</Listbox>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "behavior",
+      "title": "Both of the selection models the pattern offers",
+      "note": "The recommended model needs no modifier; the alternative replaces on a plain press and extends with Control. Press one, then Control-press another, in each.",
+      "language": "tsx",
+      "source": "<Listbox\n  aria-label=\"Files\"\n  selectionMode=\"multiple\"\n  selectionBehavior=\"replace\"\n  defaultValue={['budget.xlsx']}\n>\n  {files.map((file) => (\n    <ListboxOption key={file} value={file}>\n      <ListboxLabel>{file}</ListboxLabel>\n    </ListboxOption>\n  ))}\n</Listbox>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sections",
+      "title": "Groups, and the name each one needs",
+      "note": "Every group carries an accessible name, which the pattern requires of it. Land inside one with the arrows and a screen reader says which group you are in.",
+      "language": "tsx",
+      "source": "<Listbox aria-label=\"Fruit\">\n  <ListboxGroup label=\"Pome\">\n    <ListboxOption value=\"apple\">\n      <ListboxIndicator />\n      <ListboxLabel>Apple</ListboxLabel>\n    </ListboxOption>\n  </ListboxGroup>\n</Listbox>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "size",
+      "title": "Three steps of type and control geometry",
+      "note": "An option is a control, so its height, inset, type and glyph all read the control scale. Switch the density in the toolbar and the meaning does not change with the size.",
+      "language": "tsx",
+      "source": "<Listbox aria-label=\"Plan\" size=\"lg\">\n  {plans.map((plan) => (\n    <ListboxOption key={plan.id} value={plan.id}>\n      <ListboxLabel>{plan.name}</ListboxLabel>\n      <ListboxMeta>{plan.price}</ListboxMeta>\n    </ListboxOption>\n  ))}\n</Listbox>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variant",
+      "title": "A control on its own, or a list inside a layer",
+      "note": "framed draws the edge, the ground and the shadow a standalone control needs; plain draws none of them, because the layer around it already has an edge.",
+      "language": "tsx",
+      "source": "<Listbox aria-label=\"Sort by\" variant=\"plain\" indicator=\"check\">\n  {orders.map((order) => (\n    <ListboxOption key={order} value={order}>\n      <ListboxIndicator />\n      <ListboxLabel>{order}</ListboxLabel>\n    </ListboxOption>\n  ))}\n</Listbox>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "layout",
+      "title": "Two dimensions, and one along the inline axis",
+      "note": "With columns the arrows step by one across and by columns down; horizontal turns the axes and mirrors them in a right-to-left document.",
+      "language": "tsx",
+      "source": "<Listbox aria-label=\"Planets\" columns={3} selectionMode=\"multiple\">\n  {planets.map((planet) => (\n    <ListboxOption key={planet} value={planet}>\n      <ListboxIndicator />\n      <ListboxLabel>{planet}</ListboxLabel>\n    </ListboxOption>\n  ))}\n</Listbox>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Every state the contract declares",
+      "note": "Disabled outranks selected, so a chosen option that is disabled keeps its mark and loses its ground. Read-only keeps every option reachable and refuses each change.",
+      "language": "tsx",
+      "source": "<Listbox aria-label=\"Region\" defaultValue=\"europe\">\n  <ListboxOption value=\"europe\">\n    <ListboxIndicator />\n    <ListboxLabel>Europe</ListboxLabel>\n  </ListboxOption>\n  <ListboxOption value=\"antarctica\" disabled>\n    <ListboxIndicator />\n    <ListboxLabel>Antarctica</ListboxLabel>\n  </ListboxOption>\n</Listbox>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "typeahead",
+      "title": "Typing at a long list",
+      "note": "Type the first letters of an option and the highlight goes there; the same letter pressed again cycles through the options beginning with it. Space mid-sequence is a character.",
+      "language": "tsx",
+      "source": "<Listbox aria-label=\"Airports\">\n  {airports.map((airport) => (\n    <ListboxOption key={airport.iata} value={airport.iata} textValue={airport.city}>\n      <ListboxLabel>{airport.city}</ListboxLabel>\n      <ListboxMeta>{airport.iata}</ListboxMeta>\n    </ListboxOption>\n  ))}\n</Listbox>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "empty-and-loading",
+      "title": "Nothing yet, and nothing at all",
+      "note": "The message lives inside the listbox: outside it a reader hears \"listbox, zero items\" and then silence, and the words fall outside the box a framed listbox paints.",
+      "language": "tsx",
+      "source": "<Listbox aria-label=\"Results\" items={matches} getKey={(match) => match.id}>\n  <ListboxEmpty>No region matches that name.</ListboxEmpty>\n</Listbox>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "virtualization",
+      "title": "Ten thousand options, and the ones that are rendered",
+      "note": "Scroll it, then arrow through it: the highlight survives a recycled row, because the active option is pinned and the listbox names it rather than roving a tab stop onto it.",
+      "language": "tsx",
+      "source": "<Listbox\n  aria-label=\"Cities\"\n  virtual\n  itemSize={34}\n  items={cities}\n  getKey={(city) => city.id}\n  getLabel={(city) => city.name}\n  renderOption={(city) => (\n    <>\n      <ListboxIndicator />\n      <ListboxLabel>{city.name}</ListboxLabel>\n      <ListboxMeta>{city.country}</ListboxMeta>\n    </>\n  )}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A label long enough to wrap onto three lines, an unbroken URL, a compound German noun and a right-to-left string. The mark stays on the first line and the value never moves.",
+      "language": "tsx",
+      "source": "<ListboxOption value=\"asia-pacific\">\n  <ListboxIndicator />\n  <ListboxLabel>Asia Pacific</ListboxLabel>\n  <ListboxDescription>Sydney, Tokyo, Singapore</ListboxDescription>\n  <ListboxMeta>28</ListboxMeta>\n</ListboxOption>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "forms",
+      "title": "A choice a form carries",
+      "note": "Give it a name and every chosen key is submitted as a hidden input; required and invalid come from the Field around it, which owns the label and the message.",
+      "language": "tsx",
+      "source": "<Field>\n  <FieldLabel>Regions</FieldLabel>\n  <Listbox aria-label=\"Regions\" name=\"regions\" selectionMode=\"multiple\" required>\n    {regionOptions}\n  </Listbox>\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "What an application decides once",
+      "note": "The provider sets nineteen axes for every listbox under it, and an instance that states one still wins. The render prop moves the root onto an element the page owns.",
+      "language": "tsx",
+      "source": "<ListboxDefaultsProvider size=\"sm\" loop selectionBehavior=\"replace\">\n  <Workspace />\n</ListboxDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The whole keyboard, one press at a time",
+      "note": "Tab in, then arrow, page, Home, End, Shift and Control. The panel beside the listbox names the last key it answered and what it did with it.",
+      "language": "tsx",
+      "source": "<Listbox aria-label=\"Regions\" activeKey={activeKey} onActiveKeyChange={setActiveKey} loop>\n  {regionOptions}\n</Listbox>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "What a reader hears",
+      "note": "The same listbox under the two focus models, side by side. One roves a tab stop; the other keeps focus on the box and names the active option.",
+      "language": "tsx",
+      "source": "<Listbox aria-label=\"Suggestions\" focusMode=\"activedescendant\" activeKey={highlighted}>\n  {suggestionOptions}\n</Listbox>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}