@specverse/engines 4.2.1 → 4.3.0

package/libs/instance-factories/applications/templates/react-starter/helpers-emitter.ts

@@ -25,18 +25,19 @@ export function emitEntityDisplay(): string {
  * @specverse/realize (ReactAppStarter); edit freely — nothing in
  * the factory's regeneration will clobber your edits.
  */
-export function getEntityDisplayName(entity: Record<string, unknown> | null | undefined): string {
-  if (!entity) return '';
+export function getEntityDisplayName(entity: unknown): string {
+  if (!entity || typeof entity !== 'object') return '';
+  const record = entity as Record<string, unknown>;
 
   const candidates = ['name', 'title', 'displayName', 'label', 'username', 'email'];
   for (const key of candidates) {
-    const value = entity[key];
+    const value = record[key];
     if (typeof value === 'string' && value.trim().length > 0) {
       return value;
     }
   }
 
-  const id = entity.id;
+  const id = record.id;
   if (typeof id === 'string') {
     return id.length > 8 ? id.slice(0, 8) + '…' : id;
   }
@@ -62,5 +63,282 @@ export function resolveEntityDisplayName(
   );
   return match ? getEntityDisplayName(match) : String(id);
 }
+
+/**
+ * Format an arbitrary value for display in list cells, detail rows,
+ * and dashboard previews. Handles the cases where \`String(v ?? '')\`
+ * produces ugly output: nulls become em-dashes, booleans become
+ * "Yes"/"No", nested objects become \`{k: v, ...}\` summaries
+ * instead of "[object Object]", ISO datetimes are localized.
+ *
+ * Single source of truth for value display. Resolvers / emitters
+ * call this from expression strings.
+ */
+export function formatDisplayValue(value: unknown): string {
+  if (value === null || value === undefined) return '—';
+  if (typeof value === 'boolean') return value ? 'Yes' : 'No';
+  if (value instanceof Date) return value.toLocaleString();
+  if (typeof value === 'string' && /^\\d{4}-\\d{2}-\\d{2}T/.test(value)) {
+    return new Date(value).toLocaleString();
+  }
+  if (Array.isArray(value)) return \`[\${value.length} items]\`;
+  if (typeof value === 'object') {
+    const keys = Object.keys(value as Record<string, unknown>);
+    if (keys.length === 0) return '{}';
+    if (keys.length <= 5) {
+      const rec = value as Record<string, unknown>;
+      return keys.map(k => \`\${k}: \${formatDisplayValue(rec[k])}\`).join(', ');
+    }
+    return \`{\${keys.length} fields}\`;
+  }
+  return String(value);
+}
+`;
+}
+
+/**
+ * Source of `src/hooks/useAppEvents.ts`.
+ *
+ * Connects to the backend's `/ws` endpoint, subscribes to every
+ * CURED event, and invalidates the matching React Query cache on
+ * Created / Updated / Deleted / Evolved events. Drives live-refresh
+ * everywhere in the app.
+ *
+ * Message shapes the backend sends:
+ *   - `{ type: 'connected', timestamp }` — open handshake.
+ *   - `{ type: 'subscribed-all', events }` — ack of subscribe-all.
+ *   - `{ type: 'event', event: '{Model}{Action}', payload, timestamp }`.
+ *
+ * Message the client sends:
+ *   - `{ type: 'subscribe-all' }` once the socket opens.
+ */
+export function emitUseAppEvents(): string {
+  return `/**
+ * AppEventsProvider + useAppEvents + useRecentEvents
+ *
+ * One WebSocket connection to the backend's /ws, shared across the
+ * app. Two consumers:
+ *   - useAppEvents(): React Query invalidation on mutations (no-op
+ *     call — side effect is via the provider).
+ *   - useRecentEvents(): the Events tab's scrolling stream display.
+ *
+ * Inlined into this project by @specverse/realize (ReactAppStarter).
+ * Edit freely.
+ */
+import { useEffect, useState, useContext, createContext, type ReactNode } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+
+export interface AppEvent {
+  event: string;
+  payload: any;
+  timestamp: string;
+}
+
+interface AppEventsCtx {
+  recentEvents: AppEvent[];
+  clear: () => void;
+}
+
+const EventsContext = createContext<AppEventsCtx | null>(null);
+
+function pluralize(s: string): string {
+  if (/[^aeiou]y$/i.test(s)) return s.slice(0, -1) + 'ies';
+  if (/(s|x|z|ch|sh)$/i.test(s)) return s + 'es';
+  return s + 's';
+}
+
+function deriveWsUrl(): string {
+  const apiBase = import.meta.env.VITE_API_BASE_URL || '';
+  if (apiBase) return apiBase.replace(/^http/, 'ws') + '/ws';
+  const proto = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+  return \`\${proto}//\${window.location.host}/ws\`;
+}
+
+/** Parse "CategoryCreated" → "Category". Returns null for event names
+ *  that don't end in one of the 4 CURED verbs. */
+function modelFromEvent(eventName: string): string | null {
+  const m = eventName.match(/^(.+)(Created|Updated|Deleted|Evolved)$/);
+  return m ? m[1] : null;
+}
+
+/**
+ * Provider — wrap the app once. Maintains a single WS connection,
+ * invalidates React Query caches on mutation events, and keeps a
+ * buffer of recent events (default 100) for the Events tab.
+ */
+export function AppEventsProvider({ children, bufferSize = 100 }: { children: ReactNode; bufferSize?: number }) {
+  const qc = useQueryClient();
+  const [recentEvents, setRecentEvents] = useState<AppEvent[]>([]);
+
+  const clear = () => setRecentEvents([]);
+
+  useEffect(() => {
+    let cancelled = false;
+    let ws: WebSocket | null = null;
+    let reconnectDelay = 500;
+    let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const connect = () => {
+      if (cancelled) return;
+      try {
+        ws = new WebSocket(deriveWsUrl());
+      } catch {
+        scheduleReconnect();
+        return;
+      }
+
+      ws.addEventListener('open', () => {
+        if (cancelled) { ws?.close(); return; }
+        reconnectDelay = 500;
+        ws?.send(JSON.stringify({ type: 'subscribe-all' }));
+      });
+
+      ws.addEventListener('message', (evt) => {
+        if (cancelled) return;
+        let data: any;
+        try { data = JSON.parse(evt.data as string); } catch { return; }
+        if (data?.type !== 'event') return;
+        const appEvent: AppEvent = {
+          event: data.event,
+          payload: data.payload,
+          timestamp: data.timestamp ?? new Date().toISOString(),
+        };
+        // Append + cap at bufferSize.
+        setRecentEvents(prev => {
+          const next = [...prev, appEvent];
+          return next.length > bufferSize ? next.slice(-bufferSize) : next;
+        });
+        // Invalidate React Query cache for affected model.
+        const model = modelFromEvent(data.event);
+        if (model) {
+          const resource = pluralize(model).toLowerCase();
+          qc.invalidateQueries({ queryKey: [resource] });
+        }
+      });
+
+      ws.addEventListener('close', () => {
+        if (!cancelled) scheduleReconnect();
+      });
+
+      ws.addEventListener('error', () => {
+        try { ws?.close(); } catch { /* ignore */ }
+      });
+    };
+
+    const scheduleReconnect = () => {
+      if (cancelled) return;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      reconnectTimer = setTimeout(() => {
+        reconnectDelay = Math.min(reconnectDelay * 2, 10_000);
+        connect();
+      }, reconnectDelay);
+    };
+
+    // Microtask-deferred connect — StrictMode-safe (synchronous
+    // mount/unmount/remount won't leave a half-open socket).
+    Promise.resolve().then(() => { if (!cancelled) connect(); });
+
+    return () => {
+      cancelled = true;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      if (ws && ws.readyState === WebSocket.CONNECTING) {
+        ws.addEventListener('open', () => ws?.close(), { once: true });
+      } else if (ws) {
+        try { ws.close(); } catch { /* ignore */ }
+      }
+    };
+  }, [qc, bufferSize]);
+
+  return (
+    <EventsContext.Provider value={{ recentEvents, clear }}>
+      {children}
+    </EventsContext.Provider>
+  );
+}
+
+/**
+ * Shorthand for components that don't care about the buffer — they
+ * get live-refresh behavior "for free" because the provider runs
+ * query invalidation. Kept as a no-op hook so sites that called it
+ * under the old API still type-check and still document intent.
+ */
+export function useAppEvents() {
+  // No-op — the Provider does the work. Retained to preserve intent
+  // at call sites like "the app needs live refresh".
+  useContext(EventsContext);
+}
+
+/**
+ * Read the recent-events buffer — used by the Events tab to render
+ * a scrolling stream. Returns [] if no AppEventsProvider is mounted.
+ */
+export function useRecentEvents(): AppEventsCtx {
+  return useContext(EventsContext) ?? { recentEvents: [], clear: () => {} };
+}
+`;
+}
+
+/**
+ * Source of `src/hooks/useResizableSidebar.ts`.
+ *
+ * Ported verbatim from `@specverse/runtime/views/react/hooks/
+ * useResizableSidebar` (app-demo re-exports the same hook). Drag-to-
+ * resize sidebar width with localStorage persistence.
+ */
+export function emitUseResizableSidebar(): string {
+  return `/**
+ * useResizableSidebar — drag-to-resize sidebar width.
+ *
+ * Inlined into this project by @specverse/realize (ReactAppStarter);
+ * edit freely — nothing in the factory's regeneration will clobber
+ * your edits.
+ *
+ * Returns { width, isResizing, startResizing } — width is the current
+ * pixel value, isResizing is true during an active drag, startResizing
+ * is an onMouseDown handler to attach to the drag handle element.
+ */
+import { useState, useEffect, useCallback } from 'react';
+
+export interface ResizableSidebarOptions {
+  defaultWidth?: number;
+  minWidth?: number;
+  maxWidth?: number;
+}
+
+export function useResizableSidebar(options: ResizableSidebarOptions = {}) {
+  const { defaultWidth = 256, minWidth = 200, maxWidth = 500 } = options;
+  const [width, setWidth] = useState(defaultWidth);
+  const [isResizing, setIsResizing] = useState(false);
+
+  const startResizing = useCallback(() => {
+    setIsResizing(true);
+  }, []);
+
+  useEffect(() => {
+    if (!isResizing) return;
+
+    const handleMouseMove = (e: MouseEvent) => {
+      const newWidth = Math.min(maxWidth, Math.max(minWidth, e.clientX));
+      setWidth(newWidth);
+    };
+    const handleMouseUp = () => {
+      setIsResizing(false);
+      document.body.style.cursor = '';
+      document.body.style.userSelect = '';
+    };
+
+    document.body.style.cursor = 'col-resize';
+    document.body.style.userSelect = 'none';
+    document.addEventListener('mousemove', handleMouseMove);
+    document.addEventListener('mouseup', handleMouseUp);
+
+    return () => {
+      document.removeEventListener('mousemove', handleMouseMove);
+      document.removeEventListener('mouseup', handleMouseUp);
+    };
+  }, [isResizing, minWidth, maxWidth]);
+
+  return { width, isResizing, startResizing };
+}
 `;
 }

package/libs/instance-factories/applications/templates/react-starter/list-body-composer.ts

@@ -1,146 +1,37 @@
 /**
- * List-view body composer for ReactAppStarter
+ * List-view body composer for ReactAppStarter (Phase 3)
  *
- * Implements the `renderBody` contract of view-emitter.ts for list
- * views. Uses the canonical Tailwind adapter from
- * `@specverse/runtime/views/tailwind` to render the TABLE SHELL, then
- * injects a JSX `.map()` expression into the tbody so the generated
- * component renders rows from the `filtered` array defined by the
- * skeleton.
+ * Now a thin wrapper around the pattern walker. The 'what a list
+ * view looks like' knowledge lives in the pattern registry (section
+ * content declarations) + section resolvers in
+ * `@specverse/runtime/views/core/section-resolvers/`. This composer
+ * just calls `walkPattern('list-view', context)` and emits the
+ * resulting RenderNode tree as JSX source.
  *
- * Why split it this way: the adapter produces static HTML (the same
- * HTML app-demo uses). For Factory B we want React that maps over
- * runtime data — so we take the adapter's shell and replace a sentinel
- * inside the tbody with a `{filtered.map(...)}` expression. The shell
- * stays canonical; only the row-iteration JSX is synthesized here.
+ * Notice the shape: no column inference, no row-iteration JSX, no
+ * header rendering in this file. That logic now lives in the walker
+ * where app-demo and ReactAppRuntime can use it too.
  *
- * See README.md for the full architecture.
+ * This is the first of four composers migrated to the walker path.
+ * detail, form, dashboard follow the same shape.
  */
 
-import { createUniversalTailwindAdapter } from '@specverse/runtime/views/tailwind';
-import { inferFieldsFromSchema } from '@specverse/runtime/views/core';
-import { htmlToJsx } from './html-to-jsx.js';
-import type { EmitContext, ModelSpec } from './view-emitter.js';
-import { buildFKMap } from './belongs-to.js';
+import { walkPattern } from '@specverse/runtime/views/core';
+import type { EmitContext } from './view-emitter.js';
+import { emitJsxSource } from './emit-jsx-source.js';
 
-/**
- * Sentinel token. Must be ASCII-safe (no curly braces) so it survives
- * the html-to-jsx transform unchanged, and must be unique enough not
- * to appear in real HTML output.
- */
-const TBODY_SENTINEL = '__SPECVERSE_TBODY_ROWS__';
-
-/**
- * Compose the list view's body as JSX-safe source. Returned string is
- * meant to be dropped at `{{BODY}}` inside `skeletons/list.tsx.template`.
- */
 export function composeListBody(context: EmitContext): string {
-  const fkMap = buildFKMap(context.model);
-  // Inference (`inferFieldsFromSchema`) reads attributes and doesn't
-  // see belongsTo relationships. For list views we want a column per
-  // belongsTo so users can scan "who owns this" at a glance —
-  // otherwise a Task table hides its Project and Assignee columns.
-  // Append any FK columns the inference missed, preserving order.
-  const inferred = inferColumns(context);
-  const inferredSet = new Set(inferred);
-  const extraFKs = [...fkMap.keys()].filter(k => !inferredSet.has(k));
-  const columns = [...inferred, ...extraFKs];
-
-  // Header label for an FK column should use the relationship name
-  // ("Owner") not the raw column name ("Owner Id"). The cell rendering
-  // in buildRowMap applies the matching FK→name resolution.
-  const headers = columns.map(col => {
-    const fk = fkMap.get(col);
-    return humanize(fk ? fk.name : col);
+  // The walker returns a rendering-agnostic RenderNode tree. The
+  // imports set collects any capitalised composite components the
+  // tree references — view-emitter injects them at the top of the
+  // generated .tsx file. For list views today the tree is all
+  // lowercase HTML tags, so imports is typically empty.
+  const imports = new Set<string>();
+  const nodes = walkPattern('list-view', {
+    model: context.model,
+    modelSchemas: context.modelSchemas as any,
+    view: context.view,
   });
 
-  const adapter = createUniversalTailwindAdapter({ darkMode: true });
-  const shellHtml = adapter.components.table.render({
-    properties: { columns: headers },
-    children: TBODY_SENTINEL,
-  });
-
-  // Transform the static HTML shell to JSX-safe source. The sentinel
-  // lands in a text position inside the <tbody> and survives the
-  // transform untouched.
-  const shellJsx = htmlToJsx(shellHtml);
-
-  // Build the row-iteration JSX that replaces the sentinel. The
-  // skeleton's useMemo produces `filtered: Model[]`, so the map
-  // expression binds over that. onSelect is a prop the skeleton
-  // declares. Delete action wires to the deleteItem mutation.
-  const rowMap = buildRowMap(columns, fkMap);
-
-  if (!shellJsx.includes(TBODY_SENTINEL)) {
-    // Defensive: catches adapter output changes that no longer flow
-    // `children` into the tbody. Caught at composer time, not runtime.
-    throw new Error(
-      'composeListBody: tbody sentinel not present in adapter output. ' +
-      'The canonical Tailwind adapter may have changed its table rendering.'
-    );
-  }
-
-  return shellJsx.replace(TBODY_SENTINEL, rowMap);
-}
-
-/**
- * Select the non-metadata attributes of a model. Delegates to the
- * canonical pattern library so the column set is identical to what
- * the runtime React adapter picks for the same model — parity test P3
- * relies on this being one-and-the-same function.
- */
-function inferColumns(context: EmitContext): string[] {
-  return inferFieldsFromSchema(context.modelSchemas, context.model.name);
-}
-
-/**
- * Convert a camelCase attribute name to Title-Case words for display
- * as a column header. Matches the convention used by runtime's
- * pattern adapter (see `humanize` in runtime react-pattern-adapter).
- */
-function humanize(name: string): string {
-  return name
-    .replace(/([A-Z])/g, ' $1')
-    .replace(/^./, c => c.toUpperCase())
-    .trim();
-}
-
-/**
- * Emit the `{filtered.map(...)}` JSX expression that renders each
- * row. Keep the output readable so users inspecting the generated
- * file can follow what's happening.
- */
-function buildRowMap(columns: string[], fkMap: Map<string, { name: string; target: string }>): string {
-  // Type-cast to `any` to avoid TS generic syntax (`<string, unknown>`)
-  // inside JSX expressions, which the TSX parser can't always
-  // disambiguate from a JSX opening tag. `any` is the right choice for
-  // starter-kit output anyway — the user will often reshape the row
-  // type after editing.
-  //
-  // FK columns render through `resolveEntityDisplayName(id, options)`
-  // so the user sees a name instead of a UUID. The options array
-  // (`${relName}Options`) is populated by the hook call wired into
-  // the list skeleton via view-emitter's RELATED_HOOKS substitution.
-  const cells = columns
-    .map(col => {
-      const fk = fkMap.get(col);
-      const expr = fk
-        ? `{resolveEntityDisplayName((item as any).${col}, ${fk.name}Options)}`
-        : `{String((item as any).${col} ?? '')}`;
-      return `            <td className="px-6 py-4 text-sm text-gray-700 dark:text-gray-300">` +
-        `${expr}</td>`;
-    })
-    .join('\n');
-
-  return [
-    '{filtered.map((item, idx) => (',
-    '  <tr',
-    '    key={idx}',
-    '    onClick={() => onSelect?.(item)}',
-    '    className="hover:bg-gray-50 dark:hover:bg-gray-800 cursor-pointer"',
-    '  >',
-    cells,
-    '  </tr>',
-    '))}',
-  ].join('\n');
+  return emitJsxSource(nodes, { imports, indent: 6 });
 }