@object-ui/react 17.6.0 → 17.7.0

package/dist/utils/paramsBag.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/** The key this rule is about. One spelling, shared by both readers. */
+export declare const PARAMS_KEY = "params";
+/**
+ * Is this value a `params` BAG this rule walks? A plain object only - see the
+ * module header for why an array `params` (the definition list) is not.
+ */
+export declare function isParamsBag(value: unknown): value is Record<string, unknown>;
+/**
+ * Visit one string leaf. `path` spells where it sits the way an author would
+ * search for it: `params.target.id`, `params.ids[0]`.
+ */
+export type ParamsLeafVisitor = (leaf: string, path: string) => unknown;
+/**
+ * Map every string leaf of a `params` bag through `visit`, at any depth, and
+ * return the result - the bag itself when nothing changed (copy on write).
+ *
+ * The evaluation memo passes the evaluator; the dev diagnostic passes a visitor
+ * that records and returns the leaf unchanged, which is what makes the two
+ * radii one radius by construction.
+ */
+export declare function mapParamsLeaves(bag: Record<string, unknown>, visit: ParamsLeafVisitor, basePath?: string): Record<string, unknown>;

package/dist/utils/paramsBag.js

@@ -0,0 +1,146 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * An action's `params` values are templates, evaluated where `properties` are
+ * (objectui#7867, ruling A, maintainer 「其他同意」 2026-09-20).
+ *
+ * ## The rule
+ *
+ * Every STRING LEAF of a node's `params` bag - the node-level `params` and
+ * `properties.params` alike, at any depth - is template-evaluated by the
+ * `SchemaRenderer` evaluation memo, with the same evaluator and the same
+ * scope (`record`, `current_user`, `page`, the host's ambient roots) that
+ * already evaluates `properties`. Before it, `params` was the one argument bag
+ * an `action:button` hands the runner, and nothing walked it: the node-level
+ * bag was never evaluated at all, and `properties.params` was ONE value of a
+ * per-value, shallow loop, so a template one level inside it was never
+ * visited. A metadata-authored `navigate_edit` could not name the record it
+ * sits on.
+ *
+ * ## Why this module exists, and why it is not in `SchemaRenderer.tsx`
+ *
+ * Two readers must agree on exactly one radius: the memo that EVALUATES the
+ * leaves, and the dev diagnostic (`unevaluatedExpression.ts`) that REPORTS the
+ * leaves still carrying `${…}` afterwards. That diagnostic's header states its
+ * own rule - "Depth: exactly the evaluator's own radius, and not one level
+ * more" - so a second copy of this walk would be a second definition of that
+ * radius, free to drift. Both import this one. It lives in its own module
+ * rather than in the diagnostic's because the memo runs in production and the
+ * diagnostic module is meant to be dead code there.
+ *
+ * ## What counts as a bag, a container and a leaf
+ *
+ * - **The bag** is a PLAIN object: an object literal or JSON object, whose
+ *   prototype is `Object.prototype` or `null`. An ARRAY `params` is not a bag:
+ *   it is the `ActionParam[]` definition list `action:button` routes to
+ *   `actionParams` for the params dialog, whose members carry predicates and
+ *   formats (`visible`, `titleFormat`, option `visibleWhen`) that are evaluated
+ *   later, against another scope. It is left untouched, as before.
+ * - **Containers** inside the bag - plain objects and arrays - are walked.
+ * - **String leaves** are handed to the visitor. Everything else is passed
+ *   through by IDENTITY and never looked inside: numbers, booleans, `null`,
+ *   `undefined`, functions, and non-plain objects (`Date`, `Map`, class
+ *   instances). Those are host-built values, not authored templates.
+ * - **Keys are never visited**, only values. A key that looks like a template
+ *   stays exactly as written.
+ * - **An expression envelope** (`{ dialect, source }`) is a plain object like
+ *   any other: it is walked, and its `source` string is a leaf. It is never
+ *   collapsed to its `source` the way a bare top-level config value is.
+ * - **Cycles** end the walk: a container already on the current path is passed
+ *   through unwalked. JSON metadata cannot carry one; a host-built schema can.
+ *
+ * ## Copy on write
+ *
+ * A container is copied only when one of its descendants changed, so a bag
+ * with no template in it comes back as the very object that went in, and a
+ * changed bag never mutates the authored one (the memo's input is the
+ * caller's schema). Nothing may depend on that identity (AGENTS.md #10); it is
+ * there so that a template-free bag stays byte-for-byte and reference-for-
+ * reference what it was.
+ */
+import { isConfigBag } from './configBag.js';
+/** The key this rule is about. One spelling, shared by both readers. */
+export const PARAMS_KEY = 'params';
+/**
+ * A plain object: an object literal / JSON object, and nothing more exotic.
+ *
+ * Built ON the package's one "is this a config bag?" answer (objectui#6761)
+ * and narrowed by prototype, rather than re-spelling the object/array test:
+ * this rule asks that question plus one more (a `Date` or class instance is a
+ * bag to {@link isConfigBag}, and is not something this walk looks inside).
+ */
+function isPlainObject(value) {
+    if (!isConfigBag(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Is this value a `params` BAG this rule walks? A plain object only - see the
+ * module header for why an array `params` (the definition list) is not.
+ */
+export function isParamsBag(value) {
+    return isPlainObject(value);
+}
+function walk(value, path, visit, onPath) {
+    if (typeof value === 'string')
+        return visit(value, path);
+    if (Array.isArray(value)) {
+        if (onPath.has(value))
+            return value;
+        onPath.add(value);
+        let copy;
+        for (let i = 0; i < value.length; i++) {
+            const next = walk(value[i], path + '[' + i + ']', visit, onPath);
+            if (next !== value[i]) {
+                if (!copy)
+                    copy = value.slice();
+                copy[i] = next;
+            }
+        }
+        onPath.delete(value);
+        return copy ?? value;
+    }
+    if (isPlainObject(value)) {
+        if (onPath.has(value))
+            return value;
+        onPath.add(value);
+        let copy;
+        for (const key of Object.keys(value)) {
+            const leaf = value[key];
+            const next = walk(leaf, path + '.' + key, visit, onPath);
+            if (next !== leaf) {
+                if (!copy)
+                    copy = { ...value };
+                // `defineProperty`, not assignment: an own `__proto__` key (which
+                // `JSON.parse` does produce) must stay an own data property rather than
+                // reach the prototype setter.
+                Object.defineProperty(copy, key, {
+                    value: next,
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                });
+            }
+        }
+        onPath.delete(value);
+        return copy ?? value;
+    }
+    return value;
+}
+/**
+ * Map every string leaf of a `params` bag through `visit`, at any depth, and
+ * return the result - the bag itself when nothing changed (copy on write).
+ *
+ * The evaluation memo passes the evaluator; the dev diagnostic passes a visitor
+ * that records and returns the leaf unchanged, which is what makes the two
+ * radii one radius by construction.
+ */
+export function mapParamsLeaves(bag, visit, basePath = PARAMS_KEY) {
+    return walk(bag, basePath, visit, new Set());
+}

package/dist/utils/propsBagDiagnostic.d.ts

@@ -0,0 +1,196 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Does this node's renderer read the `props` bag as a config bag?
+ *
+ * Exported so the report and its pins cannot drift apart: one predicate, two
+ * readers. A non-string `type` answers `false` — an untyped node cannot be in
+ * a family — and the caller has already resolved a component for it, so the
+ * unknown-type box is not in play.
+ */
+export declare function readsPropsBag(type: unknown): boolean;
+/** Prefix every line starts with — the handle tests, greps and log filters hold. */
+export declare const DROPPED_PROPS_BAG_PREFIX = "[ObjectUI] A `props` config bag was not read";
+/**
+ * Build the message. Separate from the emit so a test can assert the words a
+ * developer is going to read, not merely that something was logged.
+ */
+export declare function formatDroppedPropsBagMessage(type: unknown, id: unknown, droppedKeys: readonly string[]): string;
+/**
+ * Test-only reset for the dedupe above. Without it the second test to assert
+ * the same warning reads the first test's dedupe entry and sees silence — a
+ * green run that checked nothing.
+ */
+export declare function __resetDroppedPropsBagWarnings(): void;
+/**
+ * Which keys of the OUTGOING props bag are dropped by a `schema`-reading
+ * renderer, or `null` when there is nothing to say.
+ *
+ * Two bags are read, and needing both is a MEASUREMENT rather than caution.
+ *
+ * `outgoingPropsBag` is the bag `SchemaRenderer` actually spreads — the value
+ * of `propsWithoutCanonicalKeys(schema.props, schema.properties)`, passed in
+ * rather than re-derived. That is what makes the message honest about the two
+ * cases it must not confuse:
+ *
+ *   - a key BOTH bags declare has already been subtracted by that function
+ *     (objectui#5123: `properties` wins on both channels), so the author is
+ *     getting the canonical answer and nothing was silently dropped;
+ *   - a key only `props` declares survives into that bag, and it is exactly the
+ *     key that reaches no `schema` reader.
+ *
+ * `authoredPropsBag` is what the AUTHOR wrote, read off the original schema
+ * before the evaluation memo touched it. It is needed because that memo
+ * rebuilds the bag with `{ ...newSchema.props }` under a bare truthiness guard,
+ * so a degenerate `props: 'not-a-bag'` arrives at the spread site as
+ * `{ '0': 'n', '1': 'o', … }` — measured, not supposed. Reading only the
+ * outgoing bag would therefore report nine dropped keys named `0` … `8` and
+ * tell the author that `schema.0` is undefined, which is true and useless. A
+ * string is not a config bag; there is nothing to point at, and the shape-level
+ * defect it represents is a different question from this one.
+ *
+ * Deliberately narrow, and each exclusion is a reading rather than an omission:
+ *
+ *   - an EMPTY bag says nothing was authored and nothing was lost;
+ *   - a non-object authored `props` is the degenerate case above;
+ *   - a node in the {@link readsPropsBag} family is silent by the ruling.
+ */
+export declare function collectDroppedPropsKeys(type: unknown, authoredPropsBag: unknown, outgoingPropsBag: unknown): string[] | null;
+/**
+ * Dev-build only. Reports once per distinct message via `console.warn`, and
+ * returns the message it emitted (or `null`) so a caller or a test can read the
+ * decision rather than infer it from a spy.
+ *
+ * The caller applies the production gate, so this stays a single dev-only
+ * branch at the call site and the whole module is dead code in a production
+ * build.
+ */
+export declare function reportDroppedPropsBag(type: unknown, id: unknown, authoredPropsBag: unknown, outgoingPropsBag: unknown): string | null;
+/**
+ * Refusal: a NODE-GATE PREDICATE was parked under `props` (objectui#9108,
+ * maintainer ruling 2026-09-13, verbatim 「同意」 on the `domain:spec` seat's
+ * recommendation - REFUSE).
+ *
+ * ## The defect this refuses
+ *
+ * Measured at node level on `1e0e46af9`, four rows, both spellings and both
+ * polarities:
+ *
+ *   { type: 'card', props:      { visible: false } }  -> the node RENDERED
+ *   { type: 'card', props:      { hidden:  true  } }  -> the node RENDERED
+ *   { type: 'card', properties: { visible: false } }  -> correctly hidden
+ *   { type: 'card', properties: { hidden:  true  } }  -> correctly hidden
+ *
+ * `SchemaRenderer` hoists `properties.*` onto the node; NOTHING copies
+ * `props.*`. Both node gates read the post-hoist node, so a predicate that
+ * arrived under the alias is never one of the keys either gate can see. It is
+ * fail-OPEN and silent by construction - a gate that never bit renders exactly
+ * like a gate that said yes - so no user, no screenshot and no snapshot can
+ * find it. Only counting can.
+ *
+ * ## Why REFUSE and not HONOUR - this is a ruling, not a preference
+ *
+ * The opposite arm was implemented and CLOSED (PR objectui#9144). The ruling's
+ * decisive axis: honouring the alias would have made
+ * *"8 predicate keys work while the rest stayed silently dropped - and partly
+ * working is harder to learn from than not working"*, because the author
+ * generalises "`props` is fine" and collides again on the next key with the
+ * cause now further away. The three measured readings behind it, each with a
+ * control that fires: `@objectstack/spec` already refuses `props` by name
+ * (`unrecognized_keys ["props"]`); `skills/objectui/rules/protocol.md` teaches
+ * it as an ERROR rather than as a gap; and the producer census found ZERO
+ * authored `props` bags across `examples/**` and `content/docs/**` (controls:
+ * `visibleWhen` 9 files, `type` 488 files), so there is no capability to cut.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * It changes NO verdict and NO rendered byte. Every gate answers exactly what
+ * it answered before, nothing is hoisted, `schema.<KEY>` stays undefined for a
+ * renderer declared as `({ schema })`, and the bag reaches the element with the
+ * same keys it always did. The trap stops being SILENT; it does not stop being
+ * a trap, which is the same posture objectui#6708 took one card earlier and the
+ * only posture a diagnostic can take without becoming the honour arm the ruling
+ * refused.
+ *
+ * ## Why `console.error`, and why NOT dev-only
+ *
+ * Two established postures in this tree, and this leg needs a leg of each:
+ *
+ *   - SEVERITY from `unevaluatedExpression.ts`, which is this repo's REFUSAL
+ *     tier. Its neighbour {@link reportDroppedPropsBag} warns because it
+ *     reports a value that was dropped; the ruling's word here is *refused*,
+ *     and the sibling gate diagnostic states the split explicitly ("not the
+ *     refusal `reportUnevaluatedExpressions` emits").
+ *   - ALWAYS-ON from `visibilityDiagnostic.ts`'s unresolvable-predicate leg,
+ *     which the maintainer took out of `__DEV__` in objectui#6038 (ruling
+ *     2026-08-25, option B: "the silence is no longer an accepted property")
+ *     on the ground that a node gate which has stopped biting in production is
+ *     a class-1 defect that must not be able to sit live and undiscovered.
+ *     This is that class in its widest form - the gate never bit at all, on
+ *     every render - and the ruling's own confidence gap is about exactly the
+ *     population a `__DEV__` gate would silence: *"The producer census covers
+ *     this repository's `examples/**`, `content/docs/**` and skills corpus.
+ *     It does NOT measure authored metadata in production. If stored documents
+ *     out there do carry `props`, those authors are already suffering the
+ *     silent drop today."*
+ *
+ * The rate limit that makes an always-on console line affordable is the same
+ * one objectui#6038 required: the dedupe below is keyed on the MESSAGE, so the
+ * ceiling is one line per distinct authoring bug for the lifetime of the page,
+ * not one line per render and not one per node.
+ */
+export declare const REFUSED_PROPS_PREDICATE_PREFIX = "[ObjectUI] A node-gate predicate under `props` is REFUSED";
+/**
+ * Build the refusal message. Separate from the emit so a test can assert the
+ * words a developer is going to read, not merely that something was logged.
+ *
+ * Carries the MIGRATION LINE the ruling requires by name - *"the implementing
+ * round should pair the refusal with a named migration line in the diagnostic,
+ * not let half the keys quietly start working"*. It names the keys it refused
+ * and the two spellings that do work, and it names nothing else: there is no
+ * per-key canonical-alias table here, because inventing one would be a second
+ * declaration of ADR-0089's normalization competing with the spec's own.
+ */
+export declare function formatRefusedPropsPredicateMessage(type: unknown, id: unknown, refusedKeys: readonly string[]): string;
+/**
+ * Which node-gate predicate keys of the PARKED `props` bag are refused, or
+ * `null` when there is nothing to say.
+ *
+ * `nodeGateKeys` is passed IN rather than declared here: `SchemaRenderer` owns
+ * the two chain declarations and derives this union from them, so a leg added
+ * to either chain is covered by the same edit that adds it and this module
+ * never grows a twin list to drift from them (AGENTS.md #9).
+ *
+ * `parkedPropsBag` is the value of
+ * `propsWithoutCanonicalKeys(schema.props, schema.properties)` - the same
+ * subtraction the outgoing bag and the objectui#6708 diagnostic already use, so
+ * the two cases stay un-confused exactly as they are there: a key BOTH bags
+ * declare has already been subtracted (objectui#5123: `properties` wins, the
+ * author is getting the canonical answer and nothing is parked), while a key
+ * only `props` declares survives into that bag and is precisely the one no gate
+ * can see. A degenerate `props` contributes no keys through that same function,
+ * so `props: 'not-a-bag'` refuses nothing here - its defect is a different
+ * question (objectui#6752).
+ */
+export declare function collectRefusedPropsPredicateKeys(type: unknown, nodeGateKeys: ReadonlySet<string>, parkedPropsBag: unknown): string[] | null;
+/**
+ * Test-only reset for the dedupe above. Without it the second test to assert
+ * the same refusal reads the first test's dedupe entry and sees silence - a
+ * green run that checked nothing.
+ */
+export declare function __resetRefusedPropsPredicateWarnings(): void;
+/**
+ * Reports a node-gate predicate parked under `props`, in DEVELOPMENT AND IN
+ * PRODUCTION - read {@link REFUSED_PROPS_PREDICATE_PREFIX}'s docblock for why
+ * this leg carries neither the `__DEV__` gate nor the `console.warn` severity
+ * of its neighbour in this module.
+ *
+ * Returns the message it emitted (or `null`) so a caller or a test can read the
+ * decision rather than infer it from a spy.
+ */
+export declare function reportRefusedPropsPredicate(type: unknown, id: unknown, nodeGateKeys: ReadonlySet<string>, parkedPropsBag: unknown): string | null;