pixelize-native-library 1.0.7 → 1.2.1

package/lib/typescript/modules/chip/Chip.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Chip — an interactive token: press to select/toggle, and optionally press a separate trailing "x"
+ * to remove it. Distinct from `Badge` (`../badge`), which is documented, by its own file-level
+ * comment, as non-interactive ("no press, focus, loading, or disabled state" — a `View`, never a
+ * `Pressable`). Badge displays a status/label; Chip is the touchable counterpart for filter chips,
+ * selectable tags, and removable tokens — always `accessibilityRole="button"`, always a 44dp touch
+ * target, never icon-only (`label` is required).
+ */
+import type { IconName } from "../../core/icon";
+import type { LayoutStyle } from "../../core/style";
+import type { ChipSize, ChipTone, ChipVariant, CustomToneColors } from "./Chip.variants";
+export interface ChipProps {
+    /** A chip is never icon-only — this is its whole accessible name. */
+    label: string;
+    variant?: ChipVariant;
+    tone?: ChipTone;
+    /** Required when `tone="custom"`. */
+    customColors?: CustomToneColors;
+    size?: ChipSize;
+    /** Renders the filled/accented look regardless of `variant`. Only added to
+     *  `accessibilityState` when passed — see `resolveChipAccessibility`. */
+    selected?: boolean;
+    onPress?: () => void;
+    /** Provided → a trailing "x" `Pressable` that is a SIBLING of the chip's own press target, with
+     *  its own accessible name and its own 44dp hit target, so removing never fires `onPress` and a
+     *  screen reader can reach it. Omitted → no remove affordance renders. */
+    onRemove?: () => void;
+    /** Leading glyph. Ignored when `avatarUri` is also given — see `avatarUri`. */
+    icon?: IconName;
+    /** Leading circular image. Wins over `icon` when both are passed: an identity photo is a more
+     *  specific signal than a generic glyph, the same "most specific wins" precedent `Select`'s own
+     *  `leading` slot documents for the image-over-glyph case. */
+    avatarUri?: string;
+    disabled?: boolean;
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    style?: LayoutStyle;
+    testID?: string;
+}
+export declare const Chip: import("react").NamedExoticComponent<ChipProps>;
+//# sourceMappingURL=Chip.d.ts.map

