@object-ui/sdui-parser 17.7.0 → 18.0.0

package/dist/dashboard-widget-options.d.ts

@@ -26,23 +26,18 @@
  *   dateGranularity, sortBy, sortOrder, limit   (query-affecting, framework#3588)
  *   stageOrder                                  (funnel/pyramid stage order)
  *
- * plus ONE undeclared key with a real read site:
- *
- *   description — the metric-card sub-caption channel. Read at
- *   `widgetSubCaption.ts` (`(widget.options as …)?.description`, objectui#4032
- *   item 4 — that read sat inline in `DashboardRenderer.tsx` until
- *   objectui#8889 moved it, verbatim, into the hook BOTH dashboard surfaces
- *   now call, so the authored and bundle channels compose at one decision
- *   point) and, since objectui#7293, at `DatasetWidget.tsx`'s
- *   metric branch, which renders it in the caption row; the server's
- *   `translateDashboard` OVERLAYS the `widgets.{id}.subCaption` translation
- *   onto this key (objectstack#8056, objectstack#5428 item-4: 「两个作者字段两个
- *   key」). It entered the accepted set on the translation-pipeline evidence
- *   alone — warning on a key the platform's own pipeline writes would be a
- *   false positive on legal metadata — while the dataset-bound render path
- *   displayed it nowhere. #7293 closed that gap, so `description` is now
- *   accepted for the same reason as the declared five and the accepted set no
- *   longer outruns the measured read set.
+ * and nothing else. ⛔ Not `description`: it was the metric-card sub-caption
+ * (objectui#4032 item 4, objectui#7293), read by `DatasetWidget.tsx`'s metric
+ * branch and a resolver both dashboard surfaces called, and fed by the
+ * server's `translateDashboard` overlay of the `widgets.{id}.subCaption`
+ * translation. The spec never declared it. objectui#11389 (ruling C, which
+ * reverses objectstack#5428 item 4) retires it at both ends: objectstack
+ * first, in `@objectstack/spec` 17.7.0 (the overlay is gone and the
+ * translation key is a tombstone), then the readers here. So an authored
+ * `options.description` reaches no renderer and draws this warning like any
+ * other unconsumed key. A widget keeps one authored description,
+ * `widget.description`, the card-header subtitle, which is not an `options`
+ * key and is not judged here.
  *
  * Notably NOT consumed on the path a widget really renders through:
  * `thresholds` and `format`. Both were widely believed to work; both draw this
@@ -70,10 +65,9 @@
  *     legitimate code gets deleted by the next person who hits it, which puts
  *     the claim back where it started. Leg 2 of
  *     `__tests__/dashboard-widget-options-census.test.ts` derives exactly this
- *     bound: the DatasetWidget read set is the declared set plus the
- *     sub-caption key, and neither `format` nor `thresholds` is in it. Since
- *     objectui#7293 that absence is asserted in its OWN right rather than
- *     riding on an equality whose right-hand side can grow.
+ *     bound: the DatasetWidget read set is the declared set, and neither
+ *     `format` nor `thresholds` is in it. That absence is asserted in its OWN
+ *     right rather than riding on an equality whose right-hand side can grow.
  *
  * ## Scope — where the warning deliberately does NOT fire
  *
@@ -99,7 +93,8 @@
  * `@objectstack/spec`, re-extracts the `options.<key>` reads from
  * `DatasetWidget.tsx` source text (and fails loudly if that file gains a
  * consumption shape the extractor cannot see — a spread, a destructuring, a
- * computed access), re-checks the sub-caption read site, and trips on any NEW
+ * computed access), re-checks that the retired sub-caption key has no read
+ * site left in `plugin-dashboard`, and trips on any NEW
  * file in `packages/*\/src` or `apps/*\/src` that starts reading
  * `widget.options`. A renderer change that adds or removes a consumed key
  * fails that test until this list is updated — the cost of keeping this
@@ -116,8 +111,9 @@ export declare const UNCONSUMED_WIDGET_OPTION = "unconsumed-widget-option";
 export declare const DASHBOARD_WIDGET_HOST_TYPES: ReadonlySet<string>;
 /**
  * The accepted set: every `options` key with a renderer read site on the
- * dataset-bound path, plus the sub-caption convention key. Alphabetical; the
- * warning message prints it verbatim. Derivation and evidence: file header.
+ * dataset-bound path, which is exactly the set the spec declares.
+ * Alphabetical; the warning message prints it verbatim. Derivation and
+ * evidence: file header.
  */
 export declare const CONSUMED_WIDGET_OPTION_KEYS: readonly string[];
 /**

package/dist/dashboard-widget-options.js

@@ -11,12 +11,12 @@ export const DASHBOARD_WIDGET_HOST_TYPES = new Set([
 ]);
 /**
  * The accepted set: every `options` key with a renderer read site on the
- * dataset-bound path, plus the sub-caption convention key. Alphabetical; the
- * warning message prints it verbatim. Derivation and evidence: file header.
+ * dataset-bound path, which is exactly the set the spec declares.
+ * Alphabetical; the warning message prints it verbatim. Derivation and
+ * evidence: file header.
  */
 export const CONSUMED_WIDGET_OPTION_KEYS = [
     'dateGranularity',
-    'description',
     'limit',
     'sortBy',
     'sortOrder',

package/dist/index.d.ts

@@ -29,6 +29,15 @@ export interface CompileResult {
  * → validate against the manifest → derive `requires` + binding sites.
  */
 export declare function compile(source: string, manifest: Manifest): CompileResult;
+/**
+ * The shape of one `@object-ui/types` `NodeSlotDeclaration`, restated
+ * structurally because this package imports nothing at runtime: a position in
+ * that package's key-path grammar, and whether its spelling is retired.
+ */
+export interface NodeSlotDeclarationLike {
+    readonly path: string;
+    readonly retired?: boolean;
+}
 export interface RegistryConfigLike {
     type: string;
     namespace?: string;
@@ -139,8 +148,21 @@ export declare function assertFullyLoaded(configs: RegistryConfigLike[]): void;
  * no renderer read and sailed through it green (objectstack#4413; corrected in
  * objectstack#4472). Evidence about the render path has to come from the render
  * path — see `apps/console/src/__tests__/public-block-binding-reach.test.tsx`.
+ *
+ * `opts.slotsFor` is the one exception to "copied from the registration", and
+ * it is a DECLARATION too (objectui#11170): hand it `nodeSlotsFor` from
+ * `@object-ui/types` and every entry carries `slots`, the node-slot positions
+ * that type's renderer reads besides `children`, so `validateTree` judges the
+ * nodes under them. This package has no runtime dependency and so cannot
+ * import the declaration itself; the producers that build a live manifest
+ * (`getJsxManifest` in `@object-ui/components`' page renderer, the console's
+ * manifest generator) pass it. A RETIRED position is left out here: this is
+ * the authoring tier, and the spec's own authoring walks skip the tombstoned
+ * spellings for the same reason. Without the option no `slots` key is written,
+ * so every manifest built before the option existed serialises byte-identically.
  */
 export declare function manifestFromConfigs(configs: RegistryConfigLike[], opts?: {
     only?: Set<string>;
     publicOnly?: boolean;
+    slotsFor?: (type: string) => readonly NodeSlotDeclarationLike[];
 }): Manifest;

package/dist/index.js

@@ -77,6 +77,18 @@ export function assertFullyLoaded(configs) {
  * no renderer read and sailed through it green (objectstack#4413; corrected in
  * objectstack#4472). Evidence about the render path has to come from the render
  * path — see `apps/console/src/__tests__/public-block-binding-reach.test.tsx`.
+ *
+ * `opts.slotsFor` is the one exception to "copied from the registration", and
+ * it is a DECLARATION too (objectui#11170): hand it `nodeSlotsFor` from
+ * `@object-ui/types` and every entry carries `slots`, the node-slot positions
+ * that type's renderer reads besides `children`, so `validateTree` judges the
+ * nodes under them. This package has no runtime dependency and so cannot
+ * import the declaration itself; the producers that build a live manifest
+ * (`getJsxManifest` in `@object-ui/components`' page renderer, the console's
+ * manifest generator) pass it. A RETIRED position is left out here: this is
+ * the authoring tier, and the spec's own authoring walks skip the tombstoned
+ * spellings for the same reason. Without the option no `slots` key is written,
+ * so every manifest built before the option existed serialises byte-identically.
  */
 export function manifestFromConfigs(configs, opts = {}) {
     const components = {};
@@ -85,10 +97,17 @@ export function manifestFromConfigs(configs, opts = {}) {
             continue;
         if (opts.publicOnly && c.tier !== 'public')
             continue;
+        const slots = opts.slotsFor
+            ? opts.slotsFor(c.type).filter((s) => !s.retired).map((s) => s.path)
+            : undefined;
         components[c.type] = {
             type: c.type,
             namespace: c.namespace,
             isContainer: c.isContainer,
+            // `undefined` is dropped by `JSON.stringify`, so a manifest built with
+            // no resolver — or an entry with no slots — serialises exactly as before
+            // this key existed.
+            slots: slots && slots.length > 0 ? slots : undefined,
             // The html tier's stamp, and ONLY that stamp (objectui#10735): a
             // registration's `'public'` / `'internal'` is registry mechanics the
             // manifest never carried, and `undefined` is dropped by `JSON.stringify`,

package/dist/parse.d.ts

@@ -4,7 +4,7 @@
  * A small recursive-descent parser for a CONSTRAINED JSX subset. It is
  * deliberately not a full JS/JSX parser: a bounded grammar is the point
  * (Markdoc model) — it shrinks the attack surface and the expressible-but-wrong
- * space. Output is the existing SDUI `SchemaNode` tree. Nothing is executed.
+ * space. Output is an SDUI node tree (`ParsedSchemaNode`). Nothing is executed.
  *
  * Grammar (informal):
  *   document := element                       (exactly one root)

package/dist/parse.js

@@ -4,7 +4,7 @@
  * A small recursive-descent parser for a CONSTRAINED JSX subset. It is
  * deliberately not a full JS/JSX parser: a bounded grammar is the point
  * (Markdoc model) — it shrinks the attack surface and the expressible-but-wrong
- * space. Output is the existing SDUI `SchemaNode` tree. Nothing is executed.
+ * space. Output is an SDUI node tree (`ParsedSchemaNode`). Nothing is executed.
  *
  * Grammar (informal):
  *   document := element                       (exactly one root)

package/dist/types.d.ts

@@ -2,14 +2,24 @@
  * ObjectUI — SDUI JSX-source parser (ADR-0080)
  *
  * Types shared by the constrained JSX-source compiler. The parser turns a
- * constrained JSX *text* into the existing SDUI `SchemaNode`
- * tree. It PARSES — it never executes. No `import`, no `eval`, no JS.
+ * constrained JSX *text* into an SDUI node tree (`ParsedSchemaNode`, below).
+ * It PARSES — it never executes. No `import`, no `eval`, no JS.
  */
-/** A node in the compiled SDUI tree. Mirrors `@object-ui/types` BaseSchema. */
-export type SchemaNode = SchemaElement | string;
+/**
+ * A node in the compiled SDUI tree, as parsed: an element or a text child.
+ *
+ * Not `SchemaNode`: `@object-ui/types` publishes that name for the closed
+ * AUTHORING face, a union discriminated on a literal `type` with no index
+ * signature and with primitive children admitted. This is the parser's open,
+ * as-parsed data (any `type` string, the keys as authored), neither is
+ * assignable to the other, and this package takes no runtime dependency on
+ * `@object-ui/types` to re-export from. One exported name stood for both until
+ * this declaration was renamed (objectui#6349, batch 11).
+ */
+export type ParsedSchemaNode = SchemaElement | string;
 export interface SchemaElement {
     type: string;
-    children?: SchemaNode[];
+    children?: ParsedSchemaNode[];
     [prop: string]: unknown;
 }
 export type Severity = 'error' | 'warning';
@@ -133,6 +143,19 @@ export interface ManifestComponent {
      * carry no such entry (objectui#9910; `acceptsChildren` in `validate.ts`).
      */
     inputs: ManifestInput[];
+    /**
+     * The NODE SLOTS this component's renderer reads besides `children`
+     * (objectui#11170): positions in the key-path grammar `@object-ui/types`'
+     * `NODE_SLOT_DECLARATIONS` states — `trigger`, `items[].content`,
+     * `regions[].components`. `validateTree` descends each one the way it
+     * descends `children`, so a slot-held node is judged too. Projected from
+     * that one declaration by `manifestFromConfigs`'s `slotsFor` option; the
+     * authoring tier leaves the declaration's RETIRED positions out, as the
+     * spec's own authoring walks do. ⛔ This tier keeps no slot list of its own:
+     * a manifest built without the option carries none, and the walk then
+     * follows `children` alone.
+     */
+    slots?: readonly string[];
     /**
      * LAYOUT containment (objectui#6804, objectui#9910 Q2-A): the flag the
      * react-page JSX scope builder skips and the public layout ledger lists.

package/dist/types.js

@@ -2,7 +2,7 @@
  * ObjectUI — SDUI JSX-source parser (ADR-0080)
  *
  * Types shared by the constrained JSX-source compiler. The parser turns a
- * constrained JSX *text* into the existing SDUI `SchemaNode`
- * tree. It PARSES — it never executes. No `import`, no `eval`, no JS.
+ * constrained JSX *text* into an SDUI node tree (`ParsedSchemaNode`, below).
+ * It PARSES — it never executes. No `import`, no `eval`, no JS.
  */
 export {};

package/dist/validate.d.ts

@@ -8,6 +8,13 @@
  * `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).
+ *
+ * The walk descends `children` on every node and, for a component the
+ * manifest knows, the NODE SLOTS its entry carries (`ManifestComponent.slots`,
+ * objectui#11170) — the positions besides `children` through which that
+ * renderer hands nodes back to `SchemaRenderer`, projected from the one
+ * declaration in `@object-ui/types` by `manifestFromConfigs`. ⛔ No slot list
+ * lives here.
  */
 import type { Manifest, ManifestComponent, SchemaElement, ManifestValidationResult } from './types.js';
 /**

package/dist/validate.js

@@ -8,6 +8,13 @@
  * `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).
+ *
+ * The walk descends `children` on every node and, for a component the
+ * manifest knows, the NODE SLOTS its entry carries (`ManifestComponent.slots`,
+ * objectui#11170) — the positions besides `children` through which that
+ * renderer hands nodes back to `SchemaRenderer`, projected from the one
+ * declaration in `@object-ui/types` by `manifestFromConfigs`. ⛔ No slot list
+ * lives here.
  */
 import { inputTypeArms } from './input-type.js';
 import { checkDashboardWidgetOptions } from './dashboard-widget-options.js';
@@ -126,6 +133,46 @@ 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;
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isElement = (v) => isPlainObject(v) && typeof v.type === 'string';
+/**
+ * The element nodes a slot position holds on `node`, in document order.
+ *
+ * The position is spelled in `@object-ui/types`' key-path grammar, which that
+ * package's `nodeSlotValues` implements for the other two readers and whose
+ * header states it: keys separated by `.`, a key followed by `[]` meaning each
+ * element of the array under it, and the value at the end being one node or a
+ * list of nodes. Restated here because this package imports nothing at
+ * runtime; the components-side census for objectui#11170 holds the two walks
+ * to the same answer over the same fixtures. Only element-shaped values are
+ * returned — a string child is legal in a slot and has nothing to validate.
+ */
+function slotElements(node, path) {
+    let holders = [node];
+    for (const segment of path.split('.')) {
+        const each = segment.endsWith('[]');
+        const key = each ? segment.slice(0, -2) : segment;
+        const next = [];
+        for (const holder of holders) {
+            if (!isPlainObject(holder))
+                continue;
+            const value = holder[key];
+            if (!each)
+                next.push(value);
+            else if (Array.isArray(value))
+                next.push(...value);
+        }
+        holders = next;
+    }
+    const found = [];
+    for (const holder of holders) {
+        for (const value of Array.isArray(holder) ? holder : [holder]) {
+            if (isElement(value))
+                found.push(value);
+        }
+    }
+    return found;
+}
 export function validateTree(tree, manifest) {
     const diagnostics = [];
     const requires = new Set();
@@ -263,6 +310,14 @@ export function validateTree(tree, manifest) {
         }
         if (node.children)
             node.children.forEach(visit);
+        // The node slots this component's renderer reads besides `children`
+        // (objectui#11170), as its manifest entry declares them. An unknown
+        // component has no entry and so no slots: its `unknown-component` above is
+        // the answer, and nothing under it is judged.
+        for (const path of comp?.slots ?? []) {
+            for (const element of slotElements(node, path))
+                visit(element);
+        }
     };
     if (tree)
         visit(tree);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/sdui-parser",
-  "version": "17.7.0",
+  "version": "18.0.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -25,9 +25,10 @@
     "dist"
   ],
   "devDependencies": {
-    "@objectstack/spec": "^17.0.0",
-    "@object-ui/core": "17.7.0",
-    "@object-ui/react": "17.7.0"
+    "@objectstack/spec": "^18.0.0",
+    "@object-ui/core": "18.0.0",
+    "@object-ui/react": "18.0.0",
+    "@object-ui/types": "18.0.0"
   },
   "scripts": {
     "build": "tsc && node ../../scripts/check-dist-completeness.mjs",