view-contracts 0.3.4 → 0.3.5

package/docs/cli-reference.md

@@ -2,7 +2,7 @@
 
 Contract-first UI design toolchain. Compiles restricted view-contract TSX to language-neutral View IR and renders platform targets (React, SwiftUI, Compose).
 
-**Version:** 0.3.3
+**Version:** 0.3.5
 
 ## Table of Contents
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "view-contracts",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Contract-first UI design toolchain — restricted TSX to View IR to platform renderers",
   "type": "module",
   "workspaces": [

package/renderers/react/lowering/lowerToJsx.ts

@@ -10,6 +10,7 @@ import type {
   IrNode,
   IrTextNode,
   IrValue,
+  IrViewRefNode,
 } from '../../../src/ir/types.js';
 
 function indent(level: number): string {
@@ -309,7 +310,7 @@ function visibilityGuard(inner: string, props: Record<string, IrValue>, level: n
   return `${indent(level)}{${vis} !== false ? (\n${inner}\n${indent(level)}) : null}`;
 }
 
-type NodeRenderer = (node: IrComponentNode, level: number, itemScope?: string) => string;
+type NodeRenderer = (node: IrNode, level: number, itemScope?: string) => string;
 
 function renderChildren(
   children: IrNode[],
@@ -331,15 +332,14 @@ function renderChildren(
     if (child.kind === 'fragment') {
       return renderChildren(child.children, level, renderNested, itemScope);
     }
-    if (child.kind === 'component') return renderNested(child, level, itemScope);
-    return '';
+    return renderNested(child, level, itemScope);
   }).filter(Boolean);
   return parts.join('\n');
 }
 
 function renderMap(node: IrMapNode, level: number, renderNested: NodeRenderer): string {
   const item = node.item;
-  let body = renderNested(node.body as IrComponentNode, level + 1, item);
+  let body = renderNested(node.body, level + 1, item);
   if (node.key) {
     const keyAttr = ` key={${bindingExpr(node.key, item)}}`;
     body = body.replace(/^( +)<(\w+)/, `$1<$2${keyAttr}`);
@@ -440,6 +440,22 @@ function lowerVocabularyElement(
   return visibilityGuard(body, props, level);
 }
 
+function renderViewRefProps(props: Record<string, IrValue>, itemScope?: string): string {
+  const vmRef = itemScope ?? 'vm';
+  return Object.entries(props).map(([key, value]) => {
+    if (typeof value === 'object' && value !== null && 'kind' in value && value.kind === 'binding') {
+      return `${key}={${bindingExpr(value as IrBinding, vmRef)}}`;
+    }
+    return `${key}={${renderValue(value, 0)}}`;
+  }).join(' ');
+}
+
+function renderViewRefElement(node: IrViewRefNode, level: number, itemScope?: string): string {
+  const props = renderViewRefProps(node.props, itemScope);
+  const propStr = props ? ` ${props}` : '';
+  return `${indent(level)}<${node.name}${propStr} />`;
+}
+
 function renderExtensionProps(props: Record<string, IrValue>, itemScope?: string): string {
   const vmRef = itemScope ?? 'vm';
   return Object.entries(props).map(([key, value]) => {
@@ -473,6 +489,21 @@ function isVocabulary(name: string, map: ReactElementMap, allowlistExtra: string
   return name in map.elements && !allowlistExtra.includes(name);
 }
 
+export function collectViewRefComponents(node: IrNode, names: Set<string>): void {
+  if (node.kind === 'viewRef') {
+    names.add(node.name);
+    return;
+  }
+  if (node.kind === 'component') {
+    for (const child of node.children) collectViewRefComponents(child, names);
+    return;
+  }
+  if (node.kind === 'map') collectViewRefComponents(node.body, names);
+  if (node.kind === 'fragment') {
+    for (const child of node.children) collectViewRefComponents(child, names);
+  }
+}
+
 export function collectExtensionComponents(
   node: IrNode,
   map: ReactElementMap,
@@ -493,12 +524,18 @@ export function collectExtensionComponents(
 export function createNodeRenderer(
   map: ReactElementMap,
   allowlistExtra: string[],
-): NodeRenderer {
+): (node: IrComponentNode, level: number, itemScope?: string) => string {
   const renderNested: NodeRenderer = (node, level, itemScope) => {
+    if (node.kind === 'viewRef') {
+      return renderViewRefElement(node, level, itemScope);
+    }
+    if (node.kind !== 'component') {
+      return '';
+    }
     if (isVocabulary(node.name, map, allowlistExtra)) {
       return lowerVocabularyElement(node, map.elements[node.name]!, level, itemScope, renderNested);
     }
     return renderExtensionElement(node, level, itemScope, renderNested);
   };
-  return renderNested;
+  return (node, level, itemScope) => renderNested(node, level, itemScope);
 }

package/renderers/react/renderComponents.ts

@@ -1,6 +1,12 @@
 import type { ViewIrDocument } from '../../src/ir/types.js';
+import { resolve } from 'node:path';
 import { loadReactElementMap } from './elementMap.js';
-import { collectExtensionComponents, createNodeRenderer } from './lowering/lowerToJsx.js';
+import {
+  collectExtensionComponents,
+  collectViewRefComponents,
+  createNodeRenderer,
+} from './lowering/lowerToJsx.js';
+import type { IrComponentNode, IrNode } from '../../src/ir/types.js';
 
 export interface PreviewImportSpecifiers {
   dispatch: string;
@@ -16,22 +22,65 @@ export interface RenderReactOptions {
   allowlistExtra?: string[];
   elementMapPath?: string;
   previewImports?: PreviewImportSpecifiers;
+  /** When set, viewRef nodes import from these paths instead of sibling .generated.js files. */
+  viewRefImportFrom?: Map<string, string>;
+  /** When true, omit viewRef import lines (partials defined in the same module). */
+  inlineViewRefs?: boolean;
   /** @deprecated Use runtimeImportFrom */
   componentsImportFrom?: string;
 }
 
-export async function renderReactComponent(
+function componentExportName(doc: ViewIrDocument): string {
+  if (doc.isPartial) return doc.exportName;
+  const baseName = doc.exportName.replace(/View$/, '') || doc.exportName;
+  return baseName.charAt(0).toUpperCase() + baseName.slice(1);
+}
+
+function requireComponentRoot(root: IrNode, source: string): IrComponentNode {
+  if (root.kind !== 'component') {
+    throw new Error(`View IR root must be a component node (${source})`);
+  }
+  return root;
+}
+
+function extractContractTypeNames(propsType: string | undefined): string[] {
+  if (!propsType) return [];
+  const matches = propsType.match(/\b[A-Z][A-Za-z0-9]*ViewModel\b/g);
+  return matches ? [...new Set(matches)] : [];
+}
+
+function partialFunctionParams(doc: ViewIrDocument): string {
+  if (!doc.propsType) return '';
+  const match = doc.propsType.match(/^\{\s*([^}]+)\s*\}$/);
+  if (!match) return `props: ${doc.propsType}`;
+  const inner = match[1].trim();
+  const propNames = inner.split(',').map((part) => part.split(':')[0]!.trim());
+  return `{ ${propNames.join(', ')} }: ${doc.propsType}`;
+}
+
+/** Root-level `{cond ? ...}` from visibilityGuard is invalid inside `return (...)` — wrap in fragment. */
+function formatComponentReturn(body: string): string {
+  const trimmed = body.trimStart();
+  if (trimmed.startsWith('{')) {
+    return `return (\n    <>${body}\n    </>\n  );`;
+  }
+  return `return (\n${body}\n  );`;
+}
+
+function stripModulePreamble(source: string): string {
+  let rest = source.replace(/^\/\*\*[\s\S]*?\*\/\s*/, '');
+  rest = rest.replace(/^import\s[^\n]+\n/gm, '');
+  return rest.trimStart();
+}
+
+async function buildRenderedModule(
   doc: ViewIrDocument,
   options: RenderReactOptions,
 ): Promise<string> {
   const map = await loadReactElementMap(options.elementMapPath);
   const allowlistExtra = options.allowlistExtra ?? [];
-  const baseName = doc.exportName.replace(/View$/, '') || doc.exportName;
-  const componentName = baseName.charAt(0).toUpperCase() + baseName.slice(1);
-  const root = doc.root.kind === 'component' ? doc.root : null;
-  if (!root) {
-    throw new Error(`View IR root must be a component node (${doc.source})`);
-  }
+  const componentName = componentExportName(doc);
+  const root = requireComponentRoot(doc.root, doc.source);
 
   const renderNode = createNodeRenderer(map, allowlistExtra);
   const body = renderNode(root, 2);
@@ -40,34 +89,76 @@ export async function renderReactComponent(
   collectExtensionComponents(doc.root, map, allowlistExtra, extensions);
   const extensionImports = [...extensions].sort();
 
+  const viewRefs = new Set<string>();
+  collectViewRefComponents(doc.root, viewRefs);
+  const viewRefImports = [...viewRefs].sort();
+
   const preview = options.previewImports;
   const runtimeModule = preview?.dispatch ?? options.runtimeImportFrom;
   const contractsModule = preview?.contracts ?? options.contractsImportFrom;
   const extensionsModule = preview?.extensions ?? options.extensionsImportFrom;
 
-  const imports: string[] = [`import type { ReactElement } from 'react';`];
+  const contractTypes = new Set<string>();
+  if (doc.isPartial) {
+    for (const typeName of extractContractTypeNames(doc.propsType)) {
+      contractTypes.add(typeName);
+    }
+  } else {
+    contractTypes.add(doc.viewModel);
+  }
 
+  const imports: string[] = [`import type { ReactElement } from 'react';`];
   imports.push(`import { dispatchAction } from '${runtimeModule}';`);
-  imports.push(`import type { ${doc.viewModel}, ActionDescriptor } from '${contractsModule}';`);
+
+  const typeImports = [...contractTypes].sort();
+  const typeImportList = typeImports.length > 0
+    ? `${typeImports.join(', ')}, ActionDescriptor`
+    : 'ActionDescriptor';
+  imports.push(`import type { ${typeImportList} } from '${contractsModule}';`);
+
   if (extensionImports.length > 0) {
     imports.push(`import { ${extensionImports.join(', ')} } from '${extensionsModule}';`);
   }
 
+  for (const refName of viewRefImports) {
+    if (options.inlineViewRefs) continue;
+    const importFrom = options.viewRefImportFrom?.get(refName)
+      ?? `./${refName}.generated.js`;
+    imports.push(`import { ${refName} } from '${importFrom}';`);
+  }
+
   const headerComment = preview
     ? `/**\n * Preview module — compiled live from ${doc.source}\n * Same lowering as generated/; not written to disk.\n */`
     : `/**\n * Auto-generated React component from ${doc.source}\n * DO NOT EDIT — regenerate with: view-contracts render react\n */`;
 
+  if (doc.isPartial) {
+    const fnParams = partialFunctionParams(doc);
+
+    return `${headerComment}
+${imports.join('\n')}
+
+export function ${componentName}(${fnParams}): ReactElement {
+  ${formatComponentReturn(body)}
+}
+`;
+  }
+
   return `${headerComment}
 ${imports.join('\n')}
 
 export function ${componentName}({ vm }: { vm: ${doc.viewModel} }): ReactElement {
-  return (
-${body}
-  );
+  ${formatComponentReturn(body)}
 }
 `;
 }
 
+export async function renderReactComponent(
+  doc: ViewIrDocument,
+  options: RenderReactOptions,
+): Promise<string> {
+  return buildRenderedModule(doc, options);
+}
+
 export async function renderReactFromIr(
   doc: ViewIrDocument,
   outputPath: string,
@@ -75,7 +166,71 @@ export async function renderReactFromIr(
 ): Promise<void> {
   const { writeFile, mkdir } = await import('node:fs/promises');
   const { dirname } = await import('node:path');
-  const content = await renderReactComponent(doc, options);
+  const content = await buildRenderedModule(doc, options);
   await mkdir(dirname(outputPath), { recursive: true });
   await writeFile(outputPath, content, 'utf-8');
 }
+
+/** Render screen + partial modules for preview (single file, no cross-imports). */
+export async function renderReactPreviewBundle(
+  screen: ViewIrDocument,
+  partials: ViewIrDocument[],
+  options: RenderReactOptions,
+): Promise<string> {
+  const inlineOptions: RenderReactOptions = { ...options, inlineViewRefs: true };
+
+  const partialModules = await Promise.all(
+    partials.map((partial) => renderReactComponent(partial, inlineOptions)),
+  );
+  const screenModule = await renderReactComponent(screen, inlineOptions);
+
+  const stripImports = stripModulePreamble;
+
+  const map = await loadReactElementMap(options.elementMapPath);
+  const allowlistExtra = options.allowlistExtra ?? [];
+  const extensions = new Set<string>();
+  collectExtensionComponents(screen.root, map, allowlistExtra, extensions);
+  for (const partial of partials) {
+    collectExtensionComponents(partial.root, map, allowlistExtra, extensions);
+  }
+
+  const preview = options.previewImports;
+  const runtimeModule = preview?.dispatch ?? options.runtimeImportFrom;
+  const contractsModule = preview?.contracts ?? options.contractsImportFrom;
+  const extensionsModule = preview?.extensions ?? options.extensionsImportFrom;
+
+  const contractTypes = new Set<string>([screen.viewModel]);
+  for (const partial of partials) {
+    for (const typeName of extractContractTypeNames(partial.propsType)) {
+      contractTypes.add(typeName);
+    }
+  }
+
+  const imports: string[] = [
+    `import type { ReactElement } from 'react';`,
+    `import { dispatchAction } from '${runtimeModule}';`,
+    `import type { ${[...contractTypes].sort().join(', ')}, ActionDescriptor } from '${contractsModule}';`,
+  ];
+  const extensionImports = [...extensions].sort();
+  if (extensionImports.length > 0) {
+    imports.push(`import { ${extensionImports.join(', ')} } from '${extensionsModule}';`);
+  }
+
+  const headerComment = preview
+    ? `/**\n * Preview module — compiled live from ${screen.source}\n * Same lowering as generated/; not written to disk.\n */`
+    : '';
+
+  const partialBodies = partialModules.map(stripImports);
+  const screenBody = stripImports(screenModule);
+
+  return `${headerComment}
+${imports.join('\n')}
+
+${partialBodies.join('\n\n')}
+
+${screenBody}`;
+}
+
+export function partialReactOutputPath(reactDir: string, partial: ViewIrDocument): string {
+  return resolve(reactDir, 'components', `${partial.exportName}.generated.tsx`);
+}