package/lib/typescript/modules/chip/Chip.variants.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Chip's style + behaviour resolution — same split as every sibling module:
+ *  - STRUCTURE (sizing/spacing off the theme scale) lives in the `createThemedVariants` resolvers
+ *    below — static per (brand, mode), registered once.
+ *  - COLOUR is resolved from the theme's ROLE colours (never a raw ramp, never a hardcoded hex) by
+ *    `resolveChipColors` — `tone`/`variant` are closed unions for the same reason Button's `tone` is.
+ *  - ACCESSIBILITY prop derivation is `resolveChipAccessibility`, kept pure so the "selected is only
+ *    announced when the caller controls it" contract is unit-testable without rendering React Native.
+ *
+ * Free of React and of any lucide/Pressable import, so the WCAG + behaviour tests import it directly
+ * (mocking only `react-native`'s `StyleSheet`, as `core/style` does).
+ */
+import type { RoleColors, StatusRole, Theme } from "../../theme/hooks";
+export type ChipVariant = "solid" | "outline" | "subtle";
+/** `accent`/`neutral` are brand-driven emphasis; the rest mirror the theme's status roles — same
+ *  shape `Badge`'s own `BadgeTone` uses. */
+export type ChipTone = "accent" | "neutral" | StatusRole | "custom";
+export type CustomToneColors = {
+    readonly bg: string;
+    readonly fg: string;
+};
+export type ChipSize = "sm" | "md";
+export type ChipGroupGap = "sm" | "md";
+/** Same touch-target floor as every interactive control in this library (44dp — Apple HIG minimum,
+ *  WCAG 2.5.5 AAA). */
+export declare const MIN_TOUCH_TARGET = 44;
+export interface ChipSizeSpec {
+    /** Visual height in dp. */
+    readonly height: number;
+    /** Label size, on the same compact scale `Badge`'s own sizes use. */
+    readonly fontSize: number;
+    /** Leading icon glyph size in dp. */
+    readonly iconSize: number;
+    /** Symmetric touch expansion so `height + 2·hitSlop ≥ 44` — the visual pill stays small, the
+     *  target doesn't. */
+    readonly hitSlop: number;
+}
+/**
+ * Chip-specific dimensions. Visibly smaller than Button (a chip is a token, not a call-to-action)
+ * but every size still reaches the 44dp floor via `hitSlop`, exactly like Button/Select do for
+ * their own short sizes.
+ */
+export declare const CHIP_SIZES: {
+    readonly sm: {
+        readonly height: 28;
+        readonly fontSize: 12;
+        readonly iconSize: 14;
+        readonly hitSlop: number;
+    };
+    readonly md: {
+        readonly height: 32;
+        readonly fontSize: 14;
+        readonly iconSize: 16;
+        readonly hitSlop: number;
+    };
+};
+/** Leading `avatarUri` diameter per chip size — a few dp inside the chip's own height so it never
+ *  clips the pill's vertical padding. */
+export declare const CHIP_AVATAR_SIZE: {
+    readonly sm: 18;
+    readonly md: 22;
+};
+/** The trailing "x" remove affordance. Fixed — independent of `size`, the same stance Select's row
+ *  "check" glyph and Menu's row icon take (a fixed-purpose glyph is not a caller-facing choice). */
+export declare const CHIP_REMOVE_ICON_SIZE = 12;
+/** Visual touch box for the remove glyph — small on purpose (it sits inside an already-small chip);
+ *  `CHIP_REMOVE_HIT_SLOP` is what actually carries it to the 44dp floor. */
+export declare const CHIP_REMOVE_TOUCH_BOX = 18;
+export declare const CHIP_REMOVE_HIT_SLOP: number;
+export interface ChipColors {
+    /** Chip fill. */
+    readonly background: string;
+    /** Label, leading icon, and remove glyph — one colour for all three (see `Chip.tsx`: the icon and
+     *  remove glyph reuse this exact value, so once the label clears the stricter 4.5:1 text minimum,
+     *  both glyphs clear their looser 3:1 non-text minimum for free — the same reasoning Menu's row
+     *  icon and Select's active-row check glyph rely on). */
+    readonly text: string;
+    /** Boundary colour. Equals `background` for the solid/selected (filled) look, so the structural
+     *  hairline (if any) blends away; `"transparent"` for `subtle`, which also has zero border WIDTH
+     *  structurally, so the colour never shows either way. Only `outline` (unselected) draws a real,
+     *  visible boundary. */
+    readonly border: string;
+}
+/**
+ * Resolves one (tone, variant, selected) combination's fill/text/border. `selected` renders the
+ * filled/accented look regardless of `variant` (spec) by reusing the SAME `solidFill`/`onSolid`
+ * pair `variant="solid"` reads — so "selected outline chip" and "solid chip" render identically
+ * instead of introducing a third, separately-measured filled pairing.
+ */
+export declare function resolveChipColors(colors: RoleColors, tone: ChipTone, variant: ChipVariant, selected: boolean, customColors?: CustomToneColors): ChipColors;
+/** Whether a (variant, selected) combination renders the filled/accented look — the same predicate
+ *  `resolveChipColors` and `Chip.tsx`'s own press-feedback branch both key off. */
+export declare function isChipFilled(variant: ChipVariant, selected: boolean): boolean;
+/**
+ * A resting (non-filled) chip's pressed-state background — `bg.sunken`, the exact precedent
+ * `Menu.variants.ts`'s `resolveMenuRowPressedBackground` sets (a pale neutral tint keeps the label
+ * ≥ 4.5:1, unlike the saturated `bg.hover` mid-tone). Not used for a filled chip (`variant="solid"`
+ * or `selected`): swapping a coloured fill to a flat neutral tint on every press would erase the
+ * tone/selection cue for the moment a finger is down, so a filled chip dims instead
+ * (`Chip.tsx`'s `styles.filledPressed`) — the same "disabled is a uniform dim, exempt from the
+ * contrast minimum" reasoning this library already applies, extended to a transient press.
+ */
+export declare function resolveChipPressedBackground(colors: RoleColors): string;
+export interface ChipAccessibilityInput {
+    /** The RAW prop, before any `= false` default — see the return contract below. */
+    readonly selected?: boolean | undefined;
+    readonly disabled?: boolean | undefined;
+}
+export interface ChipAccessibilityProps {
+    readonly accessibilityRole: "button";
+    /** Flat, never `accessibilityState`: react-native-web discards the object form (see
+     *  `docs/PLATFORM-A11Y-PROPS.md`). Quoted key so the compiler still checks the prop name. */
+    readonly "aria-disabled": boolean;
+    /** The WEB half of `selected`. A filter chip is a toggle button, so the correct ARIA is
+     *  `aria-pressed` — `aria-selected` is not valid on `role="button"` and browsers ignore it. */
+    readonly "aria-pressed": boolean | undefined;
+    /** The NATIVE half of `selected` — React Native has no `pressed` state, and react-native-web
+     *  discards this object, so it never reaches the DOM. `undefined` when the chip has no toggle. */
+    readonly accessibilityState: {
+        readonly selected: boolean;
+    } | undefined;
+    readonly disabled: boolean;
+}
+/**
+ * Derives the chip's accessibility surface once, purely. `selected` is only exposed when the CALLER
+ * actually passed the prop: a plain removable-token chip (never supplies `selected`) has no
+ * selection concept and shouldn't announce "not selected" as if it were part of a toggle group,
+ * while a filter chip that IS controlled (`selected` passed, even `false`) gets the full toggle
+ * semantics (WCAG 4.1.2 — a widget's state is only exposed when the widget actually has that state).
+ */
+export declare function resolveChipAccessibility(input: ChipAccessibilityInput): ChipAccessibilityProps;
+/**
+ * Structural styles only — layout, height, padding, radius, border WIDTH. No colours (tone/selected
+ * driven, applied inline over this), so this compiles once per theme identity via the themed
+ * resolver. `variant` controls border WIDTH the same way Button's own `variant` does: a hairline for
+ * `outline`, zero for `solid`/`subtle` — `resolveChipColors` supplies the border COLOUR, so
+ * `outline` is the only variant that ever draws a visible ring (`solid`/`subtle`/selected set the
+ * colour to match their own fill, or to `"transparent"`, regardless of this width).
+ */
+export declare const chipStructure: import("../../core/style").ThemedVariantResolver<Theme, {
+    size: {
+        sm: {
+            height: 28;
+            paddingHorizontal: number;
+        };
+        md: {
+            height: 32;
+            paddingHorizontal: number;
+        };
+    };
+    variant: {
+        solid: {
+            borderWidth: number;
+        };
+        outline: {
+            borderWidth: 1;
+        };
+        subtle: {
+            borderWidth: number;
+        };
+    };
+}, import("react-native").ViewStyle>;
+/**
+ * The pill's own trailing gutter, widened to hold the remove control's slot. The control itself is
+ * a SIBLING of the chip's `Pressable` (it would be unreachable to a screen reader nested inside
+ * one — see `Chip.tsx`), so nothing in flow reserves its space; this padding does. The arithmetic
+ * reproduces the old in-flow layout exactly: gutter + touch box + the chip's own `columnGap`.
+ */
+export declare const chipRemoveSlotStructure: import("../../core/style").ThemedVariantResolver<Theme, {
+    size: {
+        sm: {
+            paddingRight: number;
+        };
+        md: {
+            paddingRight: number;
+        };
+    };
+}, import("react-native").ViewStyle>;
+/**
+ * The remove glyph's own small touch box — a circle, so its pressed-state fill (see `Chip.tsx`)
+ * reads as a rounded affordance rather than a square patch inside the pill. Absolutely positioned
+ * over the slot `chipRemoveSlotStructure` reserves, which is what lets it be a sibling of the chip's
+ * `Pressable` while still sitting inside the pill: the chip's own background (and its pressed tint)
+ * keeps running underneath it, exactly as when it was a child.
+ */
+export declare const chipRemoveTouchStructure: import("../../core/style").ThemedVariantResolver<Theme, {
+    size: {
+        sm: {
+            right: number;
+            top: number;
+        };
+        md: {
+            right: number;
+            top: number;
+        };
+    };
+}, import("react-native").ViewStyle>;
+/** Resolves `ChipGroup`'s `gap` prop onto the theme's spacing scale — a direct value, not its own
+ *  `createThemedVariants` sheet, since `ChipGroup` has no other structural variant to compile
+ *  alongside it (see `ChipGroup.tsx`). */
+export declare function resolveChipGroupGap(theme: Theme, gap: ChipGroupGap): number;
+//# sourceMappingURL=Chip.variants.d.ts.map

package/lib/typescript/modules/chip/ChipGroup.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ChipGroup — a thin layout wrapper for a row of `Chip`s: wraps onto multiple lines by default, or
+ * scrolls horizontally (`scrollable`) for a filter rail. Owns no chip state of its own — selection/
+ * removal stay on each `Chip`'s own `onPress`/`onRemove`, the same "props in, events out" stance
+ * every layout-only wrapper in this library takes.
+ */
+import type { ReactNode } from "react";
+import type { LayoutStyle } from "../../core/style";
+import type { ChipGroupGap } from "./Chip.variants";
+export interface ChipGroupProps {
+    children: ReactNode;
+    /** Ignored when `scrollable` is true — a horizontal rail never wraps. */
+    wrap?: boolean;
+    gap?: ChipGroupGap;
+    /** Horizontal `ScrollView` (no wrap), for a filter rail that scrolls instead of wrapping. */
+    scrollable?: boolean;
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    style?: LayoutStyle;
+    testID?: string;
+}
+export declare const ChipGroup: import("react").NamedExoticComponent<ChipGroupProps>;
+//# sourceMappingURL=ChipGroup.d.ts.map

package/lib/typescript/modules/chip/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Public surface of `pixelize-native-library/chip`. Value exports and type exports are split for
+ * `verbatimModuleSyntax`. The resolvers (`resolveChipColors`, `CHIP_SIZES`, …) stay internal — a
+ * consumer configures a Chip through its props, never by importing its internals.
+ */
+export { Chip } from "./Chip";
+export type { ChipProps } from "./Chip";
+export { ChipGroup } from "./ChipGroup";
+export type { ChipGroupProps } from "./ChipGroup";
+export type { ChipGroupGap, ChipSize, ChipTone, ChipVariant, CustomToneColors } from "./Chip.variants";
+export type { IconName } from "../../core/icon";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/modules/combobox/Combobox.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Combobox — a searchable/filterable select. A NEW module rather than a `searchable` prop on
+ * `select`: the interaction model differs materially (a text input owns focus, results filter live,
+ * there is an async/loading path, and there is a "no results" state) — bolting that onto `Select`
+ * would double its complexity for every existing caller who never needs search.
+ *
+ * Structurally it mirrors `Select`/`MultiSelect`: a trigger field that opens an option list in React
+ * Native's OWN `Modal`, imported directly from `"react-native"` on purpose — this module must never
+ * depend on the library's own `Modal` COMPONENT, and (like every sibling picker) never imports
+ * another module's component either, with two narrow, deliberate exceptions:
+ *
+ *  1. The web portal mechanism — `ModalPortalContext`/`renderWebPortal` are a plain context + a
+ *     stateless helper with no React-tree footprint of their own (not the `Modal` component), so
+ *     Combobox reads the same ones `Modal.tsx`/`Select.tsx`/`MultiSelect.tsx` read to stay consistent
+ *     once a consumer opts in via `ModalPortalProvider`.
+ *  2. `Spinner` for the list's loading state — a small, dependency-free leaf component this library
+ *     already reuses directly across modules (e.g. `SearchBar`), unlike the heavier, stateful
+ *     components (`Modal`, `Checkbox`'s row indicator) every sibling picker duplicates instead.
+ *
+ * The search field is its OWN local `TextInput` — it does NOT import this library's `Input`. This
+ * mirrors `SearchBar`'s own documented precedent for the identical tension: `Input` exposes no
+ * `autoFocus`/ref surface (it isn't `forwardRef`, and accepts no `{...rest}` per this library's API
+ * contract), so a field that must genuinely autofocus when the sheet opens cannot be built on top of
+ * it. Reusing `Input`'s exact size/role-colour contract (never its component) keeps this module
+ * consistent with the rest of the library while still delivering the autofocus the spec calls for.
+ *
+ * The trigger's focus/open indicator is `Input`'s offset ring (drawn outside the field, on the
+ * canvas), not `Select`/`MultiSelect`'s older border-colour swap — their own docs already flag that
+ * swap as provisional, pending reconciliation with `Input`'s newer, now-current convention. Combining
+ * a border swap AND a ring would double-signal the same state, so the trigger border here is
+ * `error`-driven only (see `Combobox.variants.ts`).
+ */
+import type { LayoutStyle } from "../../core/style";
+import type { ComboboxOption } from "./Combobox.variants";
+export type { ComboboxOption };
+interface ComboboxCommonProps {
+    options: ComboboxOption[];
+    placeholder?: string;
+    searchPlaceholder?: string;
+    label?: string;
+    disabled?: boolean;
+    /** Shown below the field; announced on both platforms via `useAnnounce`. */
+    error?: string;
+    /** Shows an "x" on the field once something is selected. */
+    clearable?: boolean;
+    /** Swaps the option list for a centered `Spinner` — the list area, not the search field. */
+    loading?: boolean;
+    emptyMessage?: string;
+    /**
+     * Presence signals SERVER-side filtering: once provided, `Combobox` renders `options` verbatim and
+     * never filters locally, even if `filterFn` is also passed. Absent (the default) means local
+     * filtering. Debounced by `SEARCH_DEBOUNCE_MS`. This is the prop most likely to be misused —
+     * passing it does not add server-side filtering on top of local filtering, it REPLACES it.
+     */
+    onSearchChange?: (query: string) => void;
+    /** Overrides local filtering. Ignored entirely when `onSearchChange` is set. Default is
+     *  `defaultComboboxFilter` (case- and diacritic-insensitive substring match on `label`). */
+    filterFn?: (option: ComboboxOption, query: string) => boolean;
+    maxHeight?: number;
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    style?: LayoutStyle;
+    testID?: string;
+}
+export interface ComboboxSingleProps extends ComboboxCommonProps {
+    multiple?: false;
+    value: string | null;
+    onChange: (value: string | null) => void;
+}
+export interface ComboboxMultipleProps extends ComboboxCommonProps {
+    multiple: true;
+    values: string[];
+    onValuesChange: (values: string[]) => void;
+}
+/**
+ * A discriminated union, not one flat interface with every field optional: `multiple: true` requires
+ * `values`/`onValuesChange`, the default (`multiple` absent/`false`) requires `value`/`onChange` — a
+ * caller can never wire the wrong pair for the active mode and have it silently do nothing.
+ */
+export type ComboboxProps = ComboboxSingleProps | ComboboxMultipleProps;
+export declare const Combobox: import("react").NamedExoticComponent<ComboboxProps>;
+//# sourceMappingURL=Combobox.d.ts.map

package/lib/typescript/modules/combobox/Combobox.variants.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Combobox's pure data/style/behaviour resolution — same split every reference module uses:
+ *  - STRUCTURE (heights, padding, radius, border WIDTH) lives in the `createThemedVariants`
+ *    resolvers, registered once per theme identity.
+ *  - COLOUR is resolved from the theme's ROLE colours by `resolveComboboxTriggerColors` /
+ *    `resolveComboboxRowColors` / `resolveComboboxErrorTextColor`, never a raw ramp, never a
+ *    hardcoded hex.
+ *  - ACCESSIBILITY prop derivation (`resolveComboboxAccessibility`, `resolveComboboxRowAccessibility`)
+ *    is kept pure so the "disabled blocks opening / expanded tracks the sheet / selected+disabled per
+ *    row" contract is unit-testable without rendering React Native.
+ *  - SEARCH/SELECTION logic (`defaultComboboxFilter`, `resolveComboboxSummary`) is pure too, so the
+ *    filtering and trigger-summary rules are unit-tested directly. `defaultComboboxFilter` is the
+ *    SPEC of the default local filter, and is what a caller-supplied `filterFn` replaces — but the
+ *    component no longer calls it per option: it memoizes one normalized-label array per `options`
+ *    identity and reuses it for every pass (`Combobox.tsx`), which must stay byte-identical to this
+ *    function's result (`Combobox.filter.test.ts` pins that).
+ *
+ * `ComboboxOption` lives here, not in `Combobox.tsx`: unlike `Select`'s/`MultiSelect`'s option types
+ * (which carry a `ReactNode leading` and so must live in the component file), every field here is a
+ * plain value — no React import needed — so it can be pure like the rest of this file.
+ *
+ * Free of React and of any `Modal`/`Pressable`/`TextInput` import, so the WCAG + logic tests import
+ * this directly (mocking only `react-native`'s `StyleSheet`, as `core/style` does).
+ */
+import type { AccessibilityRole } from "react-native";
+import type { RoleColors, Theme } from "../../theme/hooks";
+import type { IconName } from "../../core/icon";
+export interface ComboboxOption {
+    readonly value: string;
+    readonly label: string;
+    readonly icon?: IconName;
+    readonly description?: string;
+    readonly disabled?: boolean;
+}
+/** Same touch-target floor as Button/Select/Input (44dp — Apple HIG minimum, WCAG 2.5.5 AAA). */
+export declare const MIN_TOUCH_TARGET = 44;
+/** No `size` prop (unlike Select/MultiSelect) — not part of this module's spec, and a search sheet's
+ *  proportions don't benefit from the sm/lg range those triggers offer. One fixed box, sized exactly
+ *  like Input's/Select's `md`, so a Combobox lines up with either in the same form. */
+export declare const COMBOBOX_FIELD_HEIGHT = 40;
+export declare const COMBOBOX_FIELD_FONT_SIZE = 16;
+export declare const COMBOBOX_FIELD_ICON_SIZE = 18;
+export declare const COMBOBOX_FIELD_HIT_SLOP: number;
+/** The trigger's clear ("x") affordance, nested inside the field `Pressable` exactly like
+ *  `DatePicker`'s own clear button — RN's responder system resolves a touch to the innermost
+ *  `Pressable` that claims it, so the field's own `onPress` never also fires. Narrower than the
+ *  field is tall, so it reaches 44×44 through `hitSlop` rather than through its own width. */
+export declare const COMBOBOX_CLEAR_BUTTON_WIDTH = 32;
+export declare const COMBOBOX_CLEAR_BUTTON_HIT_SLOP: number;
+/** Minimum height for an option row — a list item is still an interactive target (WCAG 2.5.8). Not a
+ *  fixed height: a row with a `description` line grows past this floor. */
+export declare const COMBOBOX_ROW_MIN_HEIGHT = 44;
+export declare const COMBOBOX_ROW_ICON_SIZE = 18;
+export declare const DEFAULT_PLACEHOLDER = "Select\u2026";
+export declare const DEFAULT_SEARCH_PLACEHOLDER = "Search\u2026";
+export declare const DEFAULT_EMPTY_MESSAGE = "No results";
+export declare const DEFAULT_MAX_HEIGHT = 320;
+/** `onSearchChange` debounce window — a fixed design constant, not a caller-facing prop (the spec
+ *  this module was built against fixes it at 250ms). */
+export declare const SEARCH_DEBOUNCE_MS = 250;
+/** Local-filter debounce — shorter than the networked `SEARCH_DEBOUNCE_MS`; only outruns a typing burst. */
+export declare const FILTER_DEBOUNCE_MS = 140;
+/**
+ * Strips combining diacritical marks after Unicode NFD decomposition, so "José" and "jose" match the
+ * same query. Lowercased last so the comparison is also case-insensitive.
+ */
+export declare function normalizeForSearch(value: string): string;
+/**
+ * The option list's container role — what makes `aria-activedescendant` on the search field mean
+ * anything. RN 0.86's role unions have no `listbox` (both `Role` and `AccessibilityRole` jump
+ * `list` → `listitem` → `log`), so the widening lives on this ONE audited line instead of a cast at
+ * the call site. It is a type gap, not a runtime one: `react-native-web` emits the string as the DOM
+ * `role` verbatim, and native maps roles it doesn't know to nothing.
+ */
+export declare const COMBOBOX_LISTBOX_ROLE: AccessibilityRole;
+/**
+ * Each option row's role. `aria-selected` is only valid ARIA on `option`/`row`/`tab`/`gridcell`/
+ * `treeitem` — the row sits inside a `COMBOBOX_LISTBOX_ROLE` container, so `option` is the
+ * textbook-correct pairing (2026-08 sweep fixed the row from the invalid `menuitem`+`aria-selected`
+ * combination — a followup to `select/Select.tsx`'s identical fix, both listbox/option/aria-selected
+ * per the ARIA 1.2 combobox-with-listbox-popup pattern). Same type gap as `COMBOBOX_LISTBOX_ROLE`:
+ * RN 0.86's `AccessibilityRole` union has no `option` either.
+ */
+export declare const COMBOBOX_OPTION_ROLE: AccessibilityRole;
+/**
+ * The DOM id of one option row. `aria-activedescendant` and `nativeID` must agree exactly, and
+ * every `aria-*` prop is UNCHECKED by TypeScript on an RN component (hyphenated JSX attributes are
+ * not type-checked at all) — so the id is derived here once rather than interpolated at each call
+ * site, where a typo would silently produce a dangling reference no compiler would catch.
+ */
+export declare function comboboxOptionNativeId(listId: string, value: string): string;
+/**
+ * The default local `filterFn`: case-insensitive, diacritic-insensitive substring match on `label`.
+ * An empty/whitespace-only query matches everything, so clearing the search box restores the full
+ * list instead of an empty one.
+ */
+export declare function defaultComboboxFilter(option: ComboboxOption, query: string): boolean;
+export interface ComboboxSummaryInput {
+    readonly options: ComboboxOption[];
+    readonly selectedValues: readonly string[];
+    readonly placeholder: string;
+}
+/**
+ * The trigger's display text — one rule for both single and multiple mode, since single mode is just
+ * "at most one selected value" flowing through the same collapsing rule: 0 → placeholder, 1 → that
+ * option's label, 2 → both labels joined, 3+ → "N selected". A selected value with no matching option
+ * (e.g. stale data) falls back to "1 selected" / the raw value rather than rendering nothing.
+ */
+export declare function resolveComboboxSummary(input: ComboboxSummaryInput): string;
+export interface ComboboxTriggerColors {
+    /** Trigger fill — the same surface an Input's/Select's box sits on. */
+    readonly background: string;
+    /** Boundary colour: the neutral interactive outline, or `status.danger.solid` while `error` is
+     *  set. NOT focus-driven — unlike `Select`/`MultiSelect`'s border-swap, focus/open is signalled by
+     *  `Combobox`'s offset ring instead (see the component), `Input`'s exact convention. Combining a
+     *  border swap AND a ring would double-signal the same state. */
+    readonly border: string;
+    /** Colour for the summary text once something is selected. */
+    readonly text: string;
+    /** Colour for the placeholder (nothing selected yet). */
+    readonly placeholder: string;
+    /** Chevron / clear-icon colour. */
+    readonly icon: string;
+}
+/**
+ * Maps trigger state onto role colours — the reason there is no free-form `color` prop. `error`
+ * mirrors `Input.resolveInputStatus`'s exact precedence: the error border reads `status.danger.solid`
+ * (NOT `status.danger.border`, which measures below 3:1 on every brand — see `Input.test.ts`'s
+ * identical finding).
+ */
+export declare function resolveComboboxTriggerColors(colors: RoleColors, state: {
+    readonly error: boolean;
+}): ComboboxTriggerColors;
+/** The error message under the field, read on the canvas — same role `Input.resolveInputStatus` uses
+ *  for its own `errorText`. */
+export declare function resolveComboboxErrorTextColor(colors: RoleColors): string;
+export interface ComboboxRowColors {
+    /** Row / search-row fill — the sheet's own surface. Kept constant across selection: `bg.selected`
+     *  is not proven ≥ 4.5:1 against `fg.default` on every brand (measured: fails on radiant/rosewood
+     *  light — same finding `Select`'s rows document). Selection is conveyed by the "check" glyph +
+     *  `accessibilityState.selected`, never by a background tint. */
+    readonly background: string;
+    /** Option label, and the search box's own typed text. */
+    readonly text: string;
+    /** The option `description` line, the search placeholder, and the empty-state message — all the
+     *  muted-text pairings, sharing one measured rung. */
+    readonly muted: string;
+    /** Hint ink for the row's own field — a hint, not body copy. */
+    readonly placeholder: string;
+    /** Leading option icon, the search glyph, and the clear-row icon. */
+    readonly icon: string;
+    /** The selected row's "check" glyph. Same value as `text`: if the label clears the stricter 4.5:1
+     *  text minimum, the icon clears its looser 3:1 non-text minimum for free (same reasoning
+     *  `Select`'s active-row check glyph relies on). */
+    readonly checkIcon: string;
+    /** Row background while pressed — `bg.sunken`, not `bg.hover`: the same fix `Button`'s "neutral"
+     *  tone and `RadioGroup`/`Menu`/`Select` document (the saturated `hover` mid-tone risks dropping
+     *  `text` below 4.5:1 on brand-tinted palettes; the pale `sunken` tint doesn't). */
+    readonly pressedRow: string;
+}
+export declare function resolveComboboxRowColors(colors: RoleColors): ComboboxRowColors;
+export interface ComboboxAccessibilityInput {
+    readonly disabled?: boolean | undefined;
+    readonly open: boolean;
+}
+export interface ComboboxAccessibilityProps {
+    readonly accessibilityRole: "combobox";
+    /** Flat, never `accessibilityState`: react-native-web discards the object form (see
+     *  `docs/PLATFORM-A11Y-PROPS.md`). Quoted keys so the compiler still checks the prop names. */
+    readonly "aria-disabled": boolean;
+    readonly "aria-expanded": boolean;
+    /** The `Pressable` `disabled` prop — blocks opening the sheet while disabled. */
+    readonly disabled: boolean;
+}
+/**
+ * Derives the field's accessibility surface once, purely: `expanded` tracks whether the sheet is
+ * showing (WCAG 4.1.2), `disabled` blocks it from opening at all.
+ */
+export declare function resolveComboboxAccessibility(input: ComboboxAccessibilityInput): ComboboxAccessibilityProps;
+export interface ComboboxRowAccessibilityInput {
+    readonly selected: boolean;
+    readonly disabled: boolean;
+}
+export interface ComboboxRowAccessibilityProps {
+    readonly accessibilityRole: AccessibilityRole;
+    /** Flat, never `accessibilityState`: react-native-web discards the object form (see
+     *  `docs/PLATFORM-A11Y-PROPS.md`). Quoted keys so the compiler still checks the prop names. */
+    readonly "aria-selected": boolean;
+    readonly "aria-disabled": boolean;
+    readonly disabled: boolean;
+}
+/**
+ * Every row is `option` (2026-08 sweep — was `menuitem`, which made `aria-selected` invalid ARIA;
+ * the row sits inside `COMBOBOX_LISTBOX_ROLE`, so `option` is the textbook-correct pairing), in BOTH
+ * single and multiple mode: this module's `aria-activedescendant` pattern is one listbox regardless
+ * of mode, unlike `MultiSelect`'s own separate `checkbox` rows. Selection state rides `aria-selected`,
+ * never `aria-checked`.
+ */
+export declare function resolveComboboxRowAccessibility(input: ComboboxRowAccessibilityInput): ComboboxRowAccessibilityProps;
+/**
+ * Structural styles only — layout, height, padding, radius, border WIDTH. No colours (state-driven,
+ * applied inline over this), so this compiles once per theme identity via the themed resolver.
+ */
+export declare const comboboxFieldStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** The open-target's own inner row — the selected option's icon (single mode) + the summary text,
+ *  kept in one shrinkable cluster so the clear button and chevron stay pinned to the trailing edge. */
+export declare const comboboxFieldValueStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const comboboxClearButtonStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** The full-screen overlay the sheet centers in — byte-identical to `Select`'s. `box-none` (applied
+ *  by the component) lets a tap on its empty padding fall through to the backdrop press underneath. */
+export declare const comboboxOverlayStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** No `maxHeight` baked in here — it is the one caller-configurable dimension (`maxHeight` prop,
+ *  default `DEFAULT_MAX_HEIGHT`) and is applied inline over this at the component boundary. */
+export declare const comboboxSheetStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** The search row's bottom border doubles as the divider between it and the option list — one fewer
+ *  node than a dedicated `Divider`. Colour (`border.default`, the decorative rung) is applied inline. */
+export declare const comboboxSearchRowStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** The loading spinner / empty-message container — centered in the space the option list would
+ *  otherwise occupy. */
+export declare const comboboxListStateStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const comboboxRowStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** The label + optional description cluster — `rowGap` mirrors `ListItem`'s identical title/subtitle
+ *  spacing. */
+export declare const comboboxRowTextStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+//# sourceMappingURL=Combobox.variants.d.ts.map

package/lib/typescript/modules/combobox/comboboxKeys.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Native/default counterpart of `comboboxKeys.web.ts` — the `core/a11y/keyboard.ts` pattern, local
+ * to this module. Physical-keyboard interaction is a web concern, so this is a no-op with an
+ * identical signature, and Metro keeps the DOM half out of the native graph entirely.
+ *
+ * **Why this exists instead of `core/a11y`'s `useRovingKeys`.** That helper is the right one for
+ * `menu`/`select`/`multi-select`, but its Enter/Space branch calls `preventDefault()`
+ * unconditionally — and this container holds the search `TextInput`. Attaching it here would make
+ * the space bar untypable in the search field, so Combobox handles the four navigation keys plus
+ * Enter itself and leaves Space entirely to the input. Everything else it needs (Escape, the focus
+ * trap) still comes from `core/a11y/keyboard`.
+ */
+import type { RefObject } from "react";
+import type { View } from "react-native";
+export interface ComboboxKeysOptions {
+    /** Number of options currently in the list. */
+    readonly count: number;
+    /** Index of the `aria-activedescendant` option. */
+    readonly activeIndex: number;
+    readonly onActiveIndexChange: (index: number) => void;
+    /** Enter on the container — Space is deliberately NOT an activation key here. */
+    readonly onActivate: (index: number) => void;
+}
+export declare function useComboboxKeys(_ref: RefObject<View | null>, _active: boolean, _options: ComboboxKeysOptions): void;
+//# sourceMappingURL=comboboxKeys.d.ts.map

package/lib/typescript/modules/combobox/comboboxKeys.web.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Web implementation of Combobox's own arrow-key navigation. Metro resolves this file only for a
+ * web bundle (see `comboboxKeys.ts`, which also documents why `core/a11y`'s `useRovingKeys` cannot
+ * be used for this particular container), so it is free to assume a DOM.
+ *
+ * DOM types are hand-written for the same reason `core/a11y/keyboard.web.ts` and
+ * `modules/modal/renderWebPortal.web.ts` hand-write theirs: `tsconfig.json` sets `"lib": ["ESNext"]`,
+ * so `document`/`HTMLElement`/`KeyboardEvent` do not exist as types, `any` is lint-banned, and
+ * augmenting `react-native`'s types would ship through `lib/typescript/**`.
+ */
+import type { RefObject } from "react";
+import type { View } from "react-native";
+import type { ComboboxKeysOptions } from "./comboboxKeys";
+export type { ComboboxKeysOptions };
+/**
+ * Arrow/Home/End/Enter navigation for the `aria-activedescendant` listbox pattern: focus never
+ * leaves the search field, only the active index moves.
+ *
+ * Listens on the CONTAINER in the CAPTURE phase — that is what gets past the focused `TextInput`,
+ * whose own key handling runs while the event bubbles.
+ */
+export declare function useComboboxKeys(ref: RefObject<View | null>, active: boolean, options: ComboboxKeysOptions): void;
+//# sourceMappingURL=comboboxKeys.web.d.ts.map

package/lib/typescript/modules/combobox/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public surface of `pixelize-native-library/combobox`. Value exports and type exports are split for
+ * `verbatimModuleSyntax`. The resolvers (`resolveComboboxTriggerColors`, `defaultComboboxFilter`, …)
+ * stay internal — a consumer configures a Combobox through its props, never by importing its
+ * internals.
+ */
+export { Combobox } from "./Combobox";
+export type { ComboboxProps, ComboboxSingleProps, ComboboxMultipleProps } from "./Combobox";
+export type { ComboboxOption } from "./Combobox.variants";
+export type { IconName } from "../../core/icon";
+//# sourceMappingURL=index.d.ts.map