@object-ui/core 17.6.0 → 18.0.0

package/dist/utils/sort-query.d.ts

@@ -9,19 +9,28 @@
  * sort-query — lower a block's authored `sort` to the `$orderby` value a
  * `DataSource.find` query carries.
  *
- * Two authored spellings reach every object-bound block, because both are
- * declared: the legacy OData-ish string (`ObjectGridSchema.sort: "name desc"`)
- * and the spec's `SortConfig[]` (`[{ field, order }]`). A read site that hands
- * either straight to `$orderby` works only because `QueryParams.$orderby`
- * accepts four shapes; normalizing here means one shape reaches the wire and a
- * block does not have to know which spelling its author used.
+ * ONE authored spelling reaches every object-bound block: the spec's
+ * `SortConfig[]` (`[{ field, order }]`). The legacy OData-ish string clause
+ * (`"name desc"`) that this function also honoured until objectui#8221 is
+ * RETIRED — director ruling, decision batch #77, 2026-09-07 (objectui#8221,
+ * maintainer approved), option B: "The platform has one `sort` spelling, the
+ * array, everywhere."
+ *
+ * Why the string had to go rather than be declared alongside the array: every
+ * `sort` input in the registry publishes `type: 'array'` alone, so the html
+ * tier already answered `type-mismatch` for the string, and
+ * `@objectstack/spec` refuses it outright on `element-record-picker`. A
+ * spelling that core implements, the docs teach and the validator rejects is
+ * three faces disagreeing, and the ruling settled which one wins. Declaring
+ * per-block string arms instead (option A) was rejected by name: it would make
+ * one key mean different things on different blocks.
  *
  * This is now the ONLY definition in the repo. It was hoisted here because
  * objectstack#7137 added two more read sites (`object-timeline`,
  * `record:line_items`) next to three sibling blocks that each inlined a
  * byte-identical private copy (`ObjectGantt` / `ObjectMap` / `ObjectCalendar`),
  * and a fifth and sixth copy is how the conversions start disagreeing. Those
- * three copies were deliberately left alone by #7137 and collapsed onto this
+ * three copies were deliberately left alone by objectstack-ai/objectstack#7137 and collapsed onto this
  * function by objectui#4022; every block now imports it from here.
  *
  * Two deliberate differences from those retired private copies, both of which
@@ -29,29 +38,120 @@
  * tolerance — and both are BEHAVIOUR CHANGES the migration delivered, not pure
  * refactor:
  *
- *  - **`order` is optional in `SortConfig`**, so an entry that omits it means
- *    ascending (that is what `$orderby`'s own
- *    `Array<{ field: string; order?: 'asc' | 'desc' }>` shape says). The private
- *    copies required BOTH keys and silently dropped such an entry, which lost an
+ *  - **A missing `order` is READ as ascending rather than dropped.** ⚠️ This
+ *    bullet used to say `order` is "optional in `SortConfig`". It is not:
+ *    `SortConfig.order` is required on the interface, on its zod mirror, and on
+ *    `@objectstack/spec`'s `SortItemSchema`, which refuses an entry without it
+ *    (`invalid_value` at `0.order`, measured on `@objectstack/spec@17.4.0`).
+ *    Corrected under objectui#8973, which is where objectui#8767's contract
+ *    review routed this sentence and its twin in
+ *    `@object-ui/types`' `ObjectGridSchema.sort` docblock. The tolerance is
+ *    real but it is a RUNTIME one — types are erased, so an entry missing
+ *    `order` still arrives and still has to mean something. The private copies
+ *    required BOTH keys and silently dropped such an entry, which lost an
  *    authored sort key instead of ordering by it.
  *  - **Nothing usable yields `undefined`, never `{}`.** An empty object is a
  *    truthy value that means "no ordering" only by accident of the adapter's
  *    serializer; `undefined` says it, so the query simply carries no `$orderby`.
  *
  * Not a lenient alias: an unusable input (a number, an object, an array of
- * strings) yields `undefined` rather than a guess. Only the two spellings the
- * schema types declare are honoured.
+ * strings) yields `undefined` rather than a guess. Only the ONE spelling the
+ * schema types declare is honoured.
+ *
+ * ⚠️ A retired string is REFUSED OUT LOUD, not dropped in silence. Types are
+ * erased, so the narrowed signature below cannot stop a string: authored JSON,
+ * a stored `sys_metadata` row and an `as any` bag all reach this function
+ * unparsed. Returning `undefined` and saying nothing would turn every one of
+ * those into a row order that quietly stopped applying — the exact failure this
+ * repository has measured over and over. See {@link convertSortToQueryParams}.
+ *
+ * ⚠️ OUT LOUD is about the SPELLING, not about the container it arrives in
+ * (objectui#9955). `sort: ['name asc']` is the same retired clause one level
+ * down, and it used to reach the array arm's `continue` and leave through the
+ * `undefined` return with nothing printed — the loud scalar refusal sat one arm
+ * above it, so the two spellings of one mistake got opposite treatment. Both are
+ * loud now. ⛔ Being loud is NOT accepting: the sentence four paragraphs up
+ * ("an unusable input … yields `undefined` rather than a guess") still holds
+ * byte for byte, and `['name asc']` still contributes no ordering. The ruling
+ * quoted at the top of this docblock — one `sort` spelling, the array,
+ * everywhere — is the reason making it WORK was never on the table.
  */
 /** A field name paired with a direction — the spec's `SortConfig`. */
 export interface QuerySortEntry {
     field?: string;
     order?: 'asc' | 'desc';
 }
+/**
+ * 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 declare function resetRetiredSortSpellingReports(): void;
+/**
+ * A sort entry after normalization — BOTH keys present, always. That is the
+ * difference from {@link QuerySortEntry}, whose two members are optional
+ * because it describes what an author may WRITE, not what survives this door.
+ */
+export interface NormalizedSortEntry {
+    field: string;
+    order: 'asc' | 'desc';
+}
+/**
+ * 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 declare function normalizeSortEntries(sort: QuerySortEntry[] | undefined | null): NormalizedSortEntry[] | undefined;
 /**
  * Normalize an authored `sort` into the field→direction map used for
  * `QueryParams.$orderby`.
  *
- * @param sort `"name desc"` (legacy string) or `SortConfig[]`.
+ * 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 declare function convertSortToQueryParams(sort: string | QuerySortEntry[] | undefined | null): Record<string, 'asc' | 'desc'> | undefined;
+export declare function convertSortToQueryParams(sort: QuerySortEntry[] | undefined | null): Record<string, 'asc' | 'desc'> | undefined;

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';