{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "combobox",
  "type": "registry:ui",
  "title": "Combobox",
  "description": "Combobox is an editable searchable single-select with a filterable listbox — distinct from non-searchable Select and query-only Search Field.",
  "author": "Skrewww",
  "dependencies": [
    "@phosphor-icons/react"
  ],
  "registryDependencies": [
    "@skrewww/form-field",
    "@skrewww/popover",
    "@skrewww/foundation"
  ],
  "docs": "Host requirements (assumed already present, not installed by this command): react, react-dom.",
  "files": [
    {
      "path": "components/ui/Combobox.tsx",
      "content": "/** @skrewww-component combobox */\n\"use client\";\n\nimport { CaretDown } from \"@phosphor-icons/react\";\nimport {\n  forwardRef,\n  useCallback,\n  useEffect,\n  useId,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n  useState,\n  type InputHTMLAttributes,\n  type KeyboardEvent,\n  type PointerEvent,\n  type Ref,\n} from \"react\";\nimport { cn } from \"@/lib/cn\";\nimport { FormField } from \"@/components/ui/FormField\";\nimport {\n  Popover,\n  PopoverAnchor,\n  PopoverBody,\n  PopoverContent,\n} from \"@/components/ui/Popover\";\nimport { useControllableState } from \"@/lib/use-controllable\";\nimport {\n  filterComboboxOptions,\n  findOptionByLabel,\n  resolveOptionLabel,\n  type ComboboxFilterMode,\n} from \"@/components/ui/internal/combobox-filter\";\nimport { useComboboxListStatus } from \"@/components/ui/internal/combobox-list-status\";\nimport {\n  getComboboxOptionId,\n  getComboboxOptionValueFromId,\n  moveComboboxActiveOptionId,\n  resolveInitialActiveOptionId,\n} from \"@/components/ui/internal/combobox-keyboard\";\nimport { scrollComboboxOptionIntoView } from \"@/components/ui/internal/combobox-scroll\";\nimport inputStyles from \"@/components/ui/text-input.module.css\";\nimport styles from \"@/components/ui/combobox.module.css\";\n\nexport type ComboboxOption = {\n  value: string;\n  label: string;\n  disabled?: boolean;\n};\n\nexport type ComboboxSize = \"sm\" | \"md\" | \"lg\";\n\nexport type ComboboxControlProps = Omit<\n  InputHTMLAttributes<HTMLInputElement>,\n  \"size\" | \"value\" | \"defaultValue\" | \"onChange\"\n> & {\n  options: ComboboxOption[];\n  size?: ComboboxSize;\n  placeholder?: string;\n  filterMode?: ComboboxFilterMode;\n  value?: string;\n  defaultValue?: string;\n  onValueChange?: (value: string) => void;\n  inputValue?: string;\n  defaultInputValue?: string;\n  onInputValueChange?: (value: string) => void;\n  open?: boolean;\n  defaultOpen?: boolean;\n  onOpenChange?: (open: boolean) => void;\n  listboxLabel?: string;\n  valueProvided?: boolean;\n  inputValueProvided?: boolean;\n  openProvided?: boolean;\n};\n\nconst sizeClass: Record<ComboboxSize, string> = {\n  sm: inputStyles.sizeSm,\n  md: inputStyles.sizeMd,\n  lg: inputStyles.sizeLg,\n};\n\nfunction ComboboxListbox({\n  listboxId,\n  listboxLabel,\n  listboxRef,\n  filteredOptions,\n  selectedValue,\n  activeOptionId,\n  onSelect,\n  onOptionPointerEnter,\n  onOptionPointerDown,\n  onListboxPointerMove,\n  noResultsLabel,\n}: {\n  listboxId: string;\n  listboxLabel: string;\n  listboxRef: Ref<HTMLUListElement>;\n  filteredOptions: ComboboxOption[];\n  selectedValue: string;\n  activeOptionId: string | null;\n  onSelect: (value: string) => void;\n  onOptionPointerEnter: (optionId: string, disabled?: boolean) => void;\n  onOptionPointerDown: () => void;\n  onListboxPointerMove: (event: PointerEvent<HTMLUListElement>) => void;\n  noResultsLabel: string;\n}) {\n  return (\n    <PopoverContent matchTriggerWidth className={styles.listboxPopover}>\n      <PopoverBody className={styles.listboxBody}>\n        <ul\n          ref={listboxRef}\n          id={listboxId}\n          role=\"listbox\"\n          aria-label={listboxLabel}\n          className={styles.listbox}\n          onPointerMove={onListboxPointerMove}\n        >\n          {filteredOptions.length === 0 ? (\n            <li className={styles.noResults} aria-hidden=\"true\">\n              {noResultsLabel}\n            </li>\n          ) : (\n            filteredOptions.map((option) => {\n              const optionId = getComboboxOptionId(listboxId, option.value);\n              return (\n                <li key={option.value} role=\"presentation\" className={styles.optionItem}>\n                  <div\n                    id={optionId}\n                    role=\"option\"\n                    aria-selected={option.value === selectedValue}\n                    aria-disabled={option.disabled || undefined}\n                    className={cn(\n                      styles.option,\n                      option.value === selectedValue && styles.optionSelected,\n                      activeOptionId === optionId && styles.optionActive,\n                      option.disabled && styles.optionDisabled,\n                    )}\n                    onMouseDown={(event) => {\n                      event.preventDefault();\n                      onOptionPointerDown();\n                    }}\n                    onPointerEnter={() => onOptionPointerEnter(optionId, option.disabled)}\n                    onClick={() => onSelect(option.value)}\n                  >\n                    {option.label}\n                  </div>\n                </li>\n              );\n            })\n          )}\n        </ul>\n      </PopoverBody>\n    </PopoverContent>\n  );\n}\n\nexport const ComboboxControl = forwardRef<HTMLInputElement, ComboboxControlProps>(\n  function ComboboxControl(\n    {\n      options,\n      size = \"md\",\n      placeholder,\n      filterMode = \"prefix\",\n      className,\n      disabled,\n      required,\n      name,\n      id,\n      value,\n      defaultValue = \"\",\n      onValueChange,\n      inputValue: inputValueProp,\n      defaultInputValue,\n      onInputValueChange,\n      open: openProp,\n      defaultOpen = false,\n      onOpenChange,\n      listboxLabel = \"Options\",\n      valueProvided = false,\n      inputValueProvided = false,\n      openProvided = false,\n      \"aria-invalid\": ariaInvalid,\n      \"aria-describedby\": ariaDescribedBy,\n      ...rest\n    },\n    ref,\n  ) {\n    const listboxId = useId();\n    const listStatusId = useId();\n    const inputRef = useRef<HTMLInputElement | null>(null);\n    const listboxRef = useRef<HTMLUListElement | null>(null);\n    const pendingSelectionRef = useRef(false);\n    const blurTimeoutRef = useRef<number | null>(null);\n    const pointerSyncEnabledRef = useRef(false);\n    const keyboardNavigationRef = useRef(false);\n\n    const resolvedDefaultInput =\n      defaultInputValue ?? resolveOptionLabel(options, defaultValue ?? \"\");\n    const initialSelectedRef = useRef(defaultValue ?? \"\");\n    const initialInputRef = useRef(resolvedDefaultInput);\n\n    const [selectedValue, setSelectedValue] = useControllableState({\n      value,\n      defaultValue,\n      onChange: onValueChange,\n      valueProvided,\n    });\n\n    const [inputValue, setInputValue] = useControllableState({\n      value: inputValueProp,\n      defaultValue: resolvedDefaultInput,\n      onChange: onInputValueChange,\n      valueProvided: inputValueProvided,\n    });\n\n    const [open, setOpen] = useControllableState({\n      value: openProp,\n      defaultValue: defaultOpen,\n      onChange: onOpenChange,\n      valueProvided: openProvided,\n    });\n\n    const [activeOptionId, setActiveOptionId] = useState<string | null>(null);\n    const previousSelectedValueRef = useRef<string | undefined>(undefined);\n\n    const filteredOptions = useMemo(\n      () => filterComboboxOptions(options, inputValue, filterMode),\n      [filterMode, inputValue, options],\n    );\n\n    const listStatusAnnouncement = useComboboxListStatus({\n      open,\n      disabled,\n      resultCount: filteredOptions.length,\n    });\n\n    const inputDescribedBy = useMemo(() => {\n      const ids = [ariaDescribedBy, open ? listStatusId : undefined].filter(Boolean);\n      return ids.length ? ids.join(\" \") : undefined;\n    }, [ariaDescribedBy, listStatusId, open]);\n\n    const formResetFormRef = useRef<HTMLFormElement | null>(null);\n\n    const handleFormReset = useCallback(() => {\n      if (blurTimeoutRef.current !== null) {\n        window.clearTimeout(blurTimeoutRef.current);\n        blurTimeoutRef.current = null;\n      }\n      if (!valueProvided) setSelectedValue(initialSelectedRef.current);\n      if (!inputValueProvided) setInputValue(initialInputRef.current);\n      if (!openProvided) setOpen(false);\n      previousSelectedValueRef.current = initialSelectedRef.current;\n    }, [inputValueProvided, openProvided, setInputValue, setOpen, setSelectedValue, valueProvided]);\n\n    const setInputRef = useCallback(\n      (node: HTMLInputElement | null) => {\n        inputRef.current = node;\n        if (typeof ref === \"function\") ref(node);\n        else if (ref) ref.current = node;\n\n        if (formResetFormRef.current) {\n          formResetFormRef.current.removeEventListener(\"reset\", handleFormReset);\n          formResetFormRef.current = null;\n        }\n\n        if (node?.form) {\n          formResetFormRef.current = node.form;\n          node.form.addEventListener(\"reset\", handleFormReset);\n        }\n      },\n      [handleFormReset, ref],\n    );\n\n    const closeListbox = useCallback(\n      (options?: { restoreFocus?: boolean }) => {\n        setOpen(false);\n        if (options?.restoreFocus !== false) {\n          inputRef.current?.focus();\n        }\n      },\n      [setOpen],\n    );\n\n    useEffect(() => {\n      return () => {\n        if (formResetFormRef.current) {\n          formResetFormRef.current.removeEventListener(\"reset\", handleFormReset);\n        }\n      };\n    }, [handleFormReset]);\n\n    useEffect(() => {\n      if (inputValueProvided) return;\n      if (previousSelectedValueRef.current === selectedValue) return;\n      previousSelectedValueRef.current = selectedValue;\n      const nextLabel = resolveOptionLabel(options, selectedValue);\n      if (nextLabel !== inputValue) {\n        setInputValue(nextLabel);\n      }\n    }, [inputValue, inputValueProvided, options, selectedValue, setInputValue]);\n\n    useLayoutEffect(() => {\n      if (!open) {\n        pointerSyncEnabledRef.current = false;\n        return;\n      }\n\n      pointerSyncEnabledRef.current = false;\n      keyboardNavigationRef.current = false;\n      const frame = window.requestAnimationFrame(() => {\n        pointerSyncEnabledRef.current = true;\n      });\n      return () => window.cancelAnimationFrame(frame);\n    }, [open]);\n\n    const activeSyncKey = open\n      ? `${listboxId}:${selectedValue ?? \"\"}:${filteredOptions.map((option) => option.value).join(\"\\u0001\")}`\n      : \"\";\n    const [activeForKey, setActiveForKey] = useState<string | null>(null);\n    if (activeSyncKey !== activeForKey) {\n      setActiveForKey(activeSyncKey);\n      if (!open) {\n        setActiveOptionId(null);\n      } else {\n        setActiveOptionId(\n          resolveInitialActiveOptionId(filteredOptions, listboxId, selectedValue),\n        );\n      }\n    }\n\n    useEffect(() => {\n      if (!open || !activeOptionId) return;\n      scrollComboboxOptionIntoView(\n        listboxRef.current,\n        document.getElementById(activeOptionId),\n      );\n    }, [activeOptionId, open]);\n\n    useLayoutEffect(() => {\n      const node = inputRef.current;\n      if (!node || !required || disabled) return;\n      node.setCustomValidity(selectedValue ? \"\" : \"Choose an option.\");\n    }, [disabled, required, selectedValue]);\n\n    useEffect(() => {\n      if (!open) return;\n      function handleTabClose(event: globalThis.KeyboardEvent) {\n        if (event.key === \"Tab\") {\n          closeListbox({ restoreFocus: false });\n        }\n      }\n      document.addEventListener(\"keydown\", handleTabClose);\n      return () => document.removeEventListener(\"keydown\", handleTabClose);\n    }, [closeListbox, open]);\n\n    const commitSelection = useCallback(\n      (nextValue: string) => {\n        const option = options.find((item) => item.value === nextValue);\n        if (!option || option.disabled) return;\n        setSelectedValue(option.value);\n        if (!inputValueProvided) {\n          setInputValue(option.label);\n        }\n        closeListbox({ restoreFocus: true });\n      },\n      [closeListbox, inputValueProvided, options, setInputValue, setSelectedValue],\n    );\n\n    const reconcileInputOnBlur = useCallback(() => {\n      if (inputValueProvided || pendingSelectionRef.current) return;\n      const exactMatch = findOptionByLabel(options, inputValue);\n      if (exactMatch && !exactMatch.disabled) {\n        setSelectedValue(exactMatch.value);\n        setInputValue(exactMatch.label);\n        return;\n      }\n      setInputValue(resolveOptionLabel(options, selectedValue));\n    }, [inputValue, inputValueProvided, options, selectedValue, setInputValue, setSelectedValue]);\n\n    const handleOptionPointerEnter = useCallback(\n      (optionId: string, optionDisabled?: boolean) => {\n        if (!pointerSyncEnabledRef.current || keyboardNavigationRef.current || optionDisabled) {\n          return;\n        }\n        setActiveOptionId(optionId);\n      },\n      [],\n    );\n\n    const handleListboxPointerMove = useCallback(\n      (event: PointerEvent<HTMLUListElement>) => {\n        keyboardNavigationRef.current = false;\n        if (!pointerSyncEnabledRef.current) return;\n\n        const target = (event.target as HTMLElement).closest<HTMLElement>('[role=\"option\"]');\n        if (!target || target.getAttribute(\"aria-disabled\") === \"true\") return;\n        if (target.id) setActiveOptionId(target.id);\n      },\n      [],\n    );\n\n    const handleKeyDown = useCallback(\n      (event: KeyboardEvent<HTMLInputElement>) => {\n        if (disabled) return;\n\n        if (event.key === \"ArrowDown\") {\n          event.preventDefault();\n          keyboardNavigationRef.current = true;\n          if (!open) {\n            setOpen(true);\n            setActiveOptionId(\n              resolveInitialActiveOptionId(filteredOptions, listboxId, selectedValue),\n            );\n            return;\n          }\n          setActiveOptionId((current) =>\n            moveComboboxActiveOptionId(1, current, filteredOptions, listboxId),\n          );\n          return;\n        }\n\n        if (event.key === \"ArrowUp\") {\n          event.preventDefault();\n          keyboardNavigationRef.current = true;\n          if (!open) {\n            setOpen(true);\n            setActiveOptionId(\n              resolveInitialActiveOptionId(filteredOptions, listboxId, selectedValue),\n            );\n            return;\n          }\n          setActiveOptionId((current) =>\n            moveComboboxActiveOptionId(-1, current, filteredOptions, listboxId),\n          );\n          return;\n        }\n\n        if (event.key === \"Enter\" && open) {\n          event.preventDefault();\n          const activeValue = getComboboxOptionValueFromId(activeOptionId, listboxId);\n          if (activeValue) commitSelection(activeValue);\n          return;\n        }\n\n        if (event.key === \"Escape\" && open) {\n          event.preventDefault();\n          event.stopPropagation();\n          closeListbox({ restoreFocus: true });\n        }\n      },\n      [\n        activeOptionId,\n        closeListbox,\n        commitSelection,\n        disabled,\n        filteredOptions,\n        listboxId,\n        open,\n        selectedValue,\n        setOpen,\n      ],\n    );\n\n    const handleOptionPointerDown = useCallback(() => {\n      pendingSelectionRef.current = true;\n    }, []);\n\n    const handleSelect = useCallback(\n      (nextValue: string) => {\n        pendingSelectionRef.current = false;\n        commitSelection(nextValue);\n      },\n      [commitSelection],\n    );\n\n    return (\n      <Popover\n        open={open}\n        onOpenChange={setOpen}\n        placement=\"bottom\"\n        align=\"start\"\n        focusMode=\"trigger\"\n        showArrow={false}\n      >\n        <div className={cn(styles.controlWrap, className)}>\n          {name ? (\n            <input type=\"hidden\" name={name} value={selectedValue} disabled={disabled} />\n          ) : null}\n\n          <div\n            id={listStatusId}\n            role=\"status\"\n            aria-live=\"polite\"\n            aria-atomic=\"true\"\n            className=\"sr-only\"\n          >\n            {listStatusAnnouncement}\n          </div>\n\n          <PopoverAnchor>\n            <div className={styles.inputWrap}>\n              <input\n                ref={setInputRef}\n                id={id}\n                type=\"text\"\n                role=\"combobox\"\n                className={cn(inputStyles.input, styles.input, sizeClass[size])}\n                value={inputValue}\n                placeholder={placeholder}\n                disabled={disabled}\n                aria-required={required || undefined}\n                aria-invalid={ariaInvalid === true || ariaInvalid === \"true\" ? true : undefined}\n                aria-describedby={inputDescribedBy}\n                aria-autocomplete=\"list\"\n                aria-haspopup=\"listbox\"\n                aria-expanded={open}\n                aria-controls={open ? listboxId : undefined}\n                aria-activedescendant={open && activeOptionId ? activeOptionId : undefined}\n                onChange={(event) => {\n                  keyboardNavigationRef.current = false;\n                  setInputValue(event.target.value);\n                  if (!open) setOpen(true);\n                }}\n                onFocus={() => {\n                  if (!disabled) setOpen(true);\n                }}\n                onKeyDown={handleKeyDown}\n                onBlur={() => {\n                  blurTimeoutRef.current = window.setTimeout(() => {\n                    blurTimeoutRef.current = null;\n                    if (pendingSelectionRef.current) return;\n                    closeListbox({ restoreFocus: false });\n                    reconcileInputOnBlur();\n                  }, 0);\n                }}\n                autoComplete=\"off\"\n                {...rest}\n              />\n              <span className={styles.caret} aria-hidden=\"true\">\n                <CaretDown size={16} weight=\"bold\" />\n              </span>\n            </div>\n          </PopoverAnchor>\n        </div>\n\n        <ComboboxListbox\n          listboxId={listboxId}\n          listboxLabel={listboxLabel}\n          listboxRef={listboxRef}\n          filteredOptions={filteredOptions}\n          selectedValue={selectedValue}\n          activeOptionId={activeOptionId}\n          onSelect={handleSelect}\n          onOptionPointerEnter={handleOptionPointerEnter}\n          onOptionPointerDown={handleOptionPointerDown}\n          onListboxPointerMove={handleListboxPointerMove}\n          noResultsLabel=\"No results found\"\n        />\n      </Popover>\n    );\n  },\n);\n\nexport type ComboboxProps = ComboboxControlProps & {\n  label: string;\n  supportingText?: string;\n  error?: string;\n  hideLabel?: boolean;\n};\n\nexport const Combobox = forwardRef<HTMLInputElement, ComboboxProps>(function Combobox(\n  props,\n  ref,\n) {\n  const valueProvided = \"value\" in props;\n  const inputValueProvided = \"inputValue\" in props;\n  const openProvided = \"open\" in props;\n  const {\n    label,\n    supportingText,\n    error,\n    hideLabel = false,\n    id: idProp,\n    required,\n    ...controlProps\n  } = props;\n\n  return (\n    <FormField\n      label={label}\n      controlId={idProp}\n      required={required}\n      hideLabel={hideLabel}\n      supportingText={supportingText}\n      error={error}\n    >\n      {({ controlId, describedBy, invalid }) => (\n        <ComboboxControl\n          ref={ref}\n          id={controlId}\n          required={required}\n          aria-invalid={invalid || undefined}\n          aria-describedby={describedBy}\n          listboxLabel={label}\n          valueProvided={valueProvided}\n          inputValueProvided={inputValueProvided}\n          openProvided={openProvided}\n          {...controlProps}\n        />\n      )}\n    </FormField>\n  );\n});\n",
      "type": "registry:ui",
      "target": "~/components/ui/Combobox.tsx"
    },
    {
      "path": "components/ui/combobox.module.css",
      "content": ".controlWrap {\n  position: relative;\n  display: block;\n  width: 100%;\n}\n\n.inputWrap {\n  position: relative;\n  display: block;\n  width: 100%;\n}\n\n.input {\n  display: block;\n  width: 100%;\n  padding-right: 2.25rem;\n}\n\n.caret {\n  position: absolute;\n  top: 50%;\n  right: 0.75rem;\n  transform: translateY(-50%);\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  color: var(--combobox-icon);\n  pointer-events: none;\n}\n\n/* Double class beats shared Popover `.popover` elevation/Glass mix. */\n.listboxPopover.listboxPopover {\n  box-sizing: border-box;\n  padding: 0;\n  overflow: hidden;\n  width: auto;\n  max-width: none;\n  background-color: var(--combobox-popup-surface);\n  background-image: var(--component-surface-gradient-overlay);\n  border: 1px solid var(--combobox-popup-border);\n  border-radius: var(--combobox-popup-radius);\n  box-shadow: var(--combobox-popup-elevation);\n  /* Panel owns Surface blur (lg 16px in Glass). Option rows never blur. */\n  backdrop-filter: var(--component-surface-backdrop-filter);\n  animation: none;\n}\n\n[data-skrewww-surface=\"glass\"] .listboxPopover.listboxPopover {\n  background: var(--combobox-popup-surface);\n  background-image: none;\n  border: 1px solid var(--combobox-popup-border);\n  box-shadow: var(--combobox-popup-elevation);\n  backdrop-filter: var(--glass-backdrop-filter-lg);\n}\n\n[data-skrewww-surface=\"gradient\"] .listboxPopover.listboxPopover {\n  background-image: var(--component-surface-gradient-overlay);\n}\n\n.listboxBody {\n  box-sizing: border-box;\n  width: 100%;\n  padding: var(--combobox-popup-padding);\n  overflow: hidden;\n}\n\n.listbox {\n  margin: 0;\n  padding: 0;\n  list-style: none;\n  width: 100%;\n  max-height: var(--combobox-popup-max-height);\n  overflow-y: auto;\n  outline: none;\n}\n\n.optionItem {\n  width: 100%;\n}\n\n.option {\n  display: block;\n  box-sizing: border-box;\n  width: 100%;\n  min-height: var(--combobox-option-height);\n  padding: var(--combobox-option-padding);\n  border-radius: var(--combobox-option-radius);\n  background: transparent;\n  color: var(--combobox-option-text);\n  font: inherit;\n  text-align: left;\n  cursor: pointer;\n}\n\n.option:hover:not(.optionDisabled) {\n  background-color: var(--combobox-option-active-surface);\n}\n\n.optionActive {\n  background-color: var(--combobox-option-active-surface);\n  outline: 2px solid var(--semantic-focus-ring);\n  outline-offset: -2px;\n}\n\n.optionSelected {\n  font-weight: 500;\n  background-color: var(--combobox-option-selected-surface);\n  background-image: var(--component-surface-gradient-overlay);\n}\n\n.optionSelected:hover:not(.optionDisabled),\n.optionSelected.optionActive {\n  background-color: var(--combobox-option-selected-surface);\n  background-image: var(--component-surface-gradient-overlay);\n}\n\n.optionDisabled {\n  color: var(--combobox-option-disabled-text);\n  cursor: not-allowed;\n}\n\n.noResults {\n  padding: var(--combobox-empty-padding);\n  min-height: var(--combobox-empty-min-height);\n  color: var(--combobox-empty-text);\n  font-size: 0.875rem;\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .option {\n    transition: none;\n  }\n}\n",
      "type": "registry:ui",
      "target": "~/components/ui/combobox.module.css"
    },
    {
      "path": "lib/cn.ts",
      "content": "export function cn(...classes: Array<string | false | null | undefined>): string {\n  return classes.filter(Boolean).join(\" \");\n}\n",
      "type": "registry:lib",
      "target": "~/lib/cn.ts"
    },
    {
      "path": "lib/use-controllable.ts",
      "content": "import { useCallback, useEffect, useRef, useState } from \"react\";\n\nexport function useControllableState<T>({\n  value,\n  defaultValue,\n  onChange,\n  controlled: controlledProp,\n  valueProvided,\n}: {\n  value?: T;\n  defaultValue?: T;\n  onChange?: (next: T) => void;\n  /** Explicit controlled override — prefer `valueProvided` from the component root. */\n  controlled?: boolean;\n  /** True when the parent passed a `value` prop, including `undefined`. */\n  valueProvided?: boolean;\n}) {\n  const [uncontrolled, setUncontrolled] = useState(defaultValue as T);\n  const isControlled = controlledProp ?? valueProvided ?? value !== undefined;\n  const current = isControlled ? (value as T) : uncontrolled;\n  const wasControlledRef = useRef(isControlled);\n\n  useEffect(() => {\n    if (process.env.NODE_ENV !== \"development\") return;\n    if (wasControlledRef.current !== isControlled) {\n      console.warn(\n        \"[Skrewww] A component changed between controlled and uncontrolled modes. Keep `value` or `defaultValue` usage consistent across renders.\",\n      );\n    }\n    wasControlledRef.current = isControlled;\n  }, [isControlled]);\n\n  const setValue = useCallback(\n    (next: T) => {\n      if (!isControlled) setUncontrolled(next);\n      onChange?.(next);\n    },\n    [isControlled, onChange],\n  );\n\n  return [current, setValue] as const;\n}\n",
      "type": "registry:lib",
      "target": "~/lib/use-controllable.ts"
    },
    {
      "path": "components/ui/text-input.module.css",
      "content": ".controlWrap {\n  position: relative;\n  display: flex;\n  align-items: center;\n  width: 100%;\n}\n\n.input {\n  width: 100%;\n  border: 1px solid var(--semantic-border-default);\n  border-radius: var(--shape-radius-control);\n  /* TextInput wasn't in the originally-reported list of squircle consumers,\n     but it consumes --shape-radius-control via plain border-radius exactly\n     like Button/Checkbox/Drawer's close button — same bug, fixed the same\n     way, found while auditing the other 5. */\n  clip-path: var(--squircle-clip-path-control, none);\n  background-color: var(--surface-fill-control);\n  background-image: var(--component-surface-gradient-overlay);\n  backdrop-filter: var(--glass-backdrop-filter-sm, none);\n  color: var(--semantic-text-primary);\n  font-family: inherit;\n  line-height: 1.4;\n  transition:\n    border-color 0.15s ease,\n    box-shadow 0.15s ease;\n}\n\n.input::placeholder {\n  color: var(--semantic-text-disabled);\n}\n\n.input:hover:not(:disabled):not([aria-invalid=\"true\"]) {\n  border-color: var(--semantic-border-strong);\n}\n\n.input:focus {\n  outline: none;\n}\n\n.input:focus-visible {\n  border-color: var(--semantic-focus-ring);\n  box-shadow: 0 0 0 2px var(--semantic-focus-ring);\n}\n\n/* clip-path clips an outset box-shadow ring exactly like it clips outline\n   (same reasoning as Button/Checkbox) — an inset ring stays fully visible\n   since it never extends past the clip boundary. Squircle mode only; every\n   other shape mode keeps the outset ring above unchanged. */\n[data-skrewww-shape=\"squircle\"] .input:focus-visible {\n  box-shadow: inset 0 0 0 2px var(--semantic-focus-ring);\n}\n\n.input:disabled {\n  cursor: not-allowed;\n  pointer-events: none;\n  color: var(--semantic-text-disabled);\n  border-color: var(--semantic-border-disabled);\n  background-color: var(--semantic-surface-disabled);\n  opacity: var(--opacity-disabled);\n}\n\n.input:read-only:not(:disabled) {\n  background-color: var(--semantic-surface-subtle);\n  cursor: default;\n}\n\n.input[aria-invalid=\"true\"] {\n  border-color: var(--semantic-action-danger);\n}\n\n.input[aria-invalid=\"true\"]:focus-visible {\n  box-shadow: 0 0 0 2px var(--semantic-action-danger);\n}\n\n[data-skrewww-shape=\"squircle\"] .input[aria-invalid=\"true\"]:focus-visible {\n  box-shadow: inset 0 0 0 2px var(--semantic-action-danger);\n}\n\n.input[type=\"search\"]::-webkit-search-cancel-button {\n  -webkit-appearance: none;\n  appearance: none;\n  display: none;\n}\n\n.sizeSm {\n  min-height: var(--control-height-sm);\n  padding: 0 var(--control-padding-x-sm);\n  font-size: var(--control-font-size-sm);\n}\n\n.sizeMd {\n  min-height: var(--control-height-md);\n  padding: 0 var(--control-padding-x-md);\n  font-size: var(--control-font-size-md);\n}\n\n.sizeLg {\n  min-height: var(--control-height-lg);\n  padding: 0 var(--control-padding-x-lg);\n  font-size: var(--control-font-size-lg);\n}\n\n.withLeading {\n  padding-left: 2.25rem;\n}\n\n.withTrailing {\n  padding-right: 2.25rem;\n}\n\n.leading,\n.trailing {\n  position: absolute;\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  color: var(--semantic-icon-muted);\n  pointer-events: none;\n}\n\n.leading {\n  left: 0.75rem;\n}\n\n.trailing {\n  right: 0.75rem;\n  pointer-events: auto;\n}\n\n.trailingAction {\n  position: absolute;\n  right: 0.25rem;\n  display: inline-flex;\n  align-items: center;\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .input {\n    transition: none;\n  }\n}\n",
      "type": "registry:ui",
      "target": "~/components/ui/text-input.module.css"
    },
    {
      "path": "components/ui/internal/combobox-filter.ts",
      "content": "export type ComboboxOptionLike = {\n  value: string;\n  label: string;\n  disabled?: boolean;\n};\n\nexport type ComboboxFilterMode = \"prefix\" | \"substring\";\n\nexport function filterComboboxOptions(\n  options: ComboboxOptionLike[],\n  query: string,\n  mode: ComboboxFilterMode = \"prefix\",\n): ComboboxOptionLike[] {\n  const trimmed = query.trim();\n  if (!trimmed) return options;\n\n  const normalizedQuery = trimmed.toLocaleLowerCase();\n  return options.filter((option) => {\n    const normalizedLabel = option.label.toLocaleLowerCase();\n    return mode === \"prefix\"\n      ? normalizedLabel.startsWith(normalizedQuery)\n      : normalizedLabel.includes(normalizedQuery);\n  });\n}\n\nexport function findOptionByLabel(\n  options: ComboboxOptionLike[],\n  label: string,\n): ComboboxOptionLike | undefined {\n  const normalized = label.trim().toLocaleLowerCase();\n  if (!normalized) return undefined;\n\n  const matches = options.filter(\n    (option) => option.label.trim().toLocaleLowerCase() === normalized,\n  );\n  if (matches.length !== 1) return undefined;\n  return matches[0];\n}\n\nexport function resolveOptionLabel(\n  options: ComboboxOptionLike[],\n  value: string,\n): string {\n  if (!value) return \"\";\n  return options.find((option) => option.value === value)?.label ?? \"\";\n}\n",
      "type": "registry:lib",
      "target": "~/components/ui/internal/combobox-filter.ts"
    },
    {
      "path": "components/ui/internal/combobox-list-status.ts",
      "content": "import { useState } from \"react\";\n\nexport type ComboboxListStatusInput = {\n  open: boolean;\n  disabled?: boolean;\n  resultCount: number;\n};\n\n/**\n * Polite list status announcements for Combobox filtering.\n *\n * Policy:\n * - Announce once when the listbox opens (count or no-results).\n * - Announce when results transition to empty while open.\n * - Announce when results return after being empty while open.\n * - Do not announce on every intermediate count change while typing.\n * - Stay silent when closed or disabled.\n */\nexport function useComboboxListStatus({\n  open,\n  disabled = false,\n  resultCount,\n}: ComboboxListStatusInput): string {\n  const [announcement, setAnnouncement] = useState(\"\");\n  const [tracked, setTracked] = useState<{\n    open: boolean;\n    wasEmpty: boolean;\n  }>({ open: false, wasEmpty: false });\n\n  const silent = !open || disabled;\n  const isEmpty = resultCount === 0;\n\n  if (silent) {\n    if (tracked.open) {\n      setTracked({ open: false, wasEmpty: false });\n    }\n  } else {\n    const justOpened = !tracked.open;\n    const becameEmpty = isEmpty && !tracked.wasEmpty;\n    const returned = !isEmpty && tracked.wasEmpty;\n    if (justOpened || becameEmpty || returned) {\n      const next = isEmpty ? \"No results found.\" : `${resultCount} results available.`;\n      if (announcement !== next) {\n        setAnnouncement(next);\n      }\n    }\n    if (tracked.open !== true || tracked.wasEmpty !== isEmpty) {\n      setTracked({ open: true, wasEmpty: isEmpty });\n    }\n  }\n\n  return silent ? \"\" : announcement;\n}\n",
      "type": "registry:lib",
      "target": "~/components/ui/internal/combobox-list-status.ts"
    },
    {
      "path": "components/ui/internal/combobox-keyboard.ts",
      "content": "import type { ComboboxOptionLike } from \"@/components/ui/internal/combobox-filter\";\n\nexport function getEnabledComboboxOptions(options: ComboboxOptionLike[]): ComboboxOptionLike[] {\n  return options.filter((option) => !option.disabled);\n}\n\nexport function getComboboxOptionId(listboxId: string, value: string): string {\n  return `${listboxId}-${value}`;\n}\n\nexport function resolveInitialActiveOptionId(\n  filteredOptions: ComboboxOptionLike[],\n  listboxId: string,\n  selectedValue: string,\n): string | null {\n  const enabled = getEnabledComboboxOptions(filteredOptions);\n  if (enabled.length === 0) return null;\n  const selected = enabled.find((option) => option.value === selectedValue);\n  const target = selected ?? enabled[0];\n  return getComboboxOptionId(listboxId, target.value);\n}\n\nexport function moveComboboxActiveOptionId(\n  direction: 1 | -1,\n  activeOptionId: string | null,\n  filteredOptions: ComboboxOptionLike[],\n  listboxId: string,\n): string | null {\n  const enabled = getEnabledComboboxOptions(filteredOptions);\n  if (enabled.length === 0) return null;\n\n  const optionIds = enabled.map((option) => getComboboxOptionId(listboxId, option.value));\n  const currentIndex = activeOptionId ? optionIds.indexOf(activeOptionId) : -1;\n\n  let nextIndex = currentIndex + direction;\n  if (currentIndex === -1) {\n    nextIndex = direction === 1 ? 0 : enabled.length - 1;\n  } else {\n    nextIndex = Math.max(0, Math.min(enabled.length - 1, nextIndex));\n  }\n\n  return optionIds[nextIndex] ?? null;\n}\n\nexport function getComboboxOptionValueFromId(\n  activeOptionId: string | null,\n  listboxId: string,\n): string | null {\n  if (!activeOptionId || !activeOptionId.startsWith(`${listboxId}-`)) return null;\n  return activeOptionId.slice(listboxId.length + 1);\n}\n",
      "type": "registry:lib",
      "target": "~/components/ui/internal/combobox-keyboard.ts"
    },
    {
      "path": "components/ui/internal/combobox-scroll.ts",
      "content": "export function scrollComboboxOptionIntoView(\n  listbox: HTMLElement | null,\n  option: HTMLElement | null,\n): void {\n  if (!listbox || !option) return;\n\n  const listboxRect = listbox.getBoundingClientRect();\n  const optionRect = option.getBoundingClientRect();\n  const fullyVisible =\n    optionRect.top >= listboxRect.top && optionRect.bottom <= listboxRect.bottom;\n\n  if (fullyVisible) return;\n  option.scrollIntoView({ block: \"nearest\" });\n}\n",
      "type": "registry:lib",
      "target": "~/components/ui/internal/combobox-scroll.ts"
    }
  ]
}
