view-contracts 0.1.0 → 0.2.0

package/renderers/react/renderComponents.ts

@@ -0,0 +1,65 @@
+import type { ViewIrDocument } from '../../src/ir/types.js';
+import { loadReactElementMap } from './elementMap.js';
+import { collectExtensionComponents, createNodeRenderer } from './lowering/lowerToJsx.js';
+
+export interface RenderReactOptions {
+  componentsImportFrom: string;
+  allowlistExtra?: string[];
+  elementMapPath?: string;
+}
+
+export async function renderReactComponent(
+  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 renderNode = createNodeRenderer(map, allowlistExtra);
+  const body = renderNode(root, 2);
+
+  const extensions = new Set<string>();
+  collectExtensionComponents(doc.root, map, allowlistExtra, extensions);
+  const extensionImports = [...extensions].sort();
+
+  const imports: string[] = [
+    `import type { ReactElement } from 'react';`,
+    `import { dispatchAction } from '../runtime/dispatch.js';`,
+    `import { commonStyle, mapAlign, mapJustify } from '../components/style-helpers.js';`,
+    `import type { ${doc.viewModel}, ActionDescriptor } from '../contracts';`,
+  ];
+  if (extensionImports.length > 0) {
+    imports.push(`import { ${extensionImports.join(', ')} } from '${options.componentsImportFrom}';`);
+  }
+
+  return `/**
+ * Auto-generated React component from ${doc.source}
+ * DO NOT EDIT — regenerate with: view-contracts render react
+ */
+${imports.join('\n')}
+
+export function ${componentName}({ vm }: { vm: ${doc.viewModel} }): ReactElement {
+  return (
+${body}
+  );
+}
+`;
+}
+
+export async function renderReactFromIr(
+  doc: ViewIrDocument,
+  outputPath: string,
+  options: RenderReactOptions,
+): Promise<void> {
+  const { writeFile, mkdir } = await import('node:fs/promises');
+  const { dirname } = await import('node:path');
+  const content = await renderReactComponent(doc, options);
+  await mkdir(dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, content, 'utf-8');
+}

package/renderers/react/renderRuntime.ts

