view-contracts 0.5.7 → 0.5.9

package/dist/types/src/dsl/index.d.ts

@@ -0,0 +1,2 @@
+export { screen, view } from './screen.js';
+export type { ViewAction, ActionHandlers, ScreenContext, ViewContract, ViewPartial, ViewScreenProps, CommonProps, Option, Tone, Align, Justify, ButtonVariant, FieldSize, } from './types.js';

package/dist/types/src/dsl/screen.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+import type { FC } from 'react';
+import type { ScreenContext, ViewPartial, ViewScreenProps } from './types.js';
+export type { ViewAction, ActionHandlers, ScreenContext, ViewContract, ViewPartial, ViewScreenProps, CommonProps, Option, Tone, Align, Justify, ButtonVariant, FieldSize, } from './types.js';
+/**
+ * Wrap a restricted view-contract TSX definition.
+ *
+ * - **Preview runtime**: returns a React component (`vm` + `actions` props).
+ * - **Compiler**: statically extracts JSX from the render callback → View IR.
+ */
+export declare function screen<TViewModel>(render: (ctx: ScreenContext<TViewModel>) => ReactNode): FC<ViewScreenProps<TViewModel>>;
+/**
+ * Reusable view-contract sub-component (composable inside screen() or other view()).
+ *
+ * Compiled by inlining into the parent View IR; preview runtime renders as a normal React FC.
+ */
+export declare function view<TProps>(render: (props: TProps) => ReactNode): FC<TProps> & ViewPartial<TProps>;

package/dist/types/src/dsl/types.d.ts

@@ -0,0 +1,59 @@
+import type { ReactNode } from 'react';
+/** Action descriptor referenced from view contracts (names must match OpenAPI operationId). */
+export interface ViewAction {
+    name: string;
+    params?: Record<string, unknown>;
+}
+export type ActionHandlers = Record<string, (params?: unknown) => void | Promise<void>>;
+export interface ScreenContext<TViewModel> {
+    vm: TViewModel;
+    actions: ActionHandlers;
+}
+export interface ViewContract<TViewModel> {
+    readonly __viewContract: true;
+    readonly render: (ctx: ScreenContext<TViewModel>) => ReactNode;
+}
+export type Tone = 'default' | 'muted' | 'primary' | 'success' | 'warning' | 'danger';
+export type Align = 'start' | 'center' | 'end' | 'stretch';
+export type Justify = 'start' | 'center' | 'end' | 'between' | 'around';
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
+export type FieldSize = 'sm' | 'md' | 'lg';
+/**
+ * Shared layout/visual props.
+ * Dimension props (width, height, gap, padding, …) are numbers in logical units;
+ * the web preview maps them to px.
+ */
+export interface CommonProps {
+    id?: string;
+    testId?: string;
+    ariaLabel?: string;
+    children?: ReactNode;
+    hidden?: boolean;
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    height?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    padding?: number;
+    margin?: number;
+    gap?: number;
+    radius?: number;
+    border?: boolean;
+    shadow?: boolean;
+    tone?: Tone;
+}
+export interface Option {
+    label: string;
+    value: string;
+}
+export interface ViewPartial<TProps> {
+    readonly __viewPartial: true;
+    readonly render: (props: TProps) => ReactNode;
+}
+export type ViewScreenProps<TViewModel> = {
+    vm: TViewModel;
+    actions?: ActionHandlers;
+    /** Optional theme id — propagated from App element for future multi-theme runtime. */
+    theme?: string;
+};

package/dist/types/src/extensions/loadExtensions.d.ts

