@appinternalleads/ui 0.2.0

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

@@ -0,0 +1,178 @@
+import { matchPeople } from '../data-view/demoSource';
+import type { ComboboxSettings, ComboScene, Person } from './contract';
+
+/**
+ * **The C14 engine** — pure. `value` is what was applied; `draft` is the working selection while the
+ * panel is open. Search results replace each other (never merge); while the debounce or a request
+ * is pending the previous results stay, dimmed.
+ */
+
+export type SearchPhase = 'idle' | 'debounce' | 'searching' | 'results' | 'more' | 'error';
+export type ComboToast = { id: number; tone: 'mint' | 'apricot'; text: string; retry: boolean };
+
+export type ComboState = {
+  value: Person[];
+  open: boolean;
+  draft: Person[];
+  q: string;
+  results: Person[];
+  total: number;
+  cursor: string | null;
+  phase: SearchPhase;
+  sugg: 'loading' | 'ready' | 'none';
+  suggestions: Person[];
+  apply: 'idle' | 'working' | 'failed';
+  /** The keyboard-active row in the ordered list (Selected, then Suggested/Results). −1: none. */
+  active: number;
+  toast: ComboToast | null;
+  /** The `disabled` scene — a host's `disabled` prop does the same. */
+  disabled: boolean;
+};
+
+export type ComboSeed = Partial<ComboState>;
+
+export type ComboAction =
+  | { type: 'open'; suggestions: Person[] | null }
+  | { type: 'close' }
+  | { type: 'suggested'; items: Person[] }
+  | { type: 'query'; q: string }
+  | { type: 'searching' }
+  | { type: 'results'; q: string; items: Person[]; total: number; cursor: string | null }
+  | { type: 'searchFailed' }
+  | { type: 'moreStart' }
+  | { type: 'moreDone'; items: Person[]; cursor: string | null }
+  | { type: 'toggle'; person: Person; max: number }
+  | { type: 'active'; index: number }
+  | { type: 'applyStart' }
+  | { type: 'applied'; value: Person[]; toast: ComboToast | null }
+  | { type: 'applyFailed'; embedded: boolean; toast: ComboToast | null }
+  | { type: 'toast'; toast: ComboToast | null }
+  | { type: 'reset'; state: ComboState };
+
+const byIds = (people: Person[], ids: string[]) => ids.map(id => people.find(p => p.id === id)).filter((p): p is Person => Boolean(p));
+
+export function suggestionsOf(c: ComboboxSettings): Person[] {
+  return byIds(c.people, c.suggestions ?? []);
+}
+
+export function initialCombo(c: ComboboxSettings, seed: ComboSeed = {}, value?: Person[]): ComboState {
+  return {
+    value: value ?? byIds(c.people, c.value ?? []), open: false, draft: [], q: '', results: [], total: 0, cursor: null, phase: 'idle',
+    sugg: 'ready', suggestions: suggestionsOf(c), apply: 'idle', active: -1, toast: null, disabled: false,
+    ...seed,
+  };
+}
+
+/** "2 people", "1 person". */
+export const peopleCount = (n: number) => `${n} ${n === 1 ? 'person' : 'people'}`;
+
+/**
+ * **A demo-board scene as a seed** — the prototype's `sceneState`, on the config's directory.
+ * `loading` / `empty` / `error` are the picker's own states here (suggestions loading, none, a
+ * search error), because the picker has no card of its own to put a load state in.
+ */
+export function comboSeed(c: ComboboxSettings, scene: ComboScene | 'loading' | 'empty' | 'error', opts: { toasts?: boolean } = {}): ComboSeed {
+  const first = (k: number) => c.people.slice(0, k);
+  const openWith = (ids: string[] | null): ComboSeed => ({ open: true, draft: ids ? byIds(c.people, ids) : [] });
+  const search = (q: string, pages = 1): ComboSeed => {
+    const m = matchPeople(c.people, q);
+    const results = m.slice(0, 20 * pages);
+    return { q, total: m.length, results, cursor: results.length < m.length ? String(results.length) : null, phase: 'results' };
+  };
+  const partial = c.demoQuery.slice(0, -1);
+  switch (scene) {
+    case 'hasSelection': return { value: first(3) };
+    case 'disabled': return { disabled: true };
+    case 'open': return openWith(c.openDraft);
+    case 'suggLoading': case 'loading': return { ...openWith(null), sugg: 'loading' };
+    case 'noSugg': case 'empty': return { ...openWith(null), sugg: 'none' };
+    case 'debounce': return { ...openWith(null), ...search(partial), q: c.demoQuery, phase: 'debounce' };
+    case 'searching': return { ...openWith(null), ...search(partial), q: c.demoQuery, phase: 'searching' };
+    case 'results': return { ...openWith(c.openDraft), ...search(c.demoQuery) };
+    case 'loadingMore': return { ...openWith(c.openDraft), ...search(c.demoQuery), phase: 'more' };
+    case 'noResults': return { ...openWith(null), q: c.noMatchQuery, phase: 'results', results: [], total: 0 };
+    case 'noResultsMax': return { open: true, draft: first(c.max || 3), q: c.noMatchQuery, phase: 'results', results: [], total: 0 };
+    case 'searchError': case 'error': return { ...openWith(null), q: c.demoQuery, phase: 'error' };
+    case 'atMax': return { open: true, draft: first(c.max || 3) };
+    case 'applying': return { open: true, draft: c.openDraft ? byIds(c.people, c.openDraft) : first(2), apply: 'working' };
+    case 'applied': return { value: first(2), toast: { id: 1, tone: 'mint', text: `Assigned ${peopleCount(2)}`, retry: false } };
+    case 'applyFailed': {
+      const draft = first(2);
+      const toast: ComboToast = { id: 1, tone: 'apricot', text: `Couldn’t assign ${peopleCount(2)}`, retry: true };
+      return opts.toasts === false ? { open: true, draft, apply: 'failed' } : { draft, toast };
+    }
+    default: return {};
+  }
+}
+
+export function reduceCombo(s: ComboState, a: ComboAction): ComboState {
+  switch (a.type) {
+    case 'open':
+      return {
+        ...s, open: true, draft: s.value.slice(), q: '', phase: 'idle', results: [], total: 0, cursor: null, active: -1, apply: 'idle',
+        sugg: a.suggestions ? (a.suggestions.length ? 'ready' : 'none') : 'loading', suggestions: a.suggestions ?? s.suggestions,
+      };
+    case 'close': return { ...s, open: false, q: '', phase: 'idle', active: -1 };
+    case 'suggested': return s.sugg === 'loading' ? { ...s, sugg: a.items.length ? 'ready' : 'none', suggestions: a.items } : s;
+    /* An empty query returns to Suggested at once; anything else waits out the debounce. */
+    case 'query': return a.q.trim()
+      ? { ...s, q: a.q, phase: 'debounce', active: -1 }
+      : { ...s, q: a.q, phase: 'idle', results: [], total: 0, cursor: null, active: -1 };
+    case 'searching': return { ...s, phase: 'searching' };
+    case 'results': return s.q !== a.q ? s : { ...s, phase: 'results', results: a.items, total: a.total, cursor: a.cursor };
+    case 'searchFailed': return { ...s, phase: 'error' };
+    case 'moreStart': return s.phase === 'results' && s.cursor ? { ...s, phase: 'more' } : s;
+    case 'moreDone': return { ...s, phase: 'results', results: s.results.concat(a.items.filter(p => !s.results.some(r => r.id === p.id))), cursor: a.cursor };
+    case 'toggle': {
+      const on = s.draft.some(p => p.id === a.person.id);
+      if (!on && a.max && s.draft.length >= a.max) return s;
+      const draft = on ? s.draft.filter(p => p.id !== a.person.id) : s.draft.concat(a.person);
+      return { ...s, draft, apply: s.apply === 'failed' ? 'idle' : s.apply };
+    }
+    case 'active': return { ...s, active: a.index };
+    case 'applyStart': return s.apply === 'working' ? s : { ...s, apply: 'working', toast: null };
+    case 'applied': return { ...s, apply: 'idle', value: a.value, open: false, q: '', phase: 'idle', toast: a.toast };
+    case 'applyFailed': return { ...s, apply: a.embedded ? 'failed' : 'idle', open: a.embedded, toast: a.toast };
+    case 'toast': return { ...s, toast: a.toast };
+    case 'reset': return a.state;
+  }
+}
+
+/** The ordered list the keyboard walks and the listbox draws: Selected, then Suggested or Results. */
+export function comboModel(c: ComboboxSettings, s: ComboState, max: number) {
+  const inDraft = (p: Person) => s.draft.some(d => d.id === p.id);
+  const hasQ = Boolean(s.q.trim());
+  const showResults = hasQ && s.phase !== 'idle';
+  const others = showResults
+    ? (s.phase === 'error' ? [] : s.results.filter(p => !inDraft(p)))
+    : s.sugg === 'ready' ? s.suggestions.filter(p => !inDraft(p)) : [];
+  const n = s.draft.length;
+  const atMax = Boolean(max) && n >= max;
+  return {
+    hasQ,
+    selected: s.draft,
+    others,
+    ordered: s.draft.concat(others),
+    n,
+    atMax,
+    maxHint: `Up to ${max} people`,
+    selectedHead: `Selected · ${n}`,
+    showSuggHead: !hasQ && s.sugg !== 'none',
+    suggLoading: !hasQ && s.sugg === 'loading',
+    noSugg: !hasQ && s.sugg === 'none' && n === 0,
+    showResultsHead: showResults && s.phase !== 'error' && (others.length > 0 || s.phase === 'debounce' || s.phase === 'searching'),
+    resultsHead: s.total ? `Results · ${s.total}` : 'Results',
+    noResults: showResults && s.phase === 'results' && s.total === 0,
+    noResultsText: `No people match ‘${s.q.trim()}’`,
+    searchError: hasQ && s.phase === 'error',
+    moreLoading: s.phase === 'more',
+    canMore: s.phase === 'results' && Boolean(s.cursor),
+    searching: s.phase === 'searching',
+    dim: s.phase === 'debounce' || s.phase === 'searching',
+    liveText: s.phase === 'results' && hasQ ? (s.total ? `${s.total} ${s.total === 1 ? 'person' : 'people'} found` : 'No people found') : '',
+    applyText: (label: string) => (s.apply === 'working' ? 'Assigning…' : s.apply === 'failed' ? 'Retry' : label.replace('{n}', String(n))),
+    canApply: n > 0 && s.apply !== 'working',
+    triggerLabel: s.value.length ? peopleCount(s.value.length) : (c.emptyLabel || 'Assign to…'),
+    triggerAria: s.value.length ? `${c.fieldLabel}: ${s.value.map(p => p.name).join(', ')}` : (c.emptyLabel || 'Assign to…'),
+  };
+}

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

@@ -0,0 +1,7 @@
+export { COMBO_PRESETS, COMBO_SCENES, COMBO_IN_FLIGHT, validateCombobox, type ComboboxSettings, type ComboScene } from './contract';
+export {
+  comboModel, comboSeed, initialCombo, peopleCount, reduceCombo, suggestionsOf,
+  type ComboAction, type ComboSeed, type ComboState, type ComboToast, type SearchPhase,
+} from './engine';
+export { demoComboOperations, useCombobox, type ComboboxApi, type ComboboxOperations } from './runtime';
+export { Combobox, ComboPanel, ComboSheet, ComboTrigger, type ComboboxProps } from './ComboboxView';