@@ -0,0 +1,134 @@
+import { readFile, writeFile, mkdir, stat, cp, unlink } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { ViewContractsConfig } from '../../src/config.js';
+import { projectRoot } from '../../src/config.js';
+import { loadThemeCss } from '../../src/catalog/loadThemeCss.js';
+import { packageRoot } from '../../src/lib/packageRoot.js';
+import { renderTemplate } from '../../src/renderer/template.js';
+import { reactRuntimeDir, reactTemplatesDir } from './paths.js';
+
+const toolchainRoot = packageRoot();
+
+function toolchainSchemaDir(): string {
+  return resolve(toolchainRoot, 'src/generated/schema');
+}
+
+async function pathExists(target: string): Promise<boolean> {
+  try {
+    await stat(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function rewriteSchemaImports(content: string): string {
+  return content.split('../../../src/generated/schema/').join('./schema/');
+}
+
+async function copySchemaBundle(componentsDir: string): Promise<void> {
+  const schemaSrc = toolchainSchemaDir();
+  if (!(await pathExists(schemaSrc))) return;
+
+  const schemaDest = resolve(componentsDir, 'schema');
+  await cp(schemaSrc, schemaDest, { recursive: true });
+  for (const name of ['dsl-properties.ts', 'tokens.ts', 'schema-document.ts', 'index.ts'] as const) {
+    const file = resolve(schemaDest, name);
+    if (await pathExists(file)) {
+      await writeFile(file, rewriteSchemaImports(await readFile(file, 'utf-8')), 'utf-8');
+    }
+  }
+}
+
+async function copyStyleBundle(componentsDir: string): Promise<void> {
+  const runtimeSrc = reactRuntimeDir();
+  const style = rewriteSchemaImports(await readFile(resolve(runtimeSrc, 'style.ts'), 'utf-8'));
+  await writeFile(resolve(componentsDir, 'style.ts'), style, 'utf-8');
+
+  const types = rewriteSchemaImports(await readFile(resolve(runtimeSrc, 'types.ts'), 'utf-8'));
+  await writeFile(resolve(componentsDir, 'types.ts'), types, 'utf-8');
+}
+
+async function writeThemeCss(root: string, themeOut: string, templatesDir?: string): Promise<void> {
+  const runtimeTheme = resolve(reactRuntimeDir(), 'theme.css');
+  let css = await loadThemeCss(runtimeTheme);
+  const extensionsCss = resolve(root, 'src/theme.extensions.css');
+  if (await pathExists(extensionsCss)) {
+    css += `\n\n${await readFile(extensionsCss, 'utf-8')}`;
+  }
+  const content = await renderTemplate(reactTemplatesDir(templatesDir), 'theme.css.hbs', { themeCss: css });
+  await writeFile(themeOut, content, 'utf-8');
+}
+
+async function removeStaleGeneratedFiles(componentsDir: string): Promise<void> {
+  for (const name of ['ui-components.tsx', 'core.ts', 'actionRuntime.ts', 'shared.tsx', 'shared.ts'] as const) {
+    const target = resolve(componentsDir, name);
+    if (await pathExists(target)) {
+      await unlink(target);
+    }
+  }
+}
+
+/** Emit standalone generated runtime (no preview vocabulary copy; no @view-contracts imports). */
+export async function renderReactRuntime(configPath: string, config: ViewContractsConfig): Promise<void> {
+  const root = projectRoot(configPath);
+  const templatesDir = config.rendererTemplatesDir
+    ? resolve(root, config.rendererTemplatesDir)
+    : undefined;
+  const templates = reactTemplatesDir(templatesDir);
+  const componentsDir = resolve(config.generated.reactDir, '../components');
+  const runtimeDir = resolve(config.generated.reactDir, '../runtime');
+  const srcComponentsDir = resolve(root, 'src/components');
+
+  await mkdir(componentsDir, { recursive: true });
+  await mkdir(runtimeDir, { recursive: true });
+
+  await removeStaleGeneratedFiles(componentsDir);
+  await copySchemaBundle(componentsDir);
+  await copyStyleBundle(componentsDir);
+  await writeFile(
+    resolve(componentsDir, 'style-helpers.ts'),
+    await renderTemplate(templates, 'style-helpers.ts.hbs', {}),
+    'utf-8',
+  );
+  await writeFile(
+    resolve(componentsDir, 'index.ts'),
+    await renderTemplate(templates, 'components-index.ts.hbs', {}),
+    'utf-8',
+  );
+
+  for (const name of ['extensions.tsx', 'sample-types.ts'] as const) {
+    const src = resolve(srcComponentsDir, name);
+    let body = await readFile(src, 'utf-8');
+    if (name === 'sample-types.ts') {
+      body = body.replace("from './core.js'", "from './types.js'");
+    }
+    await writeFile(resolve(componentsDir, name), body, 'utf-8');
+  }
+
+  const handlersSrc = resolve(root, 'src/runtime/handlers.ts');
+  const handlersBody = (await readFile(handlersSrc, 'utf-8')).replace(
+    /export async function handleAppAction\(action:\s*\{[\s\S]*?\}\)/,
+    'export async function handleAppAction(action: DispatchableAction)',
+  );
+  await writeFile(
+    resolve(runtimeDir, 'handlers.ts'),
+    await renderTemplate(templates, 'handlers.ts.hbs', { handlersBody }),
+    'utf-8',
+  );
+
+  await writeThemeCss(root, resolve(config.generated.reactDir, '../theme.css'), templatesDir);
+  await writeFile(
+    resolve(runtimeDir, 'types.ts'),
+    await renderTemplate(templates, 'runtime-types.ts.hbs', {}),
+    'utf-8',
+  );
+  await writeFile(
+    resolve(runtimeDir, 'dispatch.ts'),
+    await renderTemplate(templates, 'dispatch.ts.hbs', {}),
+    'utf-8',
+  );
+
+  console.log(`  components → ${componentsDir}`);
+  console.log(`  theme → ${resolve(config.generated.reactDir, '../theme.css')}`);
+}

package/renderers/react/routes.yaml

@@ -2,9 +2,10 @@
 # Vocabulary: spec/ui-dsl.schema.json. Per-target maps: renderers/{target}/elements.yaml
 
 react:
-  description: Production / preview React components via project componentsModule
-  importFrom: '@view-contracts/components'
+  description: Production React via compile-time IR lowering + template-emitted runtime
+  importFrom: '../components/index.js'
   themeCss: theme.css
+  templates: renderers/react/templates
   outputs:
     screen:
       pattern: '{{projectRoot}}/generated/react/{{screenName}}.generated.tsx'

package/{src/renderer → renderers}/react/runtime/actionRuntime.ts

@@ -1,5 +1,5 @@
-import type { ViewAction } from '@view-contracts/core';
-import { dispatchAction } from '@view-contracts/runtime';
+import type { DispatchableAction } from './types.js';
+import { dispatchAction } from './dispatch.js';
 
 const globalHandlers: Record<string, (params?: unknown) => void | Promise<void>> = {};
 
@@ -15,7 +15,7 @@ export function clearPreviewActions(): void {
   }
 }
 
-export async function dispatchPreviewAction(action?: ViewAction): Promise<void> {
+export async function dispatchPreviewAction(action?: DispatchableAction): Promise<void> {
   if (!action) return;
   const handler = globalHandlers[action.name];
   if (handler) {

package/renderers/react/runtime/dispatch.ts

@@ -0,0 +1,21 @@
+import type { DispatchableAction } from './types.js';
+
+type ActionHandler = (action: DispatchableAction) => void | Promise<void>;
+
+let handler: ActionHandler | undefined;
+
+export function registerActionHandler(nextHandler: ActionHandler): void {
+  handler = nextHandler;
+}
+
+export async function dispatchAction(action: DispatchableAction): Promise<void> {
+  if (handler) {
+    await handler(action);
+    return;
+  }
+  if (action.name === 'navigate' && typeof action.params?.to === 'string') {
+    window.location.href = action.params.to;
+    return;
+  }
+  window.dispatchEvent(new CustomEvent('view-contracts:action', { detail: action }));
+}

package/renderers/react/runtime/index.ts

@@ -0,0 +1,5 @@
+/** Preview/toolchain React runtime primitives — not copied to generated/. */
+export * from './types.js';
+export { commonStyle, isHidden, toneClass, mapAlign, mapJustify } from './style.js';
+export { registerPreviewActions, clearPreviewActions, dispatchPreviewAction } from './actionRuntime.js';
+export { registerActionHandler, dispatchAction } from './dispatch.js';

package/{src/renderer → renderers}/react/runtime/style.ts

@@ -1,6 +1,23 @@
 import type { CSSProperties } from 'react';
-import type { Clip, ContentAlign, Shadow } from '../../../generated/schema/tokens.js';
-import type { DslProperties } from '../../../generated/schema/dsl-properties.js';
+import type { Align, Clip, ContentAlign, FontWeight, Justify, Shadow } from '../../../src/generated/schema/tokens.js';
+import type { CommonProps } from './types.js';
+
+export function mapAlign(value?: Align): string | undefined {
+  if (!value) return undefined;
+  if (value === 'start') return 'flex-start';
+  if (value === 'end') return 'flex-end';
+  return value;
+}
+
+export function mapJustify(value?: Justify | string): string | undefined {
+  if (!value) return undefined;
+  if (value === 'start') return 'flex-start';
+  if (value === 'end') return 'flex-end';
+  if (value === 'between' || value === 'spaceBetween') return 'space-between';
+  if (value === 'around' || value === 'spaceAround') return 'space-around';
+  if (value === 'spaceEvenly') return 'space-evenly';
+  return value;
+}
 
 function len(value: number): string {
   return `${value}px`;
@@ -24,12 +41,18 @@ const CONTENT_ALIGN: Record<ContentAlign, string> = {
   bottomEnd: 'end end',
 };
 
-function shadowStyle(shadow: Shadow | undefined): string | undefined {
+function shadowStyle(shadow: Shadow | boolean | undefined): string | undefined {
+  if (shadow === true) return SHADOW.md;
   if (!shadow || shadow === 'none') return undefined;
   return SHADOW[shadow];
 }
 
-export function commonStyle(props: DslProperties): CSSProperties {
+function fontSizeStyle(size: number | string | undefined): string | undefined {
+  if (size === undefined) return undefined;
+  return typeof size === 'number' ? len(size) : size;
+}
+
+export function commonStyle(props: CommonProps): CSSProperties {
   const style: CSSProperties = {};
   if (typeof props.width === 'number') style.width = len(props.width);
   if (typeof props.minWidth === 'number') style.minWidth = len(props.minWidth);
@@ -38,9 +61,9 @@ export function commonStyle(props: DslProperties): CSSProperties {
   if (typeof props.minHeight === 'number') style.minHeight = len(props.minHeight);
   if (typeof props.maxHeight === 'number') style.maxHeight = len(props.maxHeight);
   if (props.aspectRatio !== undefined) style.aspectRatio = String(props.aspectRatio);
-  if (props.weight !== undefined) style.flexGrow = props.weight;
+  if (typeof props.weight === 'number') style.flexGrow = props.weight;
   if (typeof props.padding === 'number') style.padding = len(props.padding);
-  if (typeof props.margin === 'number') style.margin = len(props.margin);
+  if (typeof (props as { margin?: number }).margin === 'number') style.margin = len((props as { margin: number }).margin);
   if (typeof props.gap === 'number') style.gap = len(props.gap);
   if (typeof props.radius === 'number') style.borderRadius = len(props.radius);
   if (props.border) style.border = '1px solid var(--ui-border)';
@@ -52,12 +75,16 @@ export function commonStyle(props: DslProperties): CSSProperties {
   if (props.foreground) style.color = `var(--ui-${props.foreground}, ${props.foreground})`;
   if (props.textAlign) style.textAlign = props.textAlign === 'start' ? 'left' : props.textAlign === 'end' ? 'right' : 'center';
   if (props.contentAlign) style.placeItems = CONTENT_ALIGN[props.contentAlign];
-  if (props.overflow) style.overflow = props.overflow;
+  if ((props as { overflow?: string }).overflow) style.overflow = (props as { overflow: string }).overflow;
   if (props.selfAlign) style.alignSelf = props.selfAlign === 'start' ? 'flex-start' : props.selfAlign === 'end' ? 'flex-end' : props.selfAlign;
+  const fontSize = fontSizeStyle(props.size);
+  if (fontSize) style.fontSize = fontSize;
+  const fontWeight = typeof props.weight === 'string' ? props.weight : props.fontWeight;
+  if (fontWeight) style.fontWeight = fontWeight as FontWeight;
   return style;
 }
 
-export function isHidden(props: DslProperties): boolean {
+export function isHidden(props: CommonProps): boolean {
   return props.visible === false;
 }
 

package/renderers/react/runtime/types.ts

@@ -0,0 +1,63 @@
+import type { ReactNode } from 'react';
+import type { DslProperties } from '../../../src/generated/schema/dsl-properties.js';
+import type { FontWeight, Justify, Shadow, WidthSize } from '../../../src/generated/schema/tokens.js';
+
+export type {
+  Align,
+  Axis,
+  Border,
+  Clip,
+  ContentAlign,
+  Direction,
+  FontWeight,
+  HeightSize,
+  ImageFit,
+  Justify,
+  KeyboardType,
+  LineLimit,
+  TextAlign,
+  TextOverflow,
+  WidthSize,
+} from '../../../src/generated/schema/tokens.js';
+
+export type { DslProperties };
+
+export interface ViewAction {
+  name: string;
+  params?: Record<string, unknown>;
+}
+
+export type DispatchableAction = ViewAction;
+
+/** view-contracts view TSX action binding (schema property: onClick / onChange). */
+export type Action = ViewAction;
+
+/**
+ * Preview + sample extension props layered on the DSL catalog.
+ * Widens a few catalog types so sample views can use pragmatic literals (e.g. radius={16}, justify="between").
+ */
+export interface CommonProps extends Omit<DslProperties, 'justify' | 'radius' | 'shadow' | 'width' | 'weight' | 'fontWeight'> {
+  children?: ReactNode;
+  /** View-layer alias for onClick in interactive components. */
+  action?: ViewAction;
+  justify?: Justify | 'between' | 'around';
+  radius?: string | number;
+  shadow?: Shadow | boolean;
+  width?: WidthSize | number;
+  /** Flex grow (number) or sample font weight alias (string) on Text. */
+  weight?: number | string;
+  fontWeight?: FontWeight | string;
+  /** Sample/preview extension props (not in ui-dsl.schema.json). */
+  tone?: string;
+  size?: number | string;
+  ariaLabel?: string;
+  testId?: string;
+}
+
+export interface Option {
+  label: string;
+  value: string;
+}
+
+/** Preview-only field density (not in ui-dsl.schema.json). */
+export type FieldSize = 'sm' | 'md' | 'lg';

package/renderers/react/templates/components-index.ts.hbs

@@ -0,0 +1,5 @@
+/** Auto-generated component barrel — DO NOT EDIT */
+export * from './extensions.js';
+export type { TableColumn } from './extensions.js';
+export { commonStyle, mapAlign, mapJustify, isHidden, toneClass } from './style.js';
+export type { Action, CommonProps, Option } from './types.js';

package/renderers/react/templates/dispatch.ts.hbs

@@ -0,0 +1,22 @@
+/** Auto-generated runtime dispatcher — DO NOT EDIT */
+import type { DispatchableAction } from './types.js';
+
+type ActionHandler = (action: DispatchableAction) => void | Promise<void>;
+
+let handler: ActionHandler | undefined;
+
+export function registerActionHandler(nextHandler: ActionHandler): void {
+  handler = nextHandler;
+}
+
+export async function dispatchAction(action: DispatchableAction): Promise<void> {
+  if (handler) {
+    await handler(action);
+    return;
+  }
+  if (action.name === 'navigate' && typeof action.params?.to === 'string') {
+    window.location.href = action.params.to;
+    return;
+  }
+  window.dispatchEvent(new CustomEvent('view-contracts:action', { detail: action }));
+}

package/renderers/react/templates/handlers.ts.hbs

@@ -0,0 +1,4 @@
+/** Auto-generated from src/runtime/handlers.ts — DO NOT EDIT */
+import type { DispatchableAction } from './types.js';
+
+{{{handlersBody}}}

package/renderers/react/templates/runtime-types.ts.hbs

@@ -0,0 +1,5 @@
+/** Auto-generated — DO NOT EDIT */
+export interface DispatchableAction {
+  name: string;
+  params?: Record<string, unknown>;
+}

package/renderers/react/templates/style-helpers.ts.hbs

@@ -0,0 +1,2 @@
+/** Auto-generated style helpers for lowered JSX — DO NOT EDIT */
+export { commonStyle, mapAlign, mapJustify } from './style.js';

package/renderers/react/templates/theme.css.hbs

@@ -0,0 +1,2 @@
+/** Auto-generated theme — DO NOT EDIT */
+{{{themeCss}}}

package/src/generated/schema/lowering-style-properties.ts

@@ -0,0 +1,36 @@
+/** Auto-generated from spec/ui-dsl.schema.json — view-contracts v0.1.0 — DO NOT EDIT */
+/** Property names passed to commonStyle() during React HTML lowering (x-category from DSL + sample extensions). */
+export const LOWERING_STYLE_PROPERTIES = new Set<string>([
+  "align",
+  "aspectRatio",
+  "axis",
+  "background",
+  "border",
+  "clip",
+  "contentAlign",
+  "direction",
+  "fontWeight",
+  "foreground",
+  "gap",
+  "headingLevel",
+  "height",
+  "justify",
+  "lineLimit",
+  "maxHeight",
+  "maxWidth",
+  "minHeight",
+  "minWidth",
+  "opacity",
+  "padding",
+  "radius",
+  "scroll",
+  "selfAlign",
+  "shadow",
+  "textAlign",
+  "textOverflow",
+  "textStyle",
+  "variant",
+  "weight",
+  "width",
+  "size",
+]);

package/src/generated/schema/react-renderer-element-config.ts

@@ -0,0 +1,26 @@
+/** Auto-generated from renderers/react/element-config.meta.json — view-contracts v0.1.0 — DO NOT EDIT */
+/** Shape of entries in renderers/react/elements.yaml (target-specific HTML map, not DSL vocabulary). */
+export interface ReactRendererElementConfig {
+  tag: string;
+  className?: string;
+  ariaLabel?: boolean;
+  ariaHidden?: boolean;
+  flex?: "row" | "column";
+  wrapProp?: string;
+  flexGrowProp?: string;
+  void?: boolean;
+  levelProp?: string;
+  defaultLevel?: number;
+  actionEvent?: "onClick" | "onSubmit";
+  variantClass?: boolean;
+  fieldWrap?: boolean;
+  inputType?: string;
+  sizeClass?: string;
+  optionsProp?: string;
+  checkbox?: boolean;
+  defaultRole?: string;
+}
+
+export interface ReactElementMapFile {
+  elements: Record<string, ReactRendererElementConfig>;
+}