@@ -0,0 +1,17 @@
+export type ExtensionChildren = 'none' | 'any';
+export type ExtensionRenderer = 'react-only' | 'all';
+export type ExtensionPropertyType = 'string' | 'number' | 'boolean' | 'binding' | 'array' | 'object';
+export interface ExtensionPropertyDefinition {
+    type: ExtensionPropertyType;
+    category: string;
+}
+export interface ExtensionDefinition {
+    description: string;
+    children: ExtensionChildren;
+    renderer: ExtensionRenderer;
+    properties: Record<string, ExtensionPropertyDefinition>;
+}
+export interface ExtensionRegistryDocument {
+    extensions: Record<string, ExtensionDefinition>;
+}
+export declare function loadExtensions(extensionsPath?: string): Promise<ExtensionRegistryDocument>;

package/dist/types/src/extensions/validateExtensionUsage.d.ts

@@ -0,0 +1,18 @@
+import type { IrNode } from '../ir/types.js';
+import type { ExtensionRegistryDocument } from './loadExtensions.js';
+export interface ExtensionUsageValidationResult {
+    errors: string[];
+    warnings: string[];
+}
+export interface ExtensionUsageValidationOptions {
+    /** Binding targets from view-bindings.yaml (e.g. react, swiftui, compose). */
+    targets?: string[];
+    /** View or partial source path for error messages. */
+    source?: string;
+}
+export declare function validateExtensionUsage(node: IrNode, registry: ExtensionRegistryDocument, options?: ExtensionUsageValidationOptions): ExtensionUsageValidationResult;
+/** Validate extension usage for a screen and its reachable partial IR roots. */
+export declare function validateExtensionUsageForView(screen: IrNode, partialRoots: IrNode[], registry: ExtensionRegistryDocument, targets: string[], sources: {
+    screen: string;
+    partials: string[];
+}): ExtensionUsageValidationResult;

package/dist/types/src/generated/cli/contract.d.ts

@@ -0,0 +1,2 @@
+export declare const CONTRACT_YAML: string;
+export declare const CONTRACT_JSON_STR: string;

package/dist/types/src/generated/cli/program.d.ts

@@ -0,0 +1,28 @@
+import { Command } from "commander";
+export interface CommandHandlers {
+    compile: (options: {
+        config?: string;
+    }, parentOpts: Record<string, unknown>) => Promise<void>;
+    renderReact: (options: {
+        config?: string;
+    }, parentOpts: Record<string, unknown>) => Promise<void>;
+    renderBridge: (options: {
+        config?: string;
+    }, parentOpts: Record<string, unknown>) => Promise<void>;
+    build: (options: {
+        config?: string;
+    }, parentOpts: Record<string, unknown>) => Promise<void>;
+    contractsGenerate: (options: {
+        config?: string;
+    }, parentOpts: Record<string, unknown>) => Promise<void>;
+    contractsCheck: (options: {
+        config?: string;
+    }, parentOpts: Record<string, unknown>) => Promise<void>;
+    preview: (options: {
+        config?: string;
+        port?: string;
+        host?: string;
+        screen?: string;
+    }, parentOpts: Record<string, unknown>) => Promise<void>;
+}
+export declare function createProgram(handlers: CommandHandlers, version: string): Command;

package/dist/types/src/ir/collectViewRefs.d.ts

@@ -0,0 +1,3 @@
+import type { IrNode, IrViewRefNode } from './types.js';
+export declare function collectViewRefs(node: IrNode): IrViewRefNode[];
+export declare function viewRefKey(ref: IrViewRefNode): string;

package/dist/types/src/ir/types.d.ts

