@olympusoss/canvas 3.2.1 → 5.0.0

package/src/atoms/checkbox/checkbox.shared.tsx

@@ -0,0 +1,103 @@
+import { type ReactNode } from "react";
+import { type GestureResponderEvent } from "react-native";
+import { View, Pressable, Text, useTheme, type ColorTokens, type StyleProp, type ViewStyle, type TextStyle } from "../../style/index.js";
+
+// Shared Checkbox shell. Uses React Native's primitives DIRECTLY and reads the
+// active brand tokens via useTheme, so colors follow light/dark and the glass
+// surface. The shared structure (the box + glyph + label row, the size precedence,
+// accessibility, onChange/onValueChange, indeterminate) lives here once; a platform
+// file supplies only its skin (box shape/sizing/border, glyph color, press feedback)
+// and calls createCheckbox. iOS has no native checkbox, so every skin is hand-drawn
+// from the brand tokens — no platform default color ever leaks in.
+
+export interface CheckboxProps {
+  children?: ReactNode;
+  /** Controlled checked state. The component renders exactly this value. */
+  checked?: boolean;
+  /**
+   * Mixed state: some-but-not-all selected. Shown as a dash, not a tick.
+   * Takes visual precedence over `checked`.
+   */
+  indeterminate?: boolean;
+  /** Fired with the next checked value when the row is pressed. */
+  onChange?: (next: boolean) => void;
+  /** Alias of onChange, for parity with RN's value-style callbacks. */
+  onValueChange?: (next: boolean) => void;
+  // Size (pick one; default is the base box).
+  small?: boolean;
+  large?: boolean;
+  // State.
+  disabled?: boolean;
+  /** Escape hatch for layout/positioning composition. */
+  style?: StyleProp<ViewStyle>;
+}
+
+export type Size = "small" | "base" | "large";
+
+// Size precedence when more than one is passed: first match wins.
+function sizeOf(p: CheckboxProps): Size {
+  if (p.large) return "large";
+  if (p.small) return "small";
+  return "base";
+}
+
+// The only thing a platform skin owns: the box, glyph, and label styles for a given
+// state and size, plus the press/disabled feedback. Everything else is the shell.
+export interface CheckboxSkin {
+  /** The square box. `filled` = checked or indeterminate. */
+  box: (tokens: ColorTokens, filled: boolean, size: Size) => ViewStyle;
+  /** The check / dash glyph inside a filled box. */
+  glyph: (tokens: ColorTokens, size: Size) => TextStyle;
+  /** The label text to the right of the box. */
+  label: (tokens: ColorTokens, size: Size) => TextStyle;
+  /** Opacity applied to the row when disabled. */
+  disabledOpacity: number;
+  /** iOS/web dim the row on press; Android uses a ripple instead (null). */
+  pressedOpacity: number | null;
+  /** Android ripple over the box; null on iOS/web. */
+  ripple: ((tokens: ColorTokens) => { color: string; borderless: boolean; radius?: number }) | null;
+}
+
+// The row: box + optional label, top-aligned so a multi-line label hangs from the box.
+const ROW: ViewStyle = { flexDirection: "row", alignItems: "flex-start", gap: 8 };
+
+/** Build a Checkbox component from a platform skin. */
+export function createCheckbox(skin: CheckboxSkin) {
+  return function Checkbox(props: CheckboxProps) {
+    const { children, checked, indeterminate, onChange, onValueChange, disabled, style } = props;
+    const size = sizeOf(props);
+    const { tokens } = useTheme();
+    // Indeterminate reads as "selected-ish": fill the box like a checked state.
+    const filled = indeterminate || !!checked;
+    const glyph = indeterminate ? "–" : "✓"; // en dash : check mark
+
+    const handlePress = (_event: GestureResponderEvent) => {
+      const next = !checked;
+      onChange?.(next);
+      onValueChange?.(next);
+    };
+
+    const ripple = skin.ripple ? skin.ripple(tokens) : undefined;
+
+    return (
+      <Pressable
+        onPress={handlePress}
+        disabled={disabled}
+        accessibilityRole="checkbox"
+        accessibilityState={{ checked: indeterminate ? "mixed" : !!checked, disabled: !!disabled }}
+        android_ripple={ripple}
+        style={({ pressed }) => [
+          ROW,
+          disabled ? { opacity: skin.disabledOpacity } : null,
+          skin.pressedOpacity != null && pressed ? { opacity: skin.pressedOpacity } : null,
+          style,
+        ]}
+      >
+        <View style={skin.box(tokens, filled, size)}>
+          {filled ? <Text style={skin.glyph(tokens, size)}>{glyph}</Text> : null}
+        </View>
+        {children != null ? <Text style={skin.label(tokens, size)}>{children}</Text> : null}
+      </Pressable>
+    );
+  };
+}

