@atlashub/smartstack-cli 4.81.0 → 5.0.0

package/templates/skills/development/frontend/ui-primitives/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: scaffold-ui-primitives
+description: Scaffold theme-compliant UI primitives into the client project (EntityLookup combobox first; EnumSelect, DateInput planned). Idempotent, honors @customised marker.
+group: D
+phase: devFrontend
+kind: main
+section_label: 'SCAFFOLD-UI-PRIMITIVES (EntityLookup + future EnumSelect / DateInput in src/components/ui/)'
+allowed-tools: [Read, Write, Edit, Glob, Grep]
+---
+
+# scaffold-ui-primitives — Theme-compliant primitives scaffolder
+
+## Context
+
+You are scaffolding **shared UI primitives** into a SmartStack-generated client
+app. Today the only primitive is `EntityLookup` — the combobox `scaffold-component`
+imports for every FK Guid field of a Form/Detail page. Tomorrow this same skill
+will host `EnumSelect`, `DateInput`, etc.
+
+These primitives live **locally** in `src/components/ui/` (not in
+`@atlashub/smartstack`) for three reasons:
+
+1. **Theme compliance** — they must use SmartStack tokens (`var(--bg-card)`,
+   `var(--color-accent-*)`, …) so a theme swap from the admin re-paints them
+   instantly. Hardcoded Tailwind colors (`bg-blue-500`, `dark:bg-gray-700`)
+   are **forbidden** and the test snapshot enforces it.
+2. **No upstream churn** — the `EntityLookup` paradox (component documented
+   in CLI but absent from `@atlashub/smartstack`) was the trigger for this
+   skill. Scaffold-component now imports `@/components/ui/EntityLookup` and
+   this skill is what makes that import resolve.
+3. **Local override surface** — clients can replace the file (or mark it
+   `// @customised`) without forking the SDK.
+
+Without this skill, `scaffold-component` emits `<EntityLookup>` JSX → TypeScript
+fails to resolve the import → audit `DEV-UI-022` fires BLOCKING. So the
+orchestrator (`/ba-develop` Phase 3.0) MUST invoke `scaffold-ui-primitives`
+before any feature page is scaffolded.
+
+## Invocation
+
+```
+npx tsx skills/development/frontend/ui-primitives/cli/scaffold-ui-primitives/index.ts \
+  --spec '{"projectPath":"<abs>","appCode":"<app>"}'
+```
+
+`--spec` JSON:
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `projectPath` | string | yes | Absolute path to the web root (holds `src/`). |
+| `appCode` | string | yes | Reserved for future per-app branding hooks. |
+| `force` | boolean | no | Overwrite even when content matches. Default false. |
+
+## What it produces
+
+- `src/components/ui/EntityLookup.tsx` — debounced + paginated combobox with
+  keyboard nav, clear button, loading/empty/error states. All styling via
+  SmartStack tokens; zero Tailwind color classes; zero `dark:` prefix (theme
+  swap handles dark mode at the token layer).
+- `src/i18n/locales/{fr,en,it,de}/common.json` — deep-merged with the
+  `entityLookup.*` namespace (`loading`, `empty`, `error`, `search`, `clear`,
+  `placeholder`). Existing keys are preserved.
+
+## Idempotency contract
+
+`/* @customised */` (or `// @customised`) marker at the top of any file =
+preserve. Otherwise overwrite when content drifts. AUTO-GENERATED header
+included so a re-run doesn't surprise the dev.
+
+Locale files use **deep merge**: existing keys are preserved verbatim; only
+the `entityLookup.*` subtree is reset to the canonical scaffold. Other
+namespaces (`auth.*`, `nav.*`, …) untouched.
+
+## When NOT to use
+
+- Adding a custom field-level component (e.g. `RichTextEditor`) → those are
+  feature-scoped, scaffold them in `src/features/<module>/<entity>/components/`
+  via the regular `scaffold-component` flow.
+- Changing the styling of an existing primitive → either mark the file
+  `// @customised` (one-off override) or change the tokens in `index.css` via
+  `scaffold-theme` (global). Don't patch the primitive.
+
+## Linked checks
+
+- `DEV-UI-022` (audit-dev-frontend, BLOCKING) — fires when a Form page renders
+  a FK field as `<input>`/`<select>` instead of `<EntityLookup>`.
+- `smoke-generation --quick` — used to flag `[BROKEN] @/components/ui/EntityLookup`;
+  once this skill runs at Phase 3.0, the import resolves and the flag clears.