@@ -0,0 +1,67 @@
+/** Language-neutral View Contract intermediate representation. */
+export interface ViewIrDocument {
+    version: 1;
+    /**
+     * Project-root-relative POSIX path of the .view.tsx this document was compiled from.
+     * Stamped into generated artifacts, so it must not depend on the working directory
+     * the compiler was invoked from.
+     */
+    source: string;
+    viewModel: string;
+    exportName: string;
+    root: IrNode;
+    /** True when this IR document represents a view() partial, not a screen(). */
+    isPartial?: boolean;
+    /** TypeScript props type for partial exports (e.g. "{ items: KpiCardViewModel[] }"). */
+    propsType?: string;
+}
+export type IrNode = IrComponentNode | IrTextNode | IrMapNode | IrFragmentNode | IrBinding | IrViewRefNode;
+export interface IrComponentNode {
+    kind: 'component';
+    name: string;
+    props: Record<string, IrValue>;
+    children: IrNode[];
+}
+export interface IrTextNode {
+    kind: 'text';
+    value: string;
+}
+export interface IrFragmentNode {
+    kind: 'fragment';
+    children: IrNode[];
+}
+/** Reference to a view() partial — preserved instead of inlining at compile time. */
+export interface IrViewRefNode {
+    kind: 'viewRef';
+    name: string;
+    sourcePath: string;
+    props: Record<string, IrValue>;
+}
+export interface IrMapNode {
+    kind: 'map';
+    source: IrBinding;
+    item: string;
+    key?: IrBinding;
+    body: IrNode;
+}
+export type IrValue = string | number | boolean | null | IrBinding | IrAction | IrLiteral | IrConcat | IrValue[];
+export interface IrBinding {
+    kind: 'binding';
+    /** Dot path relative to vm or map item scope (e.g. "title", "projects.rows") */
+    path: string;
+    /** When inside a map callback, names the scope variable (e.g. "item", "row") */
+    scope?: string;
+}
+export interface IrAction {
+    kind: 'action';
+    name: string;
+    params?: Record<string, IrValue>;
+}
+export interface IrLiteral {
+    kind: 'literal';
+    value: unknown;
+}
+export interface IrConcat {
+    kind: 'concat';
+    parts: (string | IrBinding)[];
+}

package/dist/types/src/lib/packageRoot.d.ts

@@ -0,0 +1,2 @@
+/** Installed package root (directory containing package.json). */
+export declare function packageRoot(): string;

package/dist/types/src/lib/projectPath.d.ts

@@ -0,0 +1,2 @@
+/** Project-relative POSIX path for generated artifacts (no absolute paths). */
+export declare function relativeProjectPath(projectDir: string, absolutePath: string): string;

package/dist/types/src/lib/rendererPaths.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sole src/ module that may import or reference renderers/.
+ * All other src/ code must use loadRendererRegistry() or the path helpers here.
+ */
+export type { RenderReactOptions } from '../../renderers/react/renderComponents.js';
+type RendererRegistry = typeof import('../../renderers/registry.js');
+/** Lazy-load the unified renderer registry (renderers/registry.ts). */
+export declare function loadRendererRegistry(): Promise<RendererRegistry>;
+export declare function reactTemplatesDir(customDir?: string): string;
+export declare function reactRuntimeDir(): string;
+export declare function reactStructuralCssPath(): string;
+export declare function reactElementsYamlPath(): string;
+export declare function isReactElementsYamlFile(filePath: string): boolean;

package/dist/types/src/preview/compileScreen.d.ts

@@ -0,0 +1,15 @@
+export declare const PREVIEW_SCREEN_PREFIX = "view-contracts:screen/";
+export declare const PREVIEW_THEME_ID = "view-contracts:theme.css";
+export declare function previewScreenModuleId(screenName: string): string;
+export declare const PREVIEW_IMPORTS: {
+    readonly dispatch: "view-contracts:runtime/dispatch";
+    readonly style: "view-contracts:runtime/style";
+    readonly types: "view-contracts:runtime/types";
+    readonly styleHelpers: "view-contracts:runtime/style-helpers";
+    readonly contracts: "view-contracts:contracts";
+    readonly extensions: "view-contracts:extensions";
+    readonly mock: "view-contracts:preview/mock";
+};
+export declare function previewMockImport(screenName: string): string;
+/** Compile views/*.view.tsx → lowered React source (same pipeline as build, not written to generated/). */
+export declare function compilePreviewScreen(configPath: string, screenName: string): Promise<string>;

