@object-ui/react 17.5.0 → 17.7.0

package/dist/utils/error-message.d.ts

@@ -12,6 +12,40 @@
  * usable can be extracted, so callers fall back to a generic localized string.
  */
 export declare function extractWriteErrorMessage(err: unknown): string | null;
+/**
+ * The refusal text the PRODUCER explicitly marked as addressed to the end user,
+ * or `null` when the refusal carries no marking.
+ *
+ * `userMessage` is the opt-in channel added by objectstack `79c46da90` (maintainer
+ * ruling 2026-08-19 on objectui#5210), declared on `ApiErrorSchema` /
+ * `EnhancedApiErrorSchema` in the pinned `@objectstack/spec`.
+ * Three properties of the contract decide this reader's whole shape:
+ *
+ *   - **Presence IS the marking.** The mark and the marked text are ONE value —
+ *     a field carrying the text, not a boolean beside `message` — so no boundary
+ *     that rewraps or substitutes `message` can promote platform prose into the
+ *     marked channel. Platform and driver code never set it.
+ *   - **Status-agnostic.** Not a 403 special case; any refusal status may carry
+ *     it. Callers must not gate this read on a status.
+ *   - **Verbatim.** The author wrote it for their user, already localized. It is
+ *     returned untouched — none of {@link extractWriteErrorMessage}'s prefix
+ *     stripping applies, because there is no machine prefix to strip.
+ *
+ * Read from the two places the adapter boundary parks the envelope, both under
+ * the SAME declared key: the error itself (`@objectstack/client` lifts a marked
+ * body onto `err.userMessage`, from either wire dialect) and `details`, which
+ * the client falls back to the whole response body — the identical pair
+ * {@link isPermissionError} reads `code` from. Deliberately NOT read: the raw
+ * JSON tail `ApiDataSource` bakes into its message string. Scraping a marking
+ * out of a transport's prose is the consumer-side guessing objectstack#3821
+ * exists to prevent; a transport that flattens the envelope should carry the
+ * field instead.
+ *
+ * Everything unmarked answers `null`, so callers keep their generic localized
+ * substitution and objectstack#3821's protection holds BY CONSTRUCTION: this
+ * function can never return text the producer did not opt in.
+ */
+export declare function declaredUserMessage(err: unknown): string | null;
 /** One field the server rejected, normalised for `form.setError`. */
 export interface WriteFieldError {
     /** Field name, matching the form control's `name`. */
@@ -50,3 +84,28 @@ export declare function extractFieldErrors(err: unknown): WriteFieldError[] | nu
  * the raw server text.
  */
 export declare function isPermissionError(err: unknown): boolean;
+/** What {@link classifyLoadError} answers. */
+export type LoadErrorKind = 'api-disabled' | 'forbidden' | 'unauthorized' | 'rejected' | 'network';
+/**
+ * Classify a failed data FETCH (as opposed to a failed write, above) by HTTP
+ * status / error code, so an error panel can say what actually happened. A
+ * 403 rendered as "check your connection" is indistinguishable from a real
+ * outage — users were told to debug their network when the server had
+ * (correctly) denied them access.
+ *
+ * Originally `ListView`'s module-local `classifyLoadError`
+ * (`packages/plugin-list/src/ListView.tsx`); lifted here (objectui#4693) so
+ * `RecordAttachmentsPanel` can reuse the same "is this retry-invariant"
+ * verdict for the `sys_attachment` list read instead of re-deriving it. Both
+ * `@object-ui/plugin-list` and `@object-ui/app-shell` already depend on this
+ * package, so the lift adds no new dependency edge to either.
+ *
+ * Purely a classifier — it returns a KIND, never rendered text. Each caller
+ * owns its own copy for what a kind means on its surface (`ListView` shows a
+ * title + message per kind and a Retry for every kind but `api-disabled`;
+ * `RecordAttachmentsPanel` only distinguishes `api-disabled` from everything
+ * else, folding `forbidden`/`unauthorized`/`rejected`/`network` into its own
+ * coarser `denied`/`unavailable` split via {@link isPermissionError}) — so
+ * lifting this function does not couple the two surfaces' i18n or copy.
+ */
+export declare function classifyLoadError(err: unknown): LoadErrorKind;

package/dist/utils/error-message.js

@@ -6,7 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * Helpers for turning a failed data-source write into user-facing feedback.
+ * Helpers for turning a failed data-source read or write into user-facing
+ * feedback.
  *
  * Different DataSource adapters throw differently shaped errors:
  *   - the ObjectStack adapter (`@object-ui/data-objectstack`) decorates the
@@ -18,6 +19,7 @@
  * These helpers normalise across both so a caller's `catch` can surface the
  * real reason (e.g. a row-level-security denial) instead of swallowing it.
  */
+import { isApiAccessDeniedError } from '@object-ui/data-objectstack';
 function firstString(...vals) {
     for (const v of vals) {
         if (typeof v === 'string' && v.trim())
@@ -68,6 +70,54 @@ export function extractWriteErrorMessage(err) {
         .trim();
     return clean || null;
 }
+/**
+ * The refusal text the PRODUCER explicitly marked as addressed to the end user,
+ * or `null` when the refusal carries no marking.
+ *
+ * `userMessage` is the opt-in channel added by objectstack `79c46da90` (maintainer
+ * ruling 2026-08-19 on objectui#5210), declared on `ApiErrorSchema` /
+ * `EnhancedApiErrorSchema` in the pinned `@objectstack/spec`.
+ * Three properties of the contract decide this reader's whole shape:
+ *
+ *   - **Presence IS the marking.** The mark and the marked text are ONE value —
+ *     a field carrying the text, not a boolean beside `message` — so no boundary
+ *     that rewraps or substitutes `message` can promote platform prose into the
+ *     marked channel. Platform and driver code never set it.
+ *   - **Status-agnostic.** Not a 403 special case; any refusal status may carry
+ *     it. Callers must not gate this read on a status.
+ *   - **Verbatim.** The author wrote it for their user, already localized. It is
+ *     returned untouched — none of {@link extractWriteErrorMessage}'s prefix
+ *     stripping applies, because there is no machine prefix to strip.
+ *
+ * Read from the two places the adapter boundary parks the envelope, both under
+ * the SAME declared key: the error itself (`@objectstack/client` lifts a marked
+ * body onto `err.userMessage`, from either wire dialect) and `details`, which
+ * the client falls back to the whole response body — the identical pair
+ * {@link isPermissionError} reads `code` from. Deliberately NOT read: the raw
+ * JSON tail `ApiDataSource` bakes into its message string. Scraping a marking
+ * out of a transport's prose is the consumer-side guessing objectstack#3821
+ * exists to prevent; a transport that flattens the envelope should carry the
+ * field instead.
+ *
+ * Everything unmarked answers `null`, so callers keep their generic localized
+ * substitution and objectstack#3821's protection holds BY CONSTRUCTION: this
+ * function can never return text the producer did not opt in.
+ */
+export function declaredUserMessage(err) {
+    if (!err || typeof err !== 'object')
+        return null;
+    const e = err;
+    // Non-empty after trimming, returned untrimmed — the same predicate
+    // `@objectstack/client` applies when it lifts the field off the wire.
+    if (typeof e.userMessage === 'string' && e.userMessage.trim())
+        return e.userMessage;
+    const details = e.details;
+    if (details && typeof details === 'object'
+        && typeof details.userMessage === 'string' && details.userMessage.trim()) {
+        return details.userMessage;
+    }
+    return null;
+}
 /**
  * Per-field errors from a rejected write, or `null` when the failure was not
  * field-scoped.
@@ -136,3 +186,68 @@ export function isPermissionError(err) {
     const text = `${typeof e.message === 'string' ? e.message : ''} ${e.details?.error ?? e.error ?? ''}`;
     return /row-level security|access denied|permission denied|not permitted/i.test(text);
 }
+/** 400-class error codes the data API returns for a request it will never accept. */
+const REJECTED_REQUEST_CODES = new Set([
+    'INVALID_FILTER',
+    'UNSUPPORTED_QUERY_PARAM',
+    'INVALID_QUERY',
+]);
+/**
+ * Classify a failed data FETCH (as opposed to a failed write, above) by HTTP
+ * status / error code, so an error panel can say what actually happened. A
+ * 403 rendered as "check your connection" is indistinguishable from a real
+ * outage — users were told to debug their network when the server had
+ * (correctly) denied them access.
+ *
+ * Originally `ListView`'s module-local `classifyLoadError`
+ * (`packages/plugin-list/src/ListView.tsx`); lifted here (objectui#4693) so
+ * `RecordAttachmentsPanel` can reuse the same "is this retry-invariant"
+ * verdict for the `sys_attachment` list read instead of re-deriving it. Both
+ * `@object-ui/plugin-list` and `@object-ui/app-shell` already depend on this
+ * package, so the lift adds no new dependency edge to either.
+ *
+ * Purely a classifier — it returns a KIND, never rendered text. Each caller
+ * owns its own copy for what a kind means on its surface (`ListView` shows a
+ * title + message per kind and a Retry for every kind but `api-disabled`;
+ * `RecordAttachmentsPanel` only distinguishes `api-disabled` from everything
+ * else, folding `forbidden`/`unauthorized`/`rejected`/`network` into its own
+ * coarser `denied`/`unavailable` split via {@link isPermissionError}) — so
+ * lifting this function does not couple the two surfaces' i18n or copy.
+ */
+export function classifyLoadError(err) {
+    const e = err;
+    // The ObjectStack client decorates errors with `httpStatus`; raw fetch
+    // wrappers surface `status` / `statusCode`; some adapters only embed the
+    // status in the message ("HTTP 403 Forbidden — …").
+    let status = [e?.httpStatus, e?.status, e?.statusCode]
+        .find((s) => typeof s === 'number');
+    if (status === undefined) {
+        const m = /HTTP (\d{3})\b/.exec(String(e?.message ?? ''));
+        if (m)
+            status = Number(m[1]);
+    }
+    const code = typeof e?.code === 'string' ? e.code.toUpperCase() : '';
+    // The object's `enable` block withholds this operation — checked FIRST, on
+    // the CODE alone (delegated to the shared predicate so this file and
+    // `@object-ui/data-objectstack` cannot drift on which codes count). Status
+    // cannot carry this verdict: the denial is a 404, the same status a missing
+    // collection and a missing record answer with, and its 405 sibling is the
+    // same status any other method rejection uses. Unlike every kind below it
+    // this one is not about the request, the session or the network — it is a
+    // permanent property of the object, identical for every persona and every
+    // retry (objectui#4408).
+    if (isApiAccessDeniedError(err))
+        return 'api-disabled';
+    if (status === 403 || code === 'PERMISSION_DENIED' || code === 'FORBIDDEN')
+        return 'forbidden';
+    if (status === 401 || code === 'UNAUTHORIZED' || code === 'UNAUTHENTICATED')
+        return 'unauthorized';
+    // The server understood the request and refused it as malformed. Retrying
+    // sends the identical bad request, so "check your connection and try again"
+    // is the same wrong advice this function exists to stop giving — one status
+    // code over. The server now rejects a `$filter` that is not a filter AST
+    // (objectstack#4121) and an unsupported `$`-parameter, both as 400.
+    if (status === 400 || REJECTED_REQUEST_CODES.has(code))
+        return 'rejected';
+    return 'network';
+}

package/dist/utils/inlineAria.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+import type { AriaProps } from '@objectstack/spec/ui';
+/**
+ * Resolves the spec's NESTED `aria` bag to the DOM attributes it declares
+ * (objectui#11051).
+ *
+ * The bag is `@objectstack/spec`'s `AriaPropsSchema`, the `aria` member a
+ * block's own props schema carries (`element:text`, `element:button`,
+ * `element:image` and `element:number` among them). It declares three keys,
+ * and each maps to one attribute:
+ *
+ *   `ariaLabel`       → `aria-label`, resolved with the spec's own
+ *                       `resolveI18nLabel` against `locale`: a plain string is
+ *                       used as written, and an inline locale map
+ *                       (`{ en: 'Order total', 'zh-CN': '订单合计' }`) gives the
+ *                       entry for the viewer's language;
+ *   `ariaDescribedBy` → `aria-describedby`;
+ *   `role`            → `role`.
+ *
+ * A key that resolves to nothing, or to an empty string, is left out of the
+ * result instead of being written as an empty or `undefined` attribute. A key
+ * the bag does not declare is not read: the spec refuses such keys when the
+ * document is parsed, so this function adds no alias for them.
+ *
+ * ## Two vocabularies, two readers (objectui#4580 Q2-B)
+ *
+ * This is NOT `SchemaRenderer`'s `resolveAriaProps`. That one reads the FLAT
+ * node keys (`BaseSchema.ariaLabel` / `ariaDescribedBy` / `role`) and resolves
+ * `ariaLabel` in objectui's KEYED vocabulary (`{ key, defaultValue?, params? }`,
+ * via `resolveKeyedI18nLabel`). The nested bag uses the INLINE locale map.
+ * Neither resolver accepts the other's shape: the keyed one returns `undefined`
+ * for a locale map, and the spec's one treats `key` / `defaultValue` as locale
+ * tags. So the two readers stay separate, as objectui#4580 Q2-B ruled.
+ *
+ * ## Why a pure function and not a hook
+ *
+ * The caller passes the locale; this function reads no React context. That
+ * lets a renderer call it anywhere in its body, including after an early
+ * return, and lets code outside React call it too. Renderers pass
+ * `useDisplayLocale()` from `@object-ui/i18n`, the locale every
+ * `resolveI18nLabel` read site in this repo resolves against (objectui#4580
+ * revised Q1-A). Like the spec's resolver, `locale` is a required parameter
+ * that may be `undefined` (which resolves as `en`), so a caller cannot forget
+ * it by accident.
+ *
+ * @param aria - The authored bag, taken directly from the node's config. A
+ *   missing bag, or a value that is not an object, gives `{}`.
+ * @param locale - BCP-47 tag of the viewer's language, e.g. `zh-CN`.
+ * @returns The attributes to spread onto the element that carries the name.
+ */
+export declare function resolveInlineAriaProps(aria: AriaProps | null | undefined, locale: string | undefined): {
+    'aria-label'?: string;
+    'aria-describedby'?: string;
+    role?: string;
+};

package/dist/utils/inlineAria.js

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+import { resolveI18nLabel as resolveInlineI18nLabel } from '@objectstack/spec/ui';
+/**
+ * Resolves the spec's NESTED `aria` bag to the DOM attributes it declares
+ * (objectui#11051).
+ *
+ * The bag is `@objectstack/spec`'s `AriaPropsSchema`, the `aria` member a
+ * block's own props schema carries (`element:text`, `element:button`,
+ * `element:image` and `element:number` among them). It declares three keys,
+ * and each maps to one attribute:
+ *
+ *   `ariaLabel`       → `aria-label`, resolved with the spec's own
+ *                       `resolveI18nLabel` against `locale`: a plain string is
+ *                       used as written, and an inline locale map
+ *                       (`{ en: 'Order total', 'zh-CN': '订单合计' }`) gives the
+ *                       entry for the viewer's language;
+ *   `ariaDescribedBy` → `aria-describedby`;
+ *   `role`            → `role`.
+ *
+ * A key that resolves to nothing, or to an empty string, is left out of the
+ * result instead of being written as an empty or `undefined` attribute. A key
+ * the bag does not declare is not read: the spec refuses such keys when the
+ * document is parsed, so this function adds no alias for them.
+ *
+ * ## Two vocabularies, two readers (objectui#4580 Q2-B)
+ *
+ * This is NOT `SchemaRenderer`'s `resolveAriaProps`. That one reads the FLAT
+ * node keys (`BaseSchema.ariaLabel` / `ariaDescribedBy` / `role`) and resolves
+ * `ariaLabel` in objectui's KEYED vocabulary (`{ key, defaultValue?, params? }`,
+ * via `resolveKeyedI18nLabel`). The nested bag uses the INLINE locale map.
+ * Neither resolver accepts the other's shape: the keyed one returns `undefined`
+ * for a locale map, and the spec's one treats `key` / `defaultValue` as locale
+ * tags. So the two readers stay separate, as objectui#4580 Q2-B ruled.
+ *
+ * ## Why a pure function and not a hook
+ *
+ * The caller passes the locale; this function reads no React context. That
+ * lets a renderer call it anywhere in its body, including after an early
+ * return, and lets code outside React call it too. Renderers pass
+ * `useDisplayLocale()` from `@object-ui/i18n`, the locale every
+ * `resolveI18nLabel` read site in this repo resolves against (objectui#4580
+ * revised Q1-A). Like the spec's resolver, `locale` is a required parameter
+ * that may be `undefined` (which resolves as `en`), so a caller cannot forget
+ * it by accident.
+ *
+ * @param aria - The authored bag, taken directly from the node's config. A
+ *   missing bag, or a value that is not an object, gives `{}`.
+ * @param locale - BCP-47 tag of the viewer's language, e.g. `zh-CN`.
+ * @returns The attributes to spread onto the element that carries the name.
+ */
+export function resolveInlineAriaProps(aria, locale) {
+    if (!aria || typeof aria !== 'object')
+        return {};
+    const out = {};
+    const label = resolveInlineI18nLabel(aria.ariaLabel, locale);
+    if (label)
+        out['aria-label'] = label;
+    if (typeof aria.ariaDescribedBy === 'string' && aria.ariaDescribedBy) {
+        out['aria-describedby'] = aria.ariaDescribedBy;
+    }
+    if (typeof aria.role === 'string' && aria.role)
+        out.role = aria.role;
+    return out;
+}

package/dist/utils/nonGridRowCeiling.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ */
+import React from 'react';
+import type { NonGridCeilingResult } from '@object-ui/core';
+/**
+ * The loud footnote a non-grid view shows when it drew only the first
+ * `NON_GRID_ROW_CEILING` rows of a larger result set (objectui#7210).
+ *
+ * Placement and tone follow objectui#7148's chart footnote — a `role="note"`
+ * line in muted small type directly under the visualisation, naming BOTH
+ * numbers, because the count is the half a reader cannot recover from the
+ * picture. A truncated schedule renders as a healthy, confident schedule of a
+ * fraction of itself; "some rows are missing" leaves it indistinguishable from
+ * a complete one, and `2,000 of 40,000` is the bit that was missing.
+ *
+ * Two sentences because there are two conditions: a known total states the
+ * fact with both numbers; an adapter that reported no `total` still gets a
+ * DEFINITE sentence (the probe row proves more rows exist), it simply cannot
+ * name how many.
+ *
+ * ## It takes the RESULT, and nothing else (objectui#7508, ruling A′)
+ *
+ * The only prop is the `NonGridCeilingResult` that `applyNonGridRowCeiling`
+ * returned. Every number the note prints is read off that one object — the
+ * drawn count is `result.rows.length`, the total is `result.total`, the
+ * verdict is `result.truncated` — so a footnote whose numbers disagree with
+ * the rows actually drawn is not something a caller can write. The earlier
+ * shape took `drawn` / `total` / `truncated` as three loose props, and every
+ * call site hand-wrote `drawn={NON_GRID_ROW_CEILING}` next to a `total` from
+ * somewhere else: an incoherent pair was expressible and nothing refused it.
+ * ⛔ No deprecated path keeps those props; there were no released consumers.
+ *
+ * Renders `null` when nothing was truncated, so a caller holding a result can
+ * mount it unconditionally and gains no wrapper element on the healthy path.
+ */
+export declare function NonGridRowCeilingNote({ result, }: {
+    /** What `applyNonGridRowCeiling` returned for the rows being drawn. */
+    result: NonGridCeilingResult;
+}): React.JSX.Element | null;

package/dist/utils/nonGridRowCeiling.js

@@ -0,0 +1,78 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useObjectTranslation, en } from '@object-ui/i18n';
+// The non-React half of the non-grid row ceiling — `NON_GRID_ROW_CEILING`,
+// `nonGridRowCeilingQuery`, `applyNonGridRowCeiling` and `NonGridCeilingResult`
+// — lives in `@object-ui/core` beside the `extractRecords` it wraps
+// (objectui#7508, ruling A′). Only the footnote is React, so only the footnote
+// is here.
+/**
+ * The loud footnote a non-grid view shows when it drew only the first
+ * `NON_GRID_ROW_CEILING` rows of a larger result set (objectui#7210).
+ *
+ * Placement and tone follow objectui#7148's chart footnote — a `role="note"`
+ * line in muted small type directly under the visualisation, naming BOTH
+ * numbers, because the count is the half a reader cannot recover from the
+ * picture. A truncated schedule renders as a healthy, confident schedule of a
+ * fraction of itself; "some rows are missing" leaves it indistinguishable from
+ * a complete one, and `2,000 of 40,000` is the bit that was missing.
+ *
+ * Two sentences because there are two conditions: a known total states the
+ * fact with both numbers; an adapter that reported no `total` still gets a
+ * DEFINITE sentence (the probe row proves more rows exist), it simply cannot
+ * name how many.
+ *
+ * ## It takes the RESULT, and nothing else (objectui#7508, ruling A′)
+ *
+ * The only prop is the `NonGridCeilingResult` that `applyNonGridRowCeiling`
+ * returned. Every number the note prints is read off that one object — the
+ * drawn count is `result.rows.length`, the total is `result.total`, the
+ * verdict is `result.truncated` — so a footnote whose numbers disagree with
+ * the rows actually drawn is not something a caller can write. The earlier
+ * shape took `drawn` / `total` / `truncated` as three loose props, and every
+ * call site hand-wrote `drawn={NON_GRID_ROW_CEILING}` next to a `total` from
+ * somewhere else: an incoherent pair was expressible and nothing refused it.
+ * ⛔ No deprecated path keeps those props; there were no released consumers.
+ *
+ * Renders `null` when nothing was truncated, so a caller holding a result can
+ * mount it unconditionally and gains no wrapper element on the healthy path.
+ */
+export function NonGridRowCeilingNote({ result, }) {
+    // ⚠️ A HOOK AT RENDER, never a module-scope `createSafeTranslation(...)`
+    // factory, and that is a correctness constraint rather than taste. This
+    // module is re-exported from `@object-ui/react`'s entry, so anything at its
+    // module scope runs on IMPORT for every consumer that touches the barrel —
+    // and a factory call there throws inside any test that partially mocks
+    // `@object-ui/i18n` with an object literal instead of `importOriginal`,
+    // before a single assertion runs. Two such files went red in CI on exactly
+    // that, and the population is repo-wide rather than knowable from here, so
+    // the call moved to where it cannot fire at import time. `en` is likewise
+    // dereferenced HERE, at render, not in a module-scope constant.
+    //
+    // `useObjectTranslation` is the one that interpolates on the provider-less
+    // path too (objectui#6219), so `{{shown}}` / `{{total}}` are filled whether
+    // or not the host mounted an `I18nProvider`. The `defaultValue` is read from
+    // the `en` pack rather than retyped: both sit in the same eagerly-loaded
+    // chunk, so a hand copy would ship identical bytes twice, and reading the
+    // pack makes an inline default that disagrees with `en` unrepresentable
+    // instead of merely policed.
+    const { t } = useObjectTranslation();
+    if (!result.truncated)
+        return null;
+    const shown = result.rows.length;
+    const text = typeof result.total === 'number'
+        ? t('common.rowCeilingNote', {
+            shown,
+            total: result.total,
+            defaultValue: en.common.rowCeilingNote,
+        })
+        : t('common.rowCeilingNoteUnknownTotal', {
+            shown,
+            defaultValue: en.common.rowCeilingNoteUnknownTotal,
+        });
+    // `shrink-0` is the note's own, not a caller's: under a `flex-1` view pane in
+    // a fixed-height host a plain sibling can be clipped out of view — the
+    // construction objectui#7148's `ChartFootnote` measured, and the reason the
+    // gantt used to pass this exact class in. Outside a flex container it does
+    // nothing, so all four views take it and no caller needs a styling prop.
+    return (_jsx("p", { role: "note", "data-row-ceiling-note": "non-grid", className: "shrink-0 px-1 py-1 text-xs text-muted-foreground", children: text }));
+}

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());
+}