package/templates/skills/development/frontend/ui-primitives/cli/scaffold-ui-primitives/__tests__/generate.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect } from 'vitest';
+import { generate } from '../generate.js';
+import type { ScaffoldUiPrimitivesInput } from '../types.js';
+
+function fixture(overrides: Partial<ScaffoldUiPrimitivesInput> = {}): ScaffoldUiPrimitivesInput {
+  return {
+    projectPath: '/tmp/web',
+    appCode: 'crm',
+    force: false,
+    ...overrides,
+  };
+}
+
+describe('scaffold-ui-primitives / generate — file shape', () => {
+  it('emits EntityLookup.tsx with overwrite strategy', () => {
+    const files = generate(fixture());
+    const lookup = files.find((f) => f.path === 'src/components/ui/EntityLookup.tsx');
+    expect(lookup).toBeDefined();
+    expect(lookup!.strategy).toBe('overwrite');
+  });
+
+  it('emits one locale file per supported language with deep-merge-json strategy', () => {
+    const files = generate(fixture());
+    for (const locale of ['fr', 'en', 'it', 'de']) {
+      const f = files.find((x) => x.path === `src/i18n/locales/${locale}/common.json`);
+      expect(f, `missing locale ${locale}`).toBeDefined();
+      expect(f!.strategy).toBe('deep-merge-json');
+      const parsed = JSON.parse(f!.content);
+      expect(parsed.entityLookup).toBeDefined();
+      expect(parsed.entityLookup.placeholder).toBeTruthy();
+      expect(parsed.entityLookup.empty).toBeTruthy();
+      expect(parsed.entityLookup.error).toBeTruthy();
+    }
+  });
+
+  it('includes the AUTO-GENERATED header so re-runs do not surprise the dev', () => {
+    const files = generate(fixture());
+    const lookup = files.find((f) => f.path === 'src/components/ui/EntityLookup.tsx')!;
+    expect(lookup.content).toMatch(/AUTO-GENERATED/);
+    expect(lookup.content).toMatch(/scaffold-ui-primitives/);
+  });
+});
+
+describe('scaffold-ui-primitives / generate — theme compliance (non-negotiable)', () => {
+  // Catalog of Tailwind palette tokens. Any of these in the EntityLookup
+  // would break the theme swap contract — the audit lives here so a future
+  // hand-edit can't silently regress.
+  const FORBIDDEN_PALETTES = [
+    'slate', 'gray', 'zinc', 'neutral', 'stone',
+    'red', 'orange', 'amber', 'yellow', 'lime', 'green', 'emerald', 'teal',
+    'cyan', 'sky', 'blue', 'indigo', 'violet', 'purple', 'fuchsia', 'pink', 'rose',
+  ];
+
+  it('uses zero hardcoded Tailwind color classes (bg-*-XXX / text-*-XXX / border-*-XXX)', () => {
+    const files = generate(fixture());
+    const lookup = files.find((f) => f.path === 'src/components/ui/EntityLookup.tsx')!;
+    for (const palette of FORBIDDEN_PALETTES) {
+      const re = new RegExp(`\\b(?:bg|text|border|ring|placeholder|from|to|via|divide|outline)-${palette}-\\d{2,3}\\b`);
+      const matches = lookup.content.match(re);
+      expect(matches, `Hardcoded Tailwind color found (${palette}): ${matches?.join(', ')}`).toBeNull();
+    }
+  });
+
+  it('uses zero dark: prefix (theme swap handles dark mode at the token layer)', () => {
+    const files = generate(fixture());
+    const lookup = files.find((f) => f.path === 'src/components/ui/EntityLookup.tsx')!;
+    expect(lookup.content).not.toMatch(/\bdark:/);
+  });
+
+  it('uses zero hex literals in className (only via tokens)', () => {
+    const files = generate(fixture());
+    const lookup = files.find((f) => f.path === 'src/components/ui/EntityLookup.tsx')!;
+    // Spot any `className="…#abc123…"` style hex literals — there must be none.
+    const classNameBlocks = lookup.content.match(/className=[`"']([^`"']*)[`"']/g) ?? [];
+    for (const block of classNameBlocks) {
+      expect(block, `Hex literal in className: ${block}`).not.toMatch(/#[0-9a-fA-F]{3,8}/);
+    }
+  });
+
+  it('references the SmartStack tokens it depends on (bg-card, border-color, accent-500, text-primary, text-muted, bg-hover)', () => {
+    const files = generate(fixture());
+    const lookup = files.find((f) => f.path === 'src/components/ui/EntityLookup.tsx')!;
+    expect(lookup.content).toMatch(/var\(--bg-card\)/);
+    expect(lookup.content).toMatch(/var\(--border-color\)/);
+    expect(lookup.content).toMatch(/var\(--color-accent-500\)/);
+    expect(lookup.content).toMatch(/var\(--text-primary\)/);
+    expect(lookup.content).toMatch(/var\(--text-muted\)/);
+    expect(lookup.content).toMatch(/var\(--bg-hover\)/);
+  });
+});
+
+describe('scaffold-ui-primitives / generate — EntityLookup contract', () => {
+  it('exports an EntityLookup component with the documented props shape', () => {
+    const files = generate(fixture());
+    const lookup = files.find((f) => f.path === 'src/components/ui/EntityLookup.tsx')!;
+    expect(lookup.content).toMatch(/export function EntityLookup<TItem extends RefItem = RefItem>/);
+    // Required props per the spec
+    expect(lookup.content).toMatch(/apiEndpoint: string/);
+    expect(lookup.content).toMatch(/value: string \| null/);
+    expect(lookup.content).toMatch(/onChange: \(id: string \| null, item\?: TItem\) => void/);
+    expect(lookup.content).toMatch(/label: string/);
+    // Optional props that must be present in the interface
+    expect(lookup.content).toMatch(/mapOption\?:/);
+    expect(lookup.content).toMatch(/required\?: boolean/);
+    expect(lookup.content).toMatch(/disabled\?: boolean/);
+    expect(lookup.content).toMatch(/error\?: string/);
+    expect(lookup.content).toMatch(/multi\?: boolean/);
+  });
+
+  it('fetches lookup results from apiEndpoint using api.get with debouncedSearch', () => {
+    const files = generate(fixture());
+    const lookup = files.find((f) => f.path === 'src/components/ui/EntityLookup.tsx')!;
+    expect(lookup.content).toMatch(/api\.get<PaginatedResult<TItem>>\(apiEndpoint/);
+    expect(lookup.content).toMatch(/search: debouncedSearch/);
+  });
+
+  it('emits 300ms debounce constant', () => {
+    const files = generate(fixture());
+    const lookup = files.find((f) => f.path === 'src/components/ui/EntityLookup.tsx')!;
+    expect(lookup.content).toMatch(/DEBOUNCE_MS = 300/);
+  });
+
+  it('renders an ARIA combobox with role=combobox + role=listbox + role=option', () => {
+    const files = generate(fixture());
+    const lookup = files.find((f) => f.path === 'src/components/ui/EntityLookup.tsx')!;
+    expect(lookup.content).toMatch(/role="combobox"/);
+    expect(lookup.content).toMatch(/role="listbox"/);
+    expect(lookup.content).toMatch(/role="option"/);
+    expect(lookup.content).toMatch(/aria-expanded=\{open\}/);
+    expect(lookup.content).toMatch(/aria-autocomplete="list"/);
+  });
+
+  it('handles keyboard navigation (ArrowDown/Up/Enter/Escape)', () => {
+    const files = generate(fixture());
+    const lookup = files.find((f) => f.path === 'src/components/ui/EntityLookup.tsx')!;
+    expect(lookup.content).toMatch(/e\.key === 'ArrowDown'/);
+    expect(lookup.content).toMatch(/e\.key === 'ArrowUp'/);
+    expect(lookup.content).toMatch(/e\.key === 'Enter'/);
+    expect(lookup.content).toMatch(/e\.key === 'Escape'/);
+  });
+
+  it('throws not-implemented when multi=true (reserved API)', () => {
+    const files = generate(fixture());
+    const lookup = files.find((f) => f.path === 'src/components/ui/EntityLookup.tsx')!;
+    expect(lookup.content).toMatch(/multi-select is not implemented yet/);
+  });
+
+  it('uses i18n via useTranslation("common") with entityLookup.* namespace', () => {
+    const files = generate(fixture());
+    const lookup = files.find((f) => f.path === 'src/components/ui/EntityLookup.tsx')!;
+    expect(lookup.content).toMatch(/useTranslation\('common'\)/);
+    expect(lookup.content).toMatch(/entityLookup\.placeholder/);
+    expect(lookup.content).toMatch(/entityLookup\.empty/);
+    expect(lookup.content).toMatch(/entityLookup\.error/);
+    expect(lookup.content).toMatch(/entityLookup\.loading/);
+    expect(lookup.content).toMatch(/entityLookup\.clear/);
+  });
+});

package/templates/skills/development/frontend/ui-primitives/cli/scaffold-ui-primitives/generate.ts

@@ -0,0 +1,345 @@
+/**
+ * scaffold-ui-primitives/generate.ts — Build EntityLookup.tsx + i18n locale stubs.
+ *
+ * Pure function — no I/O. Caller in index.ts writes the returned files honoring
+ * each file's `strategy` (overwrite vs deep-merge-json for locales).
+ *
+ * Theme-compliance contract: EntityLookup.tsx MUST use only SmartStack tokens
+ * (var(--bg-card), var(--color-accent-*), …) — zero hardcoded Tailwind colors
+ * (bg-blue-500, text-gray-700, dark:bg-…). The companion test asserts this
+ * with a regex sweep so a future hand-edit can't silently regress it.
+ */
+import type { GeneratedFile, ScaffoldUiPrimitivesInput } from './types.js';
+
+const HEADER = `/* AUTO-GENERATED — re-run scaffold-ui-primitives to refresh. Add @customised at the top to opt out. */`;
+
+const LOCALES = ['fr', 'en', 'it', 'de'] as const;
+
+const I18N_STRINGS: Record<typeof LOCALES[number], Record<string, string>> = {
+  fr: {
+    placeholder: 'Rechercher…',
+    loading: 'Chargement…',
+    empty: 'Aucun résultat',
+    error: 'Erreur de chargement',
+    clear: 'Effacer la sélection',
+    search: 'Rechercher',
+  },
+  en: {
+    placeholder: 'Search…',
+    loading: 'Loading…',
+    empty: 'No results',
+    error: 'Failed to load',
+    clear: 'Clear selection',
+    search: 'Search',
+  },
+  it: {
+    placeholder: 'Cerca…',
+    loading: 'Caricamento…',
+    empty: 'Nessun risultato',
+    error: 'Errore di caricamento',
+    clear: 'Cancella selezione',
+    search: 'Cerca',
+  },
+  de: {
+    placeholder: 'Suchen…',
+    loading: 'Wird geladen…',
+    empty: 'Keine Ergebnisse',
+    error: 'Ladefehler',
+    clear: 'Auswahl löschen',
+    search: 'Suchen',
+  },
+};
+
+function entityLookupComponent(): string {
+  return `${HEADER}
+import { useCallback, useEffect, useMemo, useRef, useState, type KeyboardEvent } from 'react';
+import { useTranslation } from 'react-i18next';
+import { api } from '@atlashub/smartstack';
+import { Search, ChevronDown, X, Loader2 } from 'lucide-react';
+
+/**
+ * Paginated reference shape returned by GET /api/{module}/{plural}/lookup.
+ * Matches \`{Entity}RefDto\` emitted by scaffold-business.
+ */
+interface RefItem {
+  id: string;
+  displayName: string;
+  [k: string]: unknown;
+}
+
+interface PaginatedResult<T> {
+  items: T[];
+  // Matches SmartStack.app PaginatedResult<T>.TotalCount on the wire (JSON: "totalCount").
+  totalCount: number;
+  page: number;
+  pageSize: number;
+}
+
+export interface EntityLookupProps<TItem extends RefItem = RefItem> {
+  /** Endpoint hitting the lookup contract, e.g. \`/api/hr/departments/lookup\`. */
+  apiEndpoint: string;
+  /** Currently selected entity id (the FK Guid to persist). \`null\` = empty. */
+  value: string | null;
+  /** Receives the selected id (or null on clear) and, when available, the
+   *  full item so the caller can store a denormalised label without a refetch. */
+  onChange: (id: string | null, item?: TItem) => void;
+  /** Visible field label rendered above the input. */
+  label: string;
+  /** Override for the search input placeholder. Defaults to
+   *  \`t('entityLookup.placeholder')\`. */
+  placeholder?: string;
+  /** Optional remap when the backend returns more than \`{ id, displayName }\`.
+   *  Defaults to \`(it) => ({ id: it.id, label: it.displayName })\`. */
+  mapOption?: (item: TItem) => { id: string; label: string; sublabel?: string };
+  required?: boolean;
+  disabled?: boolean;
+  /** Error string rendered under the input — typically a form validation
+   *  message from react-hook-form / zod. */
+  error?: string;
+  /** Multi-select — not implemented yet; reserved so the API doesn't break
+   *  callers when the feature lands. Throws at runtime if set to true. */
+  multi?: boolean;
+}
+
+const PAGE_SIZE = 20;
+const DEBOUNCE_MS = 300;
+
+export function EntityLookup<TItem extends RefItem = RefItem>({
+  apiEndpoint,
+  value,
+  onChange,
+  label,
+  placeholder,
+  mapOption,
+  required = false,
+  disabled = false,
+  error,
+  multi = false,
+}: EntityLookupProps<TItem>) {
+  if (multi) {
+    throw new Error('EntityLookup: multi-select is not implemented yet (PR3 scope).');
+  }
+  const { t } = useTranslation('common');
+  const [search, setSearch] = useState('');
+  const [debouncedSearch, setDebouncedSearch] = useState('');
+  const [open, setOpen] = useState(false);
+  const [focusedIdx, setFocusedIdx] = useState(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listRef = useRef<HTMLUListElement>(null);
+
+  const [data, setData] = useState<PaginatedResult<TItem> | undefined>();
+  const [isLoading, setIsLoading] = useState(false);
+  const [isError, setIsError] = useState(false);
+  const [selectedItem, setSelectedItem] = useState<TItem | null>(null);
+
+  // Debounce the search input so we don't fire a request per keystroke.
+  useEffect(() => {
+    const t = setTimeout(() => setDebouncedSearch(search), DEBOUNCE_MS);
+    return () => clearTimeout(t);
+  }, [search]);
+
+  // Fetch lookup results when dropdown is open.
+  const fetchResults = useCallback(async (signal: AbortSignal) => {
+    setIsLoading(true);
+    setIsError(false);
+    try {
+      const result = await api.get<PaginatedResult<TItem>>(apiEndpoint, {
+        params: { search: debouncedSearch || undefined, page: 1, pageSize: PAGE_SIZE },
+        signal,
+      });
+      setData(result);
+    } catch (err) {
+      if (!(err instanceof DOMException && err.name === 'AbortError')) setIsError(true);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [apiEndpoint, debouncedSearch]);
+
+  useEffect(() => {
+    if (!open) return;
+    const ac = new AbortController();
+    void fetchResults(ac.signal);
+    return () => ac.abort();
+  }, [open, fetchResults]);
+
+  // Resolve the currently selected item label so the input shows a human
+  // name instead of the raw Guid.
+  useEffect(() => {
+    if (!value) { setSelectedItem(null); return; }
+    let cancelled = false;
+    api.get<PaginatedResult<TItem>>(apiEndpoint, { params: { search: value, pageSize: 1 } })
+      .then((result) => { if (!cancelled) setSelectedItem(result.items.find((it) => it.id === value) ?? null); })
+      .catch(() => { if (!cancelled) setSelectedItem(null); });
+    return () => { cancelled = true; };
+  }, [apiEndpoint, value]);
+
+  const options = useMemo(() => {
+    const items = data?.items ?? [];
+    return items.map((it) => {
+      const mapped = mapOption ? mapOption(it) : { id: it.id, label: it.displayName };
+      return { ...mapped, raw: it };
+    });
+  }, [data, mapOption]);
+
+  const selectedLabel = useMemo(() => {
+    if (!value) return '';
+    if (!selectedItem) return value;
+    return mapOption ? mapOption(selectedItem).label : selectedItem.displayName;
+  }, [value, selectedItem, mapOption]);
+
+  function pick(idx: number): void {
+    const opt = options[idx];
+    if (!opt) return;
+    onChange(opt.id, opt.raw);
+    setOpen(false);
+    setSearch('');
+    inputRef.current?.blur();
+  }
+
+  function onKeyDown(e: KeyboardEvent<HTMLInputElement>): void {
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      if (!open) setOpen(true);
+      setFocusedIdx((i) => Math.min(i + 1, options.length - 1));
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setFocusedIdx((i) => Math.max(i - 1, 0));
+    } else if (e.key === 'Enter') {
+      e.preventDefault();
+      pick(focusedIdx);
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      setOpen(false);
+      inputRef.current?.blur();
+    }
+  }
+
+  const inputId = useMemo(() => \`entity-lookup-\${Math.random().toString(36).slice(2, 9)}\`, []);
+  const listId = \`\${inputId}-list\`;
+
+  return (
+    <div className="flex flex-col gap-1">
+      <label htmlFor={inputId} className="text-sm font-medium text-[var(--text-primary)]">
+        {label}
+        {required && <span className="ml-0.5 text-[var(--color-danger-500)]" aria-label="required">*</span>}
+      </label>
+      <div className="relative">
+        <div className="absolute inset-y-0 left-2.5 flex items-center pointer-events-none">
+          {isLoading && open ? (
+            <Loader2 className="w-4 h-4 animate-spin text-[var(--text-muted)]" />
+          ) : (
+            <Search className="w-4 h-4 text-[var(--text-muted)]" />
+          )}
+        </div>
+        <input
+          id={inputId}
+          ref={inputRef}
+          type="text"
+          role="combobox"
+          aria-expanded={open}
+          aria-controls={listId}
+          aria-autocomplete="list"
+          aria-required={required}
+          aria-invalid={Boolean(error)}
+          value={open ? search : selectedLabel}
+          onChange={(e) => {
+            setSearch(e.target.value);
+            setFocusedIdx(0);
+            if (!open) setOpen(true);
+          }}
+          onFocus={() => setOpen(true)}
+          onBlur={() => setTimeout(() => setOpen(false), 150)}
+          onKeyDown={onKeyDown}
+          placeholder={placeholder ?? t('entityLookup.placeholder', { defaultValue: 'Search…' })}
+          disabled={disabled}
+          className="w-full pl-9 pr-16 py-2 rounded-[var(--radius-input,0.375rem)] border border-[var(--border-color)] bg-[var(--bg-card)] text-[var(--text-primary)] placeholder-[var(--text-muted)] focus:outline-none focus:ring-2 focus:ring-[var(--color-accent-500)] focus:border-transparent disabled:opacity-60 disabled:cursor-not-allowed"
+        />
+        <div className="absolute inset-y-0 right-2 flex items-center gap-1">
+          {value && !disabled && (
+            <button
+              type="button"
+              onMouseDown={(e) => {
+                e.preventDefault();
+                onChange(null);
+                setSearch('');
+              }}
+              aria-label={t('entityLookup.clear', { defaultValue: 'Clear selection' })}
+              className="p-1 rounded hover:bg-[var(--bg-hover)] text-[var(--text-muted)]"
+            >
+              <X className="w-3.5 h-3.5" />
+            </button>
+          )}
+          <ChevronDown className="w-4 h-4 text-[var(--text-muted)]" />
+        </div>
+        {open && (
+          <ul
+            id={listId}
+            ref={listRef}
+            role="listbox"
+            className="absolute z-10 mt-1 w-full max-h-64 overflow-y-auto rounded-[var(--radius-input,0.375rem)] border border-[var(--border-color)] bg-[var(--bg-card)] shadow-lg"
+          >
+            {isError && (
+              <li className="px-3 py-2 text-sm text-[var(--text-muted)]">
+                {t('entityLookup.error', { defaultValue: 'Failed to load' })}
+              </li>
+            )}
+            {!isError && isLoading && options.length === 0 && (
+              <li className="px-3 py-2 text-sm text-[var(--text-muted)] flex items-center gap-2">
+                <Loader2 className="w-3.5 h-3.5 animate-spin" />
+                {t('entityLookup.loading', { defaultValue: 'Loading…' })}
+              </li>
+            )}
+            {!isError && !isLoading && options.length === 0 && (
+              <li className="px-3 py-2 text-sm text-[var(--text-muted)]">
+                {t('entityLookup.empty', { defaultValue: 'No results' })}
+              </li>
+            )}
+            {options.map((opt, idx) => (
+              <li
+                key={opt.id}
+                role="option"
+                aria-selected={value === opt.id}
+                onMouseEnter={() => setFocusedIdx(idx)}
+                onMouseDown={(e) => {
+                  e.preventDefault();
+                  pick(idx);
+                }}
+                className={\`px-3 py-2 text-sm cursor-pointer flex flex-col text-[var(--text-primary)] \${
+                  idx === focusedIdx ? 'bg-[var(--bg-hover)]' : ''
+                } \${value === opt.id ? 'font-medium' : ''}\`}
+              >
+                <span>{opt.label}</span>
+                {opt.sublabel && (
+                  <span className="text-xs text-[var(--text-muted)]">{opt.sublabel}</span>
+                )}
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+      {error && (
+        <p role="alert" className="text-xs text-[var(--color-danger-500)]">
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}
+`;
+}
+
+function localeFile(locale: typeof LOCALES[number]): GeneratedFile {
+  const payload = { entityLookup: I18N_STRINGS[locale] };
+  return {
+    path: `src/i18n/locales/${locale}/common.json`,
+    content: JSON.stringify(payload, null, 2) + '\n',
+    strategy: 'deep-merge-json',
+  };
+}
+
+export function generate(_spec: ScaffoldUiPrimitivesInput): GeneratedFile[] {
+  return [
+    { path: 'src/components/ui/EntityLookup.tsx', content: entityLookupComponent(), strategy: 'overwrite' },
+    ...LOCALES.map(localeFile),
+  ];
+}