@specverse/engines 4.2.1 → 4.3.0

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

@@ -7,18 +7,19 @@ function emitEntityDisplay() {
  * @specverse/realize (ReactAppStarter); edit freely \u2014 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) + '\u2026' : id;
   }
@@ -44,8 +45,262 @@ 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 '\u2014';
+  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);
+}
+`;
+}
+function emitUseAppEvents() {
+  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 \u2014 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" \u2192 "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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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: () => {} };
+}
+`;
+}
+function emitUseResizableSidebar() {
+  return `/**
+ * useResizableSidebar \u2014 drag-to-resize sidebar width.
+ *
+ * Inlined into this project by @specverse/realize (ReactAppStarter);
+ * edit freely \u2014 nothing in the factory's regeneration will clobber
+ * your edits.
+ *
+ * Returns { width, isResizing, startResizing } \u2014 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 };
+}
 `;
 }
 export {
-  emitEntityDisplay
+  emitEntityDisplay,
+  emitUseAppEvents,
+  emitUseResizableSidebar
 };

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

@@ -1,55 +1,13 @@
-import { createUniversalTailwindAdapter } from "@specverse/runtime/views/tailwind";
-import { inferFieldsFromSchema } from "@specverse/runtime/views/core";
-import { htmlToJsx } from "./html-to-jsx.js";
-import { buildFKMap } from "./belongs-to.js";
-const TBODY_SENTINEL = "__SPECVERSE_TBODY_ROWS__";
+import { walkPattern } from "@specverse/runtime/views/core";
+import { emitJsxSource } from "./emit-jsx-source.js";
 function composeListBody(context) {
-  const fkMap = buildFKMap(context.model);
-  const inferred = inferColumns(context);
-  const inferredSet = new Set(inferred);
-  const extraFKs = [...fkMap.keys()].filter((k) => !inferredSet.has(k));
-  const columns = [...inferred, ...extraFKs];
-  const headers = columns.map((col) => {
-    const fk = fkMap.get(col);
-    return humanize(fk ? fk.name : col);
+  const imports = /* @__PURE__ */ new Set();
+  const nodes = walkPattern("list-view", {
+    model: context.model,
+    modelSchemas: context.modelSchemas,
+    view: context.view
   });
-  const adapter = createUniversalTailwindAdapter({ darkMode: true });
-  const shellHtml = adapter.components.table.render({
-    properties: { columns: headers },
-    children: TBODY_SENTINEL
-  });
-  const shellJsx = htmlToJsx(shellHtml);
-  const rowMap = buildRowMap(columns, fkMap);
-  if (!shellJsx.includes(TBODY_SENTINEL)) {
-    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);
-}
-function inferColumns(context) {
-  return inferFieldsFromSchema(context.modelSchemas, context.model.name);
-}
-function humanize(name) {
-  return name.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase()).trim();
-}
-function buildRowMap(columns, fkMap) {
-  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 });
 }
 export {
   composeListBody