@object-ui/core 17.3.0 → 17.5.0

package/dist/utils/dataset-format.js

@@ -5,6 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import { formatDisplayNumber } from './number-display.js';
 /**
  * Scale a stored `percent`-field value to its DISPLAY magnitude.
  *
@@ -16,10 +17,54 @@
  * percent cell renderer (`formatPercent` in `@object-ui/fields`) and the dataset
  * measure formatter ({@link formatMeasure}) so a percent renders identically as
  * a row value and as an aggregated metric — the two surfaces can never drift.
+ *
+ * ⚠️ That last sentence was briefly FALSE, and objectui#4576 is what made it
+ * true again. Sharing the SCALING was never enough on its own: between #4553
+ * and #4576 the cell renderer got the locale's percent CONVENTION from `Intl`
+ * while {@link formatMeasure} appended a literal '%', so a German session read
+ * `1.234,5 %` in a list cell and `1.234,5%` in a dashboard measure — the same
+ * number, scaled identically, rendered under two conventions. Both ends now go
+ * through the locale's own percent affix. If a third surface ever needs percent
+ * display, it takes BOTH halves from here — the scaling AND the convention —
+ * or this promise breaks again in the same place.
  */
 export function percentDisplayValue(value) {
     return value > -1 && value < 1 ? value * 100 : value;
 }
+/**
+ * Format one number in the DISPLAY locale, surviving a malformed locale tag.
+ *
+ * THE DUPLICATE IS GONE (objectui#4576). This used to be a hand-mirrored copy
+ * of the `try`/`catch` retry inside `formatDisplayNumber` — the ONE
+ * number-display formatter — kept in step by a comment at each end because a
+ * PACKAGE BOUNDARY stood between them: `formatDisplayNumber` lived in
+ * `@object-ui/i18n`, which depends on `i18next`/`react-i18next` and
+ * peer-depends on React, and this package is the React-free engine. #4566
+ * measured the option mapping LOSSLESS across 32,760 combinations and recorded
+ * the duplication rather than crossing that boundary; #4576 removed the
+ * boundary instead, by moving the pure function DOWN into this package
+ * (`./number-display.ts`), where `@object-ui/i18n` now re-exports it.
+ *
+ * So this is a thin ADAPTER, not a second implementation: it converts the
+ * `Intl`-shaped option bag these call sites already speak into
+ * {@link DisplayNumberFormatOptions}, and every policy decision — grouping,
+ * the malformed-locale retry, the percent convention — is made in the one
+ * home. The retry is load-bearing rather than defensive: before #4566 these
+ * sites passed a literal `undefined`, which never throws, but a THREADED tag
+ * can be malformed and a bare `Intl.NumberFormat('en_US', …)` throws
+ * `RangeError` (measured — underscore instead of hyphen is the likeliest
+ * tenant-config typo), which would take the whole widget down. A bad
+ * `currency` still throws out of both attempts, which is what lets
+ * {@link formatMeasure}'s own `catch` fall through to plain-number formatting.
+ *
+ * ⚠️ `scale` is deliberately never passed. A measure carries no field `scale`
+ * (its decimals come from a numeral format PATTERN), so the grouping policy
+ * keyed on it must not fire here — which is exactly why #4566 measured the two
+ * implementations byte-identical across all 32,760 combinations.
+ */
+function formatNumberInLocale(value, locale, options) {
+    return formatDisplayNumber(value, { ...options, locale });
+}
 /**
  * Format a MEASURE value. Currency comes from the field's declared `currency`
  * (locale-correct symbol via `Intl`), NOT from a "$" baked into the format
@@ -27,8 +72,40 @@ export function percentDisplayValue(value) {
  * never a misleading "$". The numeral `format` hint (e.g. "0,0", "0.0%")
  * controls grouping / decimals / percent; it can't be baked into the row value
  * server-side (the same number feeds charts), so it is applied here.
+ *
+ * `locale` is the BCP-47 tag of the active display locale — in React, whatever
+ * `useDisplayLocale()` returns. It is optional and LAST so every existing call
+ * keeps compiling, and omitting it reproduces the previous output byte for
+ * byte (the old code passed a literal `undefined` to `Intl`, which is exactly
+ * what an omitted argument passes now).
+ *
+ * Before objectui#4566 there was no way to pass one: all three formatting sites
+ * here hard-coded `undefined`, which is neither of the repo's two locale
+ * channels — it is the MACHINE's locale. A German session read a KPI as
+ * `1,234.5` beside a grid cell rendering the same number as `1.234,5`, and
+ * inverted separators read as a different number, not an unstyled one.
+ *
+ * ── This routes through `formatDisplayNumber` (objectui#4576) ──
+ * It did not always. #4566 measured the option mapping across 32,760
+ * value × format × currency × percentScale × locale combinations and found it
+ * LOSSLESS — routing changes no byte of output, because the policy layer
+ * `formatDisplayNumber` adds over plain `Intl` is grouping suppression keyed on
+ * a field's declared `scale`, and a measure has no `scale` to feed it (decimals
+ * here come from a numeral format PATTERN, so grouping stays on and the two
+ * agree everywhere). What blocked it was the PACKAGE BOUNDARY: the formatter
+ * lived in `@object-ui/i18n`, which depends on `i18next`/`react-i18next` and
+ * peer-depends on React, while this package is the React-free engine (AGENTS.md
+ * §3: "No UI-lib deps. Logic only.") and a runtime dependency of React-FREE
+ * consumers — the `object-ui` VS Code extension and `@object-ui/data-objectstack`.
+ *
+ * #4576 removed the boundary rather than working around it: `formatDisplayNumber`
+ * is pure, so it moved DOWN into this package (`./number-display.ts`) and
+ * `@object-ui/i18n` re-exports it. The duplicate implementation this file used
+ * to carry is gone, and with it the drift that duplicate produced — see the
+ * percent note in the body, and {@link percentDisplayValue}'s promise, which
+ * is true again.
  */