package/src/atoms/checkbox/checkbox.styles.ts

@@ -0,0 +1,106 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens } from "../../style/index.js";
+import { type CheckboxSkin, type Size } from "./checkbox.shared.js";
+
+// Co-located Checkbox skins, one per platform, all driven by the brand tokens
+// (passed in from useTheme so they follow light/dark and the glass surface). The
+// BRAND survives on every platform (the filled box is always the indigo `primary`,
+// never a platform default), and only the native SHAPE, sizing, border weight, and
+// press feedback change per OS:
+//   iOS (HIG): no native checkbox; the de-facto rounded square (~5 radius), a
+//     hairline 1px border when empty, brand fill + white check when checked, the
+//     control nudged to ~20pt; press = opacity dim (~0.8).
+//   Android (Material 3): an 18dp square with a 2dp corner radius and a 2dp outline
+//     when empty, brand fill + white check when checked; press = android_ripple over
+//     a 40dp state layer; disabled opacity 0.38.
+//   Web: the established Canvas look (the current checkbox, lifted verbatim) —
+//     14/16/20px box per size, 3 radius, 1px border, brand fill + foreground check.
+
+// Box dimensions per size.
+const WEB_BOX: Record<Size, number> = { small: 14, base: 16, large: 20 };
+const IOS_BOX: Record<Size, number> = { small: 18, base: 20, large: 24 };
+const ANDROID_BOX: Record<Size, number> = { small: 18, base: 18, large: 20 };
+
+// Glyph (check / dash) type per box family. The check sits inside the box, so the
+// font tracks the box size; `lineHeight: fontSize` keeps it optically centered.
+function glyphType(fontSize: number): TextStyle {
+  return { fontSize, lineHeight: fontSize };
+}
+const WEB_GLYPH: Record<Size, number> = { small: 12, base: 12, large: 14 };
+const IOS_GLYPH: Record<Size, number> = { small: 13, base: 14, large: 17 };
+const ANDROID_GLYPH: Record<Size, number> = { small: 13, base: 13, large: 15 };
+
+// Label type per size (shared across platforms; the label is brand type, not a
+// platform face). Matches the original Canvas label scale.
+const LABEL_TYPE: Record<Size, TextStyle> = {
+  small: { fontSize: 12, lineHeight: 16 }, // text-xs
+  base: { fontSize: 14, lineHeight: 20 }, // text-sm
+  large: { fontSize: 16, lineHeight: 24 }, // text-base
+};
+function label(tokens: ColorTokens, size: Size): TextStyle {
+  return { fontWeight: "500", color: tokens.foreground, ...LABEL_TYPE[size] };
+}
+
+// Box base: a square, centered, nudged down (`marginTop: 2`) to align with the
+// label's first line. Per-platform radius/border weight is layered on by each skin.
+function boxBase(box: number): ViewStyle {
+  return {
+    marginTop: 2,
+    flexShrink: 0,
+    alignItems: "center",
+    justifyContent: "center",
+    width: box,
+    height: box,
+  };
+}
+
+// ---------- Web: the established Canvas look ----------
+export const webSkin: CheckboxSkin = {
+  box: (t, filled, size) => ({
+    ...boxBase(WEB_BOX[size]),
+    borderRadius: 3,
+    borderWidth: 1,
+    ...(filled
+      ? { borderColor: t.primary, backgroundColor: t.primary }
+      : { borderColor: t.input, backgroundColor: "transparent" }),
+  }),
+  glyph: (t, size) => ({ fontWeight: "500", color: t["primary-foreground"], ...glyphType(WEB_GLYPH[size]) }),
+  label,
+  disabledOpacity: 0.5,
+  pressedOpacity: 0.9,
+  ripple: null,
+};
+
+// ---------- iOS (HIG): rounded square, hairline border, dim on press ----------
+export const iosSkin: CheckboxSkin = {
+  box: (t, filled, size) => ({
+    ...boxBase(IOS_BOX[size]),
+    borderRadius: size === "small" ? 4 : size === "large" ? 6 : 5,
+    borderWidth: 1, // hairline when empty; the fill hides it when checked
+    ...(filled
+      ? { borderColor: t.primary, backgroundColor: t.primary }
+      : { borderColor: t.input, backgroundColor: "transparent" }),
+  }),
+  glyph: (_t, size) => ({ fontWeight: "600", color: "#ffffff", ...glyphType(IOS_GLYPH[size]) }),
+  label,
+  disabledOpacity: 0.5,
+  pressedOpacity: 0.8,
+  ripple: null,
+};
+
+// ---------- Android (Material 3): 18dp square, 2dp radius/outline, ripple ----------
+export const androidSkin: CheckboxSkin = {
+  box: (t, filled, size) => ({
+    ...boxBase(ANDROID_BOX[size]),
+    borderRadius: 2,
+    borderWidth: 2,
+    ...(filled
+      ? { borderColor: t.primary, backgroundColor: t.primary }
+      : { borderColor: t["muted-foreground"], backgroundColor: "transparent" }),
+  }),
+  glyph: (_t, size) => ({ fontWeight: "700", color: "#ffffff", ...glyphType(ANDROID_GLYPH[size]) }),
+  label,
+  disabledOpacity: 0.38, // M3 disabled opacity
+  pressedOpacity: null, // Android uses a ripple instead
+  ripple: (t) => ({ color: t.primary, borderless: true, radius: 20 }), // 40dp state layer
+};