package/dist/types/src/preview/previewAssets.d.ts

@@ -0,0 +1,9 @@
+export interface PreviewAssets {
+    themeCss: string;
+    bundleJs: string;
+    version: number;
+}
+export declare function buildPreviewAssets(configPath: string, screenName: string, version: number): Promise<PreviewAssets & {
+    html: string;
+}>;
+export declare function resolvePreviewScreenName(configPath: string, requested?: string): Promise<string>;

package/dist/types/src/preview/previewMock.d.ts

@@ -0,0 +1,16 @@
+import type { ViewContractsConfig } from '../config.js';
+export declare const PREVIEW_MOCK_PREFIX = "view-contracts:preview/mock/";
+export declare class PreviewMockError extends Error {
+    constructor(message: string);
+}
+export declare function defaultPreviewMocksDir(): string;
+export declare function previewMockModuleId(screenName: string): string;
+export declare function previewMockExportName(screenName: string): string;
+export declare function previewMockFilePath(configPath: string, config: ViewContractsConfig, screenName: string): string;
+export declare function parsePreviewMockDocument(source: unknown, sourceLabel: string): Record<string, unknown>;
+export declare function loadPreviewMockYaml(filePath: string): Promise<Record<string, unknown>>;
+export declare function emitPreviewMockModule(screenName: string, data: Record<string, unknown>): string;
+export declare function buildPreviewMockModule(configPath: string, config: ViewContractsConfig, screenName: string): Promise<string>;
+export declare function isPreviewMockModuleId(id: string): string | null;
+export declare function previewMocksRoot(configPath: string, config: ViewContractsConfig): Promise<string>;
+export declare function pathExists(target: string): Promise<boolean>;

package/dist/types/src/preview/previewMockPlugin.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from 'vite';
+export interface PreviewMockPluginOptions {
+    configPath: string;
+}
+/** Resolve view-contracts:preview/mock/<Screen> from views/preview/*.mock.yaml */
+export declare function viewContractsPreviewMockPlugin(options: PreviewMockPluginOptions): Plugin;

package/dist/types/src/preview/previewServer.d.ts

@@ -0,0 +1,7 @@
+export interface PreviewServerOptions {
+    configPath: string;
+    port?: number;
+    host?: string;
+    screen?: string;
+}
+export declare function runPreviewServer(options: PreviewServerOptions): Promise<void>;

package/dist/types/src/preview/publish.d.ts

@@ -0,0 +1,5 @@
+/** Public npm entry — Vite preview plugins for consumer projects. */
+export { viewContractsPreviewPlugin, previewRuntimeAliases, previewFsAllowPaths, } from './vitePlugin.js';
+export type { ViewContractsPreviewPluginOptions } from './vitePlugin.js';
+export { viewContractsPreviewMockPlugin } from './previewMockPlugin.js';
+export type { PreviewMockPluginOptions } from './previewMockPlugin.js';

package/dist/types/src/preview/vitePlugin.d.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from 'vite';
+export { viewContractsPreviewMockPlugin } from './previewMockPlugin.js';
+export interface ViewContractsPreviewPluginOptions {
+    configPath: string;
+}
+export declare function viewContractsPreviewPlugin(options: ViewContractsPreviewPluginOptions): Plugin;
+/** Vite resolve.alias entries for preview dev (uses installed view-contracts package root). */
+export declare function previewRuntimeAliases(projectRootDir: string): Array<{
+    find: string | RegExp;
+    replacement: string;
+}>;
+/** Paths for vite server.fs.allow — project + installed view-contracts package. */
+export declare function previewFsAllowPaths(viteDir: string, projectRootDir: string): string[];

package/dist/types/src/renderer/bridge.d.ts

