@object-ui/sdui-parser 17.5.0 → 17.7.0

package/dist/validate.js

@@ -2,22 +2,129 @@
  * ObjectUI — SDUI tree validation against the registry manifest (ADR-0080 §3/§6)
  *
  * Shallow, author-time validation: unknown component, unknown/missing prop,
- * wrong coarse type, illegal enum value. Collects `requires` (plugin provenance)
- * and binding sites the SERVER must resolve against object schema (we cannot
- * resolve objects/fields here — that check is framework-side by design).
+ * wrong coarse type, illegal enum value, and containment — a child list under
+ * a component whose registration declares no `children` input draws
+ * `not-a-container` (objectui#9910; see `acceptsChildren`). Collects
+ * `requires` (plugin provenance) and binding sites the SERVER must resolve
+ * against object schema (we cannot resolve objects/fields here — that check is
+ * framework-side by design).
  */
-/** Base props every node may carry (mirrors BaseSchema) — never "unknown prop". */
-const BASE_PROPS = new Set([
-    'type',
-    'id',
-    'className',
-    'style',
-    'visible',
-    'visibleOn',
-    'disabled',
-    'disabledOn',
-    'children',
+import { inputTypeArms } from './input-type.js';
+import { checkDashboardWidgetOptions } from './dashboard-widget-options.js';
+import { checkRetiredBodyDialect } from './body-dialect.js';
+/**
+ * The protocol's ONE child-list key — `BaseSchema.children` — and therefore the
+ * name of the `inputs` entry a registration declares when its renderer puts
+ * that list on the page: `{ name: 'children', type: 'slot' }` (objectui#9910).
+ */
+export const CHILD_LIST_KEY = 'children';
+/**
+ * Does this component ACCEPT an authored child list? (objectui#9910)
+ *
+ * Read from exactly ONE declaration: an input named {@link CHILD_LIST_KEY} in
+ * the component's `inputs`. That is the shape ten registrations already
+ * carried when the maintainer ruled it the containment contract
+ * (2026-09-24, objectui#9910 Q1-A "declare-and-pin"), and it is held in both
+ * directions by the runtime census in
+ * `packages/components/src/renderers/__tests__/container-declaration-ratchet.test.tsx`:
+ * a renderer that puts `schema.children` on the page without declaring the
+ * input is red, and a declaration whose renderer never renders the list is
+ * red too.
+ *
+ * ⛔ `isContainer` is NOT consulted and is NOT a fallback. It used to decide
+ * this branch and it lied both ways: a hand-kept flag drifted from the code
+ * (objectui#3900 / `7c9b044f4` / #6764 / #6779 found the same drift four times),
+ * and after objectui#6771 converged a dozen registrations onto `children`
+ * the flag put a FALSE `not-a-container` on the one key they read
+ * (objectui#9910). The flag now means LAYOUT containment only — the
+ * react-page JSX scope and the public layout ledger read it; this tier does
+ * not (objectui#6804, objectui#9910 Q2-A).
+ */
+export function acceptsChildren(comp) {
+    return comp.inputs.some((input) => input.name === CHILD_LIST_KEY);
+}
+/**
+ * The base props: the `BaseSchema` members this tier accepts on a node without
+ * a registration declaring them. ONE list, read by BOTH of its consumers —
+ * {@link validateTree}'s `unknown-prop` branch and `generateDts`'s
+ * `SduiBaseProps` (objectui#11044). Before this list the two were separate
+ * hand-kept copies and had drifted: the validator accepted `bind` and `hidden`
+ * (objectui#11008) while the generated types still refused both.
+ *
+ * `bind` and `hidden` are `'every-node'` (objectui#11008). `BaseSchema` declares
+ * both for every node and no registration declares either as an input, so
+ * before they joined, the undeclared-key branch below answered every authored
+ * one with `unknown-prop` — "has no prop" about a key the protocol declares,
+ * on the nodes that honour it: `hidden` is read for every node by
+ * `SchemaRenderer`'s hide chain, and `bind` by every renderer that calls
+ * `useDataScope` (`list`, `tree-view`, the `object-*` widgets). The
+ * declaration outranks the implementation, so the parser's view is the
+ * declared type's, not a per-registration subset. The cost is accepted and
+ * named: a `bind` on a node that does not read it — `data-table`
+ * (objectui#6575) — draws nothing here either, and its render-time console
+ * warning is the one signal left.
+ *
+ * `visibleWhen`, `hiddenOn` and `testId` are `'every-node'` for the same reason
+ * (objectui#11044): no registration declares any of them, `SchemaRenderer`'s
+ * hide chain reads the first two for every node, and it strips `testId` and
+ * re-emits it as `data-testid`. `visibleWhen` is the canonical ADR-0089
+ * predicate; before it joined, the deprecated `visibleOn` was silent while it
+ * drew `unknown-prop`.
+ *
+ * The `'where-undeclared'` members (objectui#11044, triage ruling) are the
+ * `BaseSchema` members some registrations DECLARE as typed inputs — the input
+ * family's `placeholder`, `label`, `name`, … . Skipping them the way the
+ * `'every-node'` members are skipped would silence those registrations'
+ * `type-mismatch`, so they are base props only where the type declares no
+ * input of that name. ⛔ Never move one to `'every-node'` to accept a key: that
+ * silences a declared type check.
+ *
+ * Held over the live registry by `base-props-one-list-11044.test.tsx` in
+ * `@object-ui/components` — every member a `BaseSchema` member, and `body` the
+ * one member left out.
+ *
+ * ⛔ `body` is NOT here and must not be added. It was `BaseSchema`'s second
+ * child-list spelling until objectui#6771 retired it; teaching this list the
+ * key was the option that ruling refused, because it would have blessed a
+ * second permanent spelling of one concept. `./body-dialect.ts` answers it by
+ * name instead.
+ *
+ * `children` IS here: the key is legal on every node, so it never draws
+ * `unknown-prop` and its declared `slot` input is never type-checked. Whether
+ * a given component RENDERS it is the containment question below, answered by
+ * {@link acceptsChildren} from the declared input.
+ */
+export const SDUI_BASE_PROPS = Object.freeze([
+    { name: 'type', scope: 'every-node', tsType: null },
+    { name: 'id', scope: 'every-node', tsType: 'string' },
+    { name: 'className', scope: 'every-node', tsType: 'string' },
+    { name: 'style', scope: 'every-node', tsType: 'Record<string, unknown>' },
+    { name: 'visible', scope: 'every-node', tsType: 'boolean' },
+    { name: 'visibleWhen', scope: 'every-node', tsType: 'string' },
+    { name: 'visibleOn', scope: 'every-node', tsType: 'string' },
+    { name: 'hidden', scope: 'every-node', tsType: 'boolean' },
+    { name: 'hiddenOn', scope: 'every-node', tsType: 'string' },
+    { name: 'disabled', scope: 'every-node', tsType: 'boolean' },
+    { name: 'disabledOn', scope: 'every-node', tsType: 'string' },
+    { name: 'bind', scope: 'every-node', tsType: 'string' },
+    { name: 'testId', scope: 'every-node', tsType: 'string' },
+    { name: CHILD_LIST_KEY, scope: 'every-node', tsType: 'unknown' },
+    { name: 'name', scope: 'where-undeclared', tsType: 'string' },
+    { name: 'label', scope: 'where-undeclared', tsType: 'string | Record<string, string>' },
+    { name: 'description', scope: 'where-undeclared', tsType: 'string | Record<string, string>' },
+    { name: 'placeholder', scope: 'where-undeclared', tsType: 'string' },
+    { name: 'data', scope: 'where-undeclared', tsType: 'unknown' },
+    {
+        name: 'ariaLabel',
+        scope: 'where-undeclared',
+        tsType: 'string | { key: string; defaultValue?: string; params?: Record<string, unknown> }',
+    },
 ]);
+const basePropNames = (scope) => new Set(SDUI_BASE_PROPS.filter((prop) => prop.scope === scope).map((prop) => prop.name));
+/** The `'every-node'` members of {@link SDUI_BASE_PROPS}: never "unknown prop". */
+const BASE_PROPS = basePropNames('every-node');
+/** The `'where-undeclared'` members of {@link SDUI_BASE_PROPS}. */
+const WHERE_UNDECLARED_BASE_PROPS = basePropNames('where-undeclared');
 const isExpr = (v) => typeof v === 'object' && v !== null && '$expr' in v;
 export function validateTree(tree, manifest) {
     const diagnostics = [];
@@ -54,9 +161,23 @@ export function validateTree(tree, manifest) {
             for (const [key, value] of Object.entries(node)) {
                 if (BASE_PROPS.has(key))
                     continue;
+                // A declaration outranks a `'where-undeclared'` base prop
+                // (objectui#11044): skipped only when this type declares no input of
+                // that name, so a declared one keeps its type check below.
+                if (WHERE_UNDECLARED_BASE_PROPS.has(key) && !byName.has(key))
+                    continue;
                 const input = byName.get(key);
                 if (!input) {
-                    diagnostics.push({
+                    // The retired `body` child-list dialect gets its replacement named
+                    // rather than the bare "has no prop" every typo gets
+                    // (objectui#6771). Asked INSIDE this branch, so a component that
+                    // declares its own `body` input keeps its declared type check —
+                    // mechanism in `./body-dialect.ts`. Its containment verdict is the
+                    // SAME predicate the `children` branch below reads — the declared
+                    // `children` input, never `isContainer` (objectui#9910) — so the two
+                    // spellings cannot disagree about which components take a list.
+                    const retiredBody = checkRetiredBodyDialect(node.type, key, value, acceptsChildren(comp));
+                    diagnostics.push(retiredBody ?? {
                         severity: 'warning',
                         code: 'unknown-prop',
                         message: `<${node.type}> has no prop "${key}"`,
@@ -67,14 +188,64 @@ export function validateTree(tree, manifest) {
                 if (input.binding) {
                     bindings.push({ tag: node.type, input: key, kind: input.binding, value });
                 }
-                if (!isExpr(value)) {
+                if (isExpr(value)) {
+                    // A braced value that failed JSON materialization compiled to the
+                    // parser's deferred `{ $expr }` marker — and NOTHING downstream
+                    // evaluates that marker: this tier parses, never executes
+                    // (ADR-0080), and no renderer consumes `$expr`. The value therefore
+                    // reaches the renderer as an opaque object, every defensive
+                    // non-array/non-object read degrades it to "not declared", and the
+                    // author's binding silently vanishes (objectui#6598: eight `columns`
+                    // spellings on a data block, all eaten without a single diagnostic —
+                    // rows rendered, zero data columns). ADR-0078 prohibits exactly this
+                    // parsed-but-silently-inert state, so name it at compile time, with
+                    // the fix in the message.
+                    //
+                    // The message must name the CURRENT accepted grammar, and objectui#6614
+                    // (Q1-A, ruled 2026-08-28) moved it: `interpretBrace` now materializes
+                    // the JS literal subset, so single-quoted strings and unquoted
+                    // identifier keys REACH the renderer and can no longer draw this
+                    // warning. The old wording ("write it as JSON, double-quoted") named a
+                    // now-legal spelling as the illegal one — advice that would have sent
+                    // an author to edit working source. What is left on this side of the
+                    // boundary is a genuine expression, so that is what the message names.
+                    //
+                    // Warning, not error, per the `8d58f46b4` precedent for inert
+                    // authored keys. ⛔ Escalation to error is objectui#6614 Q2 and is
+                    // deliberately NOT part of this change: it belongs at the SAVE GATE,
+                    // once the framework wires the registry manifest into
+                    // `validate-jsx-pages` (objectstack#12719 records that gap).
+                    diagnostics.push({
+                        severity: 'warning',
+                        code: 'inert-expression',
+                        message: `<${node.type}> prop "${key}" is a braced expression this tier never evaluates — ` +
+                            `the value will be silently ignored at render. This tier materializes LITERALS only ` +
+                            `(strings, numbers, booleans, null, arrays, objects; quotes may be single or double, ` +
+                            `object keys may be unquoted), e.g. columns={['name','amount']} works — ` +
+                            `columns={rows.map((r) => r.name)} cannot`,
+                        tag: node.type,
+                    });
+                }
+                else {
                     const typeDiag = checkType(node.type, input, value);
-                    if (typeDiag)
+                    if (typeDiag) {
                         diagnostics.push(typeDiag);
+                    }
+                    else {
+                        // Members only once the CONTAINER kind was accepted. Reporting a
+                        // member of a value that is not even the declared container is two
+                        // diagnostics for one mistake, and the second one names positions
+                        // of a shape the author did not write (objectui#8067).
+                        const memberDiag = checkMemberTypes(node.type, input, value);
+                        if (memberDiag)
+                            diagnostics.push(memberDiag);
+                    }
                 }
             }
-            // containment
-            if (node.children?.length && !comp.isContainer) {
+            // containment — decided by the declared `children` input and by NOTHING
+            // else (objectui#9910 Q1-A). ⛔ No `isContainer` fallback: see
+            // `acceptsChildren` for why the flag stopped deciding this.
+            if (node.children?.length && !acceptsChildren(comp)) {
                 diagnostics.push({
                     severity: 'warning',
                     code: 'not-a-container',
@@ -82,6 +253,13 @@ export function validateTree(tree, manifest) {
                     tag: node.type,
                 });
             }
+            // Dashboard widgets: an `options` key riding the spec's `.passthrough()`
+            // that no renderer consumes is legal, silent and inert — warn, naming
+            // the consumed set (the 2026-08-23 ruling; census + scope in
+            // `./dashboard-widget-options.ts`). Like `not-a-container`, this runs
+            // only for a component the manifest knows: an unresolved tag already
+            // drew `unknown-component`, and deep diagnostics on it would be noise.
+            diagnostics.push(...checkDashboardWidgetOptions(node));
         }
         if (node.children)
             node.children.forEach(visit);
@@ -90,42 +268,155 @@ export function validateTree(tree, manifest) {
         visit(tree);
     return { diagnostics, requires: [...requires], bindings };
 }
-function checkType(tag, input, value) {
-    const mismatch = (expected) => ({
-        severity: 'warning',
-        code: 'type-mismatch',
-        message: `<${tag}> prop "${input.name}" expected ${expected}`,
-        tag,
-    });
-    switch (input.type) {
+/** The values an `enum` arm admits, flattened from either declaration form. */
+const enumValues = (input) => (input.enum ?? []).map((e) => (typeof e === 'object' ? e.value : e));
+/**
+ * Does ONE coarse arm accept this value?
+ *
+ * An arm outside the vocabulary — and `'slot'`, which describes a child
+ * position rather than a value — accepts everything, preserving the old
+ * `default: return null` branch: those inputs never drew a diagnostic and must
+ * not start now.
+ */
+function armAccepts(arm, input, value) {
+    switch (arm) {
         case 'number':
-            return typeof value === 'number' ? null : mismatch('a number');
+            return typeof value === 'number';
         case 'boolean':
-            return typeof value === 'boolean' ? null : mismatch('a boolean');
+            return typeof value === 'boolean';
         case 'string':
         case 'color':
         case 'date':
         case 'code':
         case 'file':
-            return typeof value === 'string' ? null : mismatch('a string');
+            return typeof value === 'string';
         case 'array':
-            return Array.isArray(value) ? null : mismatch('an array');
+            return Array.isArray(value);
         case 'object':
-            return typeof value === 'object' && value !== null && !Array.isArray(value)
-                ? null
-                : mismatch('an object');
-        case 'enum': {
-            const allowed = (input.enum ?? []).map((e) => (typeof e === 'object' ? e.value : e));
-            return allowed.includes(value)
-                ? null
-                : {
-                    severity: 'error',
-                    code: 'invalid-enum',
-                    message: `<${tag}> prop "${input.name}"=${JSON.stringify(value)} is not one of ${JSON.stringify(allowed)}`,
-                    tag,
-                };
-        }
+            return typeof value === 'object' && value !== null && !Array.isArray(value);
+        case 'enum':
+            return enumValues(input).includes(value);
         default:
-            return null;
+            return true;
     }
 }
+/** How one arm is named in a diagnostic message. */
+function armExpectation(arm, input) {
+    switch (arm) {
+        case 'number':
+            return 'a number';
+        case 'boolean':
+            return 'a boolean';
+        case 'array':
+            return 'an array';
+        case 'object':
+            return 'an object';
+        case 'enum':
+            return `one of ${JSON.stringify(enumValues(input))}`;
+        default:
+            return 'a string';
+    }
+}
+/**
+ * The member positions of a container value, as `[position, member]` pairs, or
+ * `null` when the value has no member position to speak of.
+ *
+ * Arrays index by position and objects by key, which is exactly the pair
+ * `ComponentInput.of` describes: array ELEMENTS, and the VALUES of an object
+ * used as a map. A scalar returns `null` rather than an empty list, so a value
+ * that only satisfied a non-container arm of a union declaration
+ * (`type: ['string', 'array'], of: 'string'`) is not reported as an empty
+ * container that trivially conforms — it is simply not the arm `of` describes.
+ */
+function memberEntries(value) {
+    if (Array.isArray(value))
+        return value.map((member, index) => [String(index), member]);
+    if (typeof value === 'object' && value !== null)
+        return Object.entries(value);
+    return null;
+}
+/**
+ * Coarse MEMBER check, over the arms `of` declares (objectui#8067).
+ *
+ * The same question `checkType` asks, one level down and with the same answer
+ * shape: ANY declared arm accepting a member clears it, a member no arm accepts
+ * is reported, and an input that declares no `of` is checked exactly as it was
+ * before the key existed — this function returns immediately on an empty arm
+ * list, so nothing published today changes severity or gains a diagnostic.
+ *
+ * ONE diagnostic per prop, naming every offending position, rather than one per
+ * member: a page that passes an array of the wrong member kind is one mistake
+ * made once, and N copies of it is the noise this repo treats as the thing that
+ * trains authors to dismiss real reports.
+ *
+ * Severity mirrors `checkType`'s rule for the same reason — `error` when an
+ * `enum` arm is present, because a closed list is the one fact this layer can
+ * be certain about; `warning` otherwise, since the coarse kind is a KIND claim
+ * and `os validate` / `os build` remain the judge of values.
+ */
+function checkMemberTypes(tag, input, value) {
+    const arms = inputTypeArms(input.of);
+    if (arms.length === 0)
+        return null;
+    const entries = memberEntries(value);
+    if (entries === null)
+        return null;
+    const offenders = entries.filter(([, member]) => !arms.some((arm) => armAccepts(arm, input, member)));
+    if (offenders.length === 0)
+        return null;
+    const expectation = arms.map((arm) => armExpectation(arm, input)).join(' or ');
+    return {
+        severity: arms.includes('enum') ? 'error' : 'warning',
+        code: 'member-type-mismatch',
+        message: `<${tag}> prop "${input.name}" expected every member to be ${expectation}` +
+            ` — ${offenders.map(([position]) => `[${position}]`).join(', ')} ` +
+            `${offenders.length === 1 ? 'is' : 'are'} not`,
+        tag,
+    };
+}
+/**
+ * Coarse type check, over the arms an input declares (objectui#3832).
+ *
+ * ANY arm accepting the value clears the prop — that is what lets a key whose
+ * contract is a union (`string | number`, or a string plus an inline
+ * translation map) be declared honestly instead of picking one arm and having
+ * this function report the other arm's legal values.
+ *
+ * When NO arm accepts it the prop is still reported; a union widens what counts
+ * as legal, it does not turn the check off. Two properties of the reporting are
+ * deliberate:
+ *
+ *  - A single-arm input produces the byte-identical diagnostic it always did,
+ *    `invalid-enum` included. This change adds a form; it does not restate the
+ *    old one.
+ *  - A multi-arm input produces ONE diagnostic naming every arm, at the
+ *    STRICTEST arm's severity — `error` when an `enum` arm is present, because
+ *    an enum's closed list is the one fact this layer can be certain about, and
+ *    a value outside it should not become dismissible merely because a second
+ *    arm was added next to it. Its code is `type-mismatch` (not `invalid-enum`)
+ *    since the reported fact is "fits none of the declared arms", and the
+ *    message carries the allowed values so the author still sees the list.
+ */
+function checkType(tag, input, value) {
+    const arms = inputTypeArms(input.type);
+    if (arms.length === 0)
+        return null;
+    if (arms.some((arm) => armAccepts(arm, input, value)))
+        return null;
+    if (arms.length === 1 && arms[0] === 'enum') {
+        return {
+            severity: 'error',
+            code: 'invalid-enum',
+            message: `<${tag}> prop "${input.name}"=${JSON.stringify(value)} is not one of ${JSON.stringify(enumValues(input))}`,
+            tag,
+        };
+    }
+    return {
+        severity: arms.includes('enum') ? 'error' : 'warning',
+        code: 'type-mismatch',
+        message: `<${tag}> prop "${input.name}" expected ${arms
+            .map((arm) => armExpectation(arm, input))
+            .join(' or ')}`,
+        tag,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/sdui-parser",
-  "version": "17.5.0",
+  "version": "17.7.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -25,13 +25,13 @@
     "dist"
   ],
   "devDependencies": {
-    "@objectstack/spec": "^17.0.0-rc.6",
-    "@object-ui/core": "17.5.0",
-    "@object-ui/react": "17.5.0"
+    "@objectstack/spec": "^17.0.0",
+    "@object-ui/core": "17.7.0",
+    "@object-ui/react": "17.7.0"
   },
   "scripts": {
-    "build": "tsc",
-    "test": "vitest run",
+    "build": "tsc && node ../../scripts/check-dist-completeness.mjs",
+    "test": "vitest run --root ../.. packages/sdui-parser/",
     "type-check": "tsc --noEmit && tsc -p tsconfig.test.json",
     "lint": "eslint ."
   }