@object-ui/core 17.3.0 → 17.6.0

package/dist/actions/recordIdParam.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ */
+/**
+ * Seeding an action's `recordIdParam` from the row — and refusing to dispatch
+ * when the row cannot supply it (objectstack#8018).
+ *
+ * An `api` action declaring `recordIdParam` names the request key that carries
+ * the record it acts on; `recordIdField` names the row field whose value seeds
+ * it (default `id`). Every call site used to spell the read the same permissive
+ * way:
+ *
+ * ```ts
+ * const rowValue = rowRecord[action.recordIdField || 'id'];
+ * if (rowValue != null) body[action.recordIdParam] = rowValue;   // else: nothing
+ * ```
+ *
+ * The `else` branch is the defect. It cannot distinguish "this row has no such
+ * key" from "this row's value is null", and in both cases it drops the parameter
+ * and lets the request go out anyway. What reaches the server is a mutation with
+ * no record named — and a backend that treats a missing selector as "match
+ * nothing" answers `{ status: true }` for having deleted nothing. The user is
+ * told the action succeeded. The measured instance was a session-revocation
+ * control that revoked nothing, which is the worst shape this can take: a
+ * security affordance that reports success while no-op'ing.
+ *
+ * The absent-key half is reachable from ordinary authoring, not just from bad
+ * data: the grid projects `$select` from the listView columns, so until
+ * `recordIdField` was harvested into it (see `listViewPredicates`) any action
+ * keyed on a non-column field got a row without that key. The harvest closes the
+ * common route; this guard closes the class, because a row can still lack the key
+ * for reasons projection cannot fix — a server-side read mask that strips the
+ * field regardless of projection (`internal: true`), a partial payload handed
+ * down from a host, a field the principal cannot read.
+ *
+ * Contract-first (AGENTS.md #0.1): the answer to an under-specified request is to
+ * refuse it at the producer, loudly, not to send it and hope the server objects.
+ * The two failures are named separately because they point at different repairs —
+ * an absent key is a projection/visibility problem, a null value is a data one.
+ */
+/** The minimal action shape this resolution reads. */
+export interface RecordIdParamAction {
+    /** Request key that carries the record id. Absent ⇒ no injection is declared. */
+    recordIdParam?: string;
+    /** Row field whose value seeds it. Defaults to `id`. */
+    recordIdField?: string;
+    /** Used only to make the refusal message name the action. */
+    name?: string;
+    label?: string;
+}
+/**
+ * Either the value to inject, or the reason the action must not be dispatched.
+ * `{}` (neither key) means no injection is declared — carry on unchanged.
+ */
+export type RecordIdParamSeed = {
+    value: unknown;
+    error?: undefined;
+} | {
+    value?: undefined;
+    error: string;
+} | {
+    value?: undefined;
+    error?: undefined;
+};
+/**
+ * Resolve the value an action's `recordIdParam` should carry, or the refusal.
+ *
+ * Pure — reads the action and the row, mutates nothing. Returns `{}` when the
+ * action declares no `recordIdParam` (nothing to inject) or when there is no row
+ * record at all (the caller is on a path where no row context exists; that is not
+ * this guard's business).
+ */
+export declare function resolveRecordIdParamSeed(action: RecordIdParamAction | null | undefined, rowRecord: Record<string, unknown> | null | undefined): RecordIdParamSeed;

package/dist/actions/recordIdParam.js

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+/**
+ * Resolve the value an action's `recordIdParam` should carry, or the refusal.
+ *
+ * Pure — reads the action and the row, mutates nothing. Returns `{}` when the
+ * action declares no `recordIdParam` (nothing to inject) or when there is no row
+ * record at all (the caller is on a path where no row context exists; that is not
+ * this guard's business).
+ */
+export function resolveRecordIdParamSeed(action, rowRecord) {
+    const param = action?.recordIdParam;
+    if (!param || !rowRecord || typeof rowRecord !== 'object')
+        return {};
+    const field = action?.recordIdField || 'id';
+    const label = action?.label || action?.name || param;
+    if (!(field in rowRecord)) {
+        return {
+            error: `Action "${label}" identifies its record by "${field}", but that field is not ` +
+                `present on the row. Add it to the view's columns, or check that it is readable ` +
+                `— running without it would send a request that names no record.`,
+        };
+    }
+    const value = rowRecord[field];
+    if (value == null) {
+        return {
+            error: `Action "${label}" identifies its record by "${field}", but this record has no ` +
+                `value for it — running without it would send a request that names no record.`,
+        };
+    }
+    return { value };
+}