@@ -0,0 +1,32 @@
+import type { ViewIrDocument } from '../ir/types.js';
+import type { ViewContractsConfig } from '../config.js';
+import { type RenderReactOptions } from '../lib/rendererPaths.js';
+export type { RenderReactOptions };
+export declare function renderReactFromIr(doc: ViewIrDocument, outputPath: string, options: RenderReactOptions): Promise<void>;
+export declare function renderReactPreviewBundle(screen: ViewIrDocument, partials: ViewIrDocument[], options: RenderReactOptions): Promise<string>;
+export declare function partialReactOutputPath(reactDir: string, partial: ViewIrDocument): string;
+export declare function renderReactRuntime(configPath: string, config: ViewContractsConfig): Promise<void>;
+export declare function renderSwiftUIRuntime(configPath: string, config: ViewContractsConfig, bindings: import('../config.js').ViewBindingsFile, design?: {
+    theme: import('../design/types.js').ThemeIR;
+    tokens: import('../design/types.js').TokenIR;
+}, compiledDocs?: {
+    screens: Map<string, ViewIrDocument>;
+    partials: ViewIrDocument[];
+}): Promise<void>;
+export declare function renderSwiftComponent(doc: ViewIrDocument, options: {
+    theme: import('../design/types.js').ThemeIR;
+    tokens: import('../design/types.js').TokenIR;
+    allowlistExtra?: string[];
+}): Promise<string>;
+export declare function renderComposeComponent(doc: ViewIrDocument, options: {
+    theme: import('../design/types.js').ThemeIR;
+    tokens: import('../design/types.js').TokenIR;
+    allowlistExtra?: string[];
+}): Promise<string>;
+export declare function renderComposeRuntime(configPath: string, config: ViewContractsConfig, bindings: import('../config.js').ViewBindingsFile, design?: {
+    theme: import('../design/types.js').ThemeIR;
+    tokens: import('../design/types.js').TokenIR;
+}, compiledDocs?: {
+    screens: Map<string, ViewIrDocument>;
+    partials: ViewIrDocument[];
+}): Promise<void>;

package/dist/types/src/renderer/elementMapValidation.d.ts

@@ -0,0 +1,6 @@
+/** Load a YAML file into a typed object (target-agnostic). */
+export declare function loadYamlFile<T>(path: string): Promise<T>;
+/** Ensure element names exist in the DSL vocabulary allowlist. */
+export declare function validateVocabularyElementNames(elementNames: Iterable<string>, allowed: ReadonlySet<string>, sourceLabel: string): void;
+/** Ensure each map entry has required fields (e.g. HTML tag for lowering). */
+export declare function validateMapEntryFields<T extends object>(entries: Record<string, T>, requiredKeys: (keyof T)[], sourceLabel: string): void;

package/dist/types/src/renderer/style/mergeVisualProps.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Renderer-agnostic compile-time visual property merge.
+ * Precedence: instance > variant > themeDefault (right wins — no modifier accumulation).
+ */
+import type { ThemeIR, TokenIR } from '../../design/types.js';
+export type VisualPropSet = Record<string, string | number | boolean>;
+export interface MergeVisualPropsInput {
+    elementName: string;
+    theme: ThemeIR;
+    tokens: TokenIR;
+    /** Compile-time literal variant name from View IR, if any. */
+    variantLiteral?: string;
+    /** Compile-time literal visual props from the View IR node (DSL prop names). */
+    instanceLiterals: Record<string, unknown>;
+}
+/**
+ * Merge theme default, variant, and instance visual props for one vocabulary element.
+ * Later layers override earlier ones for the same property key (override, not accumulate).
+ */
+export declare function mergeVisualProps(input: MergeVisualPropsInput): VisualPropSet;

package/dist/types/src/renderer/template.d.ts

@@ -0,0 +1,2 @@
+/** Render a Handlebars template from a target-specific templates directory. */
+export declare function renderTemplate(templatesDir: string, templateName: string, data: Record<string, unknown>): Promise<string>;

package/dist/types/src/scaffold/standalone.d.ts