package/src/atoms/checkbox/checkbox.tsx

@@ -0,0 +1,6 @@
+import { createCheckbox } from "./checkbox.shared.js";
+import { webSkin } from "./checkbox.styles.js";
+
+// Web Checkbox (the base; Metro falls back to it on native, web bundlers resolve it).
+export const Checkbox = createCheckbox(webSkin);
+export type { CheckboxProps } from "./checkbox.shared.js";

package/src/atoms/combobox/combobox.android.tsx

@@ -0,0 +1,6 @@
+import { createCombobox } from "./combobox.shared.js";
+import { androidSkin } from "./combobox.styles.js";
+
+// Material 3 Combobox. Metro resolves this file on Android; the docs import it for preview.
+export const Combobox = createCombobox(androidSkin);
+export type { ComboboxProps } from "./combobox.shared.js";

package/src/atoms/combobox/combobox.ios.tsx

@@ -0,0 +1,6 @@
+import { createCombobox } from "./combobox.shared.js";
+import { iosSkin } from "./combobox.styles.js";
+
+// iOS (HIG) Combobox. Metro resolves this file on iOS; the docs import it for preview.
+export const Combobox = createCombobox(iosSkin);
+export type { ComboboxProps } from "./combobox.shared.js";

package/src/atoms/combobox/combobox.md