package/dist/actions/serverActionHandler.d.ts

@@ -52,7 +52,7 @@
  * // <ActionProvider handlers={{ script }} … />  (or runner.registerHandler('script', script))
  * ```
  */
-import type { ActionContext, ActionDef, ActionResult } from './ActionRunner';
+import type { ActionContext, ActionDef, ActionResult } from './ActionRunner.js';
 /** The response surface the dispatcher needs — satisfied by a WHATWG `Response`. */
 export interface ServerActionFetchResponse {
     ok: boolean;

package/dist/actions/serverActionHandler.js

@@ -5,7 +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 { interpretActionResponse } from './actionResponse';
+import { interpretActionResponse } from './actionResponse.js';
 /**
  * An action that also mounts on list rows (`list_item`) or record pages is
  * designed to run against a single record. When such an action is launched

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;

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

@@ -0,0 +1,216 @@
+/**
+ * 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.
+ */
+/**
+ * `@object-ui/core` — ElementDataSource resolution (objectstack#5576).
+ *
+ * `PageComponentSchema.dataSource` (the spec's `ElementDataSourceSchema`) is the
+ * per-element data binding a page component uses to query a different object
+ * than the page's own context:
+ *
+ * ```json
+ * { "object": "account", "view": "hot", "filter": { … }, "sort": [ … ], "limit": 20 }
+ * ```
+ *
+ * This module owns the two pure halves of consuming it — telling the METADATA
+ * apart from a runtime data-source adapter, and composing a named saved view
+ * with the binding's own keys. Both are needed in two places (the render path in
+ * `@object-ui/plugin-list`, and `ViewDataProvider.resolveElementDataSource`), so
+ * they live here rather than being written twice.
+ *
+ * ## Composition semantics
+ *
+ * The spec's own `describe()` text settles the one case that could go either
+ * way. `filter` is documented as "**Additional** filter criteria" — additional
+ * to what the named view already restricts — so a view filter and a binding
+ * filter COMBINE under `and`; the binding can only narrow the view, never widen
+ * it. That is also the safe direction for AI-authored metadata: a typo in a
+ * per-element filter cannot silently expose rows the saved view excluded.
+ *
+ * Nothing else in the binding is described as additional, and the remaining keys
+ * are single-valued (one ordering, one cap), so for those the rule is **the view
+ * provides the baseline and an explicit key overrides it**:
+ *
+ * | key        | source                                  | rule                        |
+ * |------------|-----------------------------------------|-----------------------------|
+ * | `object`   | binding (required)                      | binding wins                |
+ * | `columns`  | view only — the binding has no such key | view                        |
+ * | `filter`   | view + binding                          | AND-combined ("additional") |
+ * | `sort`     | view or binding                         | binding overrides view      |
+ * | `limit`    | view (`pagination.pageSize`) or binding | binding overrides view      |
+ * | `viewType` | view only                               | view                        |
+ *
+ * A lone `filter` — only the view has one, or only the binding does — is passed
+ * through in the shape it was stored in; only the two-source case is lowered to
+ * an ObjectQL AST, because that is what combining requires.
+ *
+ * `viewType` rides along because `list-view` IS the multi-kind view container
+ * (its registry `inputs` enumerate grid/kanban/gallery/…): naming a saved kanban
+ * view and rendering a grid would be a silently wrong answer.
+ */
+import { mergeFilterNodes } from '../utils/filter-converter.js';
+import { resolveViewId } from '../utils/resolve-view-id.js';
+const isPlainObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/**
+ * 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 function isElementDataSourceConfig(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (typeof value.find === 'function')
+        return false;
+    const object = value.object;
+    return typeof object === 'string' && object.length > 0;
+}
+/**
+ * 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 function collectSavedViews(...sources) {
+    const out = {};
+    for (const source of sources) {
+        if (Array.isArray(source)) {
+            for (const entry of source) {
+                if (!isPlainObject(entry))
+                    continue;
+                const id = entry.name ?? entry.id;
+                if (typeof id === 'string' && id)
+                    out[id] = entry;
+            }
+        }
+        else if (isPlainObject(source)) {
+            for (const [id, entry] of Object.entries(source)) {
+                if (isPlainObject(entry))
+                    out[id] = entry;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * 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 function resolveSavedView(views, requested, object) {
+    const id = resolveViewId(requested, Object.keys(views), object);
+    return id === undefined ? undefined : views[id];
+}
+/** Read a saved view's row cap — `pagination.pageSize`, or a flat `limit`. */
+function savedViewLimit(view) {
+    if (!view)
+        return undefined;
+    const pagination = view.pagination;
+    if (isPlainObject(pagination) && typeof pagination.pageSize === 'number') {
+        return pagination.pageSize;
+    }
+    return typeof view.limit === 'number' ? view.limit : undefined;
+}
+/**
+ * Read a saved view's render kind. `type` is the spec's key (and what
+ * `ObjectView` reads); `viewType` is objectui's legacy spelling, folded by
+ * `normalizeListViewSchema` downstream but accepted here so a view stored either
+ * way resolves to the same kind.
+ */
+function savedViewType(view) {
+    if (!view)
+        return undefined;
+    const kind = view.type ?? view.viewType;
+    return typeof kind === 'string' && kind ? kind : undefined;
+}
+/** Read a saved view's column list — canonical `columns`, legacy `fields`. */
+function savedViewColumns(view) {
+    if (!view)
+        return undefined;
+    if (Array.isArray(view.columns))
+        return view.columns;
+    if (Array.isArray(view.fields))
+        return view.fields;
+    return 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 function composeElementDataSource(config, view) {
+    const composed = { object: config.object };
+    const columns = savedViewColumns(view);
+    if (columns !== undefined)
+        composed.columns = columns;
+    // "Additional filter criteria" (spec) — the view restricts, the binding
+    // restricts further, so two filters COMBINE under `and` via the repo's single
+    // combiner. A lone source passes through VERBATIM: lowering a stored filter to
+    // an ObjectQL AST belongs at the last hop before the wire and nowhere earlier
+    // (see `toFilterNode`'s doc on why), and every consumer of this result hands
+    // the value to that hop anyway. Combining is the one case that cannot preserve
+    // the input shape — putting two sources under one `and` requires AST — and
+    // `mergeFilterNodes` is the sanctioned place for it.
+    const viewFilter = view?.filter;
+    const filter = viewFilter !== undefined && config.filter !== undefined
+        ? mergeFilterNodes(viewFilter, config.filter)
+        : (config.filter ?? viewFilter);
+    if (filter !== undefined)
+        composed.filter = filter;
+    const sort = config.sort ?? view?.sort;
+    if (sort !== undefined)
+        composed.sort = sort;
+    const limit = config.limit ?? savedViewLimit(view);
+    if (limit !== undefined)
+        composed.limit = limit;
+    const viewType = savedViewType(view);
+    if (viewType !== undefined)
+        composed.viewType = viewType;
+    return composed;
+}
+/**
+ * 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 function elementDataSourceViewNotFoundMessage(object, view, knownViews) {
+    const known = knownViews.length
+        ? `Known views: ${[...knownViews].sort().join(', ')}.`
+        : 'This object has no saved views.';
+    return `dataSource.view "${view}" was not found on object "${object}". ${known}`;
+}

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

@@ -8,4 +8,5 @@
  * @packageDocumentation
  */
 export { DataScopeManager, defaultDataScopeManager, type RowLevelFilter, type DataScopeConfig, } from './DataScopeManager.js';
-export { ViewDataProvider, type ViewDataConfig, type ElementDataSourceConfig, type DataFetcher, type ResolvedData, } from './ViewDataProvider.js';
+export { ViewDataProvider, type ViewDataConfig, type DataFetcher, type ResolvedData, } from './ViewDataProvider.js';
+export { collectSavedViews, composeElementDataSource, elementDataSourceViewNotFoundMessage, isElementDataSourceConfig, resolveSavedView, type ComposedElementDataSource, type ElementDataSourceConfig, type ElementDataSourceSort, type ElementSavedView, } from './element-data-source.js';

package/dist/data-scope/index.js

@@ -9,3 +9,4 @@
  */
 export { DataScopeManager, defaultDataScopeManager, } from './DataScopeManager.js';
 export { ViewDataProvider, } from './ViewDataProvider.js';
+export { collectSavedViews, composeElementDataSource, elementDataSourceViewNotFoundMessage, isElementDataSourceConfig, resolveSavedView, } from './element-data-source.js';