@appinternalleads/ui 0.2.0

package/src/components/onboarding/combobox/ComboboxView.tsx

@@ -0,0 +1,445 @@
+import { useId, useState } from 'react';
+import { Animated, Platform, Pressable as RNPressable, ScrollView, TextInput, View, type TextStyle } from 'react-native';
+import { Box, Icon, MotionView, Pressable, Text, usePresence, useTween } from '../../../core';
+import { SkeletonBar } from '../../../ds';
+import { blockRadii, DensityScope, focusRingFor, useDs, type DensityName } from '../../../tokens';
+import { resolveConfig, type OnboardingPreset, type OnboardingResult, type PatternStatus } from '../shared/contract';
+import { InvalidConfig } from '../shared/InvalidConfig';
+import { Spinner } from '../shared/parts';
+import { AlertRow, CardToast, Ghost, Initials, LoadingMore, MiniAvatarGroup, webOnly, type WebEvents } from '../data-view/parts';
+import { initials } from '../data-view/registry';
+import { COMBO_PRESETS, validateCombobox, type ComboboxSettings, type ComboScene, type Person } from './contract';
+import { comboSeed, type ComboSeed } from './engine';
+import { useCombobox, type ComboboxApi, type ComboboxOperations } from './runtime';
+import { guarded } from '../shared/guard';
+
+export type ComboboxProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<ComboboxSettings>;
+  /** A controlled starting value; `onChange` fires after a successful apply. */
+  value?: Person[];
+  onChange?: (value: Person[]) => void;
+  operations?: ComboboxOperations;
+  /** Default "Assign ({n})". */
+  applyLabel?: string;
+  placeholder?: string;
+  max?: number;
+  disabled?: boolean;
+  /** Trigger only: no field frame, no label (Table and Grid's bulk bar). */
+  bare?: boolean;
+  placement?: 'bottom' | 'top';
+  align?: 'start' | 'end';
+  /** false: the host shows the result toast. */
+  toasts?: boolean;
+  viewport?: 'web' | 'mobile';
+  density?: DensityName;
+  /** loading / empty / error open the picker in its own load states (see `comboSeed`). */
+  status?: PatternStatus;
+  result?: OnboardingResult;
+  initial?: ComboSeed;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+const WEB = Platform.OS === 'web';
+const NO_OUTLINE = (WEB ? { outlineStyle: 'none' } : {}) as TextStyle;
+
+/**
+ * **C14 · Combobox** — a ghost trigger (a D5 avatar group, "3 people", a chevron; "Assign to…" when
+ * empty) that opens a 320-wide search panel on the web and a full-screen sheet on mobile. The panel:
+ * a search field (spinner and clear inside), "Selected · n", then "Suggested" or "Results · n",
+ * rows of 44px `role="option"`, and a footer with Cancel and one coral apply. ↑/↓ move, Space
+ * toggles the active row, Enter applies, Esc closes and returns focus to the trigger.
+ */
+function ComboboxView(props: ComboboxProps) {
+  const config = resolveConfig(COMBO_PRESETS, props.preset, {
+    ...props.config,
+    ...(props.placeholder ? { placeholder: props.placeholder } : null),
+  });
+  const issues = validateCombobox(config);
+  if (issues.length) return <InvalidConfig title={config.fieldLabel} issues={issues} testID={props.testID} />;
+  return <DensityScope density={props.density}><Valid {...props} config={config} /></DensityScope>;
+}
+
+function Valid({
+  config, value, onChange, operations, applyLabel, max, disabled, bare = false, placement = 'bottom', align = 'start', toasts = true,
+  viewport, status, result, initial, onScene, testID,
+}: Omit<ComboboxProps, 'config'> & { config: ComboboxSettings }) {
+  const { colors } = useDs();
+  const seed = initial
+    ?? (status && status !== 'ready' ? comboSeed(config, status, { toasts }) : undefined)
+    ?? (!status && config.ship ? comboSeed(config, config.ship as ComboScene, { toasts }) : undefined);
+  const api = useCombobox({ config, operations, result, initial: seed, value, max, toasts, onChange, onScene });
+  const mobile = (viewport ?? config.viewport) === 'mobile';
+  const label = applyLabel ?? config.applyLabel ?? 'Assign ({n})';
+
+  const trigger = <ComboTrigger api={api} config={config} bare={bare} disabled={disabled} />;
+  /* The board's inner width: the 320px panel never overflows a narrower board. */
+  const [inner, setInner] = useState(0);
+  const panel = api.state.open && !mobile
+    ? <ComboPanel api={api} config={config} applyLabel={label} placement={placement} align={align} maxWidth={!bare && inner > 0 ? inner : undefined} />
+    : null;
+  const sheet = api.state.open && mobile ? <ComboSheet api={api} config={config} applyLabel={label} /> : null;
+  const toast = api.state.toast ? (
+    <CardToast
+      tone={api.state.toast.tone}
+      text={api.state.toast.text}
+      action={api.state.toast.retry ? 'Retry' : undefined}
+      onAction={api.retryApply}
+      onClose={api.dismissToast}
+      style={{ bottom: 16, alignSelf: 'center' }}
+    />
+  ) : null;
+
+  if (bare) {
+    return (
+      <View style={{ position: 'relative', zIndex: api.state.open ? 10 : 0 }} testID={testID}>
+        {trigger}
+        {panel}
+        {sheet}
+      </View>
+    );
+  }
+  /* The board: the field's label, the trigger, an optional note — and the panel, sheet and toast
+     anchored to it (390 × 780 on mobile, the RN frame). */
+  return (
+    <Box
+      testID={testID}
+      gap="s2"
+      onLayout={e => setInner(Math.max(0, e.nativeEvent.layout.width - 40))}
+      style={{
+        position: 'relative', width: mobile ? 390 : '100%', maxWidth: '100%', minHeight: mobile ? 780 : 520, padding: 20,
+        borderWidth: 1, borderColor: colors.hairline, borderRadius: blockRadii.major, backgroundColor: colors.surface1,
+      }}>
+      <Text style={{ fontSize: 12, fontWeight: '600', color: colors.textPrimary }}>{config.fieldLabel}</Text>
+      <View style={{ position: 'relative', alignSelf: 'flex-start', zIndex: 10 }}>
+        {trigger}
+        {panel}
+      </View>
+      {config.selNote ? <Text style={{ fontSize: 12, color: colors.textSecondary }}>{config.selNote}</Text> : null}
+      {sheet}
+      {toast}
+    </Box>
+  );
+}
+
+/** The ghost trigger — `aria-haspopup="dialog"`, `aria-expanded`; 32px in bare mode. */
+export function ComboTrigger({ api, config, bare, disabled }: { api: ComboboxApi; config: ComboboxSettings; bare?: boolean; disabled?: boolean }) {
+  const { colors, density } = useDs();
+  const v = api.state.value;
+  const [hover, setHover] = useState(false);
+  const off = disabled || api.disabled;
+  return (
+    <Pressable
+      ref={api.triggerRef as never}
+      onPress={() => (api.state.open ? api.close() : api.openPanel())}
+      onHoverIn={() => setHover(true)}
+      onHoverOut={() => setHover(false)}
+      disabled={off}
+      aria-haspopup="dialog"
+      aria-expanded={api.state.open}
+      aria-label={api.model.triggerAria}
+      press="scale"
+      row
+      gap="s2"
+      height={bare ? 32 : density.controlH}
+      alignSelf="flex-start"
+      style={{
+        paddingLeft: v.length ? 4 : 10, paddingRight: 8, borderRadius: blockRadii.inset, boxShadow: `0 0 0 1px ${colors.hairlineStrong}`,
+        backgroundColor: hover && !off ? colors.surfaceSunken : colors.surface1, opacity: off ? 0.45 : 1,
+      }}>
+      {v.length ? <MiniAvatarGroup items={v.slice(0, 3).map(p => initials(p.name)).concat(v.length > 3 ? [`+${v.length - 3}`] : [])} size={22} /> : null}
+      <Text numeric numberOfLines={1} style={{ fontSize: 13, fontWeight: '600', color: v.length ? colors.textPrimary : colors.textSecondary }}>
+        {api.model.triggerLabel}
+      </Text>
+      <Icon name="chev-d" size={14} color={colors.textSecondary} />
+    </Pressable>
+  );
+}
+
+/** The web panel (O4 popover) — under the trigger, or above it with `placement="top"`. M10 in. */
+export function ComboPanel({ api, config, applyLabel, placement, align, maxWidth }: {
+  api: ComboboxApi; config: ComboboxSettings; applyLabel: string; placement: 'bottom' | 'top'; align: 'start' | 'end';
+  /** The room the host has — the panel is 320 wide, or less in a narrower board. */
+  maxWidth?: number;
+}) {
+  const { colors, lift2 } = useDs();
+  const p = usePresence(true, { appear: true, distance: -4 });
+  return (
+    <Animated.View
+      role="dialog"
+      aria-label={config.dialogLabel || 'Choose people'}
+      {...webOnly<WebEvents>({ onKeyDown: e => { if (e.key === 'Escape') { e.preventDefault(); api.close(); } } })}
+      style={{
+        position: 'absolute', zIndex: 10, width: maxWidth ? Math.min(320, maxWidth) : 320, maxHeight: 400, padding: 8, gap: 8,
+        ...(placement === 'top' ? { bottom: '100%', marginBottom: 6 } : { top: '100%', marginTop: 6 }),
+        ...(align === 'end' ? { right: 0 } : { left: 0 }),
+        borderWidth: 1, borderColor: colors.hairlineStrong, borderRadius: blockRadii.mid, backgroundColor: colors.surface1, boxShadow: lift2,
+        opacity: p.opacity, transform: [{ translateY: p.translateY }],
+      }}>
+      <PickerBody api={api} placeholder={config.placeholder || 'Search people'} />
+      {api.state.apply === 'failed' ? <InlineApplyFailed /> : null}
+      <Box row justify="flex-end" gap="s2" style={{ paddingTop: 8, borderTopWidth: 1, borderTopColor: colors.hairline }}>
+        <Ghost label="Cancel" onPress={api.close} height={36} />
+        <ApplyButton api={api} label={applyLabel} />
+      </Box>
+    </Animated.View>
+  );
+}
+
+/** React Native: a full-screen sheet — Cancel, the title, the coral apply; the back gesture is Cancel. */
+export function ComboSheet({ api, config, applyLabel }: { api: ComboboxApi; config: ComboboxSettings; applyLabel: string }) {
+  const { colors } = useDs();
+  return (
+    <View
+      role="dialog"
+      aria-modal
+      aria-label={config.dialogLabel || 'Choose people'}
+      {...webOnly<WebEvents>({ onKeyDown: e => { if (e.key === 'Escape') { e.preventDefault(); api.close(); } } })}
+      style={{
+        position: 'absolute', top: 0, left: 0, right: 0, bottom: 0, zIndex: 10, gap: 8, paddingHorizontal: 12, paddingBottom: 12,
+        borderRadius: blockRadii.major, backgroundColor: colors.surface1,
+      }}>
+      <Box row align="center" style={{ minHeight: 52, marginHorizontal: -12, paddingHorizontal: 12, borderBottomWidth: 1, borderBottomColor: colors.hairline }}>
+        <Box flex={1} align="flex-start">
+          <Pressable onPress={api.close} height={44} style={{ paddingHorizontal: 8, marginLeft: -8, borderRadius: blockRadii.inset }}>
+            <Text style={{ fontSize: 15, color: colors.textPrimary }}>Cancel</Text>
+          </Pressable>
+        </Box>
+        <Text numberOfLines={1} role="heading" aria-level={2} style={{ fontSize: 15, fontWeight: '600', letterSpacing: -0.2, color: colors.textPrimary }}>
+          {config.sheetTitle || 'Assign'}
+        </Text>
+        <Box flex={1} align="flex-end"><ApplyButton api={api} label={applyLabel} height={36} /></Box>
+      </Box>
+      <PickerBody api={api} placeholder={config.placeholder || 'Search people'} />
+      {api.state.apply === 'failed' ? <InlineApplyFailed /> : null}
+    </View>
+  );
+}
+
+function InlineApplyFailed() {
+  const { colors } = useDs();
+  return (
+    <Box role="alert" row align="center" gap="s2" style={{ paddingVertical: 8, paddingHorizontal: 10, borderRadius: blockRadii.inset, backgroundColor: colors.statusBg.needsUser }}>
+      <Icon name="alert" size={14} color={colors.status.needsUser} />
+      <Text style={{ fontSize: 12, fontWeight: '700', color: colors.status.needsUser }}>Couldn’t assign. Nothing changed.</Text>
+    </Box>
+  );
+}
+
+/** The one coral primary: "Assign (2)" → "Assigning…" (deep coral, `aria-busy`) → done, or "Retry". */
+function ApplyButton({ api, label, height }: { api: ComboboxApi; label: string; height?: number }) {
+  const { colors, density, action } = useDs();
+  const working = api.state.apply === 'working';
+  const disabled = !api.model.n && !working;
+  const [hover, setHover] = useState(false);
+  return (
+    <Pressable
+      onPress={() => { if (api.model.n) api.apply(); }}
+      onHoverIn={() => setHover(true)}
+      onHoverOut={() => setHover(false)}
+      disabled={disabled || working}
+      aria-busy={working || undefined}
+      press="scale"
+      height={height ?? density.controlH}
+      style={{
+        paddingHorizontal: 14, borderRadius: blockRadii.inset, opacity: 1,
+        backgroundColor: working ? action.bgHover : disabled ? colors.band : hover ? action.bgHover : action.bg,
+      }}>
+      <Text numeric numberOfLines={1} style={{ fontSize: 13, fontWeight: '600', color: disabled ? colors.textSecondary : colors.accentOnFill }}>
+        {api.model.applyText(label)}
+      </Text>
+    </Pressable>
+  );
+}
+
+/** Search field, hint, listbox and its states — shared by the popover and the sheet. */
+function PickerBody({ api, placeholder }: { api: ComboboxApi; placeholder: string }) {
+  const { colors, density } = useDs();
+  const s = api.state;
+  const m = api.model;
+  const base = `cb-${useId().replace(/:/g, '')}`;
+  const listId = `${base}-list`;
+  const optId = (p: Person) => `${base}-${p.id}`;
+  const active = s.active >= 0 ? m.ordered[s.active] : undefined;
+  const [focused, setFocused] = useState(false);
+  const fade = useTween(m.dim ? 0.6 : 1);
+
+  const onKey = (e: { nativeEvent: { key: string }; preventDefault?: () => void }) => {
+    const key = e.nativeEvent.key;
+    const len = m.ordered.length;
+    if (key === 'ArrowDown') { e.preventDefault?.(); if (len) api.setActive((s.active + 1) % len); }
+    else if (key === 'ArrowUp') { e.preventDefault?.(); if (len) api.setActive((s.active - 1 + len) % len); }
+    /* Space toggles only once a row is active; otherwise it types a space. */
+    else if (key === ' ' && active) {
+      e.preventDefault?.();
+      const on = s.draft.some(d => d.id === active.id);
+      if (on || !m.atMax) api.toggle(active);
+    } else if (key === 'Enter') { e.preventDefault?.(); if (m.n && s.apply !== 'working') api.apply(); }
+    else if (key === 'Escape') { e.preventDefault?.(); api.close(); }
+  };
+
+  const row = (p: Person, i: number, on: boolean) => (
+    <OptionRow
+      key={p.id}
+      id={optId(p)}
+      person={p}
+      on={on}
+      disabled={!on && m.atMax}
+      active={i === s.active}
+      onToggle={() => api.toggle(p)}
+    />
+  );
+
+  return (
+    <>
+      <Box
+        row
+        align="center"
+        gap="s2"
+        style={{
+          height: density.controlH, paddingLeft: 10, paddingRight: 4, borderRadius: blockRadii.inset, backgroundColor: colors.surface1,
+          boxShadow: focused ? focusRingFor(colors) : `0 0 0 1px ${colors.hairlineStrong}`, flexShrink: 0,
+        }}>
+        <Icon name="search" size={15} color={colors.textSecondary} />
+        <TextInput
+          ref={api.inputRef as never}
+          value={s.q}
+          onChangeText={api.query}
+          onKeyPress={onKey as never}
+          onFocus={() => setFocused(true)}
+          onBlur={() => setFocused(false)}
+          placeholder={placeholder}
+          placeholderTextColor={colors.textSecondary}
+          autoComplete="off"
+          autoCorrect={false}
+          role="combobox"
+          aria-label={placeholder}
+          aria-expanded
+          aria-controls={listId}
+          aria-activedescendant={active ? optId(active) : undefined}
+          aria-autocomplete="list"
+          style={[{ flex: 1, minWidth: 0, height: '100%', fontSize: 13, color: colors.textPrimary }, NO_OUTLINE]}
+        />
+        {m.searching ? <Spinner size={16} label="Searching" /> : null}
+        {s.q ? (
+          <Pressable aria-label="Clear search" onPress={api.clearQuery} width={28} height={28} radius="pill">
+            <Icon name="close" size={14} color={colors.textSecondary} />
+          </Pressable>
+        ) : null}
+      </Box>
+      <View aria-live="polite" style={{ position: 'absolute', width: 1, height: 1, overflow: 'hidden', left: -10000 }}>
+        <Text>{m.liveText}</Text>
+      </View>
+      {m.atMax ? <Text numeric style={{ paddingHorizontal: 2, fontSize: 12, color: colors.textSecondary }}>{m.maxHint}</Text> : null}
+      <ScrollView
+        style={{ flexGrow: 1, flexShrink: 1, minHeight: 0, marginHorizontal: -4 }}
+        contentContainerStyle={{ gap: 2, paddingHorizontal: 4 }}
+        scrollEventThrottle={64}
+        onScroll={e => {
+          const { contentOffset, layoutMeasurement, contentSize } = e.nativeEvent;
+          if (contentOffset.y + layoutMeasurement.height > contentSize.height - 40) api.loadMore();
+        }}>
+        {/* The listbox owns options only; its section heads are plain text, its states and buttons follow it. */}
+        <View {...({ nativeID: listId, role: 'listbox', 'aria-multiselectable': true, 'aria-label': 'People' } as object)} style={{ gap: 2 }}>
+          {m.selected.length ? (
+            <>
+              <Head>{m.selectedHead}</Head>
+              {m.selected.map((p, i) => row(p, i, true))}
+            </>
+          ) : null}
+          {m.showSuggHead ? <Head>Suggested</Head> : null}
+          {m.showResultsHead ? <Head>{m.resultsHead}</Head> : null}
+          <MotionView style={{ opacity: fade, gap: 2 }}>
+            {m.others.map((p, i) => row(p, i + m.selected.length, false))}
+          </MotionView>
+        </View>
+        {m.suggLoading ? [0, 1, 2, 3].map(i => <SkeletonRow key={i} i={i} />) : null}
+        {m.noSugg ? <Text style={{ paddingVertical: 16, paddingHorizontal: 10, fontSize: 12, color: colors.textSecondary, textAlign: 'center' }}>Type to search</Text> : null}
+        {m.noResults ? (
+          <Box align="center" gap="s2" style={{ paddingVertical: 20, paddingHorizontal: 10 }}>
+            <Text style={{ fontSize: 13, color: colors.textPrimary, textAlign: 'center' }}>{m.noResultsText}</Text>
+            <Ghost label="Clear" onPress={api.clearQuery} height={28} />
+          </Box>
+        ) : null}
+        {m.searchError ? <Box style={{ marginVertical: 6 }}><AlertRow text="Couldn’t search people" action="Retry" onAction={api.retrySearch} /></Box> : null}
+        {m.moreLoading ? <Box row justify="center" style={{ minHeight: 40 }}><LoadingMore /></Box> : null}
+        {m.canMore ? <Box row justify="center" style={{ paddingVertical: 6 }}><Ghost label="Load more" onPress={api.loadMore} height={28} /></Box> : null}
+      </ScrollView>
+    </>
+  );
+}
+
+function Head({ children }: { children: string }) {
+  const { colors } = useDs();
+  return (
+    <Text role={undefined} numeric style={{ paddingTop: 8, paddingHorizontal: 10, paddingBottom: 4, fontSize: 12, fontWeight: '600', color: colors.textSecondary }}>
+      {children}
+    </Text>
+  );
+}
+
+function SkeletonRow({ i }: { i: number }) {
+  const { colors } = useDs();
+  const w: [`${number}%`, `${number}%`][] = [['50%', '32%'], ['42%', '26%'], ['56%', '30%'], ['46%', '24%']];
+  return (
+    <Box row align="center" aria-hidden style={{ gap: 10, minHeight: 44, paddingHorizontal: 10 }}>
+      <Box width={18} height={18} style={{ borderRadius: blockRadii.key, backgroundColor: colors.band }} />
+      <Box width={28} height={28} radius="pill" style={{ backgroundColor: colors.band }} />
+      <Box flex={1} gap="s2">
+        <SkeletonBar width={w[i]![0]} height={10} />
+        <SkeletonBar width={w[i]![1]} height={8} />
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * One person: an 18px checkbox visual (M7), a 28px avatar, the name and `meta`. `role="option"`,
+ * `aria-selected`; a mouse-down keeps focus in the search field, and a row is never a tab stop —
+ * the keyboard reaches it through `aria-activedescendant`.
+ */
+function OptionRow({ id, person, on, disabled, active, onToggle }: {
+  id: string; person: Person; on: boolean; disabled: boolean; active: boolean; onToggle: () => void;
+}) {
+  const { colors } = useDs();
+  const [hover, setHover] = useState(false);
+  const t = useTween(on ? 1 : 0);
+  return (
+    <RNPressable
+      nativeID={id}
+      role="option"
+      aria-selected={on}
+      aria-disabled={disabled}
+      focusable={false}
+      onPress={() => { if (!disabled) onToggle(); }}
+      onHoverIn={() => setHover(true)}
+      onHoverOut={() => setHover(false)}
+      {...webOnly<WebEvents>({ onMouseDown: e => e.preventDefault() })}
+      style={{
+        flexDirection: 'row', alignItems: 'center', gap: 10, minHeight: 44, paddingVertical: 4, paddingHorizontal: 10, borderRadius: blockRadii.inset,
+        backgroundColor: active || (hover && !disabled) ? colors.surfaceSunken : 'transparent', opacity: disabled ? 0.5 : 1,
+        ...(WEB ? ({ cursor: disabled ? 'not-allowed' : 'pointer' } as object) : null),
+      }}>
+      <Box
+        width={18}
+        height={18}
+        align="center"
+        justify="center"
+        aria-hidden
+        style={{ borderRadius: blockRadii.key, borderWidth: 1.5, borderColor: on ? colors.accentFill : colors.textSecondary, backgroundColor: on ? colors.accentFill : colors.surface1 }}>
+        <MotionView style={{ opacity: t, transform: [{ scale: t.interpolate({ inputRange: [0, 1], outputRange: [0.6, 1] }) }] }}>
+          <Icon name="tick" size={12} color={colors.accentOnFill} />
+        </MotionView>
+      </Box>
+      <Initials text={initials(person.name)} size={28} />
+      <Box flex={1} style={{ minWidth: 0 }}>
+        <Text numberOfLines={1} style={{ fontSize: 13, fontWeight: '600', color: colors.textPrimary }}>{person.name}</Text>
+        {person.meta ? <Text numberOfLines={1} style={{ fontSize: 12, color: colors.textSecondary }}>{person.meta}</Text> : null}
+      </Box>
+    </RNPressable>
+  );
+}
+
+/** Combobox, guarded: a wrong-kind config is refused by name and a render error is caught, never thrown to the page (`shared/guard`). */
+export const Combobox = guarded(ComboboxView, COMBO_PRESETS, 'Combobox');

package/src/components/onboarding/combobox/contract.ts

@@ -0,0 +1,74 @@
+import type { OnboardingIssue, PresetsFile } from '../shared/contract';
+import type { Person } from '../data-view/contract';
+import presetsJson from './presets.json';
+
+/**
+ * **C14 · Combobox — the server-side, multi-select people picker (block #51).**
+ *
+ * Source: `design_handoff_data_components_batch4` README "C14 · Combobox" (the Block PRD, 2026-09-25).
+ * Table and Grid's bulk Assign uses it in `bare` mode; its own three case studies show it as a field.
+ * Search is the host's (`search`, `suggest`); the component owns the debounce, the draft selection,
+ * the keyboard and the apply lifecycle.
+ *
+ * **`meta` is a role, not an email** — decided 2026-09-25, closing the handoff's only open question: an
+ * email is personal data inside a shared view, and the prototypes show a role.
+ */
+
+export type { Person };
+
+export type ComboboxSettings = {
+  /** The demo directory — what the demo `search` searches. A host passes its own `search`. */
+  people: Person[];
+  /** Initial value, by person id. */
+  value: string[];
+  /** Suggested people before the user types, by id. */
+  suggestions: string[];
+  fieldLabel: string;
+  dialogLabel: string;
+  sheetTitle: string;
+  placeholder: string;
+  /** `{n}` → the draft count. Default "Assign ({n})". */
+  applyLabel: string;
+  /** 0: no limit. */
+  max: number;
+  /** Demo only: the query the search scenes show. */
+  demoQuery: string;
+  /** Demo only: the query that matches no one. */
+  noMatchQuery: string;
+  viewport: 'web' | 'mobile';
+  /** Demo only: the draft the open scenes start with. */
+  openDraft: string[] | null;
+  /** The trigger's text when nothing is chosen. Default "Assign to…". */
+  emptyLabel?: string;
+  /** A muted line under the field — "3 of the 5 rows already have assignees." */
+  selNote?: string;
+  ship?: string;
+  loadErrorTitle: string;
+  loadErrorBody: string;
+  retryLabel: string;
+  emptyCta: string;
+};
+
+export const COMBO_SCENES = [
+  'default', 'hasSelection', 'disabled', 'open', 'suggLoading', 'noSugg', 'debounce', 'searching', 'results',
+  'loadingMore', 'noResults', 'noResultsMax', 'searchError', 'atMax', 'applying', 'applied', 'applyFailed',
+] as const;
+export type ComboScene = (typeof COMBO_SCENES)[number];
+/** Scenes that are an operation (or the debounce) in flight. */
+export const COMBO_IN_FLIGHT: readonly string[] = ['suggLoading', 'debounce', 'searching', 'loadingMore', 'applying'];
+
+export const COMBO_PRESETS = presetsJson as unknown as PresetsFile<ComboboxSettings>;
+
+export function validateCombobox(c: ComboboxSettings): OnboardingIssue[] {
+  if (!Array.isArray(c.people)) return [{ path: 'people', message: 'people must be a list.' }];
+  const issues: OnboardingIssue[] = [];
+  const ids = new Set<string>();
+  c.people.forEach((p, i) => {
+    if (!p.id || !p.name) issues.push({ path: `people[${i}]`, message: 'Every person needs an id and a name.' });
+    if (ids.has(p.id)) issues.push({ path: `people[${i}].id`, message: `The id “${p.id}” is used twice.` });
+    ids.add(p.id);
+  });
+  (c.suggestions ?? []).forEach((id, i) => { if (!ids.has(id)) issues.push({ path: `suggestions[${i}]`, message: `“${id}” is not one of the people.` }); });
+  if (typeof c.max !== 'number' || c.max < 0) issues.push({ path: 'max', message: 'max must be 0 (no limit) or more.' });
+  return issues;
+}