@@ -0,0 +1,2 @@
+import type { ViewBindingsFile } from '../config.js';
+export declare function scaffoldStandaloneApp(configPath: string, bindings: ViewBindingsFile): Promise<void>;

package/dist/types/src/schema/dsl-catalog.d.ts

@@ -0,0 +1,56 @@
+/**
+ * DSL Vocabulary Catalog — Single Source of Truth.
+ *
+ * All vocabulary metadata lives here. Program code imports directly.
+ * The schema generator reads this to produce spec/ui-dsl.schema.json (user-facing).
+ */
+export type LoweringMode = "inline-css" | "class-name" | "attribute" | "none";
+export interface PropertyDef {
+    readonly type: string | readonly string[];
+    readonly category: string;
+    readonly lowering: LoweringMode;
+    readonly enum?: string;
+    readonly description?: string;
+    readonly notes?: string;
+}
+export interface ElementDef {
+    readonly description: string;
+    readonly tier: "core" | "optional" | "extension";
+    readonly category: string;
+    readonly notes?: string;
+    /** Accepted property names — sole authority for property-element binding. */
+    readonly properties: readonly string[];
+    readonly children: {
+        readonly kind: "any" | "none" | "single" | "text" | "list";
+        readonly items?: readonly string[];
+    };
+}
+export declare const TOKEN_CATALOG: {
+    readonly role: readonly ["button", "link", "heading", "list", "listitem", "main", "dialog", "status"];
+    readonly widthSize: readonly ["wrap", "fill"];
+    readonly heightSize: readonly ["wrap", "fill"];
+    readonly align: readonly ["start", "center", "end", "stretch"];
+    readonly justify: readonly ["start", "center", "end", "spaceBetween", "spaceAround", "spaceEvenly"];
+    readonly contentAlign: readonly ["topStart", "top", "topEnd", "start", "center", "end", "bottomStart", "bottom", "bottomEnd"];
+    readonly axis: readonly ["vertical", "horizontal"];
+    readonly direction: readonly ["ltr", "rtl", "system"];
+    readonly scroll: readonly ["none", "vertical", "horizontal", "both"];
+    readonly border: readonly ["none"];
+    readonly shadow: readonly ["none", "sm", "md", "lg"];
+    readonly textAlign: readonly ["start", "center", "end"];
+    readonly lineLimit: readonly ["none"];
+    readonly textOverflow: readonly ["clip", "ellipsis"];
+    readonly fontWeight: readonly ["regular", "medium", "bold"];
+    readonly imageFit: readonly ["contain", "cover", "fill", "none"];
+    readonly keyboardType: readonly ["text", "number", "email", "url", "password", "tel"];
+    readonly inputType: readonly ["text", "password", "email", "url", "tel"];
+    readonly clip: readonly ["none", "bounds", "shape"];
+};
+export declare const PROPERTY_CATALOG: Record<string, PropertyDef>;
+export declare const ELEMENT_CATALOG: Record<string, ElementDef>;
+export declare const ALLOWED_COMPONENTS: Set<string>;
+export declare const LOWERING_STYLE_PROPERTIES: Set<string>;
+export declare const CLASS_NAME_PROPERTIES: Set<string>;
+export declare function elementProps(elementName: string): readonly string[];
+/** Check if an element accepts a property. Element.properties is the sole authority. */
+export declare function propertyAppliesTo(propName: string, elementName: string): boolean;

package/dist/types/src/validate/validateViewProps.d.ts

@@ -0,0 +1,5 @@
+import type { ViewIrDocument } from '../ir/types.js';
+import { type PropertyDef } from '../schema/dsl-catalog.js';
+export declare function validateViewProps(docs: Iterable<ViewIrDocument>, allowlistExtra?: string[]): Promise<void>;
+/** @internal Exported for tests. */
+export declare function isVisualProperty(def: PropertyDef | undefined): boolean;