@object-ui/react 17.3.0 → 17.6.0

package/dist/element-data-source/ElementDataSourceGate.js

@@ -0,0 +1,274 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * 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.
+ *
+ * Mapping half of consuming `PageComponentSchema.dataSource` — the spec's
+ * `ElementDataSourceSchema` per-element data binding (objectstack#5576 landed
+ * the resolution; objectstack#6953 wires it to the remaining blocks).
+ *
+ * `@object-ui/core` owns the pure half (telling the binding apart from a runtime
+ * adapter, matching a view name, composing the view with the binding's own
+ * keys). {@link useElementDataSource} owns the fetch half. This module owns the
+ * LAST hop: writing the composed result onto the schema keys a given block
+ * actually reads, and rendering the two non-final states.
+ *
+ * It exists because that hop was the part every block would otherwise copy.
+ * `dataSource` is declared on EVERY page component, so eight blocks need the
+ * same precedence table (below) with only the KEY NAMES differing — which is a
+ * mapping description, not eight algorithms. A per-block copy is how the two
+ * halves drift: one block ANDs the filters and the next replaces them, and the
+ * spec's "additional filter criteria" quietly becomes two dialects.
+ *
+ * `plugin-list`'s `ListViewBlock` carried the ORIGINAL copy of the table
+ * (objectstack#5576, which predates this module) and was collapsed onto this one
+ * by objectui#4038 — on the acceptance criterion that objectstack#5576's whole
+ * suite passes against this implementation untouched, which it does. Every
+ * object-bound block now reads the rules below from here, so this is the one
+ * place a change to them belongs.
+ *
+ * ## Precedence — one table, applied everywhere
+ *
+ * Three kinds of value arrive and they do not have the same standing:
+ *
+ *  - **`dataSource.*` keys are authoritative.** The author wrote them on THIS
+ *    placement and the spec says the binding "overrides page-level object
+ *    context", so they beat the component's own same-named key.
+ *  - **View-sourced values are a baseline.** A `view` is a *reference*; a key
+ *    written on the component itself is more specific than the view it points
+ *    at, so the component's key wins over one the view supplied.
+ *  - **`filter` never overrides — it combines.** The spec describes the
+ *    binding's filter as "*Additional* filter criteria", so component filter,
+ *    view filter and binding filter all AND together through
+ *    {@link mergeFilterNodes}. A binding can only narrow what the view already
+ *    restricts, never widen it: a mistyped per-element filter cannot expose rows
+ *    the saved view excluded.
+ *
+ * An authored-but-EMPTY `columns` counts as "not authored": `[]` is what the
+ * designer emits for an unconfigured column list, and supplying the columns is
+ * exactly why a view was named.
+ *
+ * ## What a mapping may NOT do
+ *
+ * {@link ElementDataSourceMapping} names only keys the target block genuinely
+ * reads. Writing a composed key onto a schema key the block ignores would
+ * reproduce the very defect this wiring removes — a value accepted and dropped —
+ * one layer further in, where it is even harder to see. A block with no row cap
+ * therefore leaves `limit` unmapped rather than parking it somewhere plausible,
+ * and the gap is recorded at the call site instead of being papered over here.
+ *
+ * ## A block with no ADAPTER fails loudly too (objectui#5378)
+ *
+ * The section below is about an unresolvable view NAME. The coarser failure —
+ * no runtime adapter reached the block at all — used to render an empty shell
+ * in exactly the same silence, and that is what `requiresDataSource` +
+ * {@link NoDataSourcePanel} now report. Measured on the published
+ * getting-started guide: all five of its blocks resolved no adapter, fetched
+ * nothing, and said nothing. The two panels are deliberately the same shape;
+ * they answer "which view?" and "which data source?", and an author who sees
+ * either one is being told where to look.
+ *
+ * ## An unresolvable `view` fails loudly
+ *
+ * When the named view does not exist the gate renders a configuration error
+ * instead of letting the block fall back to the object's default scope. Silently
+ * widening a named view to "all records" is the failure class the binding exists
+ * to remove, and it is the one an AI-authored page hides best: the page looks
+ * like it works.
+ */
+import * as React from 'react';
+import { isElementDataSourceConfig, mergeFilterNodes, } from '@object-ui/core';
+import { useElementDataSource, } from '../hooks/useElementDataSource.js';
+import { SchemaRendererContext } from '../context/SchemaRendererContext.js';
+const readLimit = (base, key) => {
+    if (key === 'pagination.pageSize')
+        return base.pagination?.pageSize;
+    return base[key];
+};
+const writeLimit = (next, base, key, limit) => {
+    if (key === 'pagination.pageSize') {
+        next.pagination = { ...(base.pagination ?? {}), pageSize: limit };
+        return;
+    }
+    next[key] = limit;
+};
+/**
+ * Resolve a block's `dataSource` binding and apply it to the block's own schema
+ * keys, per {@link ElementDataSourceMapping}.
+ *
+ * @param schema     The block's schema node (its `dataSource` is read).
+ * @param mapping    Which schema keys this block reads.
+ * @param dataSource Explicit adapter; falls back to `SchemaRendererContext`.
+ *
+ * @example
+ * ```tsx
+ * const bound = useElementDataSourceSchema(schema, { filter: true, sort: true });
+ * if (bound.status === 'missing') return <ElementDataSourceErrorPanel message={bound.error} />;
+ * return <ObjectCalendar schema={bound.schema} />;
+ * ```
+ */
+export function useElementDataSourceSchema(schema, mapping = {}, dataSource) {
+    // Defence in depth for the collision the binding and the adapter share by
+    // NAME: even though `SchemaRenderer` no longer spreads `schema.dataSource` as
+    // a prop, a host (or an older cached bundle) handing us the spec BINDING under
+    // this argument must never be mistaken for an adapter — that is how a
+    // spec-compliant page reported "this data source cannot list the saved views".
+    // Same guard `ListViewBlock` carries, applied for every block at once.
+    const adapter = isElementDataSourceConfig(dataSource) ? undefined : dataSource;
+    const binding = useElementDataSource(schema, adapter);
+    const { object: objectKey = 'objectName', columns, filter, sort, limit, viewType } = mapping;
+    const mapped = React.useMemo(() => {
+        const composed = binding.composed;
+        if (!composed)
+            return schema;
+        const base = (schema ?? {});
+        const next = { ...base };
+        if (objectKey !== false)
+            next[objectKey] = composed.object;
+        if (columns) {
+            // `[]` is the designer's "not configured yet", and supplying the columns
+            // is the reason a view was named — so an empty authored list yields.
+            const authored = Array.isArray(base.columns) && base.columns.length > 0;
+            if (!authored && composed.columns !== undefined)
+                next.columns = composed.columns;
+        }
+        if (filter) {
+            // Component filter AND (view filter AND binding filter). `composed.filter`
+            // already carries the latter pair; a single surviving source comes back
+            // unwrapped, so the common "only the view filters" case stays flat.
+            const merged = mergeFilterNodes(base.filter, composed.filter);
+            if (merged !== undefined)
+                next.filter = merged;
+            else
+                delete next.filter;
+        }
+        // `composed.sort`/`composed.limit` are the BINDING's when it declared one,
+        // else the view's — so the component's own key may only win over the latter.
+        if (sort && composed.sort !== undefined) {
+            const fromView = binding.config?.sort === undefined;
+            if (!fromView || base.sort === undefined)
+                next.sort = composed.sort;
+        }
+        if (limit && composed.limit !== undefined) {
+            const fromView = binding.config?.limit === undefined;
+            if (!fromView || readLimit(base, limit) === undefined) {
+                writeLimit(next, base, limit, composed.limit);
+            }
+        }
+        if (viewType && composed.viewType !== undefined && base.viewType === undefined) {
+            next.viewType = composed.viewType;
+        }
+        return next;
+    }, [schema, binding.composed, binding.config, objectKey, columns, filter, sort, limit, viewType]);
+    return React.useMemo(() => ({
+        status: binding.status,
+        schema: mapped,
+        config: binding.config,
+        error: binding.error,
+    }), [binding.status, binding.config, binding.error, mapped]);
+}
+/**
+ * The "named view does not resolve" panel. Same posture (and shape) as
+ * `SchemaRenderer`'s "Unknown component type": authored metadata pointing at
+ * something that is not there, reported where the author can see it.
+ */
+export function ElementDataSourceErrorPanel({ testId, title = 'This component’s data source could not be resolved', message, }) {
+    return (_jsxs("div", { className: "p-4 border border-red-500 rounded text-red-500 bg-red-50 my-2", role: "alert", "data-testid": `${testId}-datasource-error`, children: [_jsx("p", { className: "font-medium", children: title }), message ? _jsx("p", { className: "text-sm mt-1", children: message }) : null] }));
+}
+/**
+ * The "saved views are still being fetched" placeholder. Distinct from the error
+ * panel because a component that treated "not resolved yet" as "does not exist"
+ * would flash a configuration error on every mount.
+ */
+export function ElementDataSourceLoadingPanel({ testId, }) {
+    return (_jsx("div", { className: "p-2 text-sm text-muted-foreground animate-pulse", role: "status", "aria-live": "polite", "data-testid": `${testId}-resolving-view`, children: "Loading view\u2026" }));
+}
+/**
+ * The adapter this block would use, resolved the one way every block in the
+ * family resolves it: an explicit value first, the `SchemaRendererProvider`
+ * context second.
+ *
+ * The `isElementDataSourceConfig` guard is the same one
+ * {@link useElementDataSourceSchema} applies — a host handing us the spec
+ * BINDING under this name is handing us metadata, not an adapter, and counting
+ * it as one is how "no data source" reads as "resolved".
+ *
+ * `T` is what the CALLER expects to have been injected, and the assertion is
+ * the caller's, not this hook's: an adapter arrives here as a `dataSource` prop
+ * or a context value that nothing in this package can narrow, so the type has
+ * to be declared by whoever knows which interface their block consumes. Leave
+ * it off and you get `unknown`, which is the honest default.
+ */
+export function useResolvedDataSource(explicit) {
+    const context = React.useContext(SchemaRendererContext);
+    const named = isElementDataSourceConfig(explicit) ? undefined : explicit;
+    return (named ?? context?.dataSource ?? undefined);
+}
+/**
+ * The author-facing sentence a block with no adapter says out loud.
+ *
+ * One wording for the whole object-bound family, because the reader's mistake
+ * is the same one every time and the fix is the same one every time: the
+ * adapter is injected by an ANCESTOR (`SchemaRendererProvider`), so nothing
+ * written on the block itself can supply it. Naming the block and the object
+ * it was about to read is what turns "nothing happened" into an address.
+ */
+export function noDataSourceMessage(blockKey, objectName) {
+    const target = typeof objectName === 'string' && objectName.trim().length > 0
+        ? `“${objectName}”`
+        : 'its object';
+    return (`“${blockKey}” has no data source, so it cannot read ${target}. ` +
+        `Inject one from an ancestor — <SchemaRendererProvider dataSource={…}> from ` +
+        `@object-ui/react — or hand this block a dataSource of its own.`);
+}
+/**
+ * The "this block resolved no adapter" panel — objectui#5378 item 2, and the
+ * #5349 shape it belongs to.
+ *
+ * Until this existed, a block that resolved no adapter rendered an EMPTY SHELL:
+ * `object-grid` painted a header-only table, `object-form` a field-less card,
+ * `detail-view` nothing at all — no error, no warning, no empty state that
+ * explained itself. Measured on the published getting-started guide
+ * (`content/docs/guide/building-crud-app.md`), every one of its five blocks was
+ * in that state and the page reported success while fetching nothing.
+ *
+ * The empty shell is the defect, not a side effect of it: it is indistinguishable
+ * from "the query ran and matched no rows", which is the reading an author (very
+ * often an AI author) takes, and it points at the DATA when the fault is in the
+ * WIRING one level up. Same posture as {@link ElementDataSourceErrorPanel}: the
+ * metadata is answerable, so the answer is rendered where the author can see it.
+ */
+export function NoDataSourcePanel({ testId, title = 'No data source resolved', message, }) {
+    return (_jsxs("div", { className: "p-4 border border-red-500 rounded text-red-500 bg-red-50 my-2", role: "alert", "data-testid": `${testId}-no-data-source`, children: [_jsx("p", { className: "font-medium", children: title }), message ? _jsx("p", { className: "text-sm mt-1", children: message }) : null] }));
+}
+/**
+ * Wrap an object-bound block so its `dataSource` binding reaches the keys it
+ * reads, and so the two non-final resolution states render once, the same way,
+ * for every block.
+ *
+ * The block itself is not mounted while a named view is unresolved: rendering it
+ * against a half-resolved query is how a page shows a wider answer than the one
+ * that was authored.
+ */
+export function ElementDataSourceGate({ schema, mapping, dataSource, testId, errorTitle, requiresDataSource, noDataSourceMessage: noDataSourceText, children, }) {
+    const bound = useElementDataSourceSchema(schema, mapping, dataSource);
+    const adapter = useResolvedDataSource(dataSource);
+    // Reported BEFORE the view state, because with no adapter every downstream
+    // answer is a symptom of this one: `useElementDataSource` cannot list the
+    // object's saved views either, so a block carrying a `view` would otherwise
+    // report "this data source cannot list the saved views" — true, and pointing
+    // at the view name instead of at the missing injection.
+    if (requiresDataSource && adapter == null) {
+        return _jsx(NoDataSourcePanel, { testId: testId, message: noDataSourceText });
+    }
+    if (bound.status === 'missing') {
+        return _jsx(ElementDataSourceErrorPanel, { testId: testId, title: errorTitle, message: bound.error });
+    }
+    if (bound.status === 'loading') {
+        return _jsx(ElementDataSourceLoadingPanel, { testId: testId });
+    }
+    return children(bound.schema);
+}

package/dist/hooks/index.d.ts

@@ -5,35 +5,38 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export * from './useExpression';
-export * from './useFilterScope';
-export * from './useActionRunner';
-export * from './useNavigationOverlay';
-export * from './usePageVariables';
-export * from './usePageVariableActionBridge';
-export * from './useViewData';
-export * from './useDynamicApp';
-export * from './useDiscovery';
-export * from './useFocusTrap';
-export * from './useFocusManagement';
-export * from './useKeyboardShortcuts';
-export * from './useCrudShortcuts';
-export * from './useReducedMotion';
-export * from './useAnimation';
-export * from './useDensityMode';
-export * from './useViewSharing';
-export * from './useClientNotifications';
-export * from './useOffline';
-export * from './usePerformance';
-export * from './usePerformanceBudget';
-export * from './usePageTransition';
-export * from './useViewTransition';
-export * from './useETagCache';
-export * from './useSchemaPersistence';
-export * from './useGlobalUndo';
-export * from './useDebugMode';
-export * from './useActionEngine';
-export * from './useCapabilityGate';
-export * from './useDataRefresh';
-export * from './usePageAssignment';
-export * from './useRecordSearch';
+export * from './useExpression.js';
+export * from './useFilterScope.js';
+export * from './useActionRunner.js';
+export * from './useNavigationOverlay.js';
+export * from './usePageVariables.js';
+export * from './usePageVariableActionBridge.js';
+export * from './useViewData.js';
+export * from './useElementDataSource.js';
+export * from './useDynamicApp.js';
+export * from './useDiscovery.js';
+export * from './useFocusTrap.js';
+export * from './useFocusManagement.js';
+export * from './useKeyboardShortcuts.js';
+export * from './useCrudShortcuts.js';
+export * from './useReducedMotion.js';
+export * from './useAnimation.js';
+export * from './useDensityMode.js';
+export * from './useViewSharing.js';
+export * from './useClientNotifications.js';
+export * from './useOffline.js';
+export * from './usePerformance.js';
+export * from './usePerformanceBudget.js';
+export * from './usePageTransition.js';
+export * from './useViewTransition.js';
+export * from './useETagCache.js';
+export * from './useSchemaPersistence.js';
+export * from './useGlobalUndo.js';
+export * from './useDebugMode.js';
+export * from './useActionEngine.js';
+export * from './useActionTextLocalizer.js';
+export * from './useCapabilityGate.js';
+export * from './useDatasetDimensionLabels.js';
+export * from './useDataRefresh.js';
+export * from './usePageAssignment.js';
+export * from './useRecordSearch.js';

package/dist/hooks/index.js

@@ -5,36 +5,46 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export * from './useExpression';
+export * from './useExpression.js';
 // Session scope for filter placeholders ({current_user_id}/{current_org_id}).
-export * from './useFilterScope';
-export * from './useActionRunner';
-export * from './useNavigationOverlay';
-export * from './usePageVariables';
-export * from './usePageVariableActionBridge';
-export * from './useViewData';
-export * from './useDynamicApp';
-export * from './useDiscovery';
-export * from './useFocusTrap';
-export * from './useFocusManagement';
-export * from './useKeyboardShortcuts';
-export * from './useCrudShortcuts';
-export * from './useReducedMotion';
-export * from './useAnimation';
-export * from './useDensityMode';
-export * from './useViewSharing';
-export * from './useClientNotifications';
-export * from './useOffline';
-export * from './usePerformance';
-export * from './usePerformanceBudget';
-export * from './usePageTransition';
-export * from './useViewTransition';
-export * from './useETagCache';
-export * from './useSchemaPersistence';
-export * from './useGlobalUndo';
-export * from './useDebugMode';
-export * from './useActionEngine';
-export * from './useCapabilityGate';
-export * from './useDataRefresh';
-export * from './usePageAssignment';
-export * from './useRecordSearch';
+export * from './useFilterScope.js';
+export * from './useActionRunner.js';
+export * from './useNavigationOverlay.js';
+export * from './usePageVariables.js';
+export * from './usePageVariableActionBridge.js';
+export * from './useViewData.js';
+// PageComponentSchema.dataSource — the spec's per-element data binding.
+export * from './useElementDataSource.js';
+export * from './useDynamicApp.js';
+export * from './useDiscovery.js';
+export * from './useFocusTrap.js';
+export * from './useFocusManagement.js';
+export * from './useKeyboardShortcuts.js';
+export * from './useCrudShortcuts.js';
+export * from './useReducedMotion.js';
+export * from './useAnimation.js';
+export * from './useDensityMode.js';
+export * from './useViewSharing.js';
+export * from './useClientNotifications.js';
+export * from './useOffline.js';
+export * from './usePerformance.js';
+export * from './usePerformanceBudget.js';
+export * from './usePageTransition.js';
+export * from './useViewTransition.js';
+export * from './useETagCache.js';
+export * from './useSchemaPersistence.js';
+export * from './useGlobalUndo.js';
+export * from './useDebugMode.js';
+export * from './useActionEngine.js';
+// The ONE application of `useObjectLabel`'s action resolvers over the three
+// authored strings an action carries (label / confirmText / successMessage).
+export * from './useActionTextLocalizer.js';
+export * from './useCapabilityGate.js';
+// The analytics label net's React glue, consumed by BOTH plugin-dashboard's
+// `DatasetWidget` and plugin-report's dataset block (objectui#4389). It lives
+// here rather than in `@object-ui/core` because it reads `SchemaRendererContext`
+// — see the file header for the measured dependency direction.
+export * from './useDatasetDimensionLabels.js';
+export * from './useDataRefresh.js';
+export * from './usePageAssignment.js';
+export * from './useRecordSearch.js';

package/dist/hooks/useActionEngine.js

@@ -23,7 +23,7 @@
  */
 import { useCallback, useContext, useMemo } from 'react';
 import { ActionEngine, } from '@object-ui/core';
-import { ActionCtxReact } from '../context/ActionContext';
+import { ActionCtxReact } from '../context/ActionContext.js';
 export function useActionEngine(options = {}) {
     const { actions = [], context = {} } = options;
     // When wrapped in an <ActionProvider>, reuse its ActionRunner so that:

package/dist/hooks/useActionTextLocalizer.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ *
+ * `useActionTextLocalizer` — the ONE place a declared action's authored,
+ * user-visible strings are resolved against the active locale's bundle.
+ *
+ * ## Why this hook exists (objectui#4265)
+ *
+ * A TranslationBundle entry for an action carries THREE keys, all under the
+ * same `_actions.<name>.*` node:
+ *
+ * ```ts
+ * convert_lead: {
+ *   label: '...',           // the button
+ *   confirmText: '...',     // the confirm dialog BODY
+ *   successMessage: '...',  // the success toast
+ * }
+ * ```
+ *
+ * `useObjectLabel()` has always exposed a resolver for each of them
+ * (`actionLabel` / `actionConfirm` / `actionSuccess`, one `resolve()` and one
+ * key convention behind all three). What drifted is the CALL SITES: some
+ * render surfaces called all three, others called only `actionLabel`. On those
+ * surfaces one bundle entry met two fates — the button rendered the
+ * translation while the confirm dialog rendered the authored English literal,
+ * which is exactly what objectui#4265 reports.
+ *
+ * So this is deliberately NOT a new resolution dialect. It is a single
+ * application of the existing resolvers over the three keys, so a surface can
+ * no longer localize one of them and forget the others: there is one function
+ * to call, and it can only do all three.
+ *
+ * ## Pinned semantics
+ *
+ * - **Fallback**: no bundle entry, or an entry lacking the key, renders the
+ *   AUTHORED text. That is `useObjectLabel`'s own fallback contract; nothing
+ *   here overrides it.
+ * - **A nameless action is not translatable.** Without `action.name` there is
+ *   no `_actions.<name>` key to look up, so the literals pass through.
+ * - **`confirmText` / `successMessage` are resolved only when the action
+ *   DECLARES them.** A bundle must not be able to bolt a confirmation gate
+ *   onto an action whose metadata never asked for one (nor a success toast).
+ *   Translation localizes what exists; it does not add behaviour. This mirrors
+ *   what the already-correct call sites (`RecordDetailView`, `ObjectView`,
+ *   `DeclaredActionsBar`) each spelled out by hand.
+ * - **`label` is reduced through `pickLocalized` first**, because since rc.6 an
+ *   authored `label` may be an `I18nLabel` map rather than a string. The map is
+ *   collapsed to the active language BEFORE it is offered to the bundle as the
+ *   fallback, so a per-locale literal and a bundle entry cannot disagree about
+ *   what "the authored label" is.
+ */
+export interface ActionTextLocalizerOptions {
+    /**
+     * Last-resort display text, used only when the action declares neither a
+     * `label` nor a `name` (e.g. a positional `Action 3` placeholder).
+     */
+    fallbackLabel?: string;
+}
+/**
+ * Returns a copy of `action` with `label` — plus `confirmText` and
+ * `successMessage` when the action declares them — resolved from the active
+ * locale's bundle, falling back to the authored literals.
+ */
+export type ActionTextLocalizer = <T extends Record<string, any>>(objectName: string | undefined, action: T, options?: ActionTextLocalizerOptions) => T;
+export declare function useActionTextLocalizer(): ActionTextLocalizer;

package/dist/hooks/useActionTextLocalizer.js

@@ -0,0 +1,91 @@
+/**
+ * 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.
+ *
+ * `useActionTextLocalizer` — the ONE place a declared action's authored,
+ * user-visible strings are resolved against the active locale's bundle.
+ *
+ * ## Why this hook exists (objectui#4265)
+ *
+ * A TranslationBundle entry for an action carries THREE keys, all under the
+ * same `_actions.<name>.*` node:
+ *
+ * ```ts
+ * convert_lead: {
+ *   label: '...',           // the button
+ *   confirmText: '...',     // the confirm dialog BODY
+ *   successMessage: '...',  // the success toast
+ * }
+ * ```
+ *
+ * `useObjectLabel()` has always exposed a resolver for each of them
+ * (`actionLabel` / `actionConfirm` / `actionSuccess`, one `resolve()` and one
+ * key convention behind all three). What drifted is the CALL SITES: some
+ * render surfaces called all three, others called only `actionLabel`. On those
+ * surfaces one bundle entry met two fates — the button rendered the
+ * translation while the confirm dialog rendered the authored English literal,
+ * which is exactly what objectui#4265 reports.
+ *
+ * So this is deliberately NOT a new resolution dialect. It is a single
+ * application of the existing resolvers over the three keys, so a surface can
+ * no longer localize one of them and forget the others: there is one function
+ * to call, and it can only do all three.
+ *
+ * ## Pinned semantics
+ *
+ * - **Fallback**: no bundle entry, or an entry lacking the key, renders the
+ *   AUTHORED text. That is `useObjectLabel`'s own fallback contract; nothing
+ *   here overrides it.
+ * - **A nameless action is not translatable.** Without `action.name` there is
+ *   no `_actions.<name>` key to look up, so the literals pass through.
+ * - **`confirmText` / `successMessage` are resolved only when the action
+ *   DECLARES them.** A bundle must not be able to bolt a confirmation gate
+ *   onto an action whose metadata never asked for one (nor a success toast).
+ *   Translation localizes what exists; it does not add behaviour. This mirrors
+ *   what the already-correct call sites (`RecordDetailView`, `ObjectView`,
+ *   `DeclaredActionsBar`) each spelled out by hand.
+ * - **`label` is reduced through `pickLocalized` first**, because since rc.6 an
+ *   authored `label` may be an `I18nLabel` map rather than a string. The map is
+ *   collapsed to the active language BEFORE it is offered to the bundle as the
+ *   fallback, so a per-locale literal and a bundle entry cannot disagree about
+ *   what "the authored label" is.
+ */
+import { useMemo } from 'react';
+import { useObjectLabel, useObjectTranslation, pickLocalized } from '@object-ui/i18n';
+export function useActionTextLocalizer() {
+    const { actionLabel, actionConfirm, actionSuccess } = useObjectLabel();
+    const { language } = useObjectTranslation();
+    return useMemo(() => {
+        return ((objectName, action, options) => {
+            if (!action || typeof action !== 'object')
+                return action;
+            // An `I18nLabel` map collapses to the active language here, so what the
+            // bundle receives as its fallback is always a plain string.
+            const authoredLabel = pickLocalized(action.label, language);
+            const name = typeof action.name === 'string' && action.name
+                ? action.name
+                : undefined;
+            const displayLabel = authoredLabel || name || options?.fallbackLabel || '';
+            // No name, no translation key: the literals are the answer. The label is
+            // still normalized (map to string, last-resort placeholder applied) so
+            // every caller reads one shape.
+            if (!name) {
+                return displayLabel === action.label ? action : { ...action, label: displayLabel };
+            }
+            const out = {
+                ...action,
+                label: actionLabel(objectName, name, displayLabel),
+            };
+            if (action.confirmText !== undefined) {
+                out.confirmText = actionConfirm(objectName, name, action.confirmText);
+            }
+            if (action.successMessage !== undefined) {
+                out.successMessage = actionSuccess(objectName, name, action.successMessage);
+            }
+            return out;
+        });
+    }, [actionLabel, actionConfirm, actionSuccess, language]);
+}

package/dist/hooks/useCapabilityGate.js

@@ -23,13 +23,14 @@
  *
  * **Fail-OPEN when unknown.** No runner, no user, no `systemPermissions` array:
  * the action shows. Unknown is not denied, the server is the authority
- * (ADR-0057 D10), and hiding a permitted user's button on missing client data
- * is the worse failure. An EMPTY array is not unknown — it means "holds
- * nothing" and gates normally.
+ * (the framework's ADR-0124 D1 — server enforces, client is courtesy), and
+ * hiding a permitted user's button on missing client data is the worse
+ * failure. An EMPTY array is not unknown — it means "holds nothing" and gates
+ * normally.
  */
 import { useCallback, useContext } from 'react';
-import { ActionCtxReact } from '../context/ActionContext';
-import { usePredicateScope } from './useExpression';
+import { ActionCtxReact } from '../context/ActionContext.js';
+import { usePredicateScope } from './useExpression.js';
 /**
  * The caller's system capabilities, or `undefined` when the host never supplied
  * them (→ callers must fail open).

package/dist/hooks/useClientNotifications.js

@@ -26,8 +26,8 @@
  * server side exists.
  */
 import { useCallback, useContext, useEffect, useRef, useState } from 'react';
-import { SchemaRendererContext } from '../context/SchemaRendererContext';
-import { useNotifications } from '../context/NotificationContext';
+import { SchemaRendererContext } from '../context/SchemaRendererContext.js';
+import { useNotifications } from '../context/NotificationContext.js';
 /* ------------------------------------------------------------------ */
 /*  Helpers                                                           */
 /* ------------------------------------------------------------------ */

package/dist/hooks/useCrudShortcuts.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { useMemo } from 'react';
-import { useKeyboardShortcuts, } from './useKeyboardShortcuts';
+import { useKeyboardShortcuts, } from './useKeyboardShortcuts.js';
 /**
  * Registers standard CRUD keyboard shortcuts using the useKeyboardShortcuts hook.
  *