-export function formatMeasure(v, format, currency, percentScale) {
+export function formatMeasure(v, format, currency, percentScale, locale) {
     if (v == null)
         return '—';
     if (typeof v !== 'number')
@@ -36,20 +113,33 @@ export function formatMeasure(v, format, currency, percentScale) {
     const decimals = format ? (format.split('.')[1]?.match(/0/g)?.length ?? 0) : undefined;
     if (currency) {
         try {
-            return new Intl.NumberFormat(undefined, {
-                style: 'currency',
+            // No `style: 'currency'` here: `formatDisplayNumber` derives that from the
+            // presence of `currency` itself, which is also what keeps its "money
+            // always groups" policy in one place instead of two.
+            return formatNumberInLocale(v, locale, {
                 currency,
                 minimumFractionDigits: decimals ?? 0,
                 maximumFractionDigits: decimals ?? 2,
-            }).format(v);
+            });
         }
         catch {
             // Unknown currency code → fall through to plain number formatting.
+            // Still reachable with a locale threaded: `formatNumberInLocale` retries
+            // without the LOCALE, and a bad currency throws out of that retry too.
         }
     }
     if (!format) {
         // No format hint → preserve the plain rendering (integers verbatim).
-        return Number.isInteger(v) ? String(v) : v.toLocaleString(undefined, { maximumFractionDigits: 2 });
+        //
+        // The integer branch stays a bare `String(v)` and is deliberately NOT
+        // localized: it is the one form here that renders no separator and no
+        // decimal mark, so there is nothing for a locale to change — and routing it
+        // through `Intl` WOULD change it, in two ways this card is not about
+        // (measured): a locale with its own numbering system would re-digit it
+        // (`ar-EG` 1234 → an Arabic-Indic spelling), and `1e21` would expand from
+        // `1e+21` to its 22 digits. Only the fractional branch below ever produced
+        // locale-dependent text, and that is the site #4566 fixes.
+        return Number.isInteger(v) ? String(v) : formatNumberInLocale(v, locale, { maximumFractionDigits: 2 });
     }
     const isPercent = format.includes('%');
     // A legacy "$" literal in the format string is still honored (explicit author
@@ -68,18 +158,49 @@ export function formatMeasure(v, format, currency, percentScale) {
     const display = isPercent
         ? (percentScale ? (percentScale === 'fraction' ? v * 100 : v) : percentDisplayValue(v))
         : v;
-    const body = display.toLocaleString(undefined, { minimumFractionDigits: decimals ?? 0, maximumFractionDigits: decimals ?? 0 });
-    return `${legacyDollar}${body}${isPercent ? '%' : ''}`;
+    // The percent sign is the LOCALE's, not a literal '%' (objectui#4576).
+    //
+    // Until #4576 this appended a hard-coded '%' to a decimal-formatted body, so
+    // a German session read `1.234,5%` from a dashboard measure beside
+    // `1.234,5 %` (no-break space — the German percent convention) from a list
+    // cell showing the SAME number, because `formatPercent` had gone through
+    // `Intl` since #4553. That contradicted {@link percentDisplayValue}'s own
+    // promise that the two surfaces "can never drift": the SCALING had stopped
+    // drifting, the CONVENTION had started. Measured to differ in de, fr, es, ru,
+    // sv, cs, fi (no-break space), tr (the sign moves to the FRONT: `%1.234,5`)
+    // and ar (its own sign plus U+061C); en, ja, zh were already identical.
+    //
+    // `style: 'percentPoints'` is what closes it, and the choice of route is
+    // measured, not incidental. `display` is already in percentage POINTS, while
+    // `Intl`'s `style: 'percent'` wants a fraction — so routing through that (the
+    // way `formatPercent` does) would mean dividing by 100 for `Intl` to multiply
+    // straight back, and that round trip is lossy at rounding TIES: 27,581 of
+    // 1,200,013 ordinary-magnitude en-US forms move (`0.175` at 2 decimals goes
+    // from `0.18%` to `0.17%`), plus `MAX_SAFE_INTEGER` and everything from 1e23
+    // up. Formatting the points directly with the percent UNIT was measured to
+    // produce a byte-identical percent affix to `style: 'percent'` across all 171
+    // locale tags tested, while moving ZERO of those 1,200,013 en forms — the
+    // same convention by a route that does not touch the value.
+    const body = formatNumberInLocale(display, locale, {
+        style: isPercent ? 'percentPoints' : 'decimal',
+        minimumFractionDigits: decimals ?? 0,
+        maximumFractionDigits: decimals ?? 0,
+    });
+    return `${legacyDollar}${body}`;
 }
 /**
  * Format a non-measure (dimension / label) value — the server already resolves
  * dimension display labels, so this only tidies numbers and nulls.
+ *
+ * `locale` follows {@link formatMeasure}: optional, last, and omitting it
+ * reproduces the previous machine-locale output byte for byte. Integers stay
+ * verbatim here for the same measured reason as there.
  */
-export function formatDimensionValue(v) {
+export function formatDimensionValue(v, locale) {
     if (v == null)
         return '—';
     if (typeof v === 'number') {
-        return Number.isInteger(v) ? String(v) : v.toLocaleString(undefined, { maximumFractionDigits: 2 });
+        return Number.isInteger(v) ? String(v) : formatNumberInLocale(v, locale, { maximumFractionDigits: 2 });
     }
     return String(v);
 }

package/dist/utils/dataset-pivot.d.ts

@@ -37,19 +37,40 @@
  *
  * Pure (no React / i18n), like its `dataset-format` neighbour.
  *
- * Known residual, tracked separately in objectstack#5666: callers encode a
- * null/undefined dimension value as a placeholder string, so it still collides
- * with a value that literally equals that placeholder. That is a property of
- * the placeholder, not of the encoding below.
+ * The empty-value encoding closed the last instance of the same assumption
+ * (objectui#4056): callers used to spell a null/undefined dimension value as
+ * the STRING `'∅'` before encoding it, so a row whose value literally IS that
+ * character shared a bucket with a row whose value is absent — the placeholder
+ * reintroduced, one level up, exactly the "no value contains this character"
+ * assumption the encoder below had just removed. An empty value is now JSON
+ * `null`, which `JSON.stringify` renders as a bare `null` no string can spell,
+ * and `pivotDimensionValue` owns that normalization so no caller has to hold a
+ * placeholder literal of its own.
  */
 /**
- * Encode a pivot BUCKET id from its dimension values.
+ * Normalize ONE raw dimension value for `pivotBucketId`: an absent value (null
+ * or undefined) becomes JSON `null`, everything else its string form.
+ *
+ * This lives here rather than at each call site because a placeholder spelled
+ * by the caller is a placeholder that can collide: `String(v ?? '∅')` put an
+ * ordinary string into the tuple, so `null` and the character `'∅'` encoded
+ * identically (objectui#4056). `null` is not a string, so nothing a dimension
+ * can hold encodes to it — the same reason the tuple is JSON rather than a
+ * delimiter join.
+ */
+export declare const pivotDimensionValue: (value: unknown) => string | null;
+/**
+ * Encode a pivot BUCKET id from its dimension values, each already normalized
+ * by `pivotDimensionValue` (empty ⇒ `null`).
  *
  * Axis-neutral on purpose: a DOWN bucket and an ACROSS bucket are the same kind
  * of thing (a dimension-value tuple), and a cross-tab with multiple across
- * dimensions collides on that axis just as readily as on the down axis.
+ * dimensions collides on that axis just as readily as on the down axis. That
+ * holds for a SINGLE-value across bucket too — a bare value is a one-element
+ * tuple, and spelling it as the raw string instead is what left the dashboard's
+ * column ids on a second, colliding encoding after the row ids were fixed.
  */
-export declare const pivotBucketId: (dimensionValues: string[]) => string;
+export declare const pivotBucketId: (dimensionValues: Array<string | null>) => string;
 /**
  * Encode the cell key for a (down bucket, across bucket) pair — the key of the
  * map a renderer reads to place a measure and to resolve a drill-through.

package/dist/utils/dataset-pivot.js

@@ -37,17 +37,38 @@
  *
  * Pure (no React / i18n), like its `dataset-format` neighbour.
  *
- * Known residual, tracked separately in objectstack#5666: callers encode a
- * null/undefined dimension value as a placeholder string, so it still collides
- * with a value that literally equals that placeholder. That is a property of
- * the placeholder, not of the encoding below.
+ * The empty-value encoding closed the last instance of the same assumption
+ * (objectui#4056): callers used to spell a null/undefined dimension value as
+ * the STRING `'∅'` before encoding it, so a row whose value literally IS that
+ * character shared a bucket with a row whose value is absent — the placeholder
+ * reintroduced, one level up, exactly the "no value contains this character"
+ * assumption the encoder below had just removed. An empty value is now JSON
+ * `null`, which `JSON.stringify` renders as a bare `null` no string can spell,
+ * and `pivotDimensionValue` owns that normalization so no caller has to hold a
+ * placeholder literal of its own.
  */
 /**
- * Encode a pivot BUCKET id from its dimension values.
+ * Normalize ONE raw dimension value for `pivotBucketId`: an absent value (null
+ * or undefined) becomes JSON `null`, everything else its string form.
+ *
+ * This lives here rather than at each call site because a placeholder spelled
+ * by the caller is a placeholder that can collide: `String(v ?? '∅')` put an
+ * ordinary string into the tuple, so `null` and the character `'∅'` encoded
+ * identically (objectui#4056). `null` is not a string, so nothing a dimension
+ * can hold encodes to it — the same reason the tuple is JSON rather than a
+ * delimiter join.
+ */
+export const pivotDimensionValue = (value) => value == null ? null : String(value);
+/**
+ * Encode a pivot BUCKET id from its dimension values, each already normalized
+ * by `pivotDimensionValue` (empty ⇒ `null`).
  *
  * Axis-neutral on purpose: a DOWN bucket and an ACROSS bucket are the same kind
  * of thing (a dimension-value tuple), and a cross-tab with multiple across
- * dimensions collides on that axis just as readily as on the down axis.
+ * dimensions collides on that axis just as readily as on the down axis. That
+ * holds for a SINGLE-value across bucket too — a bare value is a one-element
+ * tuple, and spelling it as the raw string instead is what left the dashboard's
+ * column ids on a second, colliding encoding after the row ids were fixed.
  */
 export const pivotBucketId = (dimensionValues) => JSON.stringify(dimensionValues);
 /**

package/dist/utils/dom-props.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 RUNTIME EXECUTOR of the SDUI widget prop contract's DOM pass-through
+ * (objectui#4425 phase 2, promoting objectui#3291's whitelist from
+ * `packages/fields` to every registered SDUI widget).
+ *
+ * ## The defect this closes
+ *
+ * `SchemaRenderer` hands a registered component the authored node's own keys,
+ * the contents of its `props` container, the ARIA it resolved, and the host's
+ * trailing props — then a widget ending in a bare `{...props}` spread puts all
+ * of it on a DOM element. React passes unknown lowercase attributes through in
+ * complete silence and stringifies object values, so the failure is invisible:
+ *
+ * ```
+ * <div id="canary-node" name="canary_node" bind="data.revenue"
+ *      events="[object Object]" arialabel="Canary label"
+ *      datasource="[object Object]" props="[object Object]" …>
+ * ```
+ *
+ * That is one real measurement, from `plugin-chatbot:chatbot` on the sweep gate
+ * (`packages/app-shell/src/__tests__/widget-dom-leak-sweep.test.tsx`).
+ *
+ * ## Why a whitelist, and not a list of keys to drop
+ *
+ * Measured, not assumed. objectui#4357/PR #4428 answered the same defect in
+ * `plugin-dashboard` with a deny-list: it closed every one of the seven keys it
+ * enumerated, and the sweep still found the OPEN TAIL leaking on the same two
+ * components — `zzcanary`, `reference_to`, an authored `props: { colorVariant }`
+ * — because a deny-list can only name what already exists. The set of keys an
+ * author may put on a node is unbounded; the set a widget may put on an element
+ * is declared. A deny-list bounded by enumeration cannot be finished; a
+ * whitelist bounded by declaration can.
+ *
+ * ## The set, and why each key is in it
+ *
+ * Every key here is either injected by `SchemaRenderer` for the whole SDUI
+ * contract, or a GLOBAL HTML attribute legal on whatever element a widget
+ * renders — this helper cannot know that element, so nothing element-specific
+ * belongs here:
+ *
+ *  - `id` — global; `SchemaRenderer` carries the node's id.
+ *  - `className` — global (`class`); the styling channel AGENTS.md #3 requires
+ *    every widget to expose, and the carrier of ADR-0065's scope class.
+ *  - `role` — the third member of `@objectstack/spec`'s `AriaPropsSchema`,
+ *    resolved and injected by `SchemaRenderer.resolveAriaProps` alongside
+ *    `aria-label` / `aria-describedby`. Withholding it would make an authored
+ *    `role` type-check, read as supported, and silently never arrive — the
+ *    DECLARED-BUT-NOT-DELIVERED failure this repo treats as first class.
+ *  - `tabIndex`, `autoFocus` — global HTML attributes.
+ *  - `onClick`, `onBlur`, `onFocus` — React synthetic handlers, which never
+ *    become attributes at all.
+ *
+ * Plus the two OPEN families, matched by prefix so no per-attribute list is
+ * needed: `aria-*` (the resolved ARIA above — note the camelCase `ariaLabel` /
+ * `ariaDescribedBy` the author wrote do NOT match, which is the point: they are
+ * meaningless to assistive technology and the resolver already emitted the
+ * hyphenated forms) and `data-*` (open in HTML too, and how `data-obj-id` /
+ * `data-obj-type` / the debug attributes reach the element).
+ *
+ * ## Deliberately NOT here
+ *
+ * `name` and `disabled` are legal only on FORM CONTROLS, not on the container a
+ * typical SDUI widget renders — `name` on a `<div>` is exactly one of the 14
+ * leaked attributes this closes. `@object-ui/fields` declares both, because
+ * every widget there renders a control and its contract
+ * (`FieldWidgetComponentProps`) says so; that package keeps its own declared key
+ * list and calls {@link pickDomProps} with it. One MECHANISM, two DECLARATIONS,
+ * each bound to the contract it executes — not two judges.
+ *
+ * A semantic prop is CONSUMED, never forwarded: a widget that can be disabled
+ * reads `disabled` and applies it (see `plugin-chatbot`'s registrations), which
+ * is what keeps `disabledOn` working without putting `disabled="true"` on a
+ * `<div>`.
+ *
+ * Deliberate DOM pass-through beyond this set stays available the objectui#4435
+ * way — DECLARE it (`interface Props extends HTMLAttributes<HTMLDivElement>`)
+ * and forward it by name. Do not reopen the spread (AGENTS.md #0.1: fix the
+ * contract, never widen the consumer).
+ */
+export declare const SDUI_DOM_PASS_THROUGH_KEYS: readonly ["id", "className", "role", "tabIndex", "autoFocus", "onClick", "onBlur", "onFocus"];
+/** A key {@link toDomProps} forwards by name (the open families are prefixes). */
+export type SduiDomPassThroughKey = (typeof SDUI_DOM_PASS_THROUGH_KEYS)[number];
+/**
+ * `aria-*` and `data-*` are open families — open in HTML, and open in the
+ * widget contract — so they are matched by prefix rather than enumerated.
+ *
+ * Note what this does NOT match: `dataSource`. The injected data-source ADAPTER
+ * is not a `data-` attribute, and a prefix test that accepted it would put
+ * `datasource="[object Object]"` on the element of every data-bound widget —
+ * the one leak a schema-only measurement cannot see, because it only appears
+ * when a host really supplies an adapter (objectui#4428).
+ */
+export declare function isOpenDomAttributeFamily(key: string): boolean;
+/** The subset of `P` a whitelist of `K` forwards, with each key's declared type. */
+export type DomProps<P, K extends string = SduiDomPassThroughKey> = Pick<P, Extract<keyof P, K>> & {
+    [Key in Extract<keyof P, `data-${string}` | `aria-${string}`>]: P[Key];
+};
+/**
+ * The MECHANISM: keep the keys a caller's contract declares as DOM-safe plus
+ * the two open families, drop everything else.
+ *
+ * Exported for the one caller whose contract declares a different set —
+ * `@object-ui/fields`, whose widgets render form controls and whose
+ * `FieldWidgetComponentProps` therefore declares `name` and `disabled` as DOM
+ * pass-through (objectui#3291). Everything else should call {@link toDomProps},
+ * which is this function with the SDUI contract's own set already applied.
+ */
+export declare function pickDomProps<P extends object, K extends string>(props: P, keys: readonly K[]): DomProps<P, K>;
+/**
+ * Keep only what may legitimately become a DOM attribute on a registered SDUI
+ * widget's host element, and drop everything else — the injected `schema`, the
+ * data-source adapter, the authored node's metadata, the `props` container, and
+ * any extra key an author put on the node.
+ *
+ * Replaces the bare `{...props}` spread in a widget registration:
+ *
+ * ```tsx
+ * // before — forwards whatever `SchemaRenderer` handed it
+ * ({ schema, className, ...props }) => <Chatbot className={className} {...props} />
+ *
+ * // after
+ * ({ schema, className, ...props }) => (
+ *   <Chatbot {...toDomProps(props)} className={className} />
+ * )
+ * ```
+ *
+ * Semantic props a widget INTERPRETS (`disabled`, and everything it reads off
+ * `schema`) are read as before; this function only governs what gets spread.
+ */
+export declare function toDomProps<P extends object>(props: P): DomProps<P>;

package/dist/utils/dom-props.js

@@ -0,0 +1,153 @@
+/**
+ * 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 RUNTIME EXECUTOR of the SDUI widget prop contract's DOM pass-through
+ * (objectui#4425 phase 2, promoting objectui#3291's whitelist from
+ * `packages/fields` to every registered SDUI widget).
+ *
+ * ## The defect this closes
+ *
+ * `SchemaRenderer` hands a registered component the authored node's own keys,
+ * the contents of its `props` container, the ARIA it resolved, and the host's
+ * trailing props — then a widget ending in a bare `{...props}` spread puts all
+ * of it on a DOM element. React passes unknown lowercase attributes through in
+ * complete silence and stringifies object values, so the failure is invisible:
+ *
+ * ```
+ * <div id="canary-node" name="canary_node" bind="data.revenue"
+ *      events="[object Object]" arialabel="Canary label"
+ *      datasource="[object Object]" props="[object Object]" …>
+ * ```
+ *
+ * That is one real measurement, from `plugin-chatbot:chatbot` on the sweep gate
+ * (`packages/app-shell/src/__tests__/widget-dom-leak-sweep.test.tsx`).
+ *
+ * ## Why a whitelist, and not a list of keys to drop
+ *
+ * Measured, not assumed. objectui#4357/PR #4428 answered the same defect in
+ * `plugin-dashboard` with a deny-list: it closed every one of the seven keys it
+ * enumerated, and the sweep still found the OPEN TAIL leaking on the same two
+ * components — `zzcanary`, `reference_to`, an authored `props: { colorVariant }`
+ * — because a deny-list can only name what already exists. The set of keys an
+ * author may put on a node is unbounded; the set a widget may put on an element
+ * is declared. A deny-list bounded by enumeration cannot be finished; a
+ * whitelist bounded by declaration can.
+ *
+ * ## The set, and why each key is in it
+ *
+ * Every key here is either injected by `SchemaRenderer` for the whole SDUI
+ * contract, or a GLOBAL HTML attribute legal on whatever element a widget
+ * renders — this helper cannot know that element, so nothing element-specific
+ * belongs here:
+ *
+ *  - `id` — global; `SchemaRenderer` carries the node's id.
+ *  - `className` — global (`class`); the styling channel AGENTS.md #3 requires
+ *    every widget to expose, and the carrier of ADR-0065's scope class.
+ *  - `role` — the third member of `@objectstack/spec`'s `AriaPropsSchema`,
+ *    resolved and injected by `SchemaRenderer.resolveAriaProps` alongside
+ *    `aria-label` / `aria-describedby`. Withholding it would make an authored
+ *    `role` type-check, read as supported, and silently never arrive — the
+ *    DECLARED-BUT-NOT-DELIVERED failure this repo treats as first class.
+ *  - `tabIndex`, `autoFocus` — global HTML attributes.
+ *  - `onClick`, `onBlur`, `onFocus` — React synthetic handlers, which never
+ *    become attributes at all.
+ *
+ * Plus the two OPEN families, matched by prefix so no per-attribute list is
+ * needed: `aria-*` (the resolved ARIA above — note the camelCase `ariaLabel` /
+ * `ariaDescribedBy` the author wrote do NOT match, which is the point: they are
+ * meaningless to assistive technology and the resolver already emitted the
+ * hyphenated forms) and `data-*` (open in HTML too, and how `data-obj-id` /
+ * `data-obj-type` / the debug attributes reach the element).
+ *
+ * ## Deliberately NOT here
+ *
+ * `name` and `disabled` are legal only on FORM CONTROLS, not on the container a
+ * typical SDUI widget renders — `name` on a `<div>` is exactly one of the 14
+ * leaked attributes this closes. `@object-ui/fields` declares both, because
+ * every widget there renders a control and its contract
+ * (`FieldWidgetComponentProps`) says so; that package keeps its own declared key
+ * list and calls {@link pickDomProps} with it. One MECHANISM, two DECLARATIONS,
+ * each bound to the contract it executes — not two judges.
+ *
+ * A semantic prop is CONSUMED, never forwarded: a widget that can be disabled
+ * reads `disabled` and applies it (see `plugin-chatbot`'s registrations), which
+ * is what keeps `disabledOn` working without putting `disabled="true"` on a
+ * `<div>`.
+ *
+ * Deliberate DOM pass-through beyond this set stays available the objectui#4435
+ * way — DECLARE it (`interface Props extends HTMLAttributes<HTMLDivElement>`)
+ * and forward it by name. Do not reopen the spread (AGENTS.md #0.1: fix the
+ * contract, never widen the consumer).
+ */
+export const SDUI_DOM_PASS_THROUGH_KEYS = [
+    'id',
+    'className',
+    'role',
+    'tabIndex',
+    'autoFocus',
+    'onClick',
+    'onBlur',
+    'onFocus',
+];
+/**
+ * `aria-*` and `data-*` are open families — open in HTML, and open in the
+ * widget contract — so they are matched by prefix rather than enumerated.
+ *
+ * Note what this does NOT match: `dataSource`. The injected data-source ADAPTER
+ * is not a `data-` attribute, and a prefix test that accepted it would put
+ * `datasource="[object Object]"` on the element of every data-bound widget —
+ * the one leak a schema-only measurement cannot see, because it only appears
+ * when a host really supplies an adapter (objectui#4428).
+ */
+export function isOpenDomAttributeFamily(key) {
+    return key.startsWith('data-') || key.startsWith('aria-');
+}
+/**
+ * The MECHANISM: keep the keys a caller's contract declares as DOM-safe plus
+ * the two open families, drop everything else.
+ *
+ * Exported for the one caller whose contract declares a different set —
+ * `@object-ui/fields`, whose widgets render form controls and whose
+ * `FieldWidgetComponentProps` therefore declares `name` and `disabled` as DOM
+ * pass-through (objectui#3291). Everything else should call {@link toDomProps},
+ * which is this function with the SDUI contract's own set already applied.
+ */
+export function pickDomProps(props, keys) {
+    const allowed = new Set(keys);
+    const domProps = {};
+    for (const key of Object.keys(props)) {
+        if (allowed.has(key) || isOpenDomAttributeFamily(key)) {
+            domProps[key] = props[key];
+        }
+    }
+    return domProps;
+}
+/**
+ * Keep only what may legitimately become a DOM attribute on a registered SDUI
+ * widget's host element, and drop everything else — the injected `schema`, the
+ * data-source adapter, the authored node's metadata, the `props` container, and
+ * any extra key an author put on the node.
+ *
+ * Replaces the bare `{...props}` spread in a widget registration:
+ *
+ * ```tsx
+ * // before — forwards whatever `SchemaRenderer` handed it
+ * ({ schema, className, ...props }) => <Chatbot className={className} {...props} />
+ *
+ * // after
+ * ({ schema, className, ...props }) => (
+ *   <Chatbot {...toDomProps(props)} className={className} />
+ * )
+ * ```
+ *
+ * Semantic props a widget INTERPRETS (`disabled`, and everything it reads off
+ * `schema`) are read as before; this function only governs what gets spread.
+ */
+export function toDomProps(props) {
+    return pickDomProps(props, SDUI_DOM_PASS_THROUGH_KEYS);
+}

package/dist/utils/normalize-list-view.d.ts

@@ -35,13 +35,33 @@ export declare const DENSITY_MODE_TO_ROW_HEIGHT: Record<DensityMode, RowHeight>;
  */
 export declare const ROW_HEIGHT_TO_DENSITY_MODE: Record<RowHeight, DensityMode>;
 /**
- * Tolerant reader for {@link ROW_HEIGHT_TO_DENSITY_MODE}. View metadata is
- * user-authored, so `rowHeight` is not guaranteed to be one of the five spec
- * values — an unknown one lands on `comfortable` rather than rendering an
- * undefined density. Keeping the fallback here means every surface collapses
- * the same way.
+ * Runtime reader for {@link ROW_HEIGHT_TO_DENSITY_MODE}: the spec's five row
+ * heights narrowed onto the renderer's three densities, and **nothing else**.
+ *
+ * The parameter stays `unknown` because this is the boundary user-authored view
+ * metadata actually crosses — `ListViewSchema.rowHeight` is statically a
+ * `RowHeight`, but the value arrives from stored view definitions TypeScript
+ * never saw (`ObjectView`: `viewDef.rowHeight ?? listSchema.rowHeight`). The
+ * type-level half of the guarantee is the `Record<RowHeight, …>` on the table
+ * above, which fails the build when the spec grows a row height.
+ *
+ * An off-spec value gets NO density (objectui#4440). It used to be coerced to
+ * `comfortable`, which is the opposite of what `@object-ui/react`'s spec bridge
+ * answers for the same string after objectui#4352 — one metadata-driven system
+ * holding two answers for one input. AGENTS.md #0.1 decides which one survives:
+ * a renderer-side rehabilitation of off-spec metadata is a second de-facto
+ * contract, and one strict contract beats N. The producer is where a bad
+ * `rowHeight` gets fixed.
+ *
+ * Callers apply their own "nothing was said" default to `undefined`, so an
+ * off-spec row height now renders exactly like an absent one — `'compact'` in
+ * both `ListView` and `ObjectGrid`.
+ *
+ * `hasOwnProperty`, not `in`: `in` walks the prototype chain, so `'toString'`
+ * used to come back as `Object.prototype.toString` — a FUNCTION returned from
+ * something typed `DensityMode`.
  */
-export declare function rowHeightToDensityMode(rowHeight: unknown): DensityMode;
+export declare function rowHeightToDensityMode(rowHeight: unknown): DensityMode | undefined;
 /**
  * ObjectUI's `list-view` node historically used a different vocabulary from
  * `@objectstack/spec` for the same concepts (`fields` where the spec says