openuispec 0.2.13 → 0.2.15

package/schema/component.schema.json

@@ -0,0 +1,278 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openuispec.rsteam.uz/schema/component.schema.json",
+  "title": "OpenUISpec Component",
+  "description": "Reusable composition of contracts with named slots — root key is the component name",
+  "type": "object",
+  "minProperties": 1,
+  "maxProperties": 1,
+  "propertyNames": {
+    "pattern": "^[a-z][a-z0-9_]*$"
+  },
+  "additionalProperties": {
+    "$ref": "#/$defs/component_def"
+  },
+  "$defs": {
+    "component_def": {
+      "type": "object",
+      "description": "A component definition — composition of contracts with named slots, states, variants, and layout",
+      "properties": {
+        "semantic": {
+          "type": "string",
+          "description": "Human-readable description of this component's purpose"
+        },
+        "props": {
+          "type": "object",
+          "description": "Typed property definitions for this component",
+          "additionalProperties": {
+            "$ref": "https://openuispec.rsteam.uz/schema/custom-contract.schema.json#/$defs/prop_def"
+          }
+        },
+        "slots": {
+          "type": "object",
+          "description": "Named slots — each slot wraps a contract instance",
+          "additionalProperties": {
+            "$ref": "#/$defs/slot_def"
+          }
+        },
+        "layout": {
+          "$ref": "#/$defs/component_layout"
+        },
+        "states": {
+          "type": "object",
+          "description": "Composite states that control slot visibility and props",
+          "additionalProperties": {
+            "$ref": "#/$defs/component_state_def"
+          }
+        },
+        "variants": {
+          "type": "object",
+          "description": "Named component variants with layout and slot overrides",
+          "additionalProperties": {
+            "$ref": "#/$defs/component_variant_def"
+          }
+        },
+        "tokens": {
+          "type": "object",
+          "description": "Token bindings for the component container",
+          "additionalProperties": true
+        },
+        "a11y": {
+          "type": "object",
+          "description": "Accessibility requirements",
+          "properties": {
+            "role": {
+              "type": "string",
+              "description": "ARIA/accessibility role"
+            },
+            "label": {
+              "type": "string",
+              "description": "Accessibility label source"
+            }
+          },
+          "additionalProperties": true
+        },
+        "platform_mapping": {
+          "type": "object",
+          "description": "Per-platform native component mapping",
+          "properties": {
+            "ios": { "type": "object", "additionalProperties": true },
+            "android": { "type": "object", "additionalProperties": true },
+            "web": { "type": "object", "additionalProperties": true }
+          },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        },
+        "dependencies": {
+          "type": "object",
+          "description": "Per-platform library/framework requirements",
+          "additionalProperties": {
+            "$ref": "https://openuispec.rsteam.uz/schema/custom-contract.schema.json#/$defs/dependency_def"
+          }
+        },
+        "generation": {
+          "type": "object",
+          "description": "AI generation compliance hints",
+          "properties": {
+            "must_handle": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "should_handle": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "may_handle": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          },
+          "additionalProperties": false
+        },
+        "test_cases": {
+          "type": "array",
+          "description": "Behavioral verification scenarios",
+          "items": {
+            "$ref": "https://openuispec.rsteam.uz/schema/custom-contract.schema.json#/$defs/test_case"
+          }
+        }
+      },
+      "required": ["semantic", "slots"],
+      "additionalProperties": false
+    },
+    "slot_def": {
+      "type": "object",
+      "description": "A named slot wrapping a contract instance",
+      "properties": {
+        "contract": {
+          "type": "string",
+          "description": "Base contract family (e.g. action_trigger, input_field, data_display)"
+        },
+        "variant": {
+          "type": "string",
+          "description": "Contract variant"
+        },
+        "input_type": {
+          "type": "string",
+          "description": "Input type for input_field contracts (e.g. slider, text)"
+        },
+        "props": {
+          "type": "object",
+          "description": "Default props passed to the contract",
+          "additionalProperties": true
+        },
+        "hideable": {
+          "type": "boolean",
+          "description": "Whether this slot can be hidden by states or screen overrides"
+        },
+        "tokens_override": {
+          "type": "object",
+          "description": "Token overrides for this slot",
+          "additionalProperties": true
+        }
+      },
+      "required": ["contract"],
+      "additionalProperties": false
+    },
+    "component_layout": {
+      "type": "object",
+      "description": "Layout definition for the component",
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Layout type (e.g. stack, row, grid)"
+        },
+        "spacing": {
+          "type": "string"
+        },
+        "align": {
+          "type": "string"
+        },
+        "justify": {
+          "type": "string"
+        },
+        "sections": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/component_layout_item"
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "component_layout_item": {
+      "description": "A layout item — either a slot reference or a nested layout",
+      "type": "object",
+      "properties": {
+        "slot": {
+          "type": "string",
+          "description": "Reference to a named slot"
+        },
+        "layout": {
+          "$ref": "#/$defs/component_layout"
+        }
+      },
+      "additionalProperties": true
+    },
+    "component_state_def": {
+      "type": "object",
+      "description": "A composite state affecting slot visibility and props",
+      "properties": {
+        "semantic": {
+          "type": "string"
+        },
+        "hide_slots": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Slots to hide in this state"
+        },
+        "slot_overrides": {
+          "type": "object",
+          "description": "Per-slot prop/variant overrides in this state",
+          "additionalProperties": {
+            "$ref": "#/$defs/slot_override"
+          }
+        },
+        "transitions_to": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "States this state can transition to"
+        }
+      },
+      "additionalProperties": false
+    },
+    "component_variant_def": {
+      "type": "object",
+      "description": "A named component variant with layout and slot overrides",
+      "properties": {
+        "semantic": {
+          "type": "string"
+        },
+        "hide_slots": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Slots to hide in this variant"
+        },
+        "layout": {
+          "$ref": "#/$defs/component_layout"
+        },
+        "tokens": {
+          "type": "object",
+          "description": "Token overrides for this variant",
+          "additionalProperties": true
+        },
+        "slot_overrides": {
+          "type": "object",
+          "description": "Per-slot prop/variant overrides in this variant",
+          "additionalProperties": {
+            "$ref": "#/$defs/slot_override"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "slot_override": {
+      "type": "object",
+      "description": "Override for a specific slot",
+      "properties": {
+        "variant": {
+          "type": "string"
+        },
+        "props": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "tokens_override": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "hidden": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/openuispec.schema.json

@@ -60,6 +60,10 @@
         "locales": {
           "type": "string",
           "description": "Localization string files — one JSON file per supported locale containing translated UI text."
+        },
+        "components": {
+          "type": "string",
+          "description": "Reusable component compositions — each YAML file defines a component as a composition of contracts with named slots, states, and variants."
         }
       },
       "required": [
@@ -184,7 +188,7 @@
                 "description": "Spec categories this shared layer tracks for hash-based drift detection. Optional — when omitted, the layer relies on scope alone. Categories: manifest (project config, data models, API endpoints), tokens (visual design tokens — UI only), contracts (reusable UI component definitions — UI only, not business logic), screens (screen layouts — UI only), flows (navigation journeys — UI only), platform (per-target overrides — UI only), locales (translated UI strings).",
                 "items": {
                   "type": "string",
-                  "enum": ["manifest", "tokens", "contracts", "screens", "flows", "platform", "locales"]
+                  "enum": ["manifest", "tokens", "contracts", "components", "screens", "flows", "platform", "locales"]
                 }
               },
               "scope": {

package/schema/screen.schema.json

@@ -171,7 +171,7 @@
       "additionalProperties": false
     },
     "section_item": {
-      "description": "A section item \u2014 either a contract instance or a section group with children",
+      "description": "A section item \u2014 a contract instance, component instance, or section group with children",
       "type": "object",
       "properties": {
         "id": {
@@ -180,6 +180,17 @@
         "contract": {
           "type": "string"
         },
+        "component": {
+          "type": "string",
+          "description": "Component name (alternative to contract). References a component defined in components/*.yaml."
+        },
+        "slots": {
+          "type": "object",
+          "description": "Slot overrides when using a component. Each key is a slot name.",
+          "additionalProperties": {
+            "$ref": "https://openuispec.rsteam.uz/schema/component.schema.json#/$defs/slot_override"
+          }
+        },
         "variant": {
           "type": "string"
         },

package/schema/semantic-lint.ts

@@ -25,6 +25,7 @@ function collectLocaleKeys(data: unknown, prefix = ""): string[] {
 export interface Includes {
   tokens: string;
   contracts: string;
+  components: string;
   screens: string;
   flows: string;
   platform: string;
@@ -43,6 +44,7 @@ interface SemanticContext {
   formatterNames: Set<string>;
   mapperNames: Set<string>;
   contractNames: Set<string>;
+  componentNames: Set<string>;
   tokenRefs: Set<string>;
   iconRefs: Set<string>;
   iconVariantSuffixes: string[];
@@ -182,7 +184,8 @@ function collectIconRefs(filePath: string): { refs: Set<string>; suffixes: strin
   if (!isRecord(data) || !isRecord(data.icons)) return { refs, suffixes };
 
   const icons = data.icons as UnknownRecord;
-  const variantSuffixes = isRecord(icons.variants?.suffixes) ? icons.variants.suffixes : {};
+  const variants = isRecord(icons.variants) ? icons.variants : {};
+  const variantSuffixes = isRecord(variants.suffixes) ? variants.suffixes : {};
   for (const suffix of Object.keys(variantSuffixes)) {
     if (suffix.trim()) suffixes.push(suffix);
   }
@@ -215,8 +218,9 @@ function collectIconRefs(filePath: string): { refs: Set<string>; suffixes: strin
     }
   }
 
-  if (typeof icons.fallback?.missing_icon === "string") {
-    refs.add(icons.fallback.missing_icon);
+  const fallback = isRecord(icons.fallback) ? icons.fallback : {};
+  if (typeof fallback.missing_icon === "string") {
+    refs.add(fallback.missing_icon);
   }
 
   return { refs, suffixes };
@@ -253,6 +257,15 @@ function buildContext(projectDir: string, includes: Includes, manifest: UnknownR
     }
   }
 
+  // Components are also valid references in screen sections (via "component:" key)
+  const componentNames = new Set<string>();
+  const componentsDir = resolve(projectDir, includes.components);
+  for (const filePath of listFiles(componentsDir, ".yaml")) {
+    for (const key of rootKeys(filePath)) {
+      componentNames.add(key);
+    }
+  }
+
   const tokenRefs = new Set<string>();
   const tokensDir = resolve(projectDir, includes.tokens);
   for (const filePath of listFiles(tokensDir, ".yaml")) {
@@ -300,6 +313,7 @@ function buildContext(projectDir: string, includes: Includes, manifest: UnknownR
     formatterNames,
     mapperNames,
     contractNames,
+    componentNames,
     tokenRefs,
     iconRefs: iconData.refs,
     iconVariantSuffixes: iconData.suffixes,
@@ -429,6 +443,10 @@ function validateStringValue(
     errors.push({ path, message: `unknown contract "${value}"` });
   }
 
+  if (key === "component" && !path.includes("platform_mapping") && !context.componentNames.has(value)) {
+    errors.push({ path, message: `unknown component "${value}"` });
+  }
+
   if (
     (key === "icon" || key === "icon_active") &&
     !isDynamicReference(value) &&
@@ -617,6 +635,7 @@ export function collectSemanticLint(projectDir: string, includes: Includes): Usa
   const manifest = readManifest(projectDir) as UnknownRecord;
   const context = buildContext(projectDir, includes, manifest);
   const contractsDir = resolve(projectDir, includes.contracts);
+  const componentsDir = resolve(projectDir, includes.components);
 
   const allErrors: UsageLint[] = [
     ...lintLocaleCoverage(context),
@@ -629,11 +648,13 @@ export function collectSemanticLint(projectDir: string, includes: Includes): Usa
     ...listFiles(resolve(projectDir, includes.flows), ".yaml"),
     ...listFiles(resolve(projectDir, includes.platform), ".yaml"),
     ...listFiles(resolve(projectDir, includes.contracts), ".yaml"),
+    ...listFiles(componentsDir, ".yaml"),
   ];
 
   for (const filePath of files) {
+    const isContractOrComponent = filePath.startsWith(contractsDir) || filePath.startsWith(componentsDir);
     allErrors.push(
-      ...lintFile(filePath, context, { validateTokens: !filePath.startsWith(contractsDir) })
+      ...lintFile(filePath, context, { validateTokens: !isContractOrComponent })
     );
   }
 
@@ -645,6 +666,7 @@ export function runSemanticLint(projectDir: string, includes: Includes): number
   const context = buildContext(projectDir, includes, manifest);
   let total = 0;
   const contractsDir = resolve(projectDir, includes.contracts);
+  const componentsDir = resolve(projectDir, includes.components);
 
   total += printSemanticErrors("locales", lintLocaleCoverage(context));
   total += printSemanticErrors("openuispec.yaml", lintManifestGenerationContext(projectDir, context.manifest));
@@ -655,12 +677,14 @@ export function runSemanticLint(projectDir: string, includes: Includes): number
     ...listFiles(resolve(projectDir, includes.flows), ".yaml"),
     ...listFiles(resolve(projectDir, includes.platform), ".yaml"),
     ...listFiles(resolve(projectDir, includes.contracts), ".yaml"),
+    ...listFiles(componentsDir, ".yaml"),
   ];
 
   for (const filePath of files) {
+    const isContractOrComponent = filePath.startsWith(contractsDir) || filePath.startsWith(componentsDir);
     total += printSemanticErrors(
       basename(filePath),
-      lintFile(filePath, context, { validateTokens: !filePath.startsWith(contractsDir) })
+      lintFile(filePath, context, { validateTokens: !isContractOrComponent })
     );
   }
 

package/schema/validate.ts

@@ -478,6 +478,7 @@ function validateFile(
 const DEFAULT_INCLUDES: Includes = {
   tokens: "./tokens/",
   contracts: "./contracts/",
+  components: "./components/",
   screens: "./screens/",
   flows: "./flows/",
   platform: "./platform/",
@@ -702,6 +703,26 @@ const GROUPS: Record<string, ValidationGroup> = {
     },
   },
 
+  components: {
+    label: "Components",
+    run(ajv, projectDir, includes) {
+      let errors = 0;
+      const dir = resolveInclude(projectDir, includes.components);
+      for (const f of listFiles(dir, ".yaml")) {
+        errors += validateFile(ajv, f, `${BASE}component.schema.json`);
+      }
+      return errors;
+    },
+    collectJson(ajv, projectDir, includes, groupKey) {
+      const errors: JsonError[] = [];
+      const dir = resolveInclude(projectDir, includes.components);
+      for (const f of listFiles(dir, ".yaml")) {
+        errors.push(...collectValidateFile(ajv, f, `${BASE}component.schema.json`));
+      }
+      return { group: groupKey, errors };
+    },
+  },
+
   semantic: {
     label: "Semantic",
     run(_ajv, projectDir, includes) {

package/scripts/regenerate-previews.ts

@@ -0,0 +1,136 @@
+#!/usr/bin/env npx tsx
+/**
+ * Regenerates all preview PNGs for the 3 example projects using the
+ * preview renderer (preview-render.ts → preview.ts → Puppeteer).
+ *
+ * Outputs to examples/<project>/previews/<screen>_<sizeClass>[_<theme>].png
+ *
+ * Usage:  npx tsx scripts/regenerate-previews.ts
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { renderPreview } from "../mcp-server/preview.js";
+import { closeBrowser } from "../mcp-server/screenshot-shared.js";
+
+const ROOT = resolve(import.meta.dirname!, "..");
+
+interface Capture {
+  screen: string;
+  sizeClass: "compact" | "regular" | "expanded";
+  theme?: "light" | "dark";
+}
+
+interface ProjectDef {
+  name: string;
+  captures: Capture[];
+}
+
+function allSizes(screen: string): Capture[] {
+  return [
+    { screen, sizeClass: "compact" },
+    { screen, sizeClass: "expanded" },
+  ];
+}
+
+function allSizesWithThemes(screen: string): Capture[] {
+  return [
+    { screen, sizeClass: "compact" },
+    { screen, sizeClass: "expanded" },
+    { screen, sizeClass: "compact", theme: "light" },
+    { screen, sizeClass: "compact", theme: "dark" },
+    { screen, sizeClass: "expanded", theme: "light" },
+    { screen, sizeClass: "expanded", theme: "dark" },
+  ];
+}
+
+const PROJECTS: ProjectDef[] = [
+  {
+    name: "social-app",
+    captures: [
+      ...allSizes("home_feed"),
+      ...allSizes("discover"),
+      ...allSizes("notifications"),
+      ...allSizes("messages_inbox"),
+      ...allSizes("profile_self"),
+      ...allSizes("profile_user"),
+      ...allSizes("settings"),
+      ...allSizes("post_detail"),
+      ...allSizes("chat_detail"),
+      ...allSizes("search_results"),
+      ...allSizes("edit_profile"),
+    ],
+  },
+  {
+    name: "taskflow",
+    captures: [
+      ...allSizesWithThemes("home"),
+      ...allSizes("projects"),
+      ...allSizes("calendar"),
+      ...allSizesWithThemes("settings"),
+      ...allSizesWithThemes("task_detail"),
+      ...allSizes("project_detail"),
+      ...allSizes("profile_edit"),
+    ],
+  },
+  {
+    name: "todo-orbit",
+    captures: [
+      ...allSizes("home"),
+      ...allSizes("analytics"),
+      ...allSizes("settings"),
+      ...allSizes("task_detail"),
+    ],
+  },
+];
+
+function log(msg: string) { console.log(`\x1b[36m▸\x1b[0m ${msg}`); }
+function logOk(msg: string) { console.log(`\x1b[32m✔\x1b[0m ${msg}`); }
+function logErr(msg: string) { console.error(`\x1b[31m✖\x1b[0m ${msg}`); }
+
+async function main() {
+  let total = 0;
+  let failures = 0;
+
+  for (const project of PROJECTS) {
+    console.log(`\n\x1b[1m=== ${project.name} ===\x1b[0m\n`);
+    const projectCwd = join(ROOT, "examples", project.name);
+    const outDir = join(projectCwd, "previews");
+    mkdirSync(outDir, { recursive: true });
+
+    for (const cap of project.captures) {
+      const theme = cap.theme ?? "light";
+      const suffix = cap.theme ? `_${cap.theme}` : "";
+      const filename = `${cap.screen}_${cap.sizeClass}${suffix}.png`;
+      log(`${filename}...`);
+      total++;
+
+      try {
+        const result = await renderPreview(projectCwd, {
+          screen: cap.screen,
+          size_class: cap.sizeClass,
+          theme,
+        });
+
+        for (const item of result.content) {
+          if (item.type === "image" && "data" in item) {
+            writeFileSync(join(outDir, filename), Buffer.from(item.data, "base64"));
+            logOk(filename);
+          }
+        }
+      } catch (err: any) {
+        logErr(`${filename}: ${err.message}`);
+        failures++;
+      }
+    }
+  }
+
+  await closeBrowser();
+  console.log(`\n\x1b[${failures ? "31" : "32"}m${total - failures}/${total} previews generated, ${failures} failures\x1b[0m\n`);
+  process.exit(failures > 0 ? 1 : 0);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});