@startsimpli/ui 0.4.40 → 0.4.42

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.40",
+  "version": "0.4.42",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./catalog": "./src/catalog/index.ts",
     "./table": "./src/components/unified-table/index.ts",
     "./gantt": "./src/components/gantt/index.ts",
     "./gantt/styles": "./src/components/gantt/gantt.css",
@@ -34,7 +35,7 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/api": "0.5.39",
+    "@startsimpli/api": "0.5.41",
     "@startsimpli/auth": "0.4.29"
   },
   "peerDependenciesMeta": {

package/src/catalog/__tests__/catalog.test.ts

@@ -0,0 +1,101 @@
+import {
+  UI_CATALOG,
+  getCatalogEntry,
+  catalogByCategory,
+  builtInWidgets,
+  renderCatalogForPrompt,
+  renderDashboardConfig,
+  widgetsNeedingScaffold,
+} from '../index';
+
+describe('UI_CATALOG', () => {
+  it('has unique ids', () => {
+    const ids = UI_CATALOG.map((e) => e.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('gives every entry the fields the AI builder + scaffolder need', () => {
+    for (const e of UI_CATALOG) {
+      expect(e.id).toMatch(/^[a-z][a-z0-9-]*$/);
+      expect(['widget', 'view', 'component']).toContain(e.category);
+      expect(e.title.length).toBeGreaterThan(0);
+      expect(e.description.length).toBeGreaterThan(0);
+      expect(e.dataNeeds.length).toBeGreaterThan(0);
+      expect(e.source.export.length).toBeGreaterThan(0);
+      expect(e.source.from.startsWith('@startsimpli/ui')).toBe(true);
+    }
+  });
+
+  it('exposes the five template built-in widgets as config-only widgets', () => {
+    const builtIns = builtInWidgets().map((e) => e.id).sort();
+    expect(builtIns).toEqual(['metrics', 'pipeline', 'quick-create', 'recent', 'type-grid']);
+    for (const e of builtInWidgets()) expect(e.category).toBe('widget');
+  });
+
+  it('built-in widgets ship an example config whose kind matches their id', () => {
+    for (const e of builtInWidgets()) {
+      expect(e.configExample).toBeDefined();
+      expect(e.configExample!.kind).toBe(e.id);
+    }
+  });
+
+  it('flags heavy blocks so the AI can avoid them by default', () => {
+    // The bundle-costly ones (dnd/xlsx/calendar/gantt) must be marked heavy.
+    for (const id of ['kanban-board', 'data-table', 'calendar', 'gantt']) {
+      expect(getCatalogEntry(id)?.heavy).toBe(true);
+    }
+    // The lightweight defaults must NOT be heavy.
+    for (const id of ['metrics', 'quick-create', 'recent', 'type-grid']) {
+      expect(getCatalogEntry(id)?.heavy).toBeFalsy();
+    }
+  });
+
+  it('renderCatalogForPrompt lists every block with its heavy/built-in flags', () => {
+    const text = renderCatalogForPrompt();
+    for (const e of UI_CATALOG) expect(text).toContain(e.id);
+    expect(text).toContain('⚠ heavy');
+    expect(text).toContain('built-in');
+    expect(text).toContain('scaffolded');
+  });
+
+  it('catalogByCategory partitions the catalog', () => {
+    const total =
+      catalogByCategory('widget').length +
+      catalogByCategory('view').length +
+      catalogByCategory('component').length;
+    expect(total).toBe(UI_CATALOG.length);
+  });
+});
+
+describe('renderDashboardConfig', () => {
+  it('renders a valid foundry.dashboard.ts for known widgets', () => {
+    const r = renderDashboardConfig([
+      { kind: 'metrics', title: 'Overview' },
+      { kind: 'pipeline', type: 'topic', title: 'Pipeline' },
+      { kind: 'recent', limit: 8 },
+    ]);
+    expect(r.ok).toBe(true);
+    expect(r.errors).toEqual([]);
+    expect(r.file?.path).toBe('src/foundry.dashboard.ts');
+    expect(r.file?.content).toContain('export const dashboard: DashboardConfig = [');
+    expect(r.file?.content).toContain('"kind":"metrics"');
+    expect(r.file?.content).toContain('"type":"topic"');
+    expect(r.file?.content).toContain("import type { DashboardConfig } from '@/components/dashboard/config'");
+  });
+
+  it('rejects an unknown widget kind (never writes a config the app cannot render)', () => {
+    const r = renderDashboardConfig([{ kind: 'metrics' }, { kind: 'teleporter' }]);
+    expect(r.ok).toBe(false);
+    expect(r.file).toBeUndefined();
+    expect(r.errors.join(' ')).toContain('teleporter');
+  });
+
+  it('rejects an empty layout', () => {
+    expect(renderDashboardConfig([]).ok).toBe(false);
+  });
+
+  it('flags chosen widgets that are not built into the template', () => {
+    expect(widgetsNeedingScaffold([{ kind: 'metrics' }, { kind: 'kanban-board' }])).toEqual(['kanban-board']);
+    expect(widgetsNeedingScaffold([{ kind: 'metrics' }, { kind: 'recent' }])).toEqual([]);
+  });
+});

package/src/catalog/catalog.ts

@@ -0,0 +1,138 @@
+import type { CatalogEntry } from './types';
+
+/**
+ * The curated Foundry app-UI catalog. Order is roughly "reach for these first" →
+ * heavier/nicher last. Keep it small and honest: every entry must be genuinely
+ * useful in a data-driven tenant app and cheap to explain to a non-technical
+ * owner. `builtIn` blocks ship in the template today; the rest are scaffolded in
+ * on demand so the base template stays thin.
+ */
+export const UI_CATALOG: CatalogEntry[] = [
+  {
+    id: 'metrics',
+    category: 'widget',
+    title: 'Metrics row',
+    description:
+      'A row of big-number tiles, one per entity type, each linking to its section. The default at-a-glance overview — good on almost every app.',
+    dataNeeds: 'Any types (uses record counts).',
+    builtIn: true,
+    source: { export: 'MetricCard', from: '@startsimpli/ui' },
+    configExample: { kind: 'metrics', title: 'Overview' },
+  },
+  {
+    id: 'quick-create',
+    category: 'widget',
+    title: 'Quick add',
+    description:
+      'One-click "New <type>" buttons that open the create form in a dialog. The fast path from an empty app to its first records.',
+    dataNeeds: 'Any types.',
+    builtIn: true,
+    source: { export: 'BaseDialog', from: '@startsimpli/ui' },
+    configExample: { kind: 'quick-create', title: 'Quick add' },
+  },
+  {
+    id: 'pipeline',
+    category: 'widget',
+    title: 'Pipeline funnel',
+    description:
+      'A funnel of one type\'s records across the stages of its status field, with per-stage counts and conversion. Best for a clear forward workflow (e.g. lead → won). Reads oddly for branch statuses like "rejected".',
+    dataNeeds: 'A type with a status/enum field whose stages flow forward.',
+    builtIn: true,
+    source: { export: 'PipelineFunnel', from: '@startsimpli/ui' },
+    configExample: { kind: 'pipeline', type: '<typeKey>', title: 'Pipeline' },
+  },
+  {
+    id: 'recent',
+    category: 'widget',
+    title: 'Recent activity',
+    description:
+      'A live feed of the most recently created records — across all types or one — with type badges and relative timestamps.',
+    dataNeeds: 'Any types (uses created_at).',
+    builtIn: true,
+    source: { export: 'Card', from: '@startsimpli/ui' },
+    configExample: { kind: 'recent', limit: 8, title: 'Recent activity' },
+  },
+  {
+    id: 'type-grid',
+    category: 'widget',
+    title: 'Section cards',
+    description:
+      'The classic per-type card grid: count + status breakdown, each card links into its section. A compact index of the whole app.',
+    dataNeeds: 'Any types.',
+    builtIn: true,
+    source: { export: 'Card', from: '@startsimpli/ui' },
+    configExample: { kind: 'type-grid', title: 'All sections' },
+  },
+  {
+    id: 'kanban-board',
+    category: 'widget',
+    title: 'Kanban board preview',
+    description:
+      'A drag-to-move board that lays a status type\'s records into lanes. Use as a home widget for the primary workflow type, or as the full section for it.',
+    dataNeeds: 'A type with a status/enum field.',
+    heavy: true,
+    source: { export: 'KanbanBoard', from: '@startsimpli/ui' },
+    configExample: { kind: 'kanban-board', type: '<typeKey>', title: 'Board' },
+  },
+  {
+    id: 'data-table',
+    category: 'view',
+    title: 'Data table',
+    description:
+      'An enterprise table for one type — sortable columns, column picker, server pagination, Excel export. Use for dense list types the owner scans and exports.',
+    dataNeeds: 'Any type (renders its fields as columns).',
+    heavy: true,
+    source: { export: 'UnifiedTable', from: '@startsimpli/ui/table' },
+    configExample: { kind: 'data-table', type: '<typeKey>', title: 'Records' },
+  },
+  {
+    id: 'calendar',
+    category: 'view',
+    title: 'Calendar',
+    description:
+      'A month/week calendar of a type\'s records placed by one of its date fields. Use for anything time-anchored — events, posts, deadlines.',
+    dataNeeds: 'A type with a date field.',
+    heavy: true,
+    source: { export: 'CalendarView', from: '@startsimpli/ui' },
+    configExample: { kind: 'calendar', type: '<typeKey>', dateField: '<fieldName>', title: 'Calendar' },
+  },
+  {
+    id: 'gantt',
+    category: 'view',
+    title: 'Gantt timeline',
+    description:
+      'A timeline of records with start/end dates as bars, with board and timeline modes. Use for scheduling/project types spanning ranges.',
+    dataNeeds: 'A type with a start-date and an end-date field.',
+    heavy: true,
+    source: { export: 'GanttChart', from: '@startsimpli/ui/gantt' },
+    configExample: { kind: 'gantt', type: '<typeKey>', startField: '<start>', endField: '<end>', title: 'Timeline' },
+  },
+  {
+    id: 'metric-trend',
+    category: 'widget',
+    title: 'Trend metric',
+    description:
+      'A single metric tile with a sparkline and up/down trend. Use to headline one number that matters (this week\'s new records, a running total).',
+    dataNeeds: 'Any type, or a numeric field tracked over time.',
+    source: { export: 'MetricCard', from: '@startsimpli/ui' },
+    configExample: { kind: 'metric-trend', type: '<typeKey>', title: 'This week' },
+  },
+  {
+    id: 'command-palette',
+    category: 'component',
+    title: 'Command palette',
+    description:
+      'A ⌘K global search/jump over the app\'s sections and records. An app-shell add-on, not a home widget — enable it once for the whole app.',
+    dataNeeds: 'Any types.',
+    source: { export: 'CommandPalette', from: '@startsimpli/ui' },
+  },
+  {
+    id: 'chat',
+    category: 'component',
+    title: 'Chat thread',
+    description:
+      'A threaded message view with a composer and attachments. Use only when the app genuinely models conversations (a messages type with a thread). Niche — do not add by default.',
+    dataNeeds: 'A messages/thread type.',
+    source: { export: 'ChatThread', from: '@startsimpli/ui' },
+  },
+];

package/src/catalog/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Foundry app-UI catalog — public surface.
+ *
+ * Import from `@startsimpli/ui/catalog` (a pure-data subpath; no component code).
+ * The AI app builder uses `renderCatalogForPrompt()` to "see" what it can build;
+ * `getCatalogEntry`/`UI_CATALOG` back the scaffolder and any component picker UI.
+ */
+export { UI_CATALOG } from './catalog';
+export type { CatalogEntry, CatalogCategory, ScaffoldFile } from './types';
+export {
+  renderDashboardConfig,
+  widgetsNeedingScaffold,
+  type DashboardWidgetConfig,
+  type RenderResult,
+} from './scaffold';
+
+import { UI_CATALOG } from './catalog';
+import type { CatalogCategory, CatalogEntry } from './types';
+
+/** Look up one block by id (the foundry.dashboard.ts `kind` for widgets). */
+export function getCatalogEntry(id: string): CatalogEntry | undefined {
+  return UI_CATALOG.find((e) => e.id === id);
+}
+
+/** All blocks in a category. */
+export function catalogByCategory(category: CatalogCategory): CatalogEntry[] {
+  return UI_CATALOG.filter((e) => e.category === category);
+}
+
+/** The blocks the base template already ships (config-only, no scaffolding). */
+export function builtInWidgets(): CatalogEntry[] {
+  return UI_CATALOG.filter((e) => e.builtIn);
+}
+
+/**
+ * A compact, token-frugal rendering of the catalog for an LLM system prompt: one
+ * line per block — id, category, a ⚠ heavy marker, what it needs, and the gist.
+ * Deterministic (catalog order) so prompts stay cache-stable.
+ */
+export function renderCatalogForPrompt(): string {
+  const line = (e: CatalogEntry) => {
+    const flags = [e.builtIn ? 'built-in' : 'scaffolded', e.heavy ? '⚠ heavy' : null]
+      .filter(Boolean)
+      .join(', ');
+    return `- ${e.id} (${e.category}${flags ? `; ${flags}` : ''}) — ${e.title}: ${e.description} Needs: ${e.dataNeeds}`;
+  };
+  return UI_CATALOG.map(line).join('\n');
+}

package/src/catalog/scaffold.ts

@@ -0,0 +1,64 @@
+/**
+ * Fork-authoring helpers: turn a chosen set of catalog blocks into the concrete
+ * files that go into a tenant's forked app repo. The AI app builder calls these
+ * to produce a reviewable change (applied as a PR), so the base template stays
+ * thin — only what's chosen lands in a fork.
+ *
+ * Today: `renderDashboardConfig` writes the home layout (foundry.dashboard.ts)
+ * from built-in widgets. Per-component scaffolding of heavier blocks (calendar,
+ * gantt, …) layers on next, emitting additional ScaffoldFiles.
+ */
+import { UI_CATALOG } from './catalog';
+import type { ScaffoldFile } from './types';
+
+/** One home widget: a catalog widget id + its per-widget params (type, title…). */
+export interface DashboardWidgetConfig {
+  kind: string;
+  [param: string]: unknown;
+}
+
+const WIDGET_IDS = new Set(UI_CATALOG.filter((e) => e.category === 'widget').map((e) => e.id));
+
+/** Which of the chosen widgets are NOT built into the base template (need scaffolding). */
+export function widgetsNeedingScaffold(widgets: DashboardWidgetConfig[]): string[] {
+  const builtIn = new Set(UI_CATALOG.filter((e) => e.builtIn).map((e) => e.id));
+  return [...new Set(widgets.map((w) => w.kind))].filter((k) => WIDGET_IDS.has(k) && !builtIn.has(k));
+}
+
+export interface RenderResult {
+  ok: boolean;
+  /** Unknown/invalid widget kinds — the AI should fix these before applying. */
+  errors: string[];
+  file?: ScaffoldFile;
+}
+
+/**
+ * Render `src/foundry.dashboard.ts` for the given home layout. Validates each
+ * widget `kind` against the catalog's widget blocks; an unknown kind fails the
+ * whole render (so we never write a config referencing a widget the app can't
+ * render). Serializes params as a plain literal — valid TS the owner can hand-edit.
+ */
+export function renderDashboardConfig(widgets: DashboardWidgetConfig[]): RenderResult {
+  const errors: string[] = [];
+  if (widgets.length === 0) errors.push('layout is empty — choose at least one widget');
+  for (const w of widgets) {
+    if (!w.kind) errors.push('a widget is missing its "kind"');
+    else if (!WIDGET_IDS.has(w.kind)) errors.push(`unknown widget kind "${w.kind}"`);
+  }
+  if (errors.length > 0) return { ok: false, errors };
+
+  const body = widgets.map((w) => `  ${JSON.stringify(w)},`).join('\n');
+  const content = `/**
+ * Your app's home, as data. Generated by the Foundry app builder — safe to
+ * hand-edit. Each entry is a widget (see components/dashboard for the registry);
+ * add/remove/reorder them, or set this to 'auto' to derive a layout from your
+ * schema. Widget shapes live in components/dashboard/config.
+ */
+import type { DashboardConfig } from '@/components/dashboard/config';
+
+export const dashboard: DashboardConfig = [
+${body}
+];
+`;
+  return { ok: true, errors: [], file: { path: 'src/foundry.dashboard.ts', content } };
+}

package/src/catalog/types.ts

@@ -0,0 +1,65 @@
+/**
+ * The Foundry app-UI component catalog (startsim app-builder).
+ *
+ * A curated, machine-readable index of the @startsimpli/ui building blocks a
+ * Foundry tenant app can use on its home / sections — the surface the AI app
+ * builder reads to decide what to compose, and the source of truth for how each
+ * gets scaffolded into a tenant's forked repo.
+ *
+ * This module is PURE DATA (no React imports) so it's cheap to pull into an LLM
+ * route or a Node scaffolder without dragging component code. The heavy, curated
+ * catalog is deliberately SMALL — the ~dozen blocks that make sense in a
+ * data-driven tenant app, not the ~300 exports of the kit. The AI is told to
+ * reach past it only when asked.
+ */
+
+/**
+ * How a block is used in a tenant app:
+ * - `widget`: a home-dashboard block, referenced by `kind` in foundry.dashboard.ts.
+ * - `view`:   a full section/page for one entity type (board, table, calendar…).
+ * - `component`: an app-shell/embeddable primitive (command palette, chat…).
+ */
+export type CatalogCategory = 'widget' | 'view' | 'component';
+
+export interface CatalogEntry {
+  /** Stable id. For widgets this IS the foundry.dashboard.ts `kind`. */
+  id: string;
+  category: CatalogCategory;
+  /** Human title shown to the owner. */
+  title: string;
+  /** What it is + when to reach for it — written for the AI builder to reason over. */
+  description: string;
+  /**
+   * The schema shape this block wants, in one plain phrase (e.g. "a type with a
+   * status/enum field", "a type with a date field"). The AI only offers a block
+   * when the tenant's live schema satisfies this.
+   */
+  dataNeeds: string;
+  /**
+   * Pulls a big transitive dependency (calendar, kanban dnd, xlsx, gantt). The AI
+   * is instructed to avoid heavy blocks unless the user explicitly asks — this is
+   * how "don't just throw every component in" is enforced at the catalog level.
+   */
+  heavy?: boolean;
+  /**
+   * Already shipped in the base template's widget registry — configuring it needs
+   * only a foundry.dashboard.ts entry (no new files). Absent = must be scaffolded
+   * into the fork on demand (keeps the base template thin).
+   */
+  builtIn?: boolean;
+  /** Where the underlying component comes from, for a scaffolded wrapper's import. */
+  source: { export: string; from: string };
+  /**
+   * An example foundry.dashboard.ts entry for this block, so the AI emits valid
+   * config. `kind` matches `id` for widgets.
+   */
+  configExample?: Record<string, unknown>;
+}
+
+/** A block plus the concrete files to add to a fork to enable it (scaffolding). */
+export interface ScaffoldFile {
+  /** Repo-relative path within the tenant fork, e.g. src/components/dashboard/calendar-widget.tsx */
+  path: string;
+  /** Full file contents. */
+  content: string;
+}