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

package/docs/entity-picker.json

@@ -0,0 +1,946 @@
+{
+  "family": "entity-picker",
+  "ui": "entity-picker",
+  "binding": "angular",
+  "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 { SlEntityPicker, SlEntityPickerChip, SlEntityPickerOption, provideEntityPickerDefaults } from '@slotted/angular/entity-picker';",
+        "selector": "sl-entity-picker, ng-template[slEntityPickerOption], ng-template[slEntityPickerChip]",
+        "exportAs": "slEntityPicker"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "sl-entity-picker",
+          "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 an sl-select",
+          "required": false,
+          "purpose": "The scope a search runs in, joined to the front of the frame. Only with [scopes]."
+        },
+        {
+          "part": "control",
+          "element": "div",
+          "required": true,
+          "purpose": "The frame, and the anchor the popup hangs from."
+        },
+        {
+          "part": "selection",
+          "element": "span around an slAvatar",
+          "required": false,
+          "purpose": "single: the chosen record’s face before its name, aria-hidden."
+        },
+        {
+          "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\" of tag chips with a face, a name and a remove button; data-loading while an id resolves, data-unresolved when it never does, and a \"+N\" chip with data-count under overflow=\"collapse\"."
+        },
+        {
+          "part": "field",
+          "element": "span",
+          "required": false,
+          "purpose": "multiple: the gridcell that holds the input."
+        },
+        {
+          "part": "input",
+          "element": "input",
+          "required": true,
+          "purpose": "role=\"combobox\", aria-autocomplete=\"list\", aria-activedescendant naming the highlight."
+        },
+        {
+          "part": "clear",
+          "element": "button",
+          "required": false,
+          "purpose": "Empties the choice and the text, with reason clear."
+        },
+        {
+          "part": "trigger",
+          "element": "button",
+          "required": true,
+          "purpose": "Opens and closes the popup; tabindex=\"-1\"."
+        },
+        {
+          "part": "arrow",
+          "element": "span",
+          "required": false,
+          "purpose": "The chevron in the trigger."
+        },
+        {
+          "part": "busy",
+          "element": "span, the spinner family",
+          "required": false,
+          "purpose": "Replaces the chevron while a search or a single resolution travels."
+        },
+        {
+          "part": "positioner",
+          "element": "div, portalled",
+          "required": true,
+          "purpose": "The layer, built from an ng-template on open and destroyed on close."
+        },
+        {
+          "part": "content",
+          "element": "div",
+          "required": true,
+          "purpose": "role=\"listbox\"; aria-multiselectable in multiple; aria-busy while a search travels."
+        },
+        {
+          "part": "group",
+          "element": "div",
+          "required": false,
+          "purpose": "Chosen, Favorites, Recent, Results or a group by entity.group; role=\"group\"."
+        },
+        {
+          "part": "group-label",
+          "element": "div",
+          "required": false,
+          "purpose": "The heading of a group, drawn only when more than one group shows."
+        },
+        {
+          "part": "item",
+          "element": "div",
+          "required": false,
+          "purpose": "One record, role=\"option\"; data-create marks the offer to create, data-retry the offer to search again."
+        },
+        {
+          "part": "media",
+          "element": "span around an slAvatar",
+          "required": false,
+          "purpose": "The face, spanning both lines; a glyph on the two offers."
+        },
+        {
+          "part": "label",
+          "element": "span",
+          "required": false,
+          "purpose": "The name, two lines at most."
+        },
+        {
+          "part": "match",
+          "element": "mark, from slHighlight",
+          "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."
+        },
+        {
+          "part": "meta",
+          "element": "span",
+          "required": false,
+          "purpose": "A short fact on the name’s line."
+        },
+        {
+          "part": "indicator",
+          "element": "span",
+          "required": false,
+          "purpose": "The check on a chosen record."
+        },
+        {
+          "part": "error",
+          "element": "div",
+          "required": false,
+          "purpose": "The failure, above the retry option."
+        },
+        {
+          "part": "empty",
+          "element": "div",
+          "required": false,
+          "purpose": "Nothing answered and nothing can be created."
+        },
+        {
+          "part": "placeholder",
+          "element": "div",
+          "required": false,
+          "purpose": "Three skeleton records while the first page travels. aria-hidden."
+        },
+        {
+          "part": "more",
+          "element": "div",
+          "required": false,
+          "purpose": "One skeleton record while the next page travels. aria-hidden."
+        },
+        {
+          "part": "status",
+          "element": "div",
+          "required": true,
+          "purpose": "role=\"status\": the count, the minimum length, the wait."
+        }
+      ],
+      "api": [
+        {
+          "name": "selectionMode",
+          "type": "'single' | 'multiple'",
+          "defaultValue": "single",
+          "appliesTo": "sl-entity-picker",
+          "description": "One id or an array of ids"
+        },
+        {
+          "name": "source",
+          "type": "EntitySource",
+          "defaultValue": "—",
+          "appliesTo": "sl-entity-picker",
+          "description": "search(request, { signal }) and resolve(ids, { signal })"
+        },
+        {
+          "name": "items",
+          "type": "readonly Entity[]",
+          "defaultValue": "—",
+          "appliesTo": "sl-entity-picker",
+          "description": "A list the application holds, filtered locally"
+        },
+        {
+          "name": "entities",
+          "type": "readonly Entity[]",
+          "defaultValue": "[]",
+          "appliesTo": "sl-entity-picker",
+          "description": "Records the application already knows"
+        },
+        {
+          "name": "favorites",
+          "type": "readonly Entity[]",
+          "defaultValue": "[]",
+          "appliesTo": "sl-entity-picker",
+          "description": "The first section on an empty query"
+        },
+        {
+          "name": "recent",
+          "type": "readonly Entity[]",
+          "defaultValue": "[]",
+          "appliesTo": "sl-entity-picker",
+          "description": "The section after favorites"
+        },
+        {
+          "name": "scopes",
+          "type": "readonly { id; label }[]",
+          "defaultValue": "[]",
+          "appliesTo": "sl-entity-picker",
+          "description": "Draws an sl-select in front of the field"
+        },
+        {
+          "name": "value",
+          "type": "model<string | null | readonly string[]>",
+          "defaultValue": "null",
+          "appliesTo": "sl-entity-picker",
+          "description": "Two-way ids"
+        },
+        {
+          "name": "defaultValue",
+          "type": "string | readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "sl-entity-picker",
+          "description": "The uncontrolled start, read once"
+        },
+        {
+          "name": "inputValue",
+          "type": "model<string>",
+          "defaultValue": "''",
+          "appliesTo": "sl-entity-picker",
+          "description": "Two-way text"
+        },
+        {
+          "name": "open",
+          "type": "model<boolean>",
+          "defaultValue": "false",
+          "appliesTo": "sl-entity-picker",
+          "description": "Two-way popup"
+        },
+        {
+          "name": "highlightedValue",
+          "type": "model<string | null>",
+          "defaultValue": "null",
+          "appliesTo": "sl-entity-picker",
+          "description": "Two-way highlight"
+        },
+        {
+          "name": "scope",
+          "type": "model<string | null>",
+          "defaultValue": "null",
+          "appliesTo": "sl-entity-picker",
+          "description": "Two-way scope"
+        },
+        {
+          "name": "createEntity",
+          "type": "(query) => Entity | Promise<Entity | null>",
+          "defaultValue": "—",
+          "appliesTo": "sl-entity-picker",
+          "description": "Draws the offer to create"
+        },
+        {
+          "name": "max",
+          "type": "number",
+          "defaultValue": "null",
+          "appliesTo": "sl-entity-picker",
+          "description": "multiple: the most records chosen"
+        },
+        {
+          "name": "searchDelay",
+          "type": "number",
+          "defaultValue": "250",
+          "appliesTo": "sl-entity-picker",
+          "description": "Milliseconds after the last keystroke"
+        },
+        {
+          "name": "minQueryLength",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "sl-entity-picker",
+          "description": "Below it nothing is asked"
+        },
+        {
+          "name": "media",
+          "type": "'avatar' | 'none'",
+          "defaultValue": "avatar",
+          "appliesTo": "sl-entity-picker",
+          "description": "Faces in rows, chips and the field"
+        },
+        {
+          "name": "overflow",
+          "type": "'collapse' | 'wrap'",
+          "defaultValue": "collapse",
+          "appliesTo": "sl-entity-picker",
+          "description": "multiple: one line with +N, or three lines"
+        },
+        {
+          "name": "openOn",
+          "type": "'input' | 'focus' | 'manual'",
+          "defaultValue": "input",
+          "appliesTo": "sl-entity-picker",
+          "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": "sl-entity-picker",
+          "description": "The control step; a field sets it"
+        },
+        {
+          "name": "variant",
+          "type": "'outline' | 'subtle' | 'plain'",
+          "defaultValue": "outline",
+          "appliesTo": "sl-entity-picker",
+          "description": "plain gives the box to a cell"
+        },
+        {
+          "name": "side",
+          "type": "'bottom' | 'top'",
+          "defaultValue": "bottom",
+          "appliesTo": "sl-entity-picker",
+          "description": "Where the popup opens"
+        },
+        {
+          "name": "width",
+          "type": "'anchor' | 'content'",
+          "defaultValue": "content",
+          "appliesTo": "sl-entity-picker",
+          "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": "sl-entity-picker",
+          "description": "fixed inside a clipped ancestor"
+        },
+        {
+          "name": "clearable",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "sl-entity-picker",
+          "description": "Draws the clear button"
+        },
+        {
+          "name": "loop",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "sl-entity-picker",
+          "description": "The arrows wrap"
+        },
+        {
+          "name": "highlightMatch",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "sl-entity-picker",
+          "description": "Marks the span the query found"
+        },
+        {
+          "name": "portal",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "sl-entity-picker",
+          "description": "false keeps the layer in place"
+        },
+        {
+          "name": "fullWidth",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "sl-entity-picker",
+          "description": "false sizes the root to its content"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "sl-entity-picker",
+          "description": "Also from a field or a form control"
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "sl-entity-picker",
+          "description": "Keeps the text, withholds the popup"
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "sl-entity-picker",
+          "description": "Reported by the Validator"
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "sl-entity-picker",
+          "description": "Also from a field"
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "sl-entity-picker",
+          "description": "BCP 47. The language in force when absent"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<EntityPickerMessages>",
+          "defaultValue": "—",
+          "appliesTo": "sl-entity-picker",
+          "description": "Words laid over the language in force, key by key; {count}, {query}, {label}, {id} and {max} are slots"
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "sl-entity-picker",
+          "description": "The name when no field labels it"
+        },
+        {
+          "name": "slEntityPickerOption",
+          "type": "ng-template, context { $implicit, query, selected, current, disabled }",
+          "defaultValue": "—",
+          "appliesTo": "option content",
+          "description": "The content of an option"
+        },
+        {
+          "name": "slEntityPickerChip",
+          "type": "ng-template, context { $implicit }",
+          "defaultValue": "—",
+          "appliesTo": "chip words",
+          "description": "The words of a chip"
+        },
+        {
+          "name": "provideEntityPickerDefaults",
+          "type": "(defaults) => Provider",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "The decisions an application takes once"
+        }
+      ],
+      "composition": [],
+      "events": [
+        {
+          "name": "valueChangeRequest",
+          "payload": "ChangeRequest<string | null | readonly string[]> & { entities: readonly Entity[] }",
+          "when": "Before the choice moves: a press (pointer), Enter (keyboard), a removal (remove), clear (clear), a created record (submit). cancel() refuses it; otherwise value and a form control follow."
+        },
+        {
+          "name": "valueChange",
+          "payload": "string | null | readonly string[]",
+          "when": "The model half of [(value)], after a request nobody cancelled."
+        },
+        {
+          "name": "inputValueChangeRequest / inputValueChange",
+          "payload": "ChangeRequest<string> / string",
+          "when": "The text: typing (keyboard), a choice (select), clear (clear), leaving text that chose nothing (blur)."
+        },
+        {
+          "name": "openChangeRequest / openChange",
+          "payload": "ChangeRequest<boolean> / boolean",
+          "when": "The popup: focus and keys (keyboard), a press on the input or the trigger (pointer), escape, outsidePress, select, blur."
+        },
+        {
+          "name": "highlightedValueChangeRequest / highlightedValueChange",
+          "payload": "ChangeRequest<string | null> / string | null",
+          "when": "The highlight: arrows (keyboard), hovering (pointer)."
+        },
+        {
+          "name": "scopeChangeRequest / scopeChange",
+          "payload": "ChangeRequest<string | null> / string | null",
+          "when": "The scope, from the sl-select in front of the field (pointer, keyboard)."
+        },
+        {
+          "name": "create",
+          "payload": "{ query: string; reason }",
+          "when": "The offer to create is taken; [createEntity] makes the record, which is then chosen."
+        }
+      ],
+      "accessibility": [
+        "The input is a combobox with a listbox popup, as the APG Combobox Pattern writes it: DOM focus never leaves the input, aria-activedescendant names the highlighted record, and aria-autocomplete is list.",
+        "Each option and each chip is named by the name and the identifier, so two people called Ana Souza are two things to a screen reader; 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 removes, and focus after a removal goes to the chip that took the index, then the previous one, then the input.",
+        "The Validator reports required and unresolved to a Reactive Form, so a value that holds a deleted record is invalid without the application checking it.",
+        "The failure and every chip added or removed are said once through the shared polite announcer; the skeletons are hidden from assistive technology."
+      ]
+    }
+  },
+  "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": "html",
+      "source": "<sl-entity-picker\n  aria-label=\"Owner\"\n  [source]=\"directory\"\n  [(value)]=\"owner\"\n  (valueChangeRequest)=\"log($event)\"\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": "html",
+      "source": "<div slField>\n  <label slFieldLabel>Account owner</label>\n  <sl-entity-picker defaultValue=\"usr_bruno\" [source]=\"directory\" />\n</div>\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": "html",
+      "source": "<sl-entity-picker\n  aria-label=\"Reviewers\"\n  selectionMode=\"multiple\"\n  [defaultValue]=\"['usr_ana', 'usr_bruno', 'usr_carla']\"\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": "html",
+      "source": "<sl-entity-picker\n  aria-label=\"Assignee\"\n  [favorites]=\"pinned\"\n  [recent]=\"recent()\"\n  [source]=\"directory\"\n  (valueChangeRequest)=\"remember($event)\"\n/>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "scopes",
+      "title": "Searching in a scope",
+      "note": "An sl-select joined to the front of the field chooses what the search runs over; the scope rides on every request.",
+      "language": "html",
+      "source": "<sl-entity-picker aria-label=\"Related record\" [scopes]=\"scopes\" [(scope)]=\"scope\" [source]=\"crm\" />\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, and the record createEntity returns is chosen with reason submit.",
+      "language": "html",
+      "source": "<sl-entity-picker aria-label=\"Account\" [createEntity]=\"createAccount\" [source]=\"accounts\" />\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": "html",
+      "source": "<sl-entity-picker 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": "html",
+      "source": "<sl-entity-picker\n  aria-label=\"Watchers\"\n  selectionMode=\"multiple\"\n  [defaultValue]=\"['usr_marta', 'usr_deleted']\"\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": "html",
+      "source": "<sl-entity-picker 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.",
+      "language": "html",
+      "source": "<sl-entity-picker 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": "html",
+      "source": "<sl-entity-picker aria-label=\"Owner\" variant=\"plain\" [source]=\"directory\" />\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.",
+      "language": "html",
+      "source": "<sl-entity-picker aria-label=\"Owner\" disabled [source]=\"directory\" />\n<sl-entity-picker aria-label=\"Owner\" readOnly [source]=\"directory\" />\n<sl-entity-picker 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, and a token with no spaces breaks.",
+      "language": "html",
+      "source": "<sl-entity-picker aria-label=\"Watchers\" selectionMode=\"multiple\" [source]=\"international\" />\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": "html",
+      "source": "<sl-entity-picker aria-label=\"Reviewers\" selectionMode=\"multiple\" [source]=\"directory\" />\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "form",
+      "title": "In a form",
+      "note": "A deal form with Reactive Forms: the owner and the reviewers are form controls, required, and stand at the height of the fields beside them.",
+      "language": "html",
+      "source": "<sl-entity-picker\n  aria-label=\"Reviewers\"\n  required\n  selectionMode=\"multiple\"\n  [formControl]=\"reviewers\"\n  [source]=\"directory\"\n/>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition",
+      "note": "An option template adds the team after the address; a chip template adds the role; provideSlotted says every sentence in Portuguese once.",
+      "language": "html",
+      "source": "<sl-entity-picker aria-label=\"Reviewers\" selectionMode=\"multiple\" [source]=\"directory\">\n  <ng-template slEntityPickerOption let-person>\n    <span data-part=\"label\">{{ person.label }}</span>\n    <span data-part=\"description\">{{ person.description }} · Northwind</span>\n  </ng-template>\n  <ng-template slEntityPickerChip let-person>{{ person.label }} · {{ person.meta }}</ng-template>\n</sl-entity-picker>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}