openuispec 0.1.17 → 0.1.18

package/examples/taskflow/screens/profile_edit.yaml

@@ -23,6 +23,8 @@ profile_edit:
           - contract: data_display
             variant: inline
             props:
+              title: "user.name"
+              subtitle: "user.email"
               leading:
                 media: "user.avatar"
                 fallback: { initials: "user.name", background: "color.brand.primary" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",

package/schema/validate.ts

@@ -23,6 +23,18 @@ const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const SCHEMA_DIR = resolve(__dirname);
 
 type AjvInstance = InstanceType<typeof Ajv2020>;
+type UnknownRecord = Record<string, unknown>;
+
+interface UsageLint {
+  path: string;
+  message: string;
+}
+
+interface StandardContractRule {
+  requiredProps?: string[];
+  nonEmptyStringProps?: string[];
+  validate?: (node: UnknownRecord, props: UnknownRecord, path: string) => UsageLint[];
+}
 
 // ── helpers ──────────────────────────────────────────────────────────
 
@@ -49,6 +61,255 @@ function listFiles(dir: string, ext: string): string[] {
   }
 }
 
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function getSingleRootValue(data: unknown): unknown {
+  if (!isRecord(data)) return undefined;
+  const values = Object.values(data);
+  return values.length === 1 ? values[0] : undefined;
+}
+
+const STANDARD_CONTRACT_RULES: Record<string, StandardContractRule> = {
+  action_trigger: {
+    requiredProps: ["label"],
+    nonEmptyStringProps: ["label"],
+  },
+  data_display: {
+    requiredProps: ["title"],
+    nonEmptyStringProps: ["title"],
+  },
+  input_field: {
+    requiredProps: ["label"],
+    nonEmptyStringProps: ["label"],
+    validate(node, props, path) {
+      const inputType = node.input_type;
+      if (inputType === "select" || inputType === "radio") {
+        return hasOwnProp(props, "options")
+          ? []
+          : [{
+              path,
+              message: `contract "input_field" with input_type="${String(inputType)}" requires props.options`,
+            }];
+      }
+      if (inputType === "slider") {
+        return hasOwnProp(props, "range")
+          ? []
+          : [{
+              path,
+              message: 'contract "input_field" with input_type="slider" requires props.range',
+            }];
+      }
+      return [];
+    },
+  },
+  nav_container: {
+    requiredProps: ["items"],
+    validate(_node, props, path) {
+      const items = props.items;
+      if (!Array.isArray(items)) {
+        return [];
+      }
+      const errors: UsageLint[] = [];
+      for (const [index, item] of items.entries()) {
+        const itemPath = `${path}/props/items/${index}`;
+        if (!isRecord(item)) {
+          errors.push({
+            path: itemPath,
+            message: "nav_container items must be objects",
+          });
+          continue;
+        }
+        for (const key of ["id", "label", "icon", "destination"]) {
+          if (!hasOwnProp(item, key)) {
+            errors.push({
+              path: itemPath,
+              message: `nav_container item requires "${key}"`,
+            });
+          }
+        }
+        if (hasOwnProp(item, "label") && !isNonEmptyString(item.label)) {
+          errors.push({
+            path: `${itemPath}/label`,
+            message: 'nav_container item "label" must be a non-empty string',
+          });
+        }
+      }
+      return errors;
+    },
+  },
+  feedback: {
+    requiredProps: ["message"],
+    nonEmptyStringProps: ["message"],
+  },
+  surface: {
+    requiredProps: ["content"],
+  },
+  collection: {
+    requiredProps: ["data", "item_contract", "item_props_map"],
+  },
+};
+
+function hasOwnProp(obj: UnknownRecord, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+function validateStandardContractUsage(
+  node: UnknownRecord,
+  path: string,
+): UsageLint[] {
+  const contract = node.contract;
+  if (typeof contract !== "string") return [];
+
+  const rule = STANDARD_CONTRACT_RULES[contract];
+  if (!rule) return [];
+
+  const props = isRecord(node.props) ? node.props : {};
+  const errors: UsageLint[] = [];
+
+  for (const prop of rule.requiredProps ?? []) {
+    if (!hasOwnProp(props, prop)) {
+      errors.push({
+        path,
+        message: `contract "${contract}" requires props.${prop}`,
+      });
+    }
+  }
+
+  for (const prop of rule.nonEmptyStringProps ?? []) {
+    if (hasOwnProp(props, prop) && !isNonEmptyString(props[prop])) {
+      errors.push({
+        path: `${path}/props/${prop}`,
+        message: `props.${prop} for contract "${contract}" must be a non-empty string`,
+      });
+    }
+  }
+
+  errors.push(...(rule.validate?.(node, props, path) ?? []));
+  return errors;
+}
+
+function lintSectionItems(items: unknown, path: string): UsageLint[] {
+  if (!Array.isArray(items)) return [];
+  const errors: UsageLint[] = [];
+
+  for (const [index, item] of items.entries()) {
+    const itemPath = `${path}/${index}`;
+    if (!isRecord(item)) {
+      continue;
+    }
+
+    errors.push(...validateStandardContractUsage(item, itemPath));
+
+    if (Array.isArray(item.children)) {
+      errors.push(...lintSectionItems(item.children, `${itemPath}/children`));
+    }
+  }
+
+  return errors;
+}
+
+function lintScreenLikeDefinition(screenDef: unknown, path: string): UsageLint[] {
+  if (!isRecord(screenDef)) return [];
+  const errors: UsageLint[] = [];
+
+  if (isRecord(screenDef.layout)) {
+    errors.push(
+      ...lintSectionItems(screenDef.layout.sections, `${path}/layout/sections`),
+    );
+  }
+
+  if (isRecord(screenDef.navigation)) {
+    errors.push(
+      ...validateStandardContractUsage(
+        screenDef.navigation,
+        `${path}/navigation`,
+      ),
+    );
+  }
+
+  if (isRecord(screenDef.surfaces)) {
+    for (const [surfaceId, surfaceDef] of Object.entries(screenDef.surfaces)) {
+      const surfacePath = `${path}/surfaces/${surfaceId}`;
+      if (!isRecord(surfaceDef)) {
+        continue;
+      }
+
+      errors.push(...validateStandardContractUsage(surfaceDef, surfacePath));
+
+      const props = isRecord(surfaceDef.props) ? surfaceDef.props : {};
+      if (Array.isArray(props.content)) {
+        errors.push(
+          ...lintSectionItems(props.content, `${surfacePath}/props/content`),
+        );
+      }
+    }
+  }
+
+  return errors;
+}
+
+function lintScreenFile(dataPath: string): number {
+  const root = getSingleRootValue(loadData(dataPath));
+  const errors = lintScreenLikeDefinition(root, basename(dataPath));
+  if (errors.length === 0) {
+    return 0;
+  }
+
+  console.log(`  FAIL  ${basename(dataPath)} (${errors.length} contract usage error(s))`);
+  for (const error of errors.slice(0, 5)) {
+    console.log(`        [${error.path}] ${error.message}`);
+  }
+  if (errors.length > 5) {
+    console.log(`        ... and ${errors.length - 5} more`);
+  }
+  console.log(
+    "        Hint: built-in contract instances inherit required props from the spec even when contracts/<name>.yaml does not restate them.",
+  );
+  return errors.length;
+}
+
+function lintFlowFile(dataPath: string): number {
+  const root = getSingleRootValue(loadData(dataPath));
+  if (!isRecord(root) || !isRecord(root.screens)) {
+    return 0;
+  }
+
+  const errors: UsageLint[] = [];
+  for (const [screenId, screenEntry] of Object.entries(root.screens)) {
+    if (!isRecord(screenEntry) || !isRecord(screenEntry.screen_inline)) {
+      continue;
+    }
+    errors.push(
+      ...lintScreenLikeDefinition(
+        screenEntry.screen_inline,
+        `${basename(dataPath)}/screens/${screenId}/screen_inline`,
+      ),
+    );
+  }
+
+  if (errors.length === 0) {
+    return 0;
+  }
+
+  console.log(`  FAIL  ${basename(dataPath)} (${errors.length} contract usage error(s))`);
+  for (const error of errors.slice(0, 5)) {
+    console.log(`        [${error.path}] ${error.message}`);
+  }
+  if (errors.length > 5) {
+    console.log(`        ... and ${errors.length - 5} more`);
+  }
+  console.log(
+    "        Hint: flow screen_inline sections follow the same built-in contract requirements as screens/*.yaml.",
+  );
+  return errors.length;
+}
+
 // ── build Ajv instance with all schemas ──────────────────────────────
 
 function buildAjv(): AjvInstance {
@@ -233,7 +494,11 @@ const GROUPS: Record<string, ValidationGroup> = {
       let errors = 0;
       const dir = resolveInclude(projectDir, includes.screens);
       for (const f of listFiles(dir, ".yaml")) {
-        errors += validateFile(ajv, f, `${BASE}screen.schema.json`);
+        const schemaErrors = validateFile(ajv, f, `${BASE}screen.schema.json`);
+        errors += schemaErrors;
+        if (schemaErrors === 0) {
+          errors += lintScreenFile(f);
+        }
       }
       return errors;
     },
@@ -245,7 +510,11 @@ const GROUPS: Record<string, ValidationGroup> = {
       let errors = 0;
       const dir = resolveInclude(projectDir, includes.flows);
       for (const f of listFiles(dir, ".yaml")) {
-        errors += validateFile(ajv, f, `${BASE}flow.schema.json`);
+        const schemaErrors = validateFile(ajv, f, `${BASE}flow.schema.json`);
+        errors += schemaErrors;
+        if (schemaErrors === 0) {
+          errors += lintFlowFile(f);
+        }
       }
       return errors;
     },

package/spec/openuispec-v0.1.md

@@ -1392,6 +1392,7 @@ collection:
       grid: "grid"
       table: "table"
       carousel: "region"
+    label: "Derived from visible header text or surrounding section heading; bind with aria-labelledby or platform equivalent rather than a dedicated prop when possible"
     item_role:
       list: "listitem"
       grid: "gridcell"
@@ -1469,6 +1470,8 @@ collection:
       - "Item recycling / virtualization for large datasets"
 ```
 
+Collection containers still need an accessible name, but unlike controls such as buttons or fields, that name usually comes from visible context rather than a dedicated `label` prop. Generators SHOULD connect the collection to a visible heading or header component via `aria-labelledby` or the platform equivalent, and only fall back to an explicit synthesized label when no visible label source exists.
+
 ---
 
 ## 5. Screen composition
@@ -2022,7 +2025,7 @@ Every AI generator, regardless of platform target, MUST:
 2. Map every `contract` reference to the correct native widget per `platform_mapping`.
 3. Apply all `tokens` values within their declared `range` constraints.
 4. Implement every `state` declared in each used contract, including transitions.
-5. Set correct `a11y.role` and `a11y.label` for every component instance.
+5. Set correct `a11y.role` and `a11y.label` for every component instance. For contextual containers such as `collection`, derive the label from the visible heading/header via `aria-labelledby` or the platform equivalent when possible instead of requiring a dedicated prop.
 6. Respect `themes` by generating light/dark mode support.
 7. Handle `empty`, `loading`, and `error` states for `collection` contracts.
 8. Wire all `action.navigate` declarations to the platform's navigation system.
@@ -2039,7 +2042,7 @@ A valid OpenUISpec document:
 - Contains a root `openuispec.yaml` manifest with `spec_version`
 - References only defined tokens, contracts, screens, and flows
 - Has no circular `flow` transitions
-- Has every `required: true` prop satisfied in screen compositions
+- Has every `required: true` prop satisfied in screen compositions, including required props inherited from built-in standard contract families even when `contracts/<name>.yaml` does not restate them
 - Has every `screen.params` satisfied by its callers
 
 ### 8.4 Drift detection