@startsimpli/ui 0.4.105 → 0.4.107

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.105",
+  "version": "0.4.107",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -45,9 +45,9 @@
     "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.57",
     "@startsimpli/auth": "^0.4.35",
-    "@startsimpli/i18n": "^0.1.3",
-    "@startsimpli/api": "^0.5.56"
+    "@startsimpli/i18n": "^0.1.3"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {
@@ -121,8 +121,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@startsimpli/i18n": "0.1.3",
-    "@startsimpli/realtime": "0.0.2"
+    "@startsimpli/realtime": "0.0.2",
+    "@startsimpli/i18n": "0.1.3"
   },
   "keywords": [
     "ui",

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

@@ -94,6 +94,51 @@ describe('renderDashboardConfig', () => {
     expect(renderDashboardConfig([]).ok).toBe(false);
   });
 
+  // startsim-y5dnx. The builder wrote exactly this entry into the tandem fork:
+  //
+  //   { kind: 'source-freshness', title: 'How current is it' }
+  //
+  // and the home rendered "How current is it — 152 stale" with every one of the
+  // 152 commitments listed as "never", over a corpus whose newest record had
+  // arrived 30 minutes earlier. The widget had nothing to go on, so it guessed a
+  // type and a date field, and the field it landed on was a business date that is
+  // null until somebody resolves a commitment.
+  //
+  // "Never writes a config the app cannot render" has to cover this too: a kind
+  // the app knows, configured so incompletely that all it can do is guess.
+  it('rejects a source-freshness widget that names no timestamp field', () => {
+    const r = renderDashboardConfig([
+      { kind: 'metrics' },
+      { kind: 'source-freshness', title: 'How current is it' },
+    ]);
+    expect(r.ok).toBe(false);
+    expect(r.file).toBeUndefined();
+    expect(r.errors.join(' ')).toContain('timestampField');
+  });
+
+  it('rejects a source-freshness widget that names a type but no field', () => {
+    const r = renderDashboardConfig([{ kind: 'source-freshness', type: 'commitment' }]);
+    expect(r.ok).toBe(false);
+    expect(r.errors.join(' ')).toContain('timestampField');
+  });
+
+  it('renders a source-freshness widget once it is told what to read', () => {
+    const r = renderDashboardConfig([
+      { kind: 'source-freshness', type: 'document', timestampField: 'fetched_at', title: 'Freshness' },
+    ]);
+    expect(r.ok).toBe(true);
+    expect(r.errors).toEqual([]);
+    expect(r.file?.content).toContain('"timestampField":"fetched_at"');
+  });
+
+  it('tells the AI, in the catalog, that both keys are required', () => {
+    const entry = getCatalogEntry('source-freshness');
+    expect(entry?.configExample).toMatchObject({ kind: 'source-freshness' });
+    expect(Object.keys(entry?.configExample ?? {})).toContain('timestampField');
+    // The prompt line is all the builder sees; the requirement has to be in it.
+    expect(renderCatalogForPrompt()).toContain('timestampField');
+  });
+
   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

@@ -89,10 +89,17 @@ export const UI_CATALOG: CatalogEntry[] = [
     category: 'widget',
     title: 'Source freshness',
     description:
-      'A health card listing upstream sources as fresh vs stale by their last-updated time — any stale feed pulls the card to a warning. Use to prove ongoing ingestion is actually flowing (a stale source is a bug, not coverage).',
-    dataNeeds: 'A type whose records carry a last-updated / last-fetched timestamp.',
+      'A health card listing upstream sources as fresh vs stale by their last-updated time — any stale feed pulls the card to a warning. Use to prove ongoing ingestion is actually flowing (a stale source is a bug, not coverage). One row per record, so point it at a type whose records ARE feeds, not at a high-volume record type.',
+    dataNeeds:
+      'A type whose records carry a date field meaning "this arrived" — a fetched-at / last-synced-at / last-updated stamp, never a business date like due-at or resolved-at. Name the type AND the field: it does not guess, and it renders nothing until it is told.',
     source: { export: 'SourceFreshness', from: '@startsimpli/ui' },
-    configExample: { kind: 'source-freshness', type: '<typeKey>', title: 'Source freshness' },
+    requiredParams: ['type', 'timestampField'],
+    configExample: {
+      kind: 'source-freshness',
+      type: '<typeKey>',
+      timestampField: '<arrivalDateAttr>',
+      title: 'Source freshness',
+    },
   },
   {
     id: 'delivery-health',

package/src/catalog/index.ts

@@ -42,7 +42,14 @@ export function renderCatalogForPrompt(): string {
     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}`;
+    // `requiredParams` is the difference between a block the AI can offer and one
+    // it can offer WRONG — an under-configured widget that guesses is worse on the
+    // page than one that was never offered (bd startsim-y5dnx). The renderer
+    // rejects a config that omits these, so the prompt has to name them.
+    const required = e.requiredParams?.length
+      ? ` Requires config: ${e.requiredParams.join(', ')}.`
+      : '';
+    return `- ${e.id} (${e.category}${flags ? `; ${flags}` : ''}) — ${e.title}: ${e.description} Needs: ${e.dataNeeds}${required}`;
   };
   return UI_CATALOG.map(line).join('\n');
 }

package/src/catalog/scaffold.ts

@@ -19,6 +19,19 @@ export interface DashboardWidgetConfig {
 
 const WIDGET_IDS = new Set(UI_CATALOG.filter((e) => e.category === 'widget').map((e) => e.id));
 
+/** The config keys each widget cannot work without (see CatalogEntry.requiredParams). */
+const REQUIRED_PARAMS = new Map(
+  UI_CATALOG.filter((e) => e.requiredParams?.length).map((e) => [e.id, e.requiredParams!]),
+);
+
+/** Params a widget must be given, and was not — `undefined`/`null`/'' all count as absent. */
+function missingParams(widget: DashboardWidgetConfig): string[] {
+  return (REQUIRED_PARAMS.get(widget.kind) ?? []).filter((p) => {
+    const v = widget[p];
+    return v === undefined || v === null || v === '';
+  });
+}
+
 /** 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));
@@ -37,6 +50,11 @@ export interface RenderResult {
  * 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.
+ *
+ * A KNOWN kind fails the same way when it is missing a param it cannot work
+ * without (`requiredParams`). "A widget the app can't render" and "a widget with
+ * nothing to read" end the same way on the page — the second one worse, because
+ * it renders a number instead of nothing (bd startsim-y5dnx).
  */
 export function renderDashboardConfig(widgets: DashboardWidgetConfig[]): RenderResult {
   const errors: string[] = [];
@@ -44,6 +62,15 @@ export function renderDashboardConfig(widgets: DashboardWidgetConfig[]): RenderR
   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}"`);
+    else {
+      const missing = missingParams(w);
+      if (missing.length > 0) {
+        errors.push(
+          `widget "${w.kind}" is missing required config: ${missing.join(', ')} — ` +
+            'it will not guess, so it would render nothing (or worse, a number nobody can act on)',
+        );
+      }
+    }
   }
   if (errors.length > 0) return { ok: false, errors };
 

package/src/catalog/types.ts

@@ -54,6 +54,20 @@ export interface CatalogEntry {
    * config. `kind` matches `id` for widgets.
    */
   configExample?: Record<string, unknown>;
+  /**
+   * Config keys this block cannot work without, beyond `kind`. A widget that can
+   * still render an honest empty state with no params declares none; one that
+   * would have to GUESS what to read declares what it must be told, and
+   * `renderDashboardConfig` refuses to write a config that omits them.
+   *
+   * `source-freshness` is the reason this exists: it used to auto-pick a type and
+   * a date attribute, and on the tandem tenant that guess landed on a business
+   * date that is null until a commitment is resolved — 152 records reported as
+   * "never" and counted stale, half an hour after the newest one arrived
+   * (bd startsim-y5dnx). A schema does not record what a date MEANS, so the fork
+   * has to say.
+   */
+  requiredParams?: string[];
 }
 
 /** A block plus the concrete files to add to a fork to enable it (scaffolding). */