{
  "version": "0.2.0-preview.1",
  "content_digest": "70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721",
  "status": "preview",
  "authority": {
    "repository": "cloakedinc/design",
    "path": "packages/design-system",
    "catalog": "packages/design-system/catalog.json",
    "status": "preview"
  },
  "provenance": {
    "repo": "cloakedinc/automation",
    "commit": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
    "path": "packages/design-system",
    "imported_spec_status": "approved"
  },
  "adaptations": [
    {
      "id": "button-content-gap",
      "status": "preview",
      "description": "Use the specification's 4px content gap instead of the inherited 8px implementation gap."
    },
    {
      "id": "keyboard-focus",
      "status": "preview",
      "description": "Add visible Button and Input keyboard focus and an overridable inset focus default for shared button resets, including FAQ cards and ListItem rows."
    },
    {
      "id": "supporting-text-contrast",
      "status": "preview",
      "description": "Map light secondary text to the existing grey-04-strong primitive for readable helper text on white and cream."
    },
    {
      "id": "danger-text-contrast",
      "status": "preview",
      "description": "Separate readable danger text/borders from destructive fills; preserve the primary danger-button fill and label pair."
    },
    {
      "id": "preview-status",
      "status": "preview",
      "description": "Local components, specs and token adaptations await human sign-off; upstream approved status is provenance only."
    },
    {
      "id": "motion-comparison-accessibility",
      "status": "preview",
      "description": "Preserve the original MotionShowcase comparisons while requiring explicit replay, responding to live reduced-motion changes, and keeping duration tracks usable on small screens."
    },
    {
      "id": "list-item-ownership",
      "status": "preview",
      "description": "List owns listitem wrappers for its content rows, while section labels stay outside the row count and standalone rows retain their existing semantics."
    },
    {
      "id": "card-delta-text-contrast",
      "status": "preview",
      "description": "Mix Card.Delta foregrounds from 60% existing tone solid and 40% primary text for readable contrast in both themes; preserve the four original tone fills."
    },
    {
      "id": "carousel-keyboard-access",
      "status": "preview",
      "description": "Keep all native-scrolling carousel slide controls exposed to assistive technology and keyboard navigation; pause autoplay while focus is inside the carousel."
    }
  ],
  "id": "autocomplete",
  "name": "Autocomplete",
  "category": "Forms",
  "summary": "A controlled search field with inline, sheet, or fullscreen result presentation and explicit loading, error, empty, and disabled states.",
  "documentation": {
    "summary": "A controlled search field with inline, sheet, or fullscreen result presentation and explicit loading, error, empty, and disabled states.",
    "guidance": [
      {
        "heading": "Overview",
        "body": "A controlled type-ahead field: a search input over a `role=\"listbox\"` of results. You own the\n`query` state, debouncing, and fetching, and feed it `items`; it renders the `loading`, `error`,\nand `emptyState` for you."
      },
      {
        "heading": "When to use",
        "body": "Reach for `Autocomplete` when the option set is too long or too dynamic to show at once and the\nuser needs to type to narrow it — broker search, address lookup, anything backed by a query. It is\npresentation only: fetching and filtering stay in the app.\n\n-   Short, fixed list of a handful of options? Use `Select` — no typing needed.\n-   A list of one-off commands rather than values to filter? That's a `Menu` (`selectionMode=\"none\"`).\n\n`error` and `emptyState` are distinct: `error` means the fetch failed, `emptyState` means it\nsucceeded with no matches. In-app it powers the address lookup in the data-removal profile\n(`AddressesField.tsx`), where it also joins keyboard next-field navigation."
      }
    ],
    "usage": [],
    "examples": [],
    "source": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.mdx",
    "status": "local-preview",
    "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification."
  },
  "source": {
    "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
    "code": "import React, { useId } from 'react';\nimport { cn } from '../../../utilities';\nimport { useHaptic } from '../../../hooks/useHaptic';\nimport type { HapticFeedback } from '../../../tokens/CdsHaptic';\nimport { Spinner } from '../../status/Spinner/Spinner';\nimport { Text } from '../../primitives/Text/Text';\nimport type { InputEnterBehavior, InputEnterKeyHint } from '../../primitives/Input/Input';\nimport { SearchField, type SearchFieldSurface } from '../SearchField/SearchField';\nimport styles from './Autocomplete.module.scss';\n\nexport type AutocompleteDisplayMode = 'inline' | 'sheet' | 'fullscreen';\nexport type AutocompleteSize = 'sm' | 'md';\nexport type AutocompleteSurface = SearchFieldSurface;\n\n/**\n * One result row. Rows hold no state of their own: the component never marks an item\n * as chosen, it only reports the tap through `onSelect`.\n */\nexport interface AutocompleteItem {\n    /** Identifies the row; used as the React key and as the `${testId}-${value}` suffix. */\n    value: string;\n    /** Primary row text, sized from `size`: `body-small` at `sm`, `body` at `md`. */\n    label: React.ReactNode;\n    /** Second line under the label, always `body-small`. */\n    description?: React.ReactNode;\n    /** Optional leading visual, usually an `Icon`, `Avatar`, or `SFIcon`. */\n    leading?: React.ReactNode;\n    /** Optional visual after the copy, e.g. a chevron or a count. */\n    trailing?: React.ReactNode;\n    /** Prevents this result from being selected. */\n    disabled?: boolean;\n}\n\n/**\n * Props for `Autocomplete`. The result list is always mounted below the field — there\n * is no popover, so it takes up layout space even while empty.\n */\nexport interface AutocompleteProps {\n    /** Text shown in the search field. Display only: `items` is never filtered by it. */\n    query: string;\n    /** Called with the new text on each keystroke, and with `''` when the clear action fires. */\n    onQueryChange: (query: string) => void;\n    /** Results to render, already filtered and ordered by the app. */\n    items: AutocompleteItem[];\n    /** Called with the tapped item. Disabled items never reach it. */\n    onSelect: (item: AutocompleteItem) => void;\n    /** Replaces the list with a spinner and sets `aria-busy`. Wins over `error` and `items`. */\n    loading?: boolean;\n    /** Error copy shown instead of results. */\n    error?: React.ReactNode;\n    /** Empty state shown when there are no results. */\n    emptyState?: React.ReactNode;\n    /** Result presentation mode. Defaults to `inline`. */\n    displayMode?: AutocompleteDisplayMode;\n    /** Placeholder in the search field. Defaults to `Search`. */\n    placeholder?: string;\n    /** Search field and result row size. */\n    size: AutocompleteSize;\n    /** Search field background treatment. Defaults to `default`; use `raised` inside a raised form. */\n    surface?: AutocompleteSurface;\n    /** Return-key behavior for the search field. Left unset, `SearchField`'s `callback` applies. */\n    enterBehavior?: InputEnterBehavior;\n    /** Native on-screen keyboard return key hint for the search field. */\n    enterKeyHint?: InputEnterKeyHint;\n    /** Accessible label for the search field. */\n    ariaLabel: string;\n    /** Prevents query and selection interaction. */\n    disabled?: boolean;\n    /** Haptic feedback for result selection. Defaults to `true` (`selection`). */\n    haptic?: HapticFeedback;\n    className?: string;\n    style?: React.CSSProperties;\n    /** Optional test selector. Result rows derive `${testId}-${item.value}`. */\n    testId?: string;\n}\n\n/**\n * Renders a controlled search + result picker. Data fetching and debouncing stay in the app.\n */\nexport function Autocomplete({\n    query,\n    onQueryChange,\n    items,\n    onSelect,\n    loading,\n    error,\n    emptyState = 'No results found.',\n    displayMode = 'inline',\n    placeholder = 'Search',\n    size,\n    surface = 'default',\n    enterBehavior,\n    enterKeyHint,\n    ariaLabel,\n    disabled,\n    haptic = true,\n    className,\n    style,\n    testId,\n}: AutocompleteProps) {\n    const generatedId = useId();\n    const listboxId = `${testId ?? generatedId}-results`;\n    const fireHaptic = useHaptic('selection');\n\n    const handleSelect = (item: AutocompleteItem) => {\n        if (item.disabled) return;\n        fireHaptic(haptic);\n        onSelect(item);\n    };\n\n    return (\n        <div className={cn(styles.autocomplete, styles[`size-${size}`], className)} style={style} data-testid={testId}>\n            <SearchField\n                value={query}\n                onChange={onQueryChange}\n                placeholder={placeholder}\n                size={size}\n                surface={surface}\n                enterBehavior={enterBehavior}\n                enterKeyHint={enterKeyHint}\n                loading={loading}\n                disabled={disabled}\n                ariaLabel={ariaLabel}\n                ariaControls={listboxId}\n                testId={testId ? `${testId}-search` : undefined}\n            />\n            <div\n                id={listboxId}\n                className={cn(styles.results, styles[`mode-${displayMode}`])}\n                role='listbox'\n                aria-label={`${ariaLabel} results`}\n                aria-busy={loading || undefined}\n                data-testid={testId ? `${testId}-results` : undefined}\n            >\n                {renderResults({ items, loading, error, emptyState, size, disabled, onSelect: handleSelect, testId })}\n            </div>\n        </div>\n    );\n}\n\ninterface RenderResultsInput {\n    items: AutocompleteItem[];\n    loading?: boolean;\n    error?: React.ReactNode;\n    emptyState: React.ReactNode;\n    size: AutocompleteSize;\n    disabled?: boolean;\n    onSelect: (item: AutocompleteItem) => void;\n    testId?: string;\n}\n\nfunction renderResults({ items, loading, error, emptyState, size, disabled, onSelect, testId }: RenderResultsInput) {\n    if (loading) {\n        return (\n            <div className={styles.feedback}>\n                <Spinner size='sm' tone='primary' ariaLabel='Loading results' />\n                <Text variant='body-small' color='secondary'>\n                    Loading results\n                </Text>\n            </div>\n        );\n    }\n\n    if (error) {\n        return (\n            <Text variant='body-small' color='danger' className={styles.feedback}>\n                {error}\n            </Text>\n        );\n    }\n\n    if (items.length === 0) {\n        return (\n            <Text variant='body-small' color='secondary' className={styles.feedback}>\n                {emptyState}\n            </Text>\n        );\n    }\n\n    return items.map(item => (\n        <button\n            key={item.value}\n            type='button'\n            className={styles.option}\n            role='option'\n            aria-selected={false}\n            disabled={disabled || item.disabled}\n            onClick={() => onSelect(item)}\n            data-testid={testId ? `${testId}-${item.value}` : undefined}\n        >\n            {item.leading && <span className={styles.leading}>{item.leading}</span>}\n            <span className={styles.copy}>\n                <Text variant={size === 'sm' ? 'body-small' : 'body'} color='primary' className={styles.label}>\n                    {item.label}\n                </Text>\n                {item.description && (\n                    <Text variant='body-small' color='secondary' className={styles.description}>\n                        {item.description}\n                    </Text>\n                )}\n            </span>\n            {item.trailing && <span className={styles.trailing}>{item.trailing}</span>}\n        </button>\n    ));\n}\n"
  },
  "spec": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "Autocomplete",
      "status": "preview",
      "version": "1.1.0",
      "summary": "A controlled search field with inline, sheet, or fullscreen result presentation and explicit loading, error, empty, and disabled states."
    },
    "parts": [
      {
        "id": "root",
        "label": "Root",
        "description": "Stacks the search field and result surface at the selected density."
      },
      {
        "id": "search-field",
        "label": "Search field",
        "description": "Owns the query, search semantics, loading indicator, clear action, and the surface treatment."
      },
      {
        "id": "result-surface",
        "label": "Result surface",
        "description": "Provides the labelled listbox and selected display mode."
      },
      {
        "id": "option",
        "label": "Option",
        "description": "Pressable result row with optional leading, description, and trailing content."
      },
      {
        "id": "feedback",
        "label": "Feedback",
        "description": "Replaces options with loading, error, or empty-state content."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "base": {
          "label": "Base",
          "description": "One controlled search-and-pick pattern configured through mode and size axes."
        }
      },
      "sizes": {
        "sm": {
          "label": "Small"
        },
        "md": {
          "label": "Medium"
        }
      },
      "modes": {
        "inline": {
          "label": "Inline",
          "description": "Keeps a bounded result list directly below the search field."
        },
        "sheet": {
          "label": "Sheet",
          "description": "Uses a taller result surface with top-only rounding for sheet composition."
        },
        "fullscreen": {
          "label": "Fullscreen",
          "description": "Uses an unrounded, minimum-height result surface for a full-screen composition."
        }
      }
    },
    "variants": [
      {
        "id": "base",
        "label": "Base",
        "description": "Controlled search and listbox composition with mode, size, and async feedback kept orthogonal.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [
      {
        "id": "sm",
        "label": "Small",
        "description": "Compact search shell, 4-unit stack gap, and tighter result-row padding."
      },
      {
        "id": "md",
        "label": "Medium",
        "description": "Standard search shell, 8-unit stack gap, and roomier result rows."
      }
    ],
    "measurements": [
      {
        "id": "small-stack-gap",
        "label": "Small search-to-results gap",
        "kind": "exact",
        "token": "--cds-space-4",
        "value": 4,
        "unit": "px",
        "appliesTo": [
          "root",
          "sm"
        ]
      },
      {
        "id": "medium-stack-gap",
        "label": "Medium search-to-results gap",
        "kind": "exact",
        "token": "--cds-space-8",
        "value": 8,
        "unit": "px",
        "appliesTo": [
          "root",
          "md"
        ]
      },
      {
        "id": "medium-option-horizontal-padding",
        "label": "Medium option horizontal padding",
        "kind": "exact",
        "token": "--cds-space-16",
        "value": 16,
        "unit": "px",
        "appliesTo": [
          "option",
          "md"
        ]
      }
    ],
    "layout": {
      "alignment": "The search field and result surface fill the root width; option visuals align to the row start.",
      "flow": "Search field precedes one listbox whose contents are options or a single feedback state.",
      "notes": [
        "Keep data fetching and debouncing outside the component.",
        "Leading and trailing option content never consume the flexible copy column."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Option label",
          "description": "Medium rows use body text; compact rows use body-small text.",
          "token": "--cds-type-body-size"
        }
      ],
      "colors": [
        {
          "label": "Result surface",
          "description": "Uses the raised semantic surface.",
          "token": "--cds-bg-surface"
        },
        {
          "label": "Primary copy",
          "description": "Uses primary text emphasis for option labels.",
          "token": "--cds-text-primary"
        },
        {
          "label": "Secondary copy",
          "description": "Uses secondary emphasis for descriptions and neutral feedback.",
          "token": "--cds-text-secondary"
        },
        {
          "label": "Error copy",
          "description": "Uses the semantic danger text role.",
          "token": "--cds-status-danger-solid"
        }
      ]
    },
    "states": [
      {
        "id": "results",
        "label": "Results",
        "description": "Shows enabled and disabled options for the current query."
      },
      {
        "id": "loading",
        "label": "Loading",
        "description": "Marks the listbox busy and replaces options with a labelled spinner."
      },
      {
        "id": "empty",
        "label": "Empty",
        "description": "Shows calm no-results copy after a successful query with no matches."
      },
      {
        "id": "error",
        "label": "Error",
        "description": "Shows failure copy instead of empty-state copy or stale results."
      },
      {
        "id": "disabled",
        "label": "Disabled",
        "description": "Blocks query editing and every option press."
      }
    ],
    "behavior": [
      {
        "label": "Controlled query",
        "description": "Request each query update while the parent owns filtering, fetching, and the rendered query."
      },
      {
        "label": "Selection",
        "description": "Emit the complete selected item exactly once and ignore disabled options."
      },
      {
        "label": "Presentation modes",
        "description": "Change only result-surface composition; mode does not alter search or selection semantics."
      },
      {
        "label": "Surface treatment",
        "description": "The search field forwards a surface treatment (default or raised). Use raised inside a raised form so the field reads as an input rather than blending into the container."
      }
    ],
    "accessibility": [
      {
        "label": "Search name",
        "description": "Require a stable accessible name for the search field."
      },
      {
        "label": "Result relationship",
        "description": "Connect the search field to the labelled listbox and expose busy state during loading."
      },
      {
        "label": "Options",
        "description": "Expose each result as an option and preserve native disabled behavior."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Long result copy",
        "description": "Allow labels and descriptions to wrap within the flexible copy column."
      },
      {
        "label": "Distinct feedback",
        "description": "Use empty copy only for successful zero-result queries and error copy only for failures."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "Stable replacement",
          "description": "Replace result and feedback content without moving the search field."
        }
      ],
      "haptics": [
        {
          "label": "Selection feedback",
          "description": "Request the selection haptic after an enabled option is chosen."
        }
      ]
    },
    "platformDifferences": [
      {
        "platforms": [
          "ios",
          "android"
        ],
        "description": "Sheet and fullscreen modes should use the host platform presentation container while web applies the documented result-surface geometry in place.",
        "rationale": "The interaction contract is shared, but native containers provide expected focus, keyboard, and dismissal behavior."
      }
    ]
  },
  "spec_source": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.spec.json",
  "guidance_source": {
    "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.mdx",
    "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec } from '../../../../.storybook/blocks';\nimport * as Stories from './Autocomplete.stories';\nimport autocompleteSpec from './Autocomplete.spec.json';\n\n<Meta of={Stories} />\n\n# Autocomplete\n\nA controlled type-ahead field: a search input over a `role=\"listbox\"` of results. You own the\n`query` state, debouncing, and fetching, and feed it `items`; it renders the `loading`, `error`,\nand `emptyState` for you.\n\n<Canvas of={Stories.Playground} />\n\n## When to use\n\nReach for `Autocomplete` when the option set is too long or too dynamic to show at once and the\nuser needs to type to narrow it — broker search, address lookup, anything backed by a query. It is\npresentation only: fetching and filtering stay in the app.\n\n-   Short, fixed list of a handful of options? Use `Select` — no typing needed.\n-   A list of one-off commands rather than values to filter? That's a `Menu` (`selectionMode=\"none\"`).\n\n`error` and `emptyState` are distinct: `error` means the fetch failed, `emptyState` means it\nsucceeded with no matches. In-app it powers the address lookup in the data-removal profile\n(`AddressesField.tsx`), where it also joins keyboard next-field navigation.\n\n<Canvas of={Stories.Empty} />\n\n## Design Guidelines\n\n<ComponentSpec spec={autocompleteSpec} />\n\n## Props\n\n<Controls of={Stories.Playground} />\n"
  },
  "props": [
    {
      "name": "query",
      "type": "string",
      "declared_type": "string",
      "required": true,
      "description": "Text shown in the search field. Display only: `items` is never filtered by it.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 40
      }
    },
    {
      "name": "onQueryChange",
      "type": "(query: string) => void",
      "declared_type": "(query: string) => void",
      "required": true,
      "description": "Called with the new text on each keystroke, and with `''` when the clear action fires.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 42
      }
    },
    {
      "name": "items",
      "type": "AutocompleteItem[]",
      "declared_type": "AutocompleteItem[]",
      "required": true,
      "description": "Results to render, already filtered and ordered by the app.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 44
      }
    },
    {
      "name": "onSelect",
      "type": "(item: AutocompleteItem) => void",
      "declared_type": "(item: AutocompleteItem) => void",
      "required": true,
      "description": "Called with the tapped item. Disabled items never reach it.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 46
      }
    },
    {
      "name": "loading",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Replaces the list with a spinner and sets `aria-busy`. Wins over `error` and `items`.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 48
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "error",
      "type": "React.ReactNode",
      "declared_type": "React.ReactNode",
      "required": false,
      "description": "Error copy shown instead of results.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 50
      }
    },
    {
      "name": "emptyState",
      "type": "React.ReactNode",
      "declared_type": "React.ReactNode",
      "required": false,
      "description": "Empty state shown when there are no results.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 52
      },
      "default": "'No results found.'",
      "default_kind": "source-expression"
    },
    {
      "name": "displayMode",
      "type": "AutocompleteDisplayMode | undefined",
      "declared_type": "AutocompleteDisplayMode",
      "required": false,
      "description": "Result presentation mode. Defaults to `inline`.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 54
      },
      "values": [
        "fullscreen",
        "inline",
        "sheet"
      ],
      "values_complete": true,
      "default": "'inline'",
      "default_kind": "source-expression"
    },
    {
      "name": "placeholder",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Placeholder in the search field. Defaults to `Search`.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 56
      },
      "default": "'Search'",
      "default_kind": "source-expression"
    },
    {
      "name": "size",
      "type": "AutocompleteSize",
      "declared_type": "AutocompleteSize",
      "required": true,
      "description": "Search field and result row size.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 58
      },
      "values": [
        "md",
        "sm"
      ],
      "values_complete": true
    },
    {
      "name": "surface",
      "type": "import(\"@cloakedinc/design-system\").InputSurface | undefined",
      "declared_type": "AutocompleteSurface",
      "required": false,
      "description": "Search field background treatment. Defaults to `default`; use `raised` inside a raised form.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 60
      },
      "values": [
        "default",
        "raised"
      ],
      "values_complete": true,
      "default": "'default'",
      "default_kind": "source-expression"
    },
    {
      "name": "enterBehavior",
      "type": "InputEnterBehavior | undefined",
      "declared_type": "InputEnterBehavior",
      "required": false,
      "description": "Return-key behavior for the search field. Left unset, `SearchField`'s `callback` applies.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 62
      },
      "values": [
        "advance",
        "callback"
      ],
      "values_complete": true
    },
    {
      "name": "enterKeyHint",
      "type": "InputEnterKeyHint | undefined",
      "declared_type": "InputEnterKeyHint",
      "required": false,
      "description": "Native on-screen keyboard return key hint for the search field.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 64
      },
      "values": [
        "done",
        "enter",
        "go",
        "next",
        "previous",
        "search",
        "send"
      ],
      "values_complete": true
    },
    {
      "name": "ariaLabel",
      "type": "string",
      "declared_type": "string",
      "required": true,
      "description": "Accessible label for the search field.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 66
      }
    },
    {
      "name": "disabled",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Prevents query and selection interaction.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 68
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "haptic",
      "type": "HapticFeedback | undefined",
      "declared_type": "HapticFeedback",
      "required": false,
      "description": "Haptic feedback for result selection. Defaults to `true` (`selection`).",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 70
      },
      "values": [
        "error",
        "heavy",
        "light",
        "medium",
        "selection",
        "success",
        "warning",
        false,
        true
      ],
      "values_complete": true,
      "default": "true",
      "default_kind": "source-expression"
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 71
      }
    },
    {
      "name": "style",
      "type": "React.CSSProperties | undefined",
      "declared_type": "React.CSSProperties",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 72
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Optional test selector. Result rows derive `${testId}-${item.value}`.",
      "source": {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 74
      }
    }
  ],
  "prop_shapes": {},
  "examples": [],
  "tokens": [
    {
      "name": "--cds-space-4",
      "light": "4px",
      "dark": "4px"
    },
    {
      "name": "--cds-space-8",
      "light": "8px",
      "dark": "8px"
    },
    {
      "name": "--cds-space-16",
      "light": "16px",
      "dark": "16px"
    },
    {
      "name": "--cds-type-body-size",
      "light": "1rem",
      "dark": "1rem"
    },
    {
      "name": "--cds-bg-surface",
      "light": "#ffffff",
      "dark": "#1b1b18"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    },
    {
      "name": "--cds-text-secondary",
      "light": "#646260",
      "dark": "#ffffff99"
    },
    {
      "name": "--cds-status-danger-solid",
      "light": "#b83100",
      "dark": "#b83100"
    }
  ],
  "visual_reference": {
    "stories": [
      {
        "id": "cloaked-design-system-forms-autocomplete--playground",
        "name": "Playground",
        "title": "Cloaked Design System/Forms/Autocomplete",
        "exportName": "Playground",
        "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
        "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--playground&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-autocomplete--display-modes",
        "name": "Display Modes",
        "title": "Cloaked Design System/Forms/Autocomplete",
        "exportName": "DisplayModes",
        "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
        "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--display-modes&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-autocomplete--loading",
        "name": "Loading",
        "title": "Cloaked Design System/Forms/Autocomplete",
        "exportName": "Loading",
        "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
        "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--loading&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-autocomplete--empty",
        "name": "Empty",
        "title": "Cloaked Design System/Forms/Autocomplete",
        "exportName": "Empty",
        "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
        "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--empty&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-autocomplete--error",
        "name": "Error",
        "title": "Cloaked Design System/Forms/Autocomplete",
        "exportName": "Error",
        "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
        "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--error&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-autocomplete--disabled",
        "name": "Disabled",
        "title": "Cloaked Design System/Forms/Autocomplete",
        "exportName": "Disabled",
        "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
        "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--disabled&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-autocomplete--address-form-flow",
        "name": "Address Form Flow",
        "title": "Cloaked Design System/Forms/Autocomplete",
        "exportName": "AddressFormFlow",
        "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
        "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--address-form-flow&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-autocomplete--dark-theme",
        "name": "Dark Theme",
        "title": "Cloaked Design System/Forms/Autocomplete",
        "exportName": "DarkTheme",
        "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
        "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--dark-theme&viewMode=story"
      }
    ],
    "name": "Autocomplete",
    "id": "autocomplete",
    "category": "Forms"
  },
  "stories": [
    {
      "id": "cloaked-design-system-forms-autocomplete--playground",
      "name": "Playground",
      "title": "Cloaked Design System/Forms/Autocomplete",
      "exportName": "Playground",
      "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
      "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
      "status": "preview",
      "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--playground&viewMode=story"
    },
    {
      "id": "cloaked-design-system-forms-autocomplete--display-modes",
      "name": "Display Modes",
      "title": "Cloaked Design System/Forms/Autocomplete",
      "exportName": "DisplayModes",
      "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
      "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
      "status": "preview",
      "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--display-modes&viewMode=story"
    },
    {
      "id": "cloaked-design-system-forms-autocomplete--loading",
      "name": "Loading",
      "title": "Cloaked Design System/Forms/Autocomplete",
      "exportName": "Loading",
      "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
      "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
      "status": "preview",
      "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--loading&viewMode=story"
    },
    {
      "id": "cloaked-design-system-forms-autocomplete--empty",
      "name": "Empty",
      "title": "Cloaked Design System/Forms/Autocomplete",
      "exportName": "Empty",
      "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
      "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
      "status": "preview",
      "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--empty&viewMode=story"
    },
    {
      "id": "cloaked-design-system-forms-autocomplete--error",
      "name": "Error",
      "title": "Cloaked Design System/Forms/Autocomplete",
      "exportName": "Error",
      "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
      "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
      "status": "preview",
      "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--error&viewMode=story"
    },
    {
      "id": "cloaked-design-system-forms-autocomplete--disabled",
      "name": "Disabled",
      "title": "Cloaked Design System/Forms/Autocomplete",
      "exportName": "Disabled",
      "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
      "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
      "status": "preview",
      "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--disabled&viewMode=story"
    },
    {
      "id": "cloaked-design-system-forms-autocomplete--address-form-flow",
      "name": "Address Form Flow",
      "title": "Cloaked Design System/Forms/Autocomplete",
      "exportName": "AddressFormFlow",
      "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
      "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
      "status": "preview",
      "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--address-form-flow&viewMode=story"
    },
    {
      "id": "cloaked-design-system-forms-autocomplete--dark-theme",
      "name": "Dark Theme",
      "title": "Cloaked Design System/Forms/Autocomplete",
      "exportName": "DarkTheme",
      "source_path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
      "source_digest": "73583d057e32dd2b4714c1919b5f48fb6657b32a34687aefce2ad05e6dcecf3b",
      "status": "preview",
      "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-autocomplete--dark-theme&viewMode=story"
    }
  ],
  "stories_source": {
    "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.stories.tsx",
    "code": "import React, { useMemo, useState } from 'react';\nimport type { ComponentProps } from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { HStack } from '../../layout/HStack/HStack';\nimport { Button } from '../../primitives/Button/Button';\nimport { Icon } from '../../primitives/Icon/Icon';\nimport { Input } from '../../primitives/Input/Input';\nimport { Tag } from '../../primitives/Tag/Tag';\nimport { Text } from '../../primitives/Text/Text';\nimport { disabledControl, selectArgType } from '../../../storybook/controlOptions';\nimport { Autocomplete, type AutocompleteItem, type AutocompleteSize } from './Autocomplete';\n\nconst AUTOCOMPLETE_SIZES = ['sm', 'md'] as const satisfies readonly AutocompleteSize[];\n\nconst BROKERS: AutocompleteItem[] = [\n    {\n        value: 'acme',\n        label: 'Acme Data',\n        description: 'Data broker',\n        leading: <Icon name='search' size='small' />,\n        trailing: (\n            <Tag tone='neutral' emphasis='subtle'>\n                12\n            </Tag>\n        ),\n    },\n    {\n        value: 'atlas',\n        label: 'Atlas Search',\n        description: 'People search site',\n        leading: <Icon name='search' size='small' />,\n    },\n    {\n        value: 'locked',\n        label: 'Locked result',\n        description: 'Disabled row',\n        disabled: true,\n    },\n];\n\nconst meta: Meta<typeof Autocomplete> = {\n    title: 'Cloaked Design System/Forms/Autocomplete',\n    component: Autocomplete,\n    parameters: {\n        a11y: { test: 'error' },\n        stage: 'form-control',\n        docs: {\n            description: {\n                component:\n                    'A controlled search-and-pick field: a `SearchField` over a `role=\"listbox\"` of results. It is ' +\n                    'presentation only — you own the `query` state, debouncing, and fetching, and feed it `items`; it ' +\n                    'renders `loading`, `error`, and `emptyState` for you. Use it when the option set is too long to ' +\n                    'show at once (broker search, address lookup); use `Select` for a short fixed list. `error` and ' +\n                    '`emptyState` are distinct: `error` means the fetch failed, `emptyState` means it succeeded with ' +\n                    'no matches. Result rows and the search input derive their test ids from `testId` — a ' +\n                    'per-item value suffix on each row and a `-search` suffix on the input.',\n            },\n        },\n    },\n    args: {\n        query: '',\n        size: 'sm',\n        items: BROKERS,\n        ariaLabel: 'Broker search',\n        testId: 'autocomplete-story',\n    },\n    argTypes: {\n        onQueryChange: { ...disabledControl, description: 'Called with the next query string on each edit.' },\n        onSelect: { ...disabledControl, description: 'Called with the chosen `AutocompleteItem`.' },\n        items: { ...disabledControl, description: 'Results to render for the current query; you filter/fetch these.' },\n        emptyState: { ...disabledControl, description: 'Shown when the fetch succeeded but `items` is empty.' },\n        size: { ...selectArgType(AUTOCOMPLETE_SIZES), description: 'Search field and result-row size: `sm` vs `md`.' },\n        displayMode: {\n            ...selectArgType(['inline', 'sheet', 'fullscreen']),\n            description: 'Result presentation: `inline` under the field, `sheet`, or `fullscreen`.',\n        },\n        query: { control: 'text', description: 'Current query string (controlled by you).' },\n        placeholder: { control: 'text', description: 'Search field placeholder.' },\n        error: { control: 'text', description: 'Failure copy shown instead of results (distinct from `emptyState`).' },\n        loading: { control: 'boolean', description: 'Shows the loading state while results fetch.' },\n        disabled: { control: 'boolean', description: 'Blocks query and selection across the whole control.' },\n    },\n};\n\nexport default meta;\n\ntype Story = StoryObj<typeof Autocomplete>;\n\n/** Controlled autocomplete playground with local filtering only for the story. */\nfunction ControlledAutocomplete(args: ComponentProps<typeof Autocomplete>) {\n    const [query, setQuery] = useState(args.query);\n    const filteredItems = useMemo(\n        () => BROKERS.filter(item => String(item.label).toLowerCase().includes(query.toLowerCase())),\n        [query]\n    );\n\n    return (\n        <Autocomplete\n            {...args}\n            query={query}\n            onQueryChange={setQuery}\n            items={filteredItems}\n            onSelect={item => setQuery(String(item.label))}\n        />\n    );\n}\n\n/** Address-style form where autocomplete participates in keyboard next-field navigation. */\nfunction AddressAutocompleteForm() {\n    const [street, setStreet] = useState('');\n    const [suite, setSuite] = useState('');\n    const [zip, setZip] = useState('');\n    const [city, setCity] = useState('');\n    const [status, setStatus] = useState('Use return to move from Street Address to Suite/Apt.');\n    const addressItems = useMemo(\n        () =>\n            [\n                { value: 'main', label: '123 Main St', description: 'Boston, MA 02109' },\n                { value: 'market', label: '45 Market St', description: 'Boston, MA 02110' },\n            ].filter(item => item.label.toLowerCase().includes(street.toLowerCase())),\n        [street]\n    );\n\n    const handleSubmit = () => {\n        setStatus(`Submitted ${street || 'address'}${suite ? `, ${suite}` : ''}.`);\n    };\n\n    return (\n        <form\n            data-cds-form-scope\n            style={{ display: 'flex', flexDirection: 'column', gap: 'var(--cds-space-12)', width: 320 }}\n            onSubmit={event => event.preventDefault()}\n        >\n            <Autocomplete\n                query={street}\n                onQueryChange={setStreet}\n                items={addressItems}\n                onSelect={item => setStreet(String(item.label))}\n                displayMode='inline'\n                placeholder='123 Main St'\n                size='md'\n                ariaLabel='Street address'\n                enterBehavior='advance'\n                enterKeyHint='next'\n                testId='autocomplete-story-address-street'\n            />\n            <Input\n                value={suite}\n                onChange={setSuite}\n                placeholder='Apt 16B'\n                ariaLabel='Suite or apartment'\n                enterKeyHint='next'\n                testId='autocomplete-story-address-suite'\n            />\n            <Input\n                value={zip}\n                onChange={setZip}\n                placeholder='02109'\n                ariaLabel='ZIP code'\n                inputMode='numeric'\n                enterKeyHint='next'\n                testId='autocomplete-story-address-zip'\n            />\n            <Input\n                value={city}\n                onChange={setCity}\n                placeholder='Boston'\n                ariaLabel='City'\n                enterBehavior='callback'\n                enterKeyHint='done'\n                onEnter={handleSubmit}\n                testId='autocomplete-story-address-city'\n            />\n            <Button\n                variant='primary'\n                size='sm'\n                onPress={handleSubmit}\n                disabled={!street && !suite && !zip && !city}\n                testId='autocomplete-story-address-submit'\n            >\n                Add Address\n            </Button>\n            <Text variant='body-small' color='secondary'>\n                {status}\n            </Text>\n        </form>\n    );\n}\n\nexport const Playground: Story = {\n    render: args => <ControlledAutocomplete {...args} />,\n};\n\nexport const DisplayModes: Story = {\n    parameters: {\n        docs: { description: { story: 'The three `displayMode` presentations: `inline`, `sheet`, and `fullscreen`.' } },\n    },\n    render: args => (\n        <HStack gap={16} wrap>\n            {(['inline', 'sheet', 'fullscreen'] as const).map(displayMode => (\n                <div key={displayMode} style={{ width: 280 }}>\n                    <Autocomplete\n                        {...args}\n                        displayMode={displayMode}\n                        onQueryChange={() => {}}\n                        onSelect={() => {}}\n                        testId={`autocomplete-mode-${displayMode}`}\n                    />\n                </div>\n            ))}\n        </HStack>\n    ),\n};\n\nexport const Loading: Story = {\n    parameters: {\n        docs: { description: { story: 'Loading state while results fetch — the spinner replaces the result list.' } },\n    },\n    args: {\n        query: 'acme',\n        items: [],\n        loading: true,\n        onQueryChange: () => {},\n        onSelect: () => {},\n        testId: 'autocomplete-loading',\n    },\n};\n\nexport const Empty: Story = {\n    parameters: {\n        docs: { description: { story: 'Fetch succeeded with no matches — shows `emptyState`, not an error.' } },\n    },\n    args: {\n        query: 'zzz',\n        items: [],\n        emptyState: 'No brokers match this search.',\n        onQueryChange: () => {},\n        onSelect: () => {},\n        testId: 'autocomplete-empty',\n    },\n};\n\nexport const Error: Story = {\n    parameters: {\n        docs: {\n            description: { story: 'Fetch failed — `error` copy replaces results (distinct from the empty state).' },\n        },\n    },\n    args: {\n        query: 'acme',\n        items: [],\n        error: 'Could not load results. Check your connection and try again.',\n        onQueryChange: () => {},\n        onSelect: () => {},\n        testId: 'autocomplete-error',\n    },\n};\n\nexport const Disabled: Story = {\n    parameters: {\n        docs: { description: { story: 'Whole control disabled: the field and every result row are non-interactive.' } },\n    },\n    args: {\n        query: 'a',\n        disabled: true,\n        onQueryChange: () => {},\n        onSelect: () => {},\n        testId: 'autocomplete-disabled',\n    },\n};\n\nexport const AddressFormFlow: Story = {\n    parameters: {\n        docs: { description: { story: 'Autocomplete inside a form, joining return-key next-field navigation.' } },\n    },\n    render: () => <AddressAutocompleteForm />,\n};\n\nexport const DarkTheme: Story = {\n    globals: { theme: 'dark' },\n    parameters: { docs: { description: { story: 'Field and result-row tokens on the dark theme.' } } },\n    render: args => <ControlledAutocomplete {...args} query='a' testId='autocomplete-dark' />,\n};\n"
  },
  "links": {
    "human": "/component-autocomplete",
    "json": "/data/components/autocomplete.json",
    "markdown": "/data/components/autocomplete.md",
    "storybook": "/storybook/?path=/story/cloaked-design-system-forms-autocomplete--playground"
  },
  "contract_status": "preview",
  "contract_kind": "source-derived",
  "approval": "required",
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "Autocomplete",
    "public_path": "Autocomplete",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "Autocomplete",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
          "line": 80
        },
        "props_type": "AutocompleteProps",
        "props": [
          {
            "name": "query",
            "type": "string",
            "declared_type": "string",
            "required": true,
            "description": "Text shown in the search field. Display only: `items` is never filtered by it.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 40
            }
          },
          {
            "name": "onQueryChange",
            "type": "(query: string) => void",
            "declared_type": "(query: string) => void",
            "required": true,
            "description": "Called with the new text on each keystroke, and with `''` when the clear action fires.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 42
            }
          },
          {
            "name": "items",
            "type": "AutocompleteItem[]",
            "declared_type": "AutocompleteItem[]",
            "required": true,
            "description": "Results to render, already filtered and ordered by the app.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 44
            }
          },
          {
            "name": "onSelect",
            "type": "(item: AutocompleteItem) => void",
            "declared_type": "(item: AutocompleteItem) => void",
            "required": true,
            "description": "Called with the tapped item. Disabled items never reach it.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 46
            }
          },
          {
            "name": "loading",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Replaces the list with a spinner and sets `aria-busy`. Wins over `error` and `items`.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 48
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "error",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": false,
            "description": "Error copy shown instead of results.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 50
            }
          },
          {
            "name": "emptyState",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": false,
            "description": "Empty state shown when there are no results.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 52
            },
            "default": "'No results found.'",
            "default_kind": "source-expression"
          },
          {
            "name": "displayMode",
            "type": "AutocompleteDisplayMode | undefined",
            "declared_type": "AutocompleteDisplayMode",
            "required": false,
            "description": "Result presentation mode. Defaults to `inline`.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 54
            },
            "values": [
              "fullscreen",
              "inline",
              "sheet"
            ],
            "values_complete": true,
            "default": "'inline'",
            "default_kind": "source-expression"
          },
          {
            "name": "placeholder",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Placeholder in the search field. Defaults to `Search`.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 56
            },
            "default": "'Search'",
            "default_kind": "source-expression"
          },
          {
            "name": "size",
            "type": "AutocompleteSize",
            "declared_type": "AutocompleteSize",
            "required": true,
            "description": "Search field and result row size.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 58
            },
            "values": [
              "md",
              "sm"
            ],
            "values_complete": true
          },
          {
            "name": "surface",
            "type": "import(\"@cloakedinc/design-system\").InputSurface | undefined",
            "declared_type": "AutocompleteSurface",
            "required": false,
            "description": "Search field background treatment. Defaults to `default`; use `raised` inside a raised form.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 60
            },
            "values": [
              "default",
              "raised"
            ],
            "values_complete": true,
            "default": "'default'",
            "default_kind": "source-expression"
          },
          {
            "name": "enterBehavior",
            "type": "InputEnterBehavior | undefined",
            "declared_type": "InputEnterBehavior",
            "required": false,
            "description": "Return-key behavior for the search field. Left unset, `SearchField`'s `callback` applies.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 62
            },
            "values": [
              "advance",
              "callback"
            ],
            "values_complete": true
          },
          {
            "name": "enterKeyHint",
            "type": "InputEnterKeyHint | undefined",
            "declared_type": "InputEnterKeyHint",
            "required": false,
            "description": "Native on-screen keyboard return key hint for the search field.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 64
            },
            "values": [
              "done",
              "enter",
              "go",
              "next",
              "previous",
              "search",
              "send"
            ],
            "values_complete": true
          },
          {
            "name": "ariaLabel",
            "type": "string",
            "declared_type": "string",
            "required": true,
            "description": "Accessible label for the search field.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 66
            }
          },
          {
            "name": "disabled",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Prevents query and selection interaction.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 68
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "haptic",
            "type": "HapticFeedback | undefined",
            "declared_type": "HapticFeedback",
            "required": false,
            "description": "Haptic feedback for result selection. Defaults to `true` (`selection`).",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 70
            },
            "values": [
              "error",
              "heavy",
              "light",
              "medium",
              "selection",
              "success",
              "warning",
              false,
              true
            ],
            "values_complete": true,
            "default": "true",
            "default_kind": "source-expression"
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 71
            }
          },
          {
            "name": "style",
            "type": "React.CSSProperties | undefined",
            "declared_type": "React.CSSProperties",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 72
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Optional test selector. Result rows derive `${testId}-${item.value}`.",
            "source": {
              "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
              "line": 74
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 11,
        "name": "AutocompleteDisplayMode",
        "code": "export type AutocompleteDisplayMode = 'inline' | 'sheet' | 'fullscreen';"
      },
      {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 12,
        "name": "AutocompleteSize",
        "code": "export type AutocompleteSize = 'sm' | 'md';"
      },
      {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 13,
        "name": "AutocompleteSurface",
        "code": "export type AutocompleteSurface = SearchFieldSurface;"
      },
      {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 19,
        "name": "AutocompleteItem",
        "code": "export interface AutocompleteItem {\n    /** Identifies the row; used as the React key and as the `${testId}-${value}` suffix. */\n    value: string;\n    /** Primary row text, sized from `size`: `body-small` at `sm`, `body` at `md`. */\n    label: React.ReactNode;\n    /** Second line under the label, always `body-small`. */\n    description?: React.ReactNode;\n    /** Optional leading visual, usually an `Icon`, `Avatar`, or `SFIcon`. */\n    leading?: React.ReactNode;\n    /** Optional visual after the copy, e.g. a chevron or a count. */\n    trailing?: React.ReactNode;\n    /** Prevents this result from being selected. */\n    disabled?: boolean;\n}"
      },
      {
        "path": "packages/design-system/src/components/forms/Autocomplete/Autocomplete.tsx",
        "line": 38,
        "name": "AutocompleteProps",
        "code": "export interface AutocompleteProps {\n    /** Text shown in the search field. Display only: `items` is never filtered by it. */\n    query: string;\n    /** Called with the new text on each keystroke, and with `''` when the clear action fires. */\n    onQueryChange: (query: string) => void;\n    /** Results to render, already filtered and ordered by the app. */\n    items: AutocompleteItem[];\n    /** Called with the tapped item. Disabled items never reach it. */\n    onSelect: (item: AutocompleteItem) => void;\n    /** Replaces the list with a spinner and sets `aria-busy`. Wins over `error` and `items`. */\n    loading?: boolean;\n    /** Error copy shown instead of results. */\n    error?: React.ReactNode;\n    /** Empty state shown when there are no results. */\n    emptyState?: React.ReactNode;\n    /** Result presentation mode. Defaults to `inline`. */\n    displayMode?: AutocompleteDisplayMode;\n    /** Placeholder in the search field. Defaults to `Search`. */\n    placeholder?: string;\n    /** Search field and result row size. */\n    size: AutocompleteSize;\n    /** Search field background treatment. Defaults to `default`; use `raised` inside a raised form. */\n    surface?: AutocompleteSurface;\n    /** Return-key behavior for the search field. Left unset, `SearchField`'s `callback` applies. */\n    enterBehavior?: InputEnterBehavior;\n    /** Native on-screen keyboard return key hint for the search field. */\n    enterKeyHint?: InputEnterKeyHint;\n    /** Accessible label for the search field. */\n    ariaLabel: string;\n    /** Prevents query and selection interaction. */\n    disabled?: boolean;\n    /** Haptic feedback for result selection. Defaults to `true` (`selection`). */\n    haptic?: HapticFeedback;\n    className?: string;\n    style?: React.CSSProperties;\n    /** Optional test selector. Result rows derive `${testId}-${item.value}`. */\n    testId?: string;\n}"
      },
      {
        "path": "packages/design-system/src/components/forms/SearchField/SearchField.tsx",
        "line": 15,
        "name": "SearchFieldSurface",
        "code": "export type SearchFieldSurface = InputSurface;"
      },
      {
        "path": "packages/design-system/src/components/primitives/Input/Input.tsx",
        "line": 9,
        "name": "InputEnterBehavior",
        "code": "export type InputEnterBehavior = 'advance' | 'callback';"
      },
      {
        "path": "packages/design-system/src/components/primitives/Input/Input.tsx",
        "line": 10,
        "name": "InputEnterKeyHint",
        "code": "export type InputEnterKeyHint = 'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send';"
      },
      {
        "path": "packages/design-system/src/components/primitives/Input/Input.tsx",
        "line": 28,
        "name": "InputSurface",
        "code": "export type InputSurface = 'default' | 'raised';"
      },
      {
        "path": "packages/design-system/src/tokens/CdsHaptic.ts",
        "line": 6,
        "name": "HapticFeedback",
        "code": "export type HapticFeedback = boolean | HapticType;"
      },
      {
        "path": "packages/design-system/src/tokens/HapticType.ts",
        "line": 2,
        "name": "HapticType",
        "code": "export type HapticType = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';"
      }
    ],
    "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
  },
  "platforms": {
    "implemented": [
      "web"
    ],
    "native": "Imported design guidance only; no native implementation or parity verification in this preview.",
    "react": {
      "implementation": "local",
      "status": "preview",
      "parity": "web-reference"
    },
    "vue": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "swift": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "kotlin": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    }
  },
  "missing_facts": [
    {
      "code": "human-review-pending",
      "detail": "This local preview has no recorded human design or engineering sign-off."
    },
    {
      "code": "platform-parity-unverified",
      "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
    },
    {
      "code": "figma-mapping-unverified",
      "detail": "No current component-level Figma node and immutable revision have been verified for this contract."
    }
  ],
  "review": {
    "local_status": "not-reviewed",
    "source_approval": null,
    "imported_spec_status": "approved",
    "spec_origin": "imported-adapted",
    "local_spec_source_status": "approved",
    "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
    "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract."
  }
}