@object-ui/sdui-parser 17.6.0 → 17.7.0

package/dist/validate.js

@@ -2,24 +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).
  */
 import { inputTypeArms } from './input-type.js';
 import { checkDashboardWidgetOptions } from './dashboard-widget-options.js';
-/** 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 { 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 = [];
@@ -56,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}"`,
@@ -69,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',
@@ -86,7 +255,7 @@ export function validateTree(tree, manifest) {
             }
             // Dashboard widgets: an `options` key riding the spec's `.passthrough()`
             // that no renderer consumes is legal, silent and inert — warn, naming
-            // the consumed set (objectui#5709 ruling; census + scope in
+            // 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.
@@ -148,6 +317,63 @@ function armExpectation(arm, input) {
             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).
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/sdui-parser",
-  "version": "17.6.0",
+  "version": "17.7.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -26,12 +26,12 @@
   ],
   "devDependencies": {
     "@objectstack/spec": "^17.0.0",
-    "@object-ui/core": "17.6.0",
-    "@object-ui/react": "17.6.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 ."
   }