@object-ui/core 17.3.0 → 17.5.0

package/dist/actions/actionKeys.js

@@ -6,26 +6,46 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * What an action is allowed to carry — objectstack#4075 step 1.
+ * What an action is allowed to carry — objectstack#4075, all three steps.
  *
- * `ActionDef` ends with `[key: string]: any`, so it accepts any key of any type.
- * Concretely (objectui#2990): deleting `ActionDef.execute` produced ZERO compile
- * errors even though the field had just been removed, and stale metadata still
- * authoring `execute: 'markDone'` type-checks today. The same deletion against
- * `@object-ui/types`' `ActionSchema` — which has no index signature — correctly
- * produced `TS2353` at the authoring site. One of the two readers can catch a
- * retired key; the other is structurally incapable.
+ * `ActionDef` used to end with `[key: string]: any`, so it accepted any key of
+ * any type. Concretely (objectui#2990): deleting `ActionDef.execute` produced
+ * ZERO compile errors even though the field had just been removed, and stale
+ * metadata authoring `execute: 'markDone'` type-checked. The same deletion
+ * against `@object-ui/types`' `ActionSchema` — which has no index signature —
+ * correctly produced `TS2353` at the authoring site. One of the two readers
+ * could catch a retired key; the other was structurally incapable.
  *
- * That asymmetry is the issue. An open key set on a DECLARED METADATA CONTRACT
+ * That asymmetry was the issue. An open key set on a DECLARED METADATA CONTRACT
  * is what lets a typo (`targt`, `exectue`) and a tombstoned key (`execute`) both
  * sail through to a runner that then silently does nothing — the #2169 "Mark
  * Done does nothing" shape.
  *
- * This module is step 1 of the staged narrowing: it makes the key set VISIBLE
- * and warns on anything outside it, without changing a single type. Nothing
- * breaks, and an invisible failure becomes an audible one. Steps 2 and 3 —
- * promoting the legitimate keys to explicit optional fields, then removing the
- * index signature — are what finally let `tsc` catch typos and retired keys.
+ * This module was step 1 of the staged narrowing: make the key set VISIBLE and
+ * warn on anything outside it, without changing a single type. Step 2 promoted
+ * the legitimate keys to explicit optional fields; **step 3 removed the index
+ * signature**, so `tsc` now rejects a typo or a retired key outright.
+ *
+ * ── Why this module SURVIVES step 3 ──────────────────────────────────────────
+ * Step 1 wrote that the dev-mode warning "can retire" once the index signature
+ * came down. Step 3 measured that and kept it, because the two mechanisms cover
+ * DISJOINT populations rather than the same one twice:
+ *
+ *   - `tsc` sees action literals AUTHORED IN CODE. It rejects an unknown key at
+ *     the construction site, which is the strongest possible signal — but only
+ *     for actions that exist as TypeScript.
+ *   - the warning below sees actions that arrive as DATA. objectstack#3903
+ *     established that stored `sys_metadata` rows are rehydrated UNPARSED, so
+ *     authored metadata reaches `runner.execute()` as a plain object no
+ *     compiler ever looked at. That is the population `execute: 'markDone'`
+ *     actually lives in, and no type can reach it.
+ *
+ * Retiring the warning would therefore have re-opened the runtime half of the
+ * gap while closing the compile-time half — which is why `executeScript`'s
+ * rename-prescription branch also survives, for the same rows and the same
+ * reason. What DID retire with the index signature is the inverted pin in
+ * `actionKeys.pin.test.ts` that asserted the signature was still there; it now
+ * asserts the opposite, which was always its stated completion condition.
  *
  * The lists are pinned by `__tests__/actionKeys.pin.test.ts`, which re-derives
  * each one from its actual source. A hand-maintained list that drifts from the
@@ -66,8 +86,22 @@
  * deprecating them toward a spelling that does not exist would be worse than
  * leaving them declared.
  *
- * Step 3 remains: remove the index signature, at which point `tsc` catches both
- * typos and retired keys and the dev-mode warning below can retire with it.
+ * ── What step 3 found the first two steps had missed ─────────────────────────
+ * Deleting the index signature is the only thing that can name the keys still
+ * hiding behind it, and it named five, in two groups:
+ *
+ * `to` / `external` / `newTab` / `replace` — the `navigation` alias's own
+ * spelling. Step 1 had already ruled these legitimate and listed them below in
+ * {@link NAVIGATION_ALIAS_KEYS}, but step 2's scope was the SPEC-owned keys, so
+ * they were declared as data and never as fields; `executeNavigation` read them
+ * through the index signature. Promoted, and deliberately not `@deprecated` —
+ * step 2's acceptance ruled on exactly that point.
+ *
+ * `description` — objectui vocabulary from `@object-ui/types`' renderer view of
+ * an action, forwarded by all four action renderers (`check:action-forward-parity`
+ * requires it) and read by the param-collection dialog for its subtitle
+ * (objectui#4192). Authorable, forwarded, read — and undeclared. These were the
+ * only two `TS2353`s the deletion produced across the whole workspace.
  */
 /**
  * Every property `ActionDef` declares, in declaration order.
@@ -81,6 +115,10 @@ export const ACTION_DEF_KEYS = [
     'actionType',
     'name',
     'label',
+    // Promoted by step 3 — objectui vocabulary (`@object-ui/types`' renderer view
+    // of an action), forwarded by all four action renderers and read by the
+    // param-collection dialog, but never declared on `ActionDef`.
+    'description',
     'confirmText',
     'confirm',
     'condition',
@@ -89,6 +127,14 @@ export const ACTION_DEF_KEYS = [
     'endpoint',
     'method',
     'navigate',
+    // The `navigation` alias's own spelling, promoted to real fields by step 3.
+    // Listed a second time in `NAVIGATION_ALIAS_KEYS` below, which keeps the
+    // separate fact that these four are objectui dialect with a spec-adoption
+    // tripwire; this list is only "what the interface declares".
+    'to',
+    'external',
+    'newTab',
+    'replace',
     'onClick',
     'reload',
     'close',
@@ -169,6 +215,15 @@ export const SPEC_ACTION_KEYS = [
     'bulkEnabled',
     'component',
     'confirmText',
+    // Added to `ActionSchema` in @objectstack/spec 17.0.0-rc.6. Listed here purely
+    // because this array's contract is "every property the spec's `ActionSchema`
+    // declares" — restating the spec, not adopting a feature. `ActionDef` does NOT
+    // declare `description` and is not changed: whether the runner or any renderer
+    // should READ it is a separate question, and `actionKeys.pin.test.ts`'s
+    // `ActionDef` half stays green without it. What this entry buys is that an
+    // action carrying a `description` is no longer reported as having an unknown
+    // key, which is the only thing the inventory is consulted for.
+    'description',
     'disabled',
     'errorMessage',
     'execute',
@@ -217,8 +272,15 @@ export const NAVIGATION_ALIAS_KEYS = ['to', 'external', 'newTab', 'replace'];
  * Warned about separately from unknown keys, and more loudly: an unknown key is
  * probably a typo, while a retired key is metadata that used to work. That
  * distinction is why `executeScript` carries a runtime branch returning the
- * rename prescription — a branch that exists solely to compensate for the index
- * signature, and that can retire with it in step 3.
+ * rename prescription.
+ *
+ * Step 1 expected that branch to retire with the index signature. It does not,
+ * and the reason is the one in this module's header: `tsc` closed the
+ * code-authored half of the gap, while `execute: 'markDone'` lives in stored
+ * rows that reach the runner UNPARSED (objectstack#3903). The branch reads the
+ * key off an untyped view of the action precisely so that `ActionDef` can go on
+ * NOT declaring it — declaring it to make the read compile would re-legitimize
+ * a tombstone the spec keeps only in order to reject it by name.
  */
 export const RETIRED_ACTION_KEYS = {
     execute: '`execute` was removed in @objectstack/spec 17 (#3855) — rename the key to `target`. ' +
@@ -292,3 +354,80 @@ export function warnOnUnknownActionKeys(action, where = 'ActionRunner') {
         '(packages/core/src/actions/actionKeys.ts). Warned rather than rejected because `ActionDef` ' +
         'still carries `[key: string]: any`, so the compiler cannot see this (objectstack#4075).');
 }
+/**
+ * Keys a HOST stashes into an action's `params` for the runner's own plumbing,
+ * rather than an author writing them there as a request payload.
+ *
+ * {@link warnOnDeprecatedObjectParams} has to tell "the author put the payload in
+ * `params`" (the shape objectstack#5777 retires) apart from "a host stashed row
+ * context there" (a shape the runner itself asks for, and that is not going
+ * away). `DeclaredActionsBar` dispatches `params: { _rowRecord: record }`,
+ * `RelatedRecordActionsBridge` does the same, and `ObjectGrid` adds
+ * `_selectedIds`; the api handler lifts `recordId` out of the field values
+ * before it updates. Warning on those would fire on nearly every declared-action
+ * click and prescribe `bodyExtra`, which is the wrong home for all of them.
+ *
+ * The `_` prefix is the existing convention for the stash — `recordId` is its one
+ * unprefixed member, so it is listed rather than inferred.
+ */
+const HOST_STASHED_PARAM_KEYS = new Set(['recordId']);
+const isAuthoredParamKey = (key) => !key.startsWith('_') && !HOST_STASHED_PARAM_KEYS.has(key);
+/**
+ * Does this action carry the DEPRECATED object-form `params` — a static request
+ * payload written under the key that means "parameter definitions"?
+ *
+ * The discriminator is `Array.isArray` and the type guard is `api`, mirroring
+ * `@objectstack/spec`'s `inline-action-api-params-to-body-extra` conversion
+ * (ADR-0087 D2) key for key. Contract parity with the producer is the point: the
+ * conversion rewrites exactly this shape to `bodyExtra` at load, so the runner
+ * must recognize exactly the same shape as "the thing that got rewritten".
+ *
+ * The `api` guard is also what keeps the deprecation out of objectstack#6828's
+ * territory — object-form `params` on a `type: 'url'` action is a THIRD meaning
+ * (`interpolateTarget`'s `${param.X}` scope, `executeUrl`'s `params.newTab`) and
+ * `bodyExtra` is NOT its replacement. Do not widen this guard without that
+ * ruling.
+ */
+export function hasDeprecatedObjectParams(action) {
+    if (!action || typeof action !== 'object')
+        return false;
+    const { type, actionType, params } = action;
+    if ((type ?? actionType) !== 'api')
+        return false;
+    if (!params || typeof params !== 'object' || Array.isArray(params))
+        return false;
+    return Object.keys(params).some(isAuthoredParamKey);
+}
+/**
+ * Dev-mode only: name the object-form `params` that `@objectstack/spec` 17 already
+ * refuses at the authoring door, and prescribe `bodyExtra`.
+ *
+ * This is the audible half of the compat window the maintainer's 2026-08-06
+ * ruling on objectstack#5777 ordered (direction A — a separate key, no same-name
+ * union): the runner keeps READING a non-array `params` as the static payload for
+ * one version window, says so, and the arm is deleted at 18. The loud half lives
+ * at the producer, where it belongs — spec's `params` field refuses the object
+ * form outright with a message naming `bodyExtra`, and the ADR-0087 conversion
+ * rewrites sources that still carry it. So a warning is the correct severity
+ * HERE: by the time metadata reaches this runner the producer has already had its
+ * say, and what is left to catch is a host composing an ActionDef in code.
+ *
+ * Dev-only and warn-once, matching {@link warnOnUnknownActionKeys} — a warning
+ * that floods a production console is a warning that gets muted.
+ */
+export function warnOnDeprecatedObjectParams(action, where = 'ActionRunner') {
+    if (!isDev())
+        return;
+    if (!hasDeprecatedObjectParams(action))
+        return;
+    const name = action?.name ?? '(unnamed)';
+    const memo = `deprecated-object-params:${String(name)}`;
+    if (warned.has(memo))
+        return;
+    warned.add(memo);
+    console.warn(`[${where}] action "${String(name)}" carries a static request payload in \`params\`. ` +
+        '`params` is the parameter DEFINITION array (fields collected from the user before the ' +
+        'action runs), never a payload map — put the payload in `bodyExtra` instead ' +
+        '(objectstack#5777). Still read as the payload for one version window; the arm is ' +
+        'removed at 18. `bodyExtra` is merged LAST, so it overrides anything left here.');
+}

package/dist/data-scope/ViewDataProvider.d.ts

@@ -18,6 +18,7 @@
  * @module data-scope
  * @packageDocumentation
  */
+import { type ElementDataSourceConfig, type ElementSavedView } from './element-data-source.js';
 /** ViewData union — matches @objectstack/spec ViewDataSchema */
 export type ViewDataConfig = {
     provider: 'object';
@@ -38,17 +39,12 @@ export type ViewDataConfig = {
     provider: 'value';
     items: any[];
 };
-/** Element-level data source — matches @objectstack/spec ElementDataSourceSchema */
-export interface ElementDataSourceConfig {
-    object: string;
-    view?: string;
-    filter?: Record<string, any>;
-    sort?: Array<{
-        field: string;
-        order: 'asc' | 'desc';
-    }>;
-    limit?: number;
-}
+/**
+ * Re-exported from `./element-data-source.js`, where the binding's type now
+ * lives alongside the logic that consumes it. Kept on this module path because
+ * that is where it was declared before objectstack#5576.
+ */
+export type { ElementDataSourceConfig };
 /** Fetcher interface — consumers provide the actual fetch implementation */
 export interface DataFetcher {
     /** Fetch records for an object */
@@ -82,6 +78,19 @@ export interface DataFetcher {
         headers?: Record<string, string>;
         body?: any;
     }): Promise<any>;
+    /**
+     * Fetch the object's saved views, so an `ElementDataSource.view` name can be
+     * resolved to real columns / filter / sort (objectstack#5576).
+     *
+     * Optional because most fetchers only read records. A fetcher WITHOUT it
+     * cannot honour a named view, and {@link ViewDataProvider.resolveElementDataSource}
+     * says so in `error` rather than dropping the key — the whole point of #5576
+     * is that a `view` the runtime cannot apply must never look applied.
+     *
+     * Either shape stored views come in is accepted: a map keyed by view id, or
+     * the array of overlay rows an adapter's `listViews()` returns.
+     */
+    fetchViews?(object: string): Promise<Record<string, ElementSavedView> | ElementSavedView[]>;
 }
 /** Resolved data result */
 export interface ResolvedData {
@@ -138,6 +147,22 @@ export declare class ViewDataProvider {
     private resolveApi;
     /** Resolve object-based data (metadata-driven) */
     private resolveObject;
-    /** Resolve element-level data source */
+    /**
+     * Resolve an element-level data source (`PageComponentSchema.dataSource`).
+     *
+     * `view` is HONOURED here, not dropped. Until objectstack#5576 this method
+     * forwarded `filter`/`sort`/`limit` and silently discarded `view`, so a page
+     * component that named a saved view got every record the object had — the
+     * declared binding was inert while looking applied.
+     *
+     * Three outcomes, all explicit:
+     *  - no `view` → unchanged behaviour, the binding's own keys are forwarded;
+     *  - `view` resolved → its columns become the `fields` projection and its
+     *    filter/sort/limit the baseline the binding's keys compose with (see
+     *    {@link composeElementDataSource} for the per-key rule);
+     *  - `view` unresolvable, or the fetcher cannot list views at all → an
+     *    `error` naming the view and what the object does have. NOT an empty
+     *    result, and NOT a silent fall back to the unfiltered object.
+     */
     resolveElementDataSource(config: ElementDataSourceConfig): Promise<ResolvedData>;
 }

package/dist/data-scope/ViewDataProvider.js

@@ -5,6 +5,20 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * @object-ui/core - View Data Provider
+ *
+ * Resolves @objectstack/spec ViewData discriminated union into
+ * a unified data access interface. Supports three data modes:
+ *
+ * 1. 'object' — Metadata-driven via ObjectStack API (object name → fields/records)
+ * 2. 'api' — Custom REST API endpoints (read/write URLs)
+ * 3. 'value' — Static data (pre-loaded items array)
+ *
+ * @module data-scope
+ * @packageDocumentation
+ */
+import { collectSavedViews, composeElementDataSource, elementDataSourceViewNotFoundMessage, resolveSavedView, } from './element-data-source.js';
 /** Extract records array from various common API response shapes */
 function extractRecords(data) {
     if (Array.isArray(data))
@@ -142,12 +156,76 @@ export class ViewDataProvider {
             };
         }
     }
-    /** Resolve element-level data source */
+    /**
+     * Resolve an element-level data source (`PageComponentSchema.dataSource`).
+     *
+     * `view` is HONOURED here, not dropped. Until objectstack#5576 this method
+     * forwarded `filter`/`sort`/`limit` and silently discarded `view`, so a page
+     * component that named a saved view got every record the object had — the
+     * declared binding was inert while looking applied.
+     *
+     * Three outcomes, all explicit:
+     *  - no `view` → unchanged behaviour, the binding's own keys are forwarded;
+     *  - `view` resolved → its columns become the `fields` projection and its
+     *    filter/sort/limit the baseline the binding's keys compose with (see
+     *    {@link composeElementDataSource} for the per-key rule);
+     *  - `view` unresolvable, or the fetcher cannot list views at all → an
+     *    `error` naming the view and what the object does have. NOT an empty
+     *    result, and NOT a silent fall back to the unfiltered object.
+     */
     async resolveElementDataSource(config) {
-        return this.resolve({ provider: 'object', object: config.object }, {
-            filter: config.filter,
-            sort: config.sort,
-            limit: config.limit,
+        let view;
+        if (config.view) {
+            if (!this.fetcher?.fetchViews) {
+                return {
+                    records: [],
+                    total: 0,
+                    provider: 'object',
+                    loading: false,
+                    error: `dataSource.view "${config.view}" cannot be resolved: this data ` +
+                        `fetcher does not implement fetchViews().`,
+                };
+            }
+            let views;
+            try {
+                views = collectSavedViews(await this.fetcher.fetchViews(config.object));
+            }
+            catch (error) {
+                return {
+                    records: [],
+                    total: 0,
+                    provider: 'object',
+                    loading: false,
+                    error: error.message,
+                };
+            }
+            view = resolveSavedView(views, config.view, config.object);
+            if (!view) {
+                return {
+                    records: [],
+                    total: 0,
+                    provider: 'object',
+                    loading: false,
+                    error: elementDataSourceViewNotFoundMessage(config.object, config.view, Object.keys(views)),
+                };
+            }
+        }
+        const composed = composeElementDataSource(config, view);
+        const fields = Array.isArray(composed.columns)
+            ? composed.columns.filter((c) => typeof c === 'string' && !!c)
+            : undefined;
+        return this.resolve({ provider: 'object', object: composed.object }, {
+            // `DataFetcher.fetchRecords`'s `filter` is declared
+            // `Record<string, any>`, which predates the three filter shapes that
+            // legitimately circulate here: a MongoDB-style condition object, an
+            // ObjectQL AST node array, and a spec `ViewFilterRule[]`. The last two
+            // are arrays, so a saved view's filter does not fit the declared option
+            // — the cast is that gap, not a coercion. Widening the declared option
+            // is a separate change with its own consumers.
+            filter: composed.filter,
+            sort: composed.sort,
+            limit: composed.limit,
+            ...(fields && fields.length > 0 ? { fields } : {}),
         });
     }
 }

package/dist/data-scope/element-data-source.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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.
+ */
+/** Sort entry, as both the spec's `SortItem` and objectui's view configs spell it. */
+export interface ElementDataSourceSort {
+    field: string;
+    order: 'asc' | 'desc';
+}
+/**
+ * Element-level data source — matches `@objectstack/spec` `ElementDataSourceSchema`.
+ *
+ * `filter` is typed `unknown` rather than the spec's `FilterCondition` because
+ * three shapes legitimately reach a renderer here (a MongoDB-style condition
+ * object, an ObjectQL AST node array, a spec `ViewFilterRule[]`) and
+ * {@link mergeFilterNodes} is the single sink that lowers all three. Narrowing
+ * the type here would only move the cast, not remove it.
+ */
+export interface ElementDataSourceConfig {
+    object: string;
+    view?: string;
+    filter?: unknown;
+    sort?: ElementDataSourceSort[];
+    limit?: number;
+}
+/**
+ * The subset of a saved view's config that an `ElementDataSource` `view` name
+ * contributes. Deliberately loose: stored view metadata is user data and carries
+ * both the spec vocabulary and the legacy objectui spellings that
+ * `normalizeListViewSchema` folds at the component boundary.
+ */
+export type ElementSavedView = Record<string, unknown>;
+/** What {@link composeElementDataSource} produces for a renderer to consume. */
+export interface ComposedElementDataSource {
+    /** Object to query. */
+    object: string;
+    /** Columns the named view shows; absent when no view was named. */
+    columns?: unknown;
+    /** View filter AND binding filter, combined; `undefined` when neither. */
+    filter?: unknown;
+    /** Binding sort if given, else the view's. */
+    sort?: unknown;
+    /** Binding limit if given, else the view's page size. */
+    limit?: number;
+    /** The view's render kind (grid / kanban / …), when the view declares one. */
+    viewType?: string;
+}
+/**
+ * Is this value the spec's `dataSource` METADATA, rather than a runtime
+ * data-source adapter?
+ *
+ * This guard exists because the two collide by name and the collision was live:
+ * `SchemaRenderer` spreads every non-metadata schema key onto the component as a
+ * React prop, so a spec-compliant `dataSource: { object, view }` on a page
+ * component landed on `ListView`'s `dataSource` PROP — which is the injected
+ * adapter — and shadowed it. The first `dataSource.find(…)` then threw
+ * `dataSource.find is not a function`, which the list reported as
+ * "Couldn't load records": writing the binding the spec documents BROKE the
+ * component (objectstack#5576).
+ *
+ * The test is positive on the metadata rather than negative on the adapter: a
+ * binding is a plain object with a non-empty string `object` and no `find`
+ * method. An adapter never has a string `object`; metadata never has `find`.
+ */
+export declare function isElementDataSourceConfig(value: unknown): value is ElementDataSourceConfig;
+/**
+ * Flatten every place saved views for one object can live into `id → config`.
+ *
+ * Two sources are real and both are read, in the order app-shell's `ObjectView`
+ * reads them: the object definition's embedded `listViews` / `list_views` map
+ * (metadata-defined) and the metadata overlay rows an adapter returns from
+ * `listViews()` (user-defined). Later sources win, so a saved view shadows a
+ * metadata view of the same id — the same precedence `ObjectView` applies when
+ * it dedups its tab list.
+ *
+ * Accepts a record keyed by view id or an array of view configs (overlay rows
+ * are an array and carry their identity in `name`, falling back to `id`).
+ */
+export declare function collectSavedViews(...sources: unknown[]): Record<string, ElementSavedView>;
+/**
+ * Find the saved view a `dataSource.view` name refers to.
+ *
+ * Name matching is {@link resolveViewId}'s — the same short/qualified tolerance
+ * the object page applies to a URL-requested view — so a name that works in one
+ * surface works in the other. Returns `undefined` when nothing matches; the
+ * caller must REPORT that rather than fall back to the object's default view.
+ * Silently widening a named view to "all records" is the failure mode this whole
+ * binding exists to remove.
+ */
+export declare function resolveSavedView(views: Record<string, ElementSavedView>, requested: string | undefined | null, object: string): ElementSavedView | undefined;
+/**
+ * Compose an `ElementDataSource` binding with the saved view it names.
+ *
+ * Pure — the caller resolves the view (see {@link resolveSavedView}) and owns
+ * the "named a view that does not exist" decision. Passing `undefined` /`null`
+ * for `view` composes a binding with no view, which is exactly the pre-#5576
+ * behaviour for the other four keys.
+ *
+ * See the module doc for the per-key rule table; `filter` is the only key that
+ * combines rather than overrides, because the spec describes the binding's
+ * filter as *additional*.
+ */
+export declare function composeElementDataSource(config: ElementDataSourceConfig, view?: ElementSavedView | null): ComposedElementDataSource;
+/**
+ * The message shown when `dataSource.view` names a view the object does not
+ * have. Built here so the render path and `ViewDataProvider` report the same
+ * defect the same way, and so the known-view list (the thing that actually gets
+ * an author unstuck) is never omitted by one caller.
+ */
+export declare function elementDataSourceViewNotFoundMessage(object: string, view: string, knownViews: readonly string[]): string;