@object-ui/core 17.5.0 → 17.7.0

package/dist/utils/sort-query.js

@@ -6,30 +6,257 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * Normalize an authored `sort` into the field→direction map used for
- * `QueryParams.$orderby`.
+ * The canonical spelling, quoted in the refusal diagnostic so the message
+ * carries the fix and not just the complaint.
  *
- * @param sort `"name desc"` (legacy string) or `SortConfig[]`.
- * @returns The ordering map, or `undefined` when nothing orderable was authored.
+ * ⚠️ BOTH keys, deliberately. `order` is REQUIRED on `SortConfig`, on its zod
+ * counterpart and on `@objectstack/spec`'s `SortItemSchema`, so an example that
+ * omitted it would make this diagnostic prescribe metadata a publish refuses —
+ * objectui#9031. The pin feeds this very example back through `SortItemSchema`
+ * from the installed artifact rather than eyeballing it, because the way this
+ * regresses is somebody "simplifying" the example, not somebody editing prose.
  */
-export function convertSortToQueryParams(sort) {
+const ARRAY_FORM_EXAMPLE = "[{ field: 'name', order: 'desc' }]";
+/**
+ * Retired string clauses already reported, so one bad `sort` logs its
+ * prescription ONCE instead of once per render. The message is a fix
+ * instruction for an author, not a per-render event, and this sink runs inside
+ * the query memo of every object-bound block — a related-list derivation over
+ * an object with N lists would otherwise print N lines per pass.
+ *
+ * Module state, exactly as {@link resetRetiredSortSpellingReports}'s sibling
+ * `resetRetiredFieldTypeReports` keeps it for retired field types: the dedupe
+ * is per SPELLING, so two blocks that inherit the same bad view sort still
+ * print one line between them.
+ *
+ * ⚠️ It holds keys, not raw spellings — the two arms that report are ARM-TAGGED
+ * (objectui#9955). A retired string arrives either as the whole `sort` or as one
+ * entry of the array, and the two get DIFFERENT messages (what a reader must
+ * change, and what the query still carries, are not the same in the two cases).
+ * On one shared raw key the first arm to fire would silence the other, and the
+ * author would read a sentence about the wrong container. {@link retiredKey}
+ * builds the keys so the two spaces cannot collide, and the bound each arm keeps
+ * is unchanged: ONE line per distinct spelling per arm, however many blocks
+ * inherit the same bad view.
+ */
+const reportedRetiredSpellings = new Set();
+/**
+ * Key a report by the arm that produced it AND the spelling that produced it.
+ *
+ * The two spaces are disjoint by construction rather than by luck: `arm` is one
+ * of two fixed tokens, neither of which contains a newline, so the text before
+ * the first newline identifies the arm no matter what an author wrote. A raw
+ * spelling can be anything at all — it comes out of authored JSON — so a bare
+ * string prefix would only be disjoint until somebody authored the prefix.
+ */
+function retiredKey(arm, spelling) {
+    return `${arm}\n${spelling}`;
+}
+/**
+ * Test seam — forget which retired spellings have been reported.
+ *
+ * Needed because the dedupe above is module state: without it the second test
+ * to assert the refusal diagnostic would observe silence and pass for the
+ * wrong reason.
+ */
+export function resetRetiredSortSpellingReports() {
+    reportedRetiredSpellings.clear();
+}
+/**
+ * Name a retired string `sort` clause, once per spelling.
+ *
+ * `console.error`, not `warn`, and not dev-gated: this call REFUSES an authored
+ * row order, so the page renders in a different order than the author asked
+ * for. That is the same severity class as `reportRetiredFieldType`, which is
+ * also unconditional, and the opposite of `warnOnUnknownActionKeys`, which only
+ * reports keys nothing was ever going to read.
+ *
+ * ⚠️ This text is read at the moment the author is ALREADY being corrected, so
+ * it must not prescribe metadata the spec refuses (objectui#9031). It used to
+ * end "`order` is optional and means `'asc'`" — a RUNTIME tolerance stated as
+ * an AUTHORING permission. Both halves of that are load-bearing and both have to
+ * survive any rewording:
+ *
+ *  - the tolerance is REAL — a missing `order` is read as ascending here rather
+ *    than dropped (see {@link normalizeSortEntries}), because types are erased
+ *    and an entry that arrives without it still has to mean something;
+ *  - and it is NOT permission — `order` is required on `SortConfig`, on its zod
+ *    counterpart and on `@objectstack/spec`'s `SortItemSchema`, which refuses an
+ *    entry without it.
+ *
+ * Stating only the first is what made an author who followed this correction
+ * verbatim get refused a second time, at publish, by a different door. Deleting
+ * the tolerance instead would be the opposite error: it is what this renderer
+ * actually does, and a diagnostic that denies it sends the author hunting for a
+ * dropped sort key that was never dropped.
+ */
+function reportRetiredSortSpelling(sort) {
+    const key = retiredKey('scalar', sort);
+    if (reportedRetiredSpellings.has(key))
+        return;
+    reportedRetiredSpellings.add(key);
+    console.error(`[object-ui] convertSortToQueryParams: the legacy string \`sort\` clause is retired ` +
+        `(objectui#8221) and was REFUSED — received ${JSON.stringify(sort)}, so this query ` +
+        `carries no \`$orderby\`. Write the array form instead: ` +
+        `sort: ${ARRAY_FORM_EXAMPLE} — both keys, on every entry. \`order\` is required: on ` +
+        `\`SortConfig\`, on its zod counterpart, and on \`@objectstack/spec\`'s \`SortItemSchema\`, ` +
+        `which refuses an entry without it. (A missing \`order\` is still read as \`'asc'\` ` +
+        `here — that is a runtime tolerance, not permission to omit the key: metadata ` +
+        `written that way is refused when it is published.) ` +
+        `The array is the only spelling every \`sort\` input declares, and the only one ` +
+        `\`@objectstack/spec\` accepts.`);
+}
+/**
+ * Name a retired string clause that arrived as an ENTRY of the `sort` array,
+ * once per spelling (objectui#9955).
+ *
+ * A sibling of {@link reportRetiredSortSpelling} rather than a reuse of it, and
+ * the difference is the one sentence an author acts on: the scalar refusal can
+ * say "this query carries no `$orderby`" because refusing the whole value is
+ * refusing the whole ordering, while one bad entry among good ones leaves the
+ * other entries lowering normally — `[{ field: 'a', order: 'asc' }, 'b desc']`
+ * still orders by `a`. Reusing the scalar text here would tell an author their
+ * rows are unordered when they are ordered by everything except the key they
+ * are hunting for, which is worse than silence.
+ *
+ * Everything the scalar text carries, this one carries too, because objectui#9031
+ * ruled BOTH halves load-bearing and a reader reaching this message is being
+ * corrected in exactly the same moment: the worked array-of-objects example, the
+ * fact that `order` is REQUIRED at publish, and the fact that this renderer's
+ * ascending default is a RUNTIME tolerance and ⛔ not permission to omit the key.
+ *
+ * The caller withholds exactly one string from this reporter — `''` — because
+ * `sort: ''` does not reach the scalar reporter either (the `!sort` guard reads
+ * an empty spelling as "the author wrote nothing", and its pin says reporting it
+ * would train readers to ignore the message). Mirroring that is the point of the
+ * whole card; inverting it one container deeper would recreate the same
+ * inconsistency in the other direction.
+ *
+ * `console.error`, unconditional and not dev-gated — the same choice, for the
+ * same reason, as its scalar sibling: this refuses an authored row order, so the
+ * page renders in an order the author did not ask for. ⛔ Not the
+ * `warnOnUnknownActionKeys` class, which reports keys nothing was ever going to
+ * read; here something WAS going to be read and now is not.
+ */
+function reportRetiredSortEntrySpelling(entry) {
+    const key = retiredKey('entry', entry);
+    if (reportedRetiredSpellings.has(key))
+        return;
+    reportedRetiredSpellings.add(key);
+    console.error(`[object-ui] convertSortToQueryParams: a \`sort\` ARRAY ENTRY is the retired string ` +
+        `clause (objectui#8221) and was REFUSED — received ${JSON.stringify(entry)} as an entry ` +
+        `of the \`sort\` array, so that entry orders nothing (and if it was the only usable ` +
+        `entry, this query carries no \`$orderby\` at all). The retirement is about the ` +
+        `SPELLING, not the container: wrapping the clause in an array does not revive it. ` +
+        `Write entry OBJECTS instead: sort: ${ARRAY_FORM_EXAMPLE} — both keys, on every entry. ` +
+        `\`order\` is required: on \`SortConfig\`, on its zod counterpart, and on ` +
+        `\`@objectstack/spec\`'s \`SortItemSchema\`, which refuses an entry without it. ` +
+        `(A missing \`order\` is still read as \`'asc'\` here — that is a runtime tolerance, ` +
+        `not permission to omit the key: metadata written that way is refused when it is ` +
+        `published.) The array OF OBJECTS is the only spelling every \`sort\` input declares, ` +
+        `and the only one \`@objectstack/spec\` accepts.`);
+}
+/**
+ * Decide WHICH authored entries survive and WHAT a missing direction means —
+ * the whole of this module's normalization, with no opinion about the wire.
+ *
+ * Split out of {@link convertSortToQueryParams} by objectui#8973, which measured
+ * `object-grid` re-implementing this decision privately and getting it wrong:
+ * its array arm interpolated every key unconditionally, so an entry missing
+ * `field` or `order` reached the wire as the literal text `undefined`
+ * (`$orderby: 'name undefined'`), which the server answers `400 INVALID_QUERY`.
+ *
+ * ⚠️ It is SHAPE-AGNOSTIC on purpose, and that is what makes it reusable where
+ * the map below is not. `object-grid` sends a `"field order"` join string, not
+ * this module's `{field: direction}` map; swapping its wire shape is route B on
+ * objectui#8767, which the maintainer DECLINED by name (2026-09-10) pending a
+ * card that measures the server contract and both readers. Exporting the
+ * decision without the map lets that block share the ONE implementation of the
+ * rule while keeping the wire shape the declination protects — so "one
+ * operation, one implementation" is satisfied for the operation that actually
+ * has two copies, rather than being traded away for a shape change nobody
+ * ruled on.
+ *
+ * The two rules, unchanged from the map builder they were lifted out of:
+ *
+ *  - an entry with no usable `field` is SKIPPED (it names nothing to order by);
+ *  - `order` normalizes to `'asc'` unless it is exactly `'desc'`, so a missing
+ *    direction means ascending and a garbage one does not reach the wire.
+ *
+ * A third rule was added by objectui#9955 and it changes no RETURN value: a
+ * STRING entry is the retired clause one container deeper, so it is now REFUSED
+ * OUT LOUD before the skip above reaches it — and then skipped, contributing
+ * nothing, exactly as before. ⛔ The two rules above are untouched by it; in
+ * particular the entry-shaped object with no `field` keeps its DELIBERATE
+ * silence, because it names nothing to order by rather than naming it in a
+ * retired spelling. The seam is `typeof entry === 'string'` and only that.
+ *
+ * @returns The surviving entries in authored order, or `undefined` when nothing
+ * orderable was authored — never an empty array, so callers can omit the
+ * query key entirely rather than asking for an ordering with no content.
+ */
+export function normalizeSortEntries(sort) {
     if (!sort)
         return undefined;
-    // Legacy string clause: "name desc" / "name" (a bare field means ascending).
+    // Retired spelling — reachable only at runtime, since the signature above no
+    // longer admits it. Read through `unknown` on purpose: the check is about the
+    // VALUE that actually arrived, not about the type the caller promised.
     if (typeof sort === 'string') {
-        const [field, direction] = sort.trim().split(/\s+/);
-        if (!field)
-            return undefined;
-        return { [field]: direction?.toLowerCase() === 'desc' ? 'desc' : 'asc' };
+        reportRetiredSortSpelling(sort);
+        return undefined;
     }
     if (Array.isArray(sort)) {
-        const out = {};
+        const out = [];
         for (const entry of sort) {
+            // The retired spelling, one container deeper (objectui#9955). Read through
+            // `unknown` for the same reason the scalar arm above does: the check is
+            // about the VALUE that arrived, not the type the caller promised. ⛔ This
+            // branch does not ACCEPT the string — the entry still contributes nothing,
+            // exactly as it did when it fell through the skip below. All it adds is the
+            // sentence that says so.
+            //
+            // The one string it does not name is `''`, and that is SYMMETRY with the
+            // scalar arm rather than an exception to the seam: `sort: ''` never reaches
+            // the loud arm above either, because the `!sort` guard reads it as "the
+            // author wrote nothing" rather than as the retired clause. Whitespace is
+            // NOT in that carve-out — `'   '` is truthy, is loud on the scalar arm
+            // today, and stays loud here.
+            if (typeof entry === 'string') {
+                const spelling = entry;
+                if (spelling !== '')
+                    reportRetiredSortEntrySpelling(spelling);
+                continue;
+            }
             if (!entry || typeof entry.field !== 'string' || entry.field === '')
                 continue;
-            out[entry.field] = entry.order === 'desc' ? 'desc' : 'asc';
+            out.push({ field: entry.field, order: entry.order === 'desc' ? 'desc' : 'asc' });
         }
-        return Object.keys(out).length > 0 ? out : undefined;
+        return out.length > 0 ? out : undefined;
     }
     return undefined;
 }
+/**
+ * Normalize an authored `sort` into the field→direction map used for
+ * `QueryParams.$orderby`.
+ *
+ * The decision about which entries survive lives in
+ * {@link normalizeSortEntries}; this function is only the MAP projection of it.
+ * Duplicate fields therefore collapse last-wins, keeping the position of the
+ * first mention — the same thing the single-pass loop this replaced did, since
+ * an object key keeps its insertion position when it is re-assigned.
+ *
+ * @param sort `SortConfig[]` — the one declared spelling. The legacy string
+ * clause (`"name desc"`) is retired (objectui#8221): a string that reaches here
+ * at runtime is refused with a diagnostic naming the array form, and this
+ * function returns `undefined` so the query carries no `$orderby`.
+ * @returns The ordering map, or `undefined` when nothing orderable was authored.
+ */
+export function convertSortToQueryParams(sort) {
+    const entries = normalizeSortEntries(sort);
+    if (!entries)
+        return undefined;
+    const out = {};
+    for (const entry of entries)
+        out[entry.field] = entry.order;
+    return out;
+}

package/dist/utils/text-comparand.d.ts

@@ -0,0 +1,92 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The ONE `icontains` comparand ruling this package owns, in one place
+ * (objectui#9048).
+ *
+ * ## Why this module exists rather than a third copy
+ *
+ * `@objectstack/spec`'s `FILTER_TEXT_CASES` carries two REJECTION rows for the
+ * case-insensitive contains operator — an empty comparand and a non-string one
+ * — each with `code: 'INVALID_FILTER'` and `mustMention: ['$icontains']`.
+ * Before this module the SAME discrimination and the SAME message were written
+ * out twice inside this package: `ValueDataSource`'s `refuseTextComparand`
+ * (objectui#8748, the reference implementation) and `filter-converter`'s
+ * (objectui#9001, whose own docblock calls itself "a PORT of a shipped,
+ * reviewed implementation"). objectui#9048's triage ruled on that directly:
+ *
+ * > three implementations of one refusal, of which one is correct ⇒ the useful
+ * > dispatch is not "add a third guard" but "make the dialects share the one
+ * > that works"
+ *
+ * So the contract's half — WHICH comparands are refused, and WHAT the author is
+ * told — lives here once, and each face keeps only its own ENVELOPE. That split
+ * is not a tidy-up: it is the half that does and the half that does not
+ * transfer, and both docblocks already said so before this module existed.
+ * `ValueDataSource` excludes-and-logs because it is deciding about one ROW and
+ * HAS a row to exclude; `filter-converter` is a PRODUCER deciding whether to
+ * send a query at all and has none, so it throws `FilterOperatorError`
+ * (`INVALID_FILTER` / 400).
+ *
+ * ## Not exported from `@object-ui/core`'s entry, deliberately
+ *
+ * `src/index.ts` names its re-exports one file at a time and does NOT name this
+ * one, so nothing here reaches the published surface. The package's sibling
+ * `@object-ui/data-objectstack` carries the same defect on its own ARRAY-form
+ * producer and CANNOT reach this module — `@object-ui/core`'s `exports` map has
+ * exactly one entry (`"."`), so a second package can only import what
+ * `src/index.ts` re-exports. Closing that half is a published-surface addition
+ * and a maintainer's call, not this module's; see objectui#9048 for the exact
+ * export it would need.
+ *
+ * ## Scope
+ *
+ * Only the case-insensitive contains operator, because only that operator is
+ * what the published table declares. The sibling positive operators
+ * (`$contains` / `$startsWith` / `$endsWith`) have no such row and keep the
+ * answer they have always given on every face — widening by analogy is the
+ * table's decision, not this module's.
+ */
+/**
+ * A comparand as it appears INSIDE a refusal message.
+ *
+ * `JSON.stringify` alone is not safe here even though it is what the message
+ * wants: it THROWS on a BigInt and on a cyclic object. Both faces are hurt by
+ * that and in mirror-image ways, which is why the guard travels with the text
+ * rather than being re-derived per face. On the THROWING face the call sits
+ * inside a `throw new FilterOperatorError(...)` expression, so a `TypeError`
+ * raised while the message is being built escapes in the refusal's place, and
+ * `classifyLoadError` reads a bare `TypeError` as a network fault: the author
+ * would be told to check their connection about a filter this layer had already
+ * judged. On the EXCLUDE-AND-LOG face a refusal that throws while explaining
+ * itself turns the one path that stays quiet about a bad filter into the one
+ * path that takes the caller down.
+ *
+ * No JSON-sourced filter can carry either shape, so this is about the in-memory
+ * callers who hand a literal to a data source or to the converter.
+ * `?? String(target)` keeps `undefined` and a symbol readable — `JSON.stringify`
+ * returns `undefined` for both.
+ */
+export declare function describeComparand(target: unknown): string;
+/**
+ * THE CONTRACT HALF, now the spec's own (objectui#11073).
+ *
+ * `isRefusedTextComparand` (the discrimination: a non-string or empty
+ * comparand) and `textComparandRefusalReason` (the half of the message the
+ * contract owns, no face's envelope on it) were written here once, for both
+ * faces. `@objectstack/spec` 17.5.0 publishes the SAME two functions from
+ * `@objectstack/spec/data`, byte for byte the implementation this module carried
+ * — measured against the published `dist` when the bump landed, message text
+ * included. So they are re-exported rather than kept as a copy under the spec's
+ * own names, which `pnpm check:spec-symbols` refuses (a hand-written copy under
+ * a spec name is one release away from drifting). Both faces still import them
+ * from here, so the ONE-place property this module exists for is unchanged; the
+ * one place is now the spec. `describeComparand` above stays local: the spec
+ * does not export it.
+ */
+export { isRefusedTextComparand, textComparandRefusalReason } from '@objectstack/spec/data';

package/dist/utils/text-comparand.js

@@ -0,0 +1,99 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The ONE `icontains` comparand ruling this package owns, in one place
+ * (objectui#9048).
+ *
+ * ## Why this module exists rather than a third copy
+ *
+ * `@objectstack/spec`'s `FILTER_TEXT_CASES` carries two REJECTION rows for the
+ * case-insensitive contains operator — an empty comparand and a non-string one
+ * — each with `code: 'INVALID_FILTER'` and `mustMention: ['$icontains']`.
+ * Before this module the SAME discrimination and the SAME message were written
+ * out twice inside this package: `ValueDataSource`'s `refuseTextComparand`
+ * (objectui#8748, the reference implementation) and `filter-converter`'s
+ * (objectui#9001, whose own docblock calls itself "a PORT of a shipped,
+ * reviewed implementation"). objectui#9048's triage ruled on that directly:
+ *
+ * > three implementations of one refusal, of which one is correct ⇒ the useful
+ * > dispatch is not "add a third guard" but "make the dialects share the one
+ * > that works"
+ *
+ * So the contract's half — WHICH comparands are refused, and WHAT the author is
+ * told — lives here once, and each face keeps only its own ENVELOPE. That split
+ * is not a tidy-up: it is the half that does and the half that does not
+ * transfer, and both docblocks already said so before this module existed.
+ * `ValueDataSource` excludes-and-logs because it is deciding about one ROW and
+ * HAS a row to exclude; `filter-converter` is a PRODUCER deciding whether to
+ * send a query at all and has none, so it throws `FilterOperatorError`
+ * (`INVALID_FILTER` / 400).
+ *
+ * ## Not exported from `@object-ui/core`'s entry, deliberately
+ *
+ * `src/index.ts` names its re-exports one file at a time and does NOT name this
+ * one, so nothing here reaches the published surface. The package's sibling
+ * `@object-ui/data-objectstack` carries the same defect on its own ARRAY-form
+ * producer and CANNOT reach this module — `@object-ui/core`'s `exports` map has
+ * exactly one entry (`"."`), so a second package can only import what
+ * `src/index.ts` re-exports. Closing that half is a published-surface addition
+ * and a maintainer's call, not this module's; see objectui#9048 for the exact
+ * export it would need.
+ *
+ * ## Scope
+ *
+ * Only the case-insensitive contains operator, because only that operator is
+ * what the published table declares. The sibling positive operators
+ * (`$contains` / `$startsWith` / `$endsWith`) have no such row and keep the
+ * answer they have always given on every face — widening by analogy is the
+ * table's decision, not this module's.
+ */
+/**
+ * A comparand as it appears INSIDE a refusal message.
+ *
+ * `JSON.stringify` alone is not safe here even though it is what the message
+ * wants: it THROWS on a BigInt and on a cyclic object. Both faces are hurt by
+ * that and in mirror-image ways, which is why the guard travels with the text
+ * rather than being re-derived per face. On the THROWING face the call sits
+ * inside a `throw new FilterOperatorError(...)` expression, so a `TypeError`
+ * raised while the message is being built escapes in the refusal's place, and
+ * `classifyLoadError` reads a bare `TypeError` as a network fault: the author
+ * would be told to check their connection about a filter this layer had already
+ * judged. On the EXCLUDE-AND-LOG face a refusal that throws while explaining
+ * itself turns the one path that stays quiet about a bad filter into the one
+ * path that takes the caller down.
+ *
+ * No JSON-sourced filter can carry either shape, so this is about the in-memory
+ * callers who hand a literal to a data source or to the converter.
+ * `?? String(target)` keeps `undefined` and a symbol readable — `JSON.stringify`
+ * returns `undefined` for both.
+ */
+export function describeComparand(target) {
+    try {
+        return JSON.stringify(target) ?? String(target);
+    }
+    catch {
+        return String(target);
+    }
+}
+/**
+ * THE CONTRACT HALF, now the spec's own (objectui#11073).
+ *
+ * `isRefusedTextComparand` (the discrimination: a non-string or empty
+ * comparand) and `textComparandRefusalReason` (the half of the message the
+ * contract owns, no face's envelope on it) were written here once, for both
+ * faces. `@objectstack/spec` 17.5.0 publishes the SAME two functions from
+ * `@objectstack/spec/data`, byte for byte the implementation this module carried
+ * — measured against the published `dist` when the bump landed, message text
+ * included. So they are re-exported rather than kept as a copy under the spec's
+ * own names, which `pnpm check:spec-symbols` refuses (a hand-written copy under
+ * a spec name is one release away from drifting). Both faces still import them
+ * from here, so the ONE-place property this module exists for is unchanged; the
+ * one place is now the spec. `describeComparand` above stays local: the spec
+ * does not export it.
+ */
+export { isRefusedTextComparand, textComparandRefusalReason } from '@objectstack/spec/data';

package/dist/utils/unmaterialized-fields.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ObjectUI — unmaterialized-fields utility
+ * 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.
+ */
+/**
+ * Field types no driver materialises a stored column for — the value is
+ * computed on read (objectui#3950).
+ *
+ * A STORAGE fact, not a taste judgement, and it decides what the SERVER can be
+ * asked to do with such a field. All three query axes have now closed on it:
+ *
+ *  - SORT — refused since objectstack#6994 (`400 INVALID_SORT`). Before that it
+ *    degraded in silence: the response carried the very values it was asked to
+ *    order by, out of order, under a `200`, with ascending and descending
+ *    byte-identical (measured on a real SQL driver).
+ *  - FILTER — refused since objectstack#8296 (`400 INVALID_FIELD`); previously
+ *    `200` with zero rows whichever way the predicate pointed.
+ *  - SEARCH — refused by name since objectstack#6674.
+ *
+ * The membership is bound to `@objectstack/spec` instead of being written out
+ * here, on the reasoning the platform's own filter door applies to itself: a
+ * layer that re-decided "which types have a column" drifts from the drivers,
+ * and then either withholds an affordance that works or offers one that 400s.
+ * The spec pins the set to `formula` alone.
+ *
+ * Deliberately NOT `COMPUTED_VALUE_TYPES` (`formula` / `summary` /
+ * `autonumber`) — that is the WRITE contract ("never client-written"). A
+ * `summary` and an `autonumber` each get a real maintained column and order,
+ * filter and search correctly, so widening to that set would withhold
+ * affordances from two types that work. The platform's own conformance suite
+ * pins that trap by name.
+ *
+ * SCOPE on the sort axis: this rules out a sort the SERVER performs. A
+ * client-side sort keys off the value the cell renders — which the server
+ * hydrates on read — so it orders by exactly what the user sees and stays
+ * honest. Consumers therefore apply this where they already apply the
+ * relational carve-out (see {@link EXPANDABLE_FIELD_TYPES}): under server
+ * sorting only.
+ */
+export declare const UNMATERIALIZED_FIELD_TYPES: ReadonlySet<string>;
+/**
+ * Whether a field definition's type materialises no stored column.
+ *
+ * Shaped like {@link isExpandableFieldType}: only `type` is read, so it answers
+ * for any field-metadata shape an object schema resolves to, and an unreadable
+ * definition is not a verdict — `null` / `undefined` / a bare type string all
+ * answer `false`.
+ */
+export declare function isUnmaterializedFieldType(fieldDef: unknown): boolean;

package/dist/utils/unmaterialized-fields.js

@@ -0,0 +1,57 @@
+/**
+ * ObjectUI — unmaterialized-fields utility
+ * 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.
+ */
+import { SEARCH_VIRTUAL_TYPES } from '@objectstack/spec/data';
+/**
+ * Field types no driver materialises a stored column for — the value is
+ * computed on read (objectui#3950).
+ *
+ * A STORAGE fact, not a taste judgement, and it decides what the SERVER can be
+ * asked to do with such a field. All three query axes have now closed on it:
+ *
+ *  - SORT — refused since objectstack#6994 (`400 INVALID_SORT`). Before that it
+ *    degraded in silence: the response carried the very values it was asked to
+ *    order by, out of order, under a `200`, with ascending and descending
+ *    byte-identical (measured on a real SQL driver).
+ *  - FILTER — refused since objectstack#8296 (`400 INVALID_FIELD`); previously
+ *    `200` with zero rows whichever way the predicate pointed.
+ *  - SEARCH — refused by name since objectstack#6674.
+ *
+ * The membership is bound to `@objectstack/spec` instead of being written out
+ * here, on the reasoning the platform's own filter door applies to itself: a
+ * layer that re-decided "which types have a column" drifts from the drivers,
+ * and then either withholds an affordance that works or offers one that 400s.
+ * The spec pins the set to `formula` alone.
+ *
+ * Deliberately NOT `COMPUTED_VALUE_TYPES` (`formula` / `summary` /
+ * `autonumber`) — that is the WRITE contract ("never client-written"). A
+ * `summary` and an `autonumber` each get a real maintained column and order,
+ * filter and search correctly, so widening to that set would withhold
+ * affordances from two types that work. The platform's own conformance suite
+ * pins that trap by name.
+ *
+ * SCOPE on the sort axis: this rules out a sort the SERVER performs. A
+ * client-side sort keys off the value the cell renders — which the server
+ * hydrates on read — so it orders by exactly what the user sees and stays
+ * honest. Consumers therefore apply this where they already apply the
+ * relational carve-out (see {@link EXPANDABLE_FIELD_TYPES}): under server
+ * sorting only.
+ */
+export const UNMATERIALIZED_FIELD_TYPES = SEARCH_VIRTUAL_TYPES;
+/**
+ * Whether a field definition's type materialises no stored column.
+ *
+ * Shaped like {@link isExpandableFieldType}: only `type` is read, so it answers
+ * for any field-metadata shape an object schema resolves to, and an unreadable
+ * definition is not a verdict — `null` / `undefined` / a bare type string all
+ * answer `false`.
+ */
+export function isUnmaterializedFieldType(fieldDef) {
+    return (!!fieldDef &&
+        typeof fieldDef === 'object' &&
+        UNMATERIALIZED_FIELD_TYPES.has(fieldDef.type));
+}

package/dist/utils/without-denied-fields.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ObjectUI — the field-read rule for a single record
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The two members of a loaded permission policy the field-read rule asks.
+ *
+ * Structural on purpose: `usePermissions()` from `@object-ui/permissions`
+ * satisfies it as it is, and so does any caller-supplied policy of the same
+ * shape, so this package depends on neither React nor the permissions package.
+ */
+interface FieldReadPolicy {
+    /** False until a policy has loaded; also false with no provider mounted. */
+    readonly isLoaded: boolean;
+    /** May the viewer READ `field` on `object`? */
+    checkField(object: string, field: string, action: 'read'): boolean;
+}
+/**
+ * `record` as the viewer may READ it on `objectName`: every field the loaded
+ * `policy` denies is removed, which leaves the row ObjectStack's `FieldMasker`
+ * already serves (objectui#10594).
+ *
+ * The renderer-side field-level-security rulings (objectui#7215 /
+ * objectui#7230) say FLS gates the OUTPUT: a value the loaded policy denies is
+ * not drawn, even when a backend serves it. Every surface that builds a display
+ * value from a whole row (a record title, a lookup label, a search-hit label, a
+ * person's name) calls this one function, so a denied field reads as an absent
+ * field on every surface at once, and the display ladder falls through to its
+ * next source exactly as it does for the stripped row. Field-LIST filters (which
+ * columns to head, which relations to `$expand`) are a different shape and are
+ * not this function.
+ *
+ * - `id` and `_id` are never judged, nor is any key in `extraKeep` (a declared
+ *   id field): an id addresses the record and is not a field value the policy
+ *   withholds, and the `Record #<id>` floor reads it.
+ * - Before a policy loads, with no policy, with no object to judge the fields
+ *   against, or for a value that is not an object, `record` comes back as it
+ *   is.
+ * - When nothing is withheld, the SAME object comes back, so a caller can tell
+ *   "nothing withheld" from "something withheld" by identity and a cache keyed
+ *   on the served row keeps hitting.
+ *
+ * Pure: it reads `policy.checkField` and never writes to `record`.
+ */
+export declare function withoutDeniedFields<T>(record: T, policy: FieldReadPolicy | null | undefined, objectName: string | undefined, extraKeep?: readonly string[]): T;
+export {};