@object-ui/core 17.6.0 → 17.7.0

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

@@ -5,6 +5,63 @@
  * 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 | usable binding overrides view |
+ * | `viewType` | view only                               | view                        |
+ *
+ * Both operands of `limit` carry one extra condition the other keys do not: the
+ * destination is declared a POSITIVE INTEGER, so a cap the contract refuses is
+ * NOT AUTHORED, whichever operand carried it. One chain, one rule for both: a
+ * usable binding cap, else a usable view cap, else none (the consumer's own
+ * default). See `savedViewLimit` for why the view's refused cap is dropped
+ * rather than clamped or thrown, `bindingLimit` for why a refused binding cap
+ * yields to the view's (objectui#10016), and `elementDataSourceRefusedLimitMessage`
+ * for the half that tells the author, about either operand.
+ *
+ * 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 type { InjectedComponentInput } from '@object-ui/types';
 /** Sort entry, as both the spec's `SortItem` and objectui's view configs spell it. */
 export interface ElementDataSourceSort {
     field: string;
@@ -13,11 +70,38 @@ export interface ElementDataSourceSort {
 /**
  * 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.
+ * `filter` has two populations, and since the upstream convergence they differ:
+ *
+ * - **What an author may write** is the spec's `ViewFilterRule` array alone —
+ *   `[{ field, operator, value }, …]`. The spec's `filter` doors converged on it
+ *   (objectui#6206; migration `element-data-source-and-object-block-filter-rule-array`),
+ *   and `ElementDataSourceSchema` refuses the other two shapes at the door: the
+ *   MongoDB-style record form (`{ status: 'open' }`) by kind, and an ObjectQL
+ *   AST tuple array (`[['status', '=', 'open']]`) because each member must be a
+ *   rule object.
+ * - **What a renderer may still receive** is all three. The D2 conversion that
+ *   migration entry records, `page-component-filter-record-to-rule-array`,
+ *   rewrites a stored `filter` only where the rule array spells it losslessly —
+ *   a flat record, an operator object whose operators the rule vocabulary
+ *   spells, several such keys, or a single-level AST tuple array — on every
+ *   ObjectStack stored-row read and under `os migrate meta --stored`. It leaves
+ *   exactly as stored a filter carrying `$and` / `$or` / `$not`; any filter with
+ *   a part that has no lossless rule spelling (a `null` value, an operator such
+ *   as `$null` / `$exists` or an AST `like`, an array or object comparand in
+ *   equality position, an AST `and` / `or` group); and every filter, the
+ *   binding's included, of a component whose rows are inline
+ *   (`data: { provider: 'value' }`, a `data` array, or `staticData`). And this
+ *   renderer is backend-agnostic: it replays no conversion itself, and only
+ *   ObjectStack's own data-at-rest seams do, so a page that reaches it any other
+ *   way arrives as it was written. Any of the three shapes may therefore still
+ *   arrive here, beside the rule array.
+ *
+ * `filter` is typed `unknown` rather than the spec's `ViewFilterRule[]` because
+ * this interface carries the second population, not the first, and
+ * {@link mergeFilterNodes} is the single sink that lowers all three shapes.
+ * Narrowing the type here would only move the cast, not remove it, and it would
+ * not stop a stored record-form filter from arriving. Refusing the retired
+ * shapes is the spec schema's job at the authoring door, not this type's.
  */
 export interface ElementDataSourceConfig {
     object: string;
@@ -43,7 +127,12 @@ export interface ComposedElementDataSource {
     filter?: unknown;
     /** Binding sort if given, else the view's. */
     sort?: unknown;
-    /** Binding limit if given, else the view's page size. */
+    /**
+     * The binding's limit if it is one the contract admits, else the view's page
+     * size under the same condition. A refused cap from either operand is not
+     * authored (`bindingLimit` and `savedViewLimit` apply the one rule), and
+     * `elementDataSourceRefusedLimitMessage` is what says so.
+     */
     limit?: number;
     /** The view's render kind (grid / kanban / …), when the view declares one. */
     viewType?: string;
@@ -91,12 +180,65 @@ export declare function collectSavedViews(...sources: unknown[]): Record<string,
  * binding exists to remove.
  */
 export declare function resolveSavedView(views: Record<string, ElementSavedView>, requested: string | undefined | null, object: string): ElementSavedView | undefined;
+/**
+ * The diagnostic half of {@link savedViewLimit} and {@link bindingLimit}.
+ * `null` means "nothing to say".
+ *
+ * ## Which operand
+ *
+ * `operand` picks the refusal to describe; it defaults to `'view'`, the one
+ * this builder described before objectui#10016. Each operand gets its own
+ * sentence, and each names its operand, so the two refusals stay
+ * distinguishable when both fire. They do fire together when the binding AND
+ * the view each carry a refused cap: two declarations, one message each.
+ *
+ * `binding` is the binding as authored. The view's sentence needs it too: it
+ * says the consumer falls back to its own default, and that is only true when
+ * the binding supplied no usable cap. A usable binding cap is used whatever the
+ * view carries, so a refused view cap under one changed nothing and is not
+ * reported. That condition lives HERE, once, rather than at each caller,
+ * because every caller needs it and two copies could drift.
+ *
+ * ## Why a BUILDER here, and not a warning from the composer
+ *
+ * This is the shape {@link elementDataSourceViewNotFoundMessage} already
+ * established in this module, for the reason its doc gives: built here so every
+ * caller reports the same defect the same way. It is followed rather than
+ * re-decided because the alternative is ruled out mechanically —
+ * {@link composeElementDataSource} is PURE and the render path calls it from a
+ * `useMemo`, so a warning emitted inside it would fire during render and fire
+ * again on every re-render. The repaired relay one layer up emits from an
+ * effect for exactly that reason; a pure function has no effect to emit from,
+ * so it hands the caller the words instead.
+ *
+ * ## Why the message has to exist at all
+ *
+ * Dropping alone would be a SILENT change on the renderer path: today the
+ * refused value travels as far as a block whose own guard reports it once, and
+ * after this repair that block receives nothing and correctly says nothing —
+ * an absent key is not a mistake. So the repair would remove the only place the
+ * author was being told. The layer that makes the decision is the layer that
+ * reports it.
+ *
+ * ⛔ NOT a second guard: the predicate lives once, in {@link isUsableRowLimit},
+ * and the view's carrier is read once, by {@link savedViewRawLimit}; this reads
+ * both.
+ *
+ * ⚠️ It speaks only about a cap THIS layer dropped. A non-numeric
+ * `pagination.pageSize` never became a limit here, before or after, so there is
+ * nothing for this layer to report about it. A non-numeric binding `limit` is
+ * different: `??` used to pass it through, so this layer now drops it and says
+ * so.
+ */
+export declare function elementDataSourceRefusedLimitMessage(view: ElementSavedView | null | undefined, viewName: string | undefined | null, object: string, binding?: {
+    limit?: unknown;
+} | null, operand?: 'view' | 'binding'): string | null;
 /**
  * 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
+ * for `view` composes a binding with no view, which is exactly the pre-objectstack-ai/objectstack#5576
  * behaviour for the other four keys.
  *
  * See the module doc for the per-key rule table; `filter` is the only key that
@@ -109,5 +251,117 @@ export declare function composeElementDataSource(config: ElementDataSourceConfig
  * 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.
+ *
+ * ## Why the empty case may not say "this object has no saved views"
+ *
+ * An EMPTY `knownViews` reaches this function from two different worlds, and
+ * this function cannot tell them apart:
+ *
+ *  1. the saved views were read and there are none;
+ *  2. the read never successfully happened.
+ *
+ * World 2 is not hypothetical and not a bug to be fixed upstream: the shipped
+ * `ObjectStackAdapter.listViews` contract degrades EVERY failure — refused,
+ * offline, malformed — to `[]` on the RESOLVED path (deliberate, and objectui#8151
+ * keeps it), so a broken read arrives at `useElementDataSource` as a successful
+ * empty answer. The hook's own discrimination catches a REJECTION, which is a
+ * shape that contract never produces, so nothing separates the two worlds by the
+ * time the count lands here.
+ *
+ * Framework decision objectstack#13906 decision 1 option A — *a thing that could
+ * not be READ is not a thing that is ABSENT* — therefore binds this branch: it
+ * may only assert what is true in BOTH worlds. It names the possibilities and
+ * commits to neither, because committing is exactly the claim nobody established.
+ *
+ * ⛔ Do not "restore" the shorter sentence by inferring failure from emptiness in
+ * either direction — emptiness is what both worlds produce, so it can never tell
+ * them apart. Saying more than this needs the failure FACT plumbed in from the
+ * adapter (objectui#8151's surface), not a better guess here.
  */
 export declare function elementDataSourceViewNotFoundMessage(object: string, view: string, knownViews: readonly string[]): string;
+/**
+ * The spec key this module resolves, spelled once.
+ *
+ * Every consumer that needs the NAME (the registry injection, its gates, the
+ * pins) reads it from here rather than repeating the literal, so "which key is
+ * this?" has exactly one answer in the tree.
+ */
+export declare const ELEMENT_DATA_SOURCE_KEY = "dataSource";
+/**
+ * The authoring-surface declaration of {@link ELEMENT_DATA_SOURCE_KEY} — the one
+ * copy, emitted into every registration that wraps the runtime gate.
+ *
+ * ## Why it lives here and is injected rather than written per block
+ *
+ * `PageComponentSchema.dataSource` is READ by `ElementDataSourceGate` in
+ * `@object-ui/react` on behalf of every object-bound block that wraps itself in
+ * it — nine of them at the time of writing. It was declared by NONE: `validateTree`
+ * skips `BASE_PROPS` and otherwise looks a prop up in the component's `inputs`,
+ * and `dataSource` was in neither. So the html tier reported the one spelling
+ * that resolves a saved view — the only one that works — with the identical
+ * `unknown-prop` warning it gives the spellings that do nothing, on the tier
+ * meant to accept AI-authored pages, where the diagnostic IS the contract
+ * (objectui#6678, the reporter of objectui#6598 gave up on exactly this).
+ *
+ * The maintainer ruling of 2026-08-29 took option B **in the injection form**:
+ * emitted mechanically at the wrapping seam, so a block declares the key from
+ * the same place that reads it. Nine hand-kept copies is the shape that ruling
+ * refused — they drift, and a tenth block would simply forget. Adding the key to
+ * `sdui-parser`'s `BASE_PROPS` (option A) was refused too: that set mirrors
+ * `BaseSchema`, and silencing `dataSource` on blocks that do NOT read it
+ * (`flex`, `card`) would make the diagnostic lie in the other direction.
+ *
+ * ## Why `object`, and not a bare `'object'` kind
+ *
+ * The `binding: 'object'` marker is what tells a consumer this input names an
+ * OBJECT — `validateTree` records it as a binding site, and the designer offers
+ * an object picker rather than a free-text blob. The `type` stays the coarse
+ * `'object'` kind because the value is a record; the two words are unrelated and
+ * both are correct here.
+ *
+ * ## Typed as the framework's injected input (`9e37d9b39`)
+ *
+ * `binding` is not a `ComponentInput` member. The maintainer ruling of
+ * 2026-09-07 answered the card's product question — may an ordinary
+ * registration declare a binding input? — with no, so the ONE writer of the
+ * key is this constant, typed by `InjectedComponentInput` from
+ * `@object-ui/types`: a `ComponentInput` plus the marker. The hand-written
+ * inline type literal that used to sit here was the tell that the key had no
+ * authored home, and the splice in `Registry.register` reached the `inputs`
+ * array through an `as ComponentMeta` cast. Both are gone: the shape is now
+ * checked here and at the splice, and a registration that writes `binding`
+ * itself is an excess-property `tsc` error.
+ */
+export declare const ELEMENT_DATA_SOURCE_INPUT: InjectedComponentInput;
+/**
+ * Declare that `renderer` wraps `ElementDataSourceGate`, so its registrations
+ * publish {@link ELEMENT_DATA_SOURCE_INPUT}.
+ *
+ * This is the SEAM, and it is deliberately the only way in: `Registry.register`
+ * injects the declaration for exactly the renderers marked here, so the key is
+ * published by whatever consumes the gate and by nothing else — which is what
+ * keeps the `flex` / `card` direction of the ruling true.
+ * `scripts/check-element-data-source-declaration.mjs` fails any source that
+ * consumes the gate without passing through it, so a new block cannot forget.
+ *
+ * ## Two import paths, ONE name and ONE function
+ *
+ * `@object-ui/react` re-exports this beside `ElementDataSourceGate` so the seam is
+ * findable next to the thing it is about. That export is for DISCOVERABILITY:
+ * every CALL SITE imports from here, and
+ * `scripts/check-element-data-source-declaration.mjs` enforces it.
+ *
+ * The rule is measured, not stylistic. A registration runs at MODULE SCOPE, and
+ * `element:record_picker`'s registration in `@object-ui/components` is the
+ * worked example. 101 suites in this repo partially
+ * mock `@object-ui/react` by hand-listing the exports they return, and a
+ * module-scope read of a name those lists do not carry throws at COLLECTION
+ * time — the importing test file fails before it runs a single assertion.
+ * Measured: 17 files, all four CI shards, zero failed assertions among them.
+ * Nothing mocks `@object-ui/core`, and `@object-ui/components` already imports
+ * `ComponentRegistry` from it at module scope, so this path adds no coupling
+ * that was not already there.
+ */
+export declare function elementDataSourceBlock<C>(renderer: C): C;
+/** Whether `renderer` was marked by {@link elementDataSourceBlock}. */
+export declare function isElementDataSourceBlock(renderer: unknown): boolean;