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

package/dist/docs/entity-picker.json

@@ -0,0 +1,998 @@
+{
+  "family": "entity-picker",
+  "ui": "entity-picker",
+  "binding": "react",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Searches and picks remote records like people."
+  },
+  "axes": {
+    "selectionMode": [
+      "single",
+      "multiple"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "outline",
+      "subtle",
+      "plain"
+    ],
+    "media": [
+      "avatar",
+      "none"
+    ],
+    "overflow": [
+      "collapse",
+      "wrap"
+    ],
+    "openOn": [
+      "input",
+      "focus",
+      "manual"
+    ],
+    "side": [
+      "bottom",
+      "top"
+    ],
+    "width": [
+      "anchor",
+      "content"
+    ],
+    "strategy": [
+      "absolute",
+      "fixed"
+    ],
+    "clearable": [
+      true,
+      false
+    ],
+    "loop": [
+      true,
+      false
+    ],
+    "highlightMatch": [
+      true,
+      false
+    ],
+    "portal": [
+      true,
+      false
+    ],
+    "fullWidth": [
+      true,
+      false
+    ],
+    "disabled": [
+      true,
+      false
+    ],
+    "readOnly": [
+      true,
+      false
+    ],
+    "required": [
+      true,
+      false
+    ],
+    "invalid": [
+      true,
+      false
+    ]
+  },
+  "members": {
+    "entity-picker": {
+      "nativeElement": "div",
+      "defaults": {
+        "selectionMode": "single",
+        "size": "md",
+        "variant": "outline",
+        "media": "avatar",
+        "overflow": "collapse",
+        "openOn": "input",
+        "side": "bottom",
+        "width": "content",
+        "strategy": "absolute",
+        "clearable": true,
+        "loop": false,
+        "highlightMatch": true,
+        "portal": true,
+        "fullWidth": true,
+        "disabled": false,
+        "readOnly": false,
+        "required": false,
+        "invalid": false,
+        "searchDelay": 250,
+        "minQueryLength": 0,
+        "max": null
+      },
+      "capabilities": [
+        "selection",
+        "value",
+        "open",
+        "current",
+        "filter",
+        "size",
+        "appearance",
+        "placement",
+        "content",
+        "fullWidth",
+        "disabled",
+        "readOnly",
+        "required",
+        "invalid",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "open",
+        "disabled",
+        "readonly",
+        "invalid",
+        "required",
+        "loading",
+        "selected",
+        "current",
+        "complete"
+      ],
+      "parts": [
+        "root",
+        "scope",
+        "control",
+        "selection",
+        "values",
+        "chips",
+        "field",
+        "input",
+        "clear",
+        "trigger",
+        "arrow",
+        "busy",
+        "positioner",
+        "content",
+        "group",
+        "group-label",
+        "item",
+        "media",
+        "label",
+        "match",
+        "description",
+        "meta",
+        "indicator",
+        "error",
+        "empty",
+        "placeholder",
+        "more",
+        "status"
+      ]
+    }
+  },
+  "docs": {
+    "entity-picker": {
+      "imports": {
+        "source": "import { EntityPicker, EntityPickerDefaultsProvider, localEntitySource, rememberRecent } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div",
+          "required": true,
+          "purpose": "data-ui=\"entity-picker\", data-size, data-variant, data-selection-mode, data-overflow and the states; role=\"group\" named by the field when scopes are shown. The scope and the frame share one line at every width."
+        },
+        {
+          "part": "scope",
+          "element": "div around a Select",
+          "required": false,
+          "purpose": "The scope a search runs in, joined to the front of the frame, min(11rem, 45%) wide. Only with scopes."
+        },
+        {
+          "part": "control",
+          "element": "div",
+          "required": true,
+          "purpose": "The frame: edge, ground, shadow, focus ring and invalid edge. The anchor the popup hangs from."
+        },
+        {
+          "part": "selection",
+          "element": "span around an Avatar",
+          "required": false,
+          "purpose": "single: the chosen record’s face before its name, aria-hidden. Absent while the reader types, with media=\"none\", and for a record with avatar: null."
+        },
+        {
+          "part": "values",
+          "element": "div",
+          "required": false,
+          "purpose": "multiple: role=\"grid\" named by the label and the count of chips."
+        },
+        {
+          "part": "chips",
+          "element": "div",
+          "required": false,
+          "purpose": "multiple: role=\"row\". Each chip is a Tag (data-ui=\"tag\", role=\"gridcell\") with the face in its start slot, the name, and a remove button at tabindex=\"-1\"; data-loading while its id resolves, data-unresolved when the source did not return it. Under overflow=\"collapse\" a \"+N\" chip with data-count counts what did not fit."
+        },
+        {
+          "part": "field",
+          "element": "span",
+          "required": false,
+          "purpose": "multiple: the gridcell that holds the input, at least 2.5rem wide."
+        },
+        {
+          "part": "input",
+          "element": "input",
+          "required": true,
+          "purpose": "role=\"combobox\", aria-autocomplete=\"list\", aria-activedescendant naming the highlighted record. Every native attribute and handler reaches it."
+        },
+        {
+          "part": "clear",
+          "element": "button",
+          "required": false,
+          "purpose": "Empties the choice and the text, with reason clear. Present while there is either."
+        },
+        {
+          "part": "trigger",
+          "element": "button",
+          "required": true,
+          "purpose": "Opens and closes the popup; tabindex=\"-1\", as the combobox pattern asks."
+        },
+        {
+          "part": "arrow",
+          "element": "span",
+          "required": false,
+          "purpose": "The chevron in the trigger, turned while open."
+        },
+        {
+          "part": "busy",
+          "element": "span, a Spinner",
+          "required": false,
+          "purpose": "Replaces the chevron while a search has been travelling for 200ms, or while the chosen id of a single field resolves."
+        },
+        {
+          "part": "positioner",
+          "element": "div, portalled",
+          "required": true,
+          "purpose": "The layer, carrying data-ui=\"entity-picker\" so the stylesheet reaches it."
+        },
+        {
+          "part": "content",
+          "element": "div",
+          "required": true,
+          "purpose": "role=\"listbox\", aria-multiselectable in multiple, aria-busy while a search travels; data-loading while a new query recedes the rows already shown."
+        },
+        {
+          "part": "group",
+          "element": "div",
+          "required": false,
+          "purpose": "A section — Chosen, Favorites, Recent, Results — or a group of results by entity.group; role=\"group\" named by its label. Drawn only when more than one shows."
+        },
+        {
+          "part": "group-label",
+          "element": "div",
+          "required": false,
+          "purpose": "The heading of a group."
+        },
+        {
+          "part": "item",
+          "element": "div",
+          "required": false,
+          "purpose": "One record, role=\"option\", data-selected, data-current, data-disabled. data-create marks the offer to create, data-retry the offer to search again."
+        },
+        {
+          "part": "media",
+          "element": "span around an Avatar",
+          "required": false,
+          "purpose": "The face, spanning the name and the identifier. A glyph instead on the two offers. Absent with media=\"none\"."
+        },
+        {
+          "part": "label",
+          "element": "span",
+          "required": false,
+          "purpose": "The name, two lines at most, ordered by its own first strong character."
+        },
+        {
+          "part": "match",
+          "element": "mark, from Highlight",
+          "required": false,
+          "purpose": "The span of the name the query found."
+        },
+        {
+          "part": "description",
+          "element": "span",
+          "required": false,
+          "purpose": "The identifier that tells two records of one name apart; one line."
+        },
+        {
+          "part": "meta",
+          "element": "span",
+          "required": false,
+          "purpose": "A short fact on the name’s line — a type, a status — at most a quarter of the row."
+        },
+        {
+          "part": "indicator",
+          "element": "span",
+          "required": false,
+          "purpose": "The check on a chosen record, on the name’s first line."
+        },
+        {
+          "part": "error",
+          "element": "div",
+          "required": false,
+          "purpose": "labels.error with the alert mark, above the retry option."
+        },
+        {
+          "part": "empty",
+          "element": "div",
+          "required": false,
+          "purpose": "labels.empty, when the source answered with nothing and nothing can be created."
+        },
+        {
+          "part": "placeholder",
+          "element": "div",
+          "required": false,
+          "purpose": "Three skeleton records — a circle and two lines — while the first page travels, after 200ms. aria-hidden."
+        },
+        {
+          "part": "more",
+          "element": "div",
+          "required": false,
+          "purpose": "One skeleton record at the end while the next page travels. aria-hidden."
+        },
+        {
+          "part": "status",
+          "element": "div",
+          "required": true,
+          "purpose": "role=\"status\": the count once the source answered a typed query, the minimum length, the wait."
+        }
+      ],
+      "api": [
+        {
+          "name": "selectionMode",
+          "type": "'single' | 'multiple'",
+          "defaultValue": "single",
+          "appliesTo": "EntityPicker",
+          "description": "One id or an array of ids"
+        },
+        {
+          "name": "source",
+          "type": "EntitySource",
+          "defaultValue": "—",
+          "appliesTo": "EntityPicker",
+          "description": "search(request, { signal }) and resolve(ids, { signal }); the family calls them"
+        },
+        {
+          "name": "items",
+          "type": "readonly Entity[]",
+          "defaultValue": "—",
+          "appliesTo": "EntityPicker",
+          "description": "A list the application holds, filtered by name and identifier with the locale’s collator"
+        },
+        {
+          "name": "entities",
+          "type": "readonly Entity[]",
+          "defaultValue": "[]",
+          "appliesTo": "EntityPicker",
+          "description": "Records the application already knows, so their ids need no resolution"
+        },
+        {
+          "name": "favorites",
+          "type": "readonly Entity[]",
+          "defaultValue": "[]",
+          "appliesTo": "EntityPicker",
+          "description": "The first section on an empty query"
+        },
+        {
+          "name": "recent",
+          "type": "readonly Entity[]",
+          "defaultValue": "[]",
+          "appliesTo": "EntityPicker",
+          "description": "The section after favorites"
+        },
+        {
+          "name": "scopes",
+          "type": "readonly { id: string; label: string }[]",
+          "defaultValue": "—",
+          "appliesTo": "EntityPicker",
+          "description": "Draws a Select in front of the field; the scope rides on every request"
+        },
+        {
+          "name": "value",
+          "type": "string | null | readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "EntityPicker",
+          "description": "Present means controlled"
+        },
+        {
+          "name": "defaultValue",
+          "type": "string | null | readonly string[]",
+          "defaultValue": "null or []",
+          "appliesTo": "EntityPicker",
+          "description": "The uncontrolled start, read once"
+        },
+        {
+          "name": "inputValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "EntityPicker",
+          "description": "The text, controlled"
+        },
+        {
+          "name": "defaultInputValue",
+          "type": "string",
+          "defaultValue": "the chosen name",
+          "appliesTo": "EntityPicker",
+          "description": "The uncontrolled text"
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "EntityPicker",
+          "description": "The popup, controlled"
+        },
+        {
+          "name": "defaultOpen",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "EntityPicker",
+          "description": "The uncontrolled popup"
+        },
+        {
+          "name": "highlightedValue",
+          "type": "string | null",
+          "defaultValue": "—",
+          "appliesTo": "EntityPicker",
+          "description": "The highlighted option’s key, controlled"
+        },
+        {
+          "name": "defaultHighlightedValue",
+          "type": "string | null",
+          "defaultValue": "null",
+          "appliesTo": "EntityPicker",
+          "description": "The uncontrolled highlight"
+        },
+        {
+          "name": "scope",
+          "type": "string | null",
+          "defaultValue": "—",
+          "appliesTo": "EntityPicker",
+          "description": "The scope, controlled"
+        },
+        {
+          "name": "defaultScope",
+          "type": "string | null",
+          "defaultValue": "null",
+          "appliesTo": "EntityPicker",
+          "description": "The uncontrolled scope"
+        },
+        {
+          "name": "onCreate",
+          "type": "(query) => void | Entity | Promise<Entity | null | void>",
+          "defaultValue": "—",
+          "appliesTo": "EntityPicker",
+          "description": "Draws the offer to create"
+        },
+        {
+          "name": "renderOption",
+          "type": "(entity, state) => ReactNode",
+          "defaultValue": "name, identifier, fact",
+          "appliesTo": "EntityPicker",
+          "description": "The content of an option; the face, the check and the row stay the family’s"
+        },
+        {
+          "name": "renderChip",
+          "type": "(entity) => ReactNode",
+          "defaultValue": "the name",
+          "appliesTo": "EntityPicker",
+          "description": "The words of a chip"
+        },
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "a div",
+          "appliesTo": "EntityPicker",
+          "description": "Replaces the root element"
+        },
+        {
+          "name": "handleRef",
+          "type": "Ref<{ focus, open, close, refresh }>",
+          "defaultValue": "—",
+          "appliesTo": "EntityPicker",
+          "description": "refresh() asks the source again"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "defaultValue": "—",
+          "appliesTo": "EntityPicker",
+          "description": "The input"
+        },
+        {
+          "name": "max",
+          "type": "number | null",
+          "defaultValue": "null",
+          "appliesTo": "EntityPicker",
+          "description": "multiple: the most records chosen"
+        },
+        {
+          "name": "searchDelay",
+          "type": "number",
+          "defaultValue": "250",
+          "appliesTo": "EntityPicker",
+          "description": "Milliseconds after the last keystroke"
+        },
+        {
+          "name": "minQueryLength",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "EntityPicker",
+          "description": "Below it nothing is asked; at 0 the empty query is searched"
+        },
+        {
+          "name": "media",
+          "type": "'avatar' | 'none'",
+          "defaultValue": "avatar",
+          "appliesTo": "EntityPicker",
+          "description": "Faces in the rows, the chips and the field"
+        },
+        {
+          "name": "overflow",
+          "type": "'collapse' | 'wrap'",
+          "defaultValue": "collapse",
+          "appliesTo": "EntityPicker",
+          "description": "multiple: one line with +N, or three lines"
+        },
+        {
+          "name": "openOn",
+          "type": "'input' | 'focus' | 'manual'",
+          "defaultValue": "input",
+          "appliesTo": "EntityPicker",
+          "description": "input: typing or a press opens; focus: every focus too; manual: only the trigger and the arrows"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "EntityPicker",
+          "description": "The control step; a Field around it sets it"
+        },
+        {
+          "name": "variant",
+          "type": "'outline' | 'subtle' | 'plain'",
+          "defaultValue": "outline",
+          "appliesTo": "EntityPicker",
+          "description": "plain gives the box to a cell"
+        },
+        {
+          "name": "side",
+          "type": "'bottom' | 'top'",
+          "defaultValue": "bottom",
+          "appliesTo": "EntityPicker",
+          "description": "Where the popup opens; it flips when there is no room"
+        },
+        {
+          "name": "width",
+          "type": "'anchor' | 'content'",
+          "defaultValue": "content",
+          "appliesTo": "EntityPicker",
+          "description": "The popup at least as wide as the frame and as wide as its longest row (content), or pinned to the width of the frame (anchor)"
+        },
+        {
+          "name": "strategy",
+          "type": "'absolute' | 'fixed'",
+          "defaultValue": "absolute",
+          "appliesTo": "EntityPicker",
+          "description": "fixed inside a transformed or clipped ancestor"
+        },
+        {
+          "name": "clearable",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "EntityPicker",
+          "description": "Draws the clear button while there is something to clear"
+        },
+        {
+          "name": "loop",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "EntityPicker",
+          "description": "The arrows wrap past the ends"
+        },
+        {
+          "name": "highlightMatch",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "EntityPicker",
+          "description": "Marks the span the query found"
+        },
+        {
+          "name": "portal",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "EntityPicker",
+          "description": "false keeps the layer in place"
+        },
+        {
+          "name": "fullWidth",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "EntityPicker",
+          "description": "false sizes the root to its content"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "EntityPicker",
+          "description": "Also read from a Field or a disabled fieldset"
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "EntityPicker",
+          "description": "Keeps the text, withholds the popup and the removals"
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "EntityPicker",
+          "description": "On the input while nothing is chosen"
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "EntityPicker",
+          "description": "Also read from a Field"
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "EntityPicker",
+          "description": "BCP 47, for the local filter and the mark. The language in force when absent"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<EntityPickerMessages>",
+          "defaultValue": "—",
+          "appliesTo": "EntityPicker",
+          "description": "Words laid over the language in force, key by key; {count}, {query}, {label}, {id} and {max} are slots"
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "EntityPicker",
+          "description": "One hidden input per id under this name"
+        },
+        {
+          "name": "EntityPickerDefaultsProvider",
+          "type": "{ size, variant, media, overflow, openOn, searchDelay, minQueryLength, … }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The decisions an application takes once; an instance that states any of them wins"
+        }
+      ],
+      "composition": [],
+      "events": [
+        {
+          "name": "onValueChange",
+          "payload": "(value: string | null | readonly string[], request: ChangeRequest & { entities: readonly Entity[] })",
+          "when": "Before the choice moves: a press (pointer), Enter (keyboard), a removal (remove), the clear button or Escape twice (clear), a record onCreate returned (submit). request.entities holds the records known for the new value; cancel() refuses it."
+        },
+        {
+          "name": "onInputValueChange",
+          "payload": "(value: string, request: ChangeRequest<string>)",
+          "when": "Before the text moves: typing (keyboard), a choice (select), clear (clear), leaving text that chose nothing (blur)."
+        },
+        {
+          "name": "onOpenChange",
+          "payload": "(open: boolean, request: ChangeRequest<boolean>)",
+          "when": "Before the popup opens or closes: focus, typing, arrows (keyboard), a press on the input or the trigger (pointer), Escape (escape), a press outside (outsidePress), a choice (select), leaving (blur)."
+        },
+        {
+          "name": "onHighlightedValueChange",
+          "payload": "(key: string | null, request: ChangeRequest<string | null>)",
+          "when": "Before the highlight moves: arrows and the opening (keyboard), hovering an option (pointer)."
+        },
+        {
+          "name": "onScopeChange",
+          "payload": "(scope: string | null, request: ChangeRequest<string | null>)",
+          "when": "Before the scope moves in the Select in front of the field (pointer, keyboard)."
+        },
+        {
+          "name": "onCreate",
+          "payload": "(query: string) => void | Entity | Promise<Entity | null | void>",
+          "when": "When the offer to create is taken. A record returned is remembered and chosen with reason submit."
+        },
+        {
+          "name": "source.search / source.resolve",
+          "payload": "(request, { signal }) => Promise<…>",
+          "when": "search after searchDelay once the reader stops typing, at once for an empty query or a new scope, and again for the next page; resolve for ids the family has not seen. A superseded request is aborted."
+        },
+        {
+          "name": "onKeyDown, onFocus, onBlur and the other native handlers",
+          "payload": "the input’s own event",
+          "when": "Run first on the input; the family’s own handling is skipped when a handler calls preventDefault()."
+        }
+      ],
+      "accessibility": [
+        "The input is a combobox with a listbox popup, as the APG Combobox Pattern writes it: DOM focus never leaves the input, the highlighted record is named by aria-activedescendant, aria-autocomplete is list, and aria-expanded is always written.",
+        "Each option is named by its name, its identifier and its short fact, so two people called Ana Souza are two different options to a screen reader; a chip is named the same way, and an id without a record is named “Unavailable” with the id.",
+        "In multiple the chips are one row of a grid with one tab stop: the arrows move between chips, Delete and Backspace remove, and focus after a removal goes to the chip that took the index, then the previous one, then the input.",
+        "The status region says the count once the source answers a typed query, the minimum length and the wait; the failure and every chip added or removed are said once through the shared polite announcer. The skeletons are hidden from assistive technology.",
+        "The offer to create and the offer to search again are options, so the keyboard reaches them through the same arrows and Enter as any record; a button inside the popup would be out of reach while focus stays on the input."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-avatar-size-md",
+    "--slotted-avatar-size-sm",
+    "--slotted-avatar-size-xs",
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-control-border-color",
+    "--slotted-control-border-width",
+    "--slotted-control-font-family",
+    "--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-inner-size-lg",
+    "--slotted-control-inner-size-md",
+    "--slotted-control-inner-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-shadow-focus-geometry",
+    "--slotted-control-surface",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-background",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-medium",
+    "--slotted-duration-short",
+    "--slotted-easing-enter",
+    "--slotted-easing-exit",
+    "--slotted-easing-standard",
+    "--slotted-entity-picker-action-active-background",
+    "--slotted-entity-picker-action-color",
+    "--slotted-entity-picker-action-hover-background",
+    "--slotted-entity-picker-action-size",
+    "--slotted-entity-picker-autofill-background",
+    "--slotted-entity-picker-background",
+    "--slotted-entity-picker-border-color",
+    "--slotted-entity-picker-color",
+    "--slotted-entity-picker-content-border-color",
+    "--slotted-entity-picker-content-radius",
+    "--slotted-entity-picker-content-shadow",
+    "--slotted-entity-picker-content-text",
+    "--slotted-entity-picker-content-text-muted",
+    "--slotted-entity-picker-disabled-background",
+    "--slotted-entity-picker-disabled-border-color",
+    "--slotted-entity-picker-disabled-color",
+    "--slotted-entity-picker-error-color",
+    "--slotted-entity-picker-field-basis",
+    "--slotted-entity-picker-field-min",
+    "--slotted-entity-picker-highlight",
+    "--slotted-entity-picker-highlight-active",
+    "--slotted-entity-picker-highlight-ring",
+    "--slotted-entity-picker-hover-border-color",
+    "--slotted-entity-picker-icon-size-min",
+    "--slotted-entity-picker-invalid-border-color",
+    "--slotted-entity-picker-invalid-edge-width",
+    "--slotted-entity-picker-invalid-focus-ring-color",
+    "--slotted-entity-picker-item-radius",
+    "--slotted-entity-picker-measure",
+    "--slotted-entity-picker-meta-measure",
+    "--slotted-entity-picker-offer-color",
+    "--slotted-entity-picker-open-border-color",
+    "--slotted-entity-picker-placeholder-color",
+    "--slotted-entity-picker-plain-hover-background",
+    "--slotted-entity-picker-radius",
+    "--slotted-entity-picker-readonly-background",
+    "--slotted-entity-picker-scope-inline-size",
+    "--slotted-entity-picker-selected-color",
+    "--slotted-entity-picker-shadow",
+    "--slotted-entity-picker-subtle-background",
+    "--slotted-entity-picker-subtle-border-color",
+    "--slotted-entity-picker-subtle-hover-background",
+    "--slotted-entity-picker-surface",
+    "--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-medium",
+    "--slotted-font-weight-semibold",
+    "--slotted-line-height-md",
+    "--slotted-line-height-sm",
+    "--slotted-radius-lg",
+    "--slotted-radius-none",
+    "--slotted-shadow-md",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-surface-raised",
+    "--slotted-surface-sunken",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-surface",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-danger-text",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover",
+    "--slotted-z-index-popover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "An owner for a deal, from a directory that answers after 400ms. Change the mode, size, variant, media and overflow below; every request is written under the field with its reason.",
+      "language": "tsx",
+      "source": "const directory: EntitySource = {\n  search: async ({ query, page, scope }, { signal }) => api.people({ query, page, scope, signal }),\n  resolve: async (ids, { signal }) => api.peopleById(ids, { signal }),\n};\n\n<EntityPicker\n  aria-label=\"Owner\"\n  onValueChange={(id, request) => setOwner(id)}\n  source={directory}\n  value={owner}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "single",
+      "title": "One record",
+      "note": "The chosen name is the text of the field and the face stands before it. Typing searches; leaving text that chose nothing puts the name back.",
+      "language": "tsx",
+      "source": "<Field>\n  <FieldLabel>Account owner</FieldLabel>\n  <EntityPicker defaultValue=\"usr_ana\" source={directory} />\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "multiple",
+      "title": "Several records",
+      "note": "Reviewers as chips with faces. Choosing keeps the popup open and empties the query; the field stays one line, and what does not fit is counted by +N.",
+      "language": "tsx",
+      "source": "<EntityPicker\n  aria-label=\"Reviewers\"\n  defaultValue={['usr_ana', 'usr_bruno', 'usr_carla']}\n  selectionMode=\"multiple\"\n  source={directory}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "rich-results",
+      "title": "A record, not a string",
+      "note": "The face, the name, the identifier under it and a short fact on its line. Two people called Ana Souza are told apart by their address, in the list and in what a screen reader hears.",
+      "language": "ts",
+      "source": "const record: Entity = {\n  id: 'usr_ana',\n  label: 'Ana Souza',\n  description: 'ana.souza@northwind.io',\n  meta: 'Admin',\n};\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sections",
+      "title": "Favorites and recent",
+      "note": "Press the empty field: favorites, then recent, then what the empty query returned, with no id twice. rememberRecent keeps the application’s list.",
+      "language": "tsx",
+      "source": "<EntityPicker\n  aria-label=\"Assignee\"\n  favorites={pinned}\n  onValueChange={(id, request) => setRecent((list) => rememberRecent(list, request.entities[0]!))}\n  recent={recent}\n  source={directory}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "scopes",
+      "title": "Searching in a scope",
+      "note": "A Select joined to the front of the field chooses what the search runs over; the scope rides on every request and favorites keep only records of it.",
+      "language": "tsx",
+      "source": "<EntityPicker\n  aria-label=\"Related record\"\n  defaultScope=\"accounts\"\n  scopes={[\n    { id: 'accounts', label: 'Accounts' },\n    { id: 'contacts', label: 'Contacts' },\n    { id: 'deals', label: 'Deals' },\n  ]}\n  source={crm}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "async",
+      "title": "Waiting for the source",
+      "note": "The first page waits as three skeleton records; a new query dims the rows already shown; the next page arrives under a skeleton row at the end. Nothing is drawn for an answer faster than 200ms.",
+      "language": "ts",
+      "source": "const directory: EntitySource = {\n  search: async ({ query, cursor }, { signal }) => {\n    const page = await api.people({ query, cursor, signal });\n    return { items: page.people, hasMore: page.next !== null, cursor: page.next };\n  },\n};\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "creation",
+      "title": "Creating what is not there",
+      "note": "Type a company the source does not hold: the last option offers to create it. The record onCreate returns is chosen with reason submit.",
+      "language": "tsx",
+      "source": "<EntityPicker\n  aria-label=\"Account\"\n  onCreate={async (name) => api.createAccount({ name })}\n  source={accounts}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "error",
+      "title": "When the source fails",
+      "note": "The sentence names what failed and the option under it searches again — ArrowDown reaches it and Enter takes it. Chips already chosen stay.",
+      "language": "tsx",
+      "source": "<EntityPicker aria-label=\"Owner\" source={offline} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "unresolved",
+      "title": "Ids without records",
+      "note": "A value that arrives as ids: each chip waits as a skeleton while resolve runs, and an id the source never returns reads Unavailable and stays removable.",
+      "language": "tsx",
+      "source": "<EntityPicker\n  aria-label=\"Watchers\"\n  defaultValue={['usr_ana', 'usr_deleted']}\n  selectionMode=\"multiple\"\n  source={directory}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "limit",
+      "title": "A limit",
+      "note": "At three approvers every other record goes aria-disabled and the field says it is complete; removing one opens the list again.",
+      "language": "tsx",
+      "source": "<EntityPicker aria-label=\"Approvers\" max={3} selectionMode=\"multiple\" source={directory} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "Sizes",
+      "note": "sm, md and lg beside a text field of the same step: the frame, the face and the chips follow the control scale, and density moves all three.",
+      "language": "tsx",
+      "source": "<EntityPicker aria-label=\"Owner\" size=\"sm\" source={directory} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variants",
+      "title": "Variants",
+      "note": "outline in a form, subtle on a sunken panel, plain inside a table cell whose row is the box — square, no lift, the ring drawn inward.",
+      "language": "tsx",
+      "source": "<EntityPicker aria-label=\"Owner\" source={directory} variant=\"plain\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "States",
+      "note": "Disabled drops the remove buttons and fades the faces; read-only keeps the name copyable and withholds the popup; invalid retargets the edge and the ring; required is on the input.",
+      "language": "tsx",
+      "source": "<EntityPicker aria-label=\"Owner\" disabled source={directory} />;\n<EntityPicker aria-label=\"Owner\" readOnly source={directory} />;\n<EntityPicker aria-label=\"Owner\" invalid required source={directory} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "long-content",
+      "title": "Content the family did not choose",
+      "note": "A nine-word name clamps to two lines, a long address to one with an ellipsis, an Arabic name reads right to left in a left-to-right list, and a token with no spaces breaks.",
+      "language": "tsx",
+      "source": "<EntityPicker aria-label=\"Watchers\" items={international} selectionMode=\"multiple\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "Every key",
+      "note": "ArrowDown opens and moves, PageDown jumps ten, Enter chooses, Escape closes then reverts; in multiple, Backspace from an empty field goes to the last chip and a second press removes it.",
+      "language": "tsx",
+      "source": "<EntityPicker aria-label=\"Reviewers\" selectionMode=\"multiple\" source={directory} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "form",
+      "title": "In a form",
+      "note": "A deal form: the owner and the reviewers submit one hidden input per id under their names, beside a text field and a select of the same height.",
+      "language": "tsx",
+      "source": "<form action=\"/deals\" method=\"post\">\n  <Field>\n    <FieldLabel>Reviewers</FieldLabel>\n    <EntityPicker name=\"reviewers\" selectionMode=\"multiple\" source={directory} />\n  </Field>\n</form>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition",
+      "note": "renderOption adds the team after the address; renderChip adds the role to a chip; SlottedProvider says every sentence in Portuguese once.",
+      "language": "tsx",
+      "source": "<SlottedProvider locale=\"pt-BR\" catalogs={{ 'pt-BR': PT_BR }}>\n  <EntityPicker\n    aria-label=\"Responsável\"\n    messages={{ retry: 'Buscar outra vez' }}\n    renderOption={(person) => <span data-part=\"label\">{person.label}</span>}\n    source={directory}\n  />\n</SlottedProvider>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}