@@ -0,0 +1,213 @@
+# Comboboxes
+
+Text input + dropdown: searchable single-select.
+
+## Usage
+
+```tsx
+<Combobox
+  options={[
+    "Ada Lovelace",
+    "Grace Hopper",
+    "Kira Tanaka",
+    "Liang Bao",
+    "Marcus Allen",
+    "Noor Park",
+    "Rachel Chen"
+  ]}
+  label="Assigned to"
+  placeholder="Search a person…"
+  style={{ maxWidth: 300 }}
+/>
+```
+
+## Variants
+
+### With helper text
+
+```tsx
+<Combobox
+  options={[
+    "Ada Lovelace",
+    "Grace Hopper",
+    "Kira Tanaka",
+    "Liang Bao",
+    "Marcus Allen",
+    "Noor Park",
+    "Rachel Chen"
+  ]}
+  label="Assigned to"
+  helperText="The person responsible for this account."
+  placeholder="Search a person…"
+  style={{ maxWidth: 300 }}
+/>
+```
+
+### Disabled
+
+```tsx
+<Combobox
+  options={[
+    "Ada Lovelace",
+    "Grace Hopper",
+    "Kira Tanaka",
+    "Liang Bao",
+    "Marcus Allen",
+    "Noor Park",
+    "Rachel Chen"
+  ]}
+  label="Assigned to"
+  placeholder="Search a person…"
+  disabled
+  style={{ maxWidth: 300 }}
+/>
+```
+
+## Do & Don't
+
+### When to use
+
+**Do** — A plain select for short, fixed lists; reserve the combobox for long, searchable ones.
+
+```tsx
+<Select label="Size" options={["Small", "Medium", "Large"]} open placeholder="Select a size" style={{ maxWidth: 280 }} />
+```
+
+**Don't** — Type or click: a search field for three fixed options is overhead with nothing to filter.
+
+```tsx
+<Combobox label="Size" options={["Small", "Medium", "Large"]} open placeholder="Search…" style={{ maxWidth: 280 }} />
+```
+
+### Filtering
+
+**Do** — Type a few letters: the list narrows as you go, so a long list stays usable.
+
+```tsx
+<Combobox label="Assigned to" options={[
+    "Wade Cooper",
+    "Arlene Mccoy",
+    "Devon Webb",
+    "Tom Cook",
+    "Tanya Fox",
+    "Hellen Schmidt"
+  ]} query="co" open style={{ maxWidth: 280 }} />
+```
+
+**Don't** — Try typing: a search box that ignores input is just a dropdown wearing a costume.
+
+```tsx
+<View style={{ position: "relative", width: "100%", maxWidth: 280 }}>
+  <Text style={{ marginBottom: 6, fontWeight: "500", color: tokens.foreground, fontSize: 14, lineHeight: 20 }}>Assigned to</Text>
+  <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background, paddingHorizontal: 12, height: 36 }}>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens.foreground }}>co</Text>
+    <Text style={{ color: tokens["muted-foreground"], fontSize: 14, lineHeight: 20 }}>▾</Text>
+  </View>
+  <View style={{ position: "absolute", top: "100%", left: 0, right: 0, zIndex: 50, marginTop: 4, maxHeight: 240, borderRadius: 6, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.popover, padding: 4, ...shadow("lg") }}>
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 8, borderRadius: 2, paddingHorizontal: 8, paddingVertical: 6 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"], width: 14 }}> </Text>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"] }}>Wade Cooper</Text>
+    </View>
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 8, borderRadius: 2, paddingHorizontal: 8, paddingVertical: 6 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"], width: 14 }}> </Text>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"] }}>Arlene Mccoy</Text>
+    </View>
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 8, borderRadius: 2, paddingHorizontal: 8, paddingVertical: 6 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"], width: 14 }}> </Text>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"] }}>Devon Webb</Text>
+    </View>
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 8, borderRadius: 2, paddingHorizontal: 8, paddingVertical: 6 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"], width: 14 }}> </Text>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"] }}>Tom Cook</Text>
+    </View>
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 8, borderRadius: 2, paddingHorizontal: 8, paddingVertical: 6 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"], width: 14 }}> </Text>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"] }}>Tanya Fox</Text>
+    </View>
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 8, borderRadius: 2, paddingHorizontal: 8, paddingVertical: 6 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"], width: 14 }}> </Text>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"] }}>Hellen Schmidt</Text>
+    </View>
+  </View>
+</View>
+```
+
+### Selection
+
+**Do** — Click an option: it fills the input and stays marked as selected.
+
+```tsx
+<Combobox label="Assigned to" options={["Wade Cooper", "Arlene Mccoy", "Devon Webb", "Tom Cook"]} value="Devon Webb" open style={{ maxWidth: 280 }} />
+```
+
+**Don't** — Click an option: it flashes but the field stays empty, so you can't tell what you picked.
+
+```tsx
+<View style={{ position: "relative", width: "100%", maxWidth: 280 }}>
+  <Text style={{ marginBottom: 6, fontWeight: "500", color: tokens.foreground, fontSize: 14, lineHeight: 20 }}>Assigned to</Text>
+  <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background, paddingHorizontal: 12, height: 36 }}>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Pick a person…</Text>
+    <Text style={{ color: tokens["muted-foreground"], fontSize: 14, lineHeight: 20 }}>▾</Text>
+  </View>
+  <View style={{ position: "absolute", top: "100%", left: 0, right: 0, zIndex: 50, marginTop: 4, maxHeight: 240, borderRadius: 6, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.popover, padding: 4, ...shadow("lg") }}>
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 8, borderRadius: 2, paddingHorizontal: 8, paddingVertical: 6 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"], width: 14 }}> </Text>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"] }}>Wade Cooper</Text>
+    </View>
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 8, borderRadius: 2, paddingHorizontal: 8, paddingVertical: 6 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"], width: 14 }}> </Text>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"] }}>Arlene Mccoy</Text>
+    </View>
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 8, borderRadius: 2, paddingHorizontal: 8, paddingVertical: 6 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"], width: 14 }}> </Text>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"] }}>Devon Webb</Text>
+    </View>
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 8, borderRadius: 2, paddingHorizontal: 8, paddingVertical: 6 }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"], width: 14 }}> </Text>
+      <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["popover-foreground"] }}>Tom Cook</Text>
+    </View>
+  </View>
+</View>
+```
+
+### With label
+
+**Do** — A persistent label keeps the field named after a selection has filled the input.
+
+```tsx
+<Combobox label="Assigned to" options={["Wade Cooper", "Arlene Mccoy", "Devon Webb"]} value="Devon Webb" open style={{ maxWidth: 280 }} />
+```
+
+**Don't** — Once a value replaces the placeholder, an unlabeled field has nothing left to name it.
+
+```tsx
+<Combobox options={["Wade Cooper", "Arlene Mccoy", "Devon Webb"]} value="Devon Webb" open style={{ maxWidth: 280 }} />
+```
+
+### With helper text
+
+**Do** — A short placeholder plus persistent helper text keeps the rule visible while you type.
+
+```tsx
+<Combobox label="Assigned to" options={["Wade Cooper", "Arlene Mccoy", "Devon Webb"]} open placeholder="Search a person…" helperText="Deactivated users are hidden from the list." style={{ maxWidth: 280 }} />
+```
+
+**Don't** — Type a letter: guidance crammed into the placeholder vanishes the moment you start.
+
+```tsx
+<Combobox label="Assigned to" options={["Wade Cooper", "Arlene Mccoy", "Devon Webb"]} open placeholder="Pick an active teammate; deactivated users are hidden" style={{ maxWidth: 280 }} />
+```
+
+### Disabled
+
+**Do** — Show the locked value and say why it's fixed, so disabled reads as a settled choice.
+
+```tsx
+<Combobox label="Assigned to" options={["Wade Cooper", "Arlene Mccoy", "Devon Webb"]} value="Devon Webb" disabled helperText="Set by the project owner and can't be changed here." style={{ maxWidth: 280 }} />
+```
+
+**Don't** — An empty, dimmed field with no value reads as broken, not as intentionally locked.
+
+```tsx
+<Combobox label="Assigned to" options={["Wade Cooper", "Arlene Mccoy", "Devon Webb"]} disabled placeholder="Search a person…" style={{ maxWidth: 280 }} />
+```

package/src/atoms/combobox/combobox.shared.tsx

@@ -0,0 +1,160 @@
+import { useState } from "react";
+import { View, Pressable, Text, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import { wrapper, wrapperLifted } from "./combobox.styles.js";
+import { type ComboboxSkin, type Size } from "./combobox.styles.js";
+
+// Shared Combobox shell. A Combobox is a searchable single-select: it mirrors
+// Select's structure (a field plus an open option list) and adds text filtering
+// — the field shows the typed query, and the list narrows to options matching
+// that query as you type.
+//
+// The structure (the field, the open/close state machine, the query filtering,
+// the highlighted selected/active option, the helper text), the public
+// boolean-prop API, the size precedence, accessibility, and handlers all live
+// here once. A platform file supplies only its skin (field shape, fill,
+// border/underline, popover elevation, row layout, press feedback) and calls
+// createCombobox.
+//
+// Like Select, the open state is rendered inline (the docs render it this way;
+// there is no portal/Modal). `open` defaults to true so the floating list is
+// visible. The selected option carries a leading "✓" and an accent surface; an
+// empty filtered list shows a muted "No results" row.
+
+export interface ComboboxProps {
+  /** The text typed into the field. Filters the option list when set. */
+  query?: string;
+  /** The full list of selectable option labels. */
+  options?: string[];
+  /** The currently selected option label, marked with a check in the list. */
+  value?: string;
+  /** Prompt shown in the field when there is no query or value. */
+  placeholder?: string;
+  /**
+   * Whether the option list is open. Defaults to true so the open state is
+   * visible inline (the docs render it this way; there is no portal/Modal).
+   */
+  open?: boolean;
+  /** Fired when the open state changes (field tap, select). */
+  onOpenChange?: (open: boolean) => void;
+  /** Optional stacked field label rendered above the field. */
+  label?: string;
+  /** Optional muted helper line rendered below the option list. */
+  helperText?: string;
+  /** Dims the control and blocks interaction. */
+  disabled?: boolean;
+  /** Called with the chosen option label when a row is pressed. */
+  onSelect?: (option: string) => void;
+  // Size (pick one; default is the medium field, matching Input's h-9).
+  small?: boolean;
+  large?: boolean;
+  /** Escape hatch for layout/positioning composition (mainly width). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// First match wins when more than one size flag is passed.
+function sizeOf(p: ComboboxProps): Size {
+  if (p.small) return "small";
+  if (p.large) return "large";
+  return "default";
+}
+
+/** Build a Combobox component from a platform skin. */
+export function createCombobox(skin: ComboboxSkin) {
+  return function Combobox(props: ComboboxProps) {
+    const {
+      query,
+      options = [],
+      value,
+      label,
+      helperText,
+      placeholder = "Search…",
+      open: openProp,
+      onOpenChange,
+      disabled,
+      onSelect,
+      style,
+    } = props;
+    const size = sizeOf(props);
+    const { tokens } = useTheme();
+    // Uncontrolled by default: the field opens/closes the list, a select closes it.
+    const [internalOpen, setInternalOpen] = useState(false);
+    const open = openProp ?? internalOpen;
+    const setOpen = (next: boolean) => {
+      if (openProp === undefined) setInternalOpen(next);
+      onOpenChange?.(next);
+    };
+
+    // What the field shows: the typed query, then the selected value, else the
+    // placeholder. The first two read as foreground text; the placeholder is muted.
+    const hasQuery = query != null && query !== "";
+    const hasValue = value != null && value !== "";
+    const fieldText = hasQuery ? query : hasValue ? value : placeholder;
+    const fieldMuted = !hasQuery && !hasValue;
+
+    // Filter the list by the query (case-insensitive). With no query, show all.
+    const q = hasQuery ? (query as string).toLowerCase() : "";
+    const matches = hasQuery
+      ? options.filter((o) => o.toLowerCase().includes(q))
+      : options;
+
+    const ripple = skin.ripple ? skin.ripple(tokens) : undefined;
+
+    return (
+      <View style={[wrapper, open ? wrapperLifted : null, style]}>
+        {label != null && label !== "" ? (
+          <Text style={skin.label(tokens, size)}>{label}</Text>
+        ) : null}
+        <Pressable
+          style={({ pressed }) => [
+            skin.field(tokens, size, open),
+            skin.pressedOpacity != null && pressed ? { opacity: skin.pressedOpacity } : null,
+            disabled ? { opacity: skin.disabledOpacity } : null,
+          ]}
+          disabled={disabled}
+          onPress={() => setOpen(!open)}
+          android_ripple={ripple}
+          accessibilityRole="button"
+        >
+          <Text style={skin.fieldText(tokens, size, fieldMuted)}>{fieldText}</Text>
+          <Text style={skin.chevron(tokens, size)}>▾</Text>
+        </Pressable>
+
+        {open ? (
+          <View style={skin.popover(tokens)}>
+            {matches.length === 0 ? (
+              <View style={skin.emptyRow}>
+                <Text style={skin.emptyText(tokens, size)}>No results</Text>
+              </View>
+            ) : (
+              matches.map((option) => {
+                const selected = option === value;
+                return (
+                  <Pressable
+                    key={option}
+                    style={({ pressed }) => [
+                      skin.row,
+                      selected || pressed ? skin.rowAccent(tokens) : null,
+                    ]}
+                    onPress={() => {
+                      onSelect?.(option);
+                      setOpen(false);
+                    }}
+                    android_ripple={ripple}
+                    accessibilityRole="button"
+                  >
+                    <Text style={skin.check(tokens, size)}>{selected ? "✓" : " "}</Text>
+                    <Text style={skin.optionText(tokens, size)}>{option}</Text>
+                  </Pressable>
+                );
+              })
+            )}
+          </View>
+        ) : null}
+
+        {helperText != null && helperText !== "" ? (
+          <Text style={skin.helper(tokens)}>{helperText}</Text>
+        ) : null}
+      </View>
+    );
+  };
+}