@object-ui/core 17.5.0 → 17.7.0

package/dist/utils/retired-field-types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * ObjectUI — retired field-type spellings
+ * 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.
+ */
+/**
+ * TOMBSTONE table — field-type spellings this renderer has RETIRED, mapped to
+ * the prescription an author must follow instead (ADR-0049 enforce-or-remove).
+ *
+ * A retired spelling is not merely absent: absence here means
+ * `mapFieldTypeToFormType`'s `|| 'field:text'` tail would hand back a
+ * working plain text input, which is the failure mode this table exists to
+ * prevent. An author who writes a retired name — or an AI author who copies one
+ * out of a stale doc — must be TOLD, not quietly given a text box that looks
+ * like it worked. So each entry resolves to a registered tombstone widget that
+ * renders a visible refusal naming the migration
+ * (`packages/fields/src/index.tsx`), while {@link reportRetiredFieldType}
+ * writes the same prescription to the console.
+ *
+ * `owner` (objectui#4814, ruling A′): a synonym for `user` with zero behavioral
+ * delta — both resolved to the SAME `UserField` widget — and absent from the
+ * spec's closed 48-member `FieldType`, so no object schema could ever declare
+ * it; it was reachable only through hand-written SDUI. Three code faces had
+ * already drifted apart on this one word (the form's data-source rule excluded
+ * it while plugin-grid's bulk dialog included it), which is the standing
+ * evidence that a second spelling for one concept is a drift channel, not a
+ * convenience. The idiom survives verbatim as `{ type: 'user', name: 'owner' }`.
+ *
+ * ## Why this table lives in `@object-ui/core` and not in `@object-ui/fields`
+ *
+ * It was born in `packages/fields/src/field-type-alias.ts`, next to the widget
+ * map that is its first consumer, and `@object-ui/fields` still exports every
+ * name in this module so no consumer of that surface had to move. It was HOISTED
+ * here by objectui#4914, and for a measured reason rather than a tidiness one:
+ * the retirement gate has to run ahead of six predicate faces, and one of them
+ * — `operatorsForFieldType` / the filter row's control choice in
+ * `packages/components/src/custom/filter-builder.tsx` — lives in
+ * `@object-ui/components`, which `@object-ui/fields` DEPENDS ON (54 source
+ * files import from it). A `components → fields` import is a package cycle, so
+ * the six faces could not all read one table while that table lived in
+ * `fields`.
+ *
+ * The alternative was a second copy of the table inside `components`, and that
+ * is precisely what this file exists to make impossible: two tables means two
+ * `reportedRetiredTypes` sets, so one retired spelling logs its prescription
+ * TWICE — and the "fires once" half of the ruling would be false the day it
+ * landed. `@object-ui/core` is below all six faces' packages (it imports only
+ * `@object-ui/types`), and already owns the sibling cross-package field-type
+ * vocabulary — {@link EXPANDABLE_FIELD_TYPES} in `./expand-fields.js`, whose
+ * own docblock records what happened the last time this kind of table was
+ * hand-copied per consumer. One table, one home, seven consumers.
+ */
+export declare const RETIRED_FIELD_TYPES: Readonly<Record<string, string>>;
+/**
+ * THE retirement gate — true when a spelling has been retired by this renderer.
+ *
+ * Ruled into existence by the maintainer on 2026-08-18 (objectui#4914, option
+ * B) as the ONE question every field-type predicate asks before it answers:
+ * "a retired spelling fires `reportRetiredFieldType` once and takes the
+ * established disposition, instead of riding the lookup-family paths or
+ * silently degrading."
+ *
+ * Quantified over the whole table rather than written per spelling, which is
+ * the entire point of having a gate at all: the next retirement closes every
+ * face the day it lands in {@link RETIRED_FIELD_TYPES}, instead of leaving each
+ * consumer open until someone notices it. `owner` survived objectui#4814 in
+ * thirteen more faces exactly because each one had hand-written its own
+ * membership list.
+ *
+ * `hasOwnProperty`, not `RETIRED_FIELD_TYPES[type]`: a `type` of
+ * `'constructor'` or `'toString'` reaches `Object.prototype` and would answer
+ * truthy through a plain index read.
+ *
+ * @param type - The spelling an author wrote (or a backend column declared).
+ * @returns `true` when the spelling is retired. Pure — it does NOT log; pair it
+ * with {@link reportRetiredFieldType} at the face that wants to be loud.
+ */
+export declare function isRetiredFieldType(type: string | undefined | null): boolean;
+/**
+ * Report a retired field-type spelling loudly, once per spelling.
+ *
+ * @param fieldType - The spelling the author wrote.
+ * @returns `true` when `fieldType` is retired (whether or not this call was the
+ * one that logged), so callers can branch on it without a second table lookup.
+ */
+export declare function reportRetiredFieldType(fieldType: string): boolean;
+/** Test seam — forget which spellings have been reported. */
+export declare function resetRetiredFieldTypeReports(): void;

package/dist/utils/retired-field-types.js

@@ -0,0 +1,124 @@
+/**
+ * ObjectUI — retired field-type spellings
+ * 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.
+ */
+/**
+ * TOMBSTONE table — field-type spellings this renderer has RETIRED, mapped to
+ * the prescription an author must follow instead (ADR-0049 enforce-or-remove).
+ *
+ * A retired spelling is not merely absent: absence here means
+ * `mapFieldTypeToFormType`'s `|| 'field:text'` tail would hand back a
+ * working plain text input, which is the failure mode this table exists to
+ * prevent. An author who writes a retired name — or an AI author who copies one
+ * out of a stale doc — must be TOLD, not quietly given a text box that looks
+ * like it worked. So each entry resolves to a registered tombstone widget that
+ * renders a visible refusal naming the migration
+ * (`packages/fields/src/index.tsx`), while {@link reportRetiredFieldType}
+ * writes the same prescription to the console.
+ *
+ * `owner` (objectui#4814, ruling A′): a synonym for `user` with zero behavioral
+ * delta — both resolved to the SAME `UserField` widget — and absent from the
+ * spec's closed 48-member `FieldType`, so no object schema could ever declare
+ * it; it was reachable only through hand-written SDUI. Three code faces had
+ * already drifted apart on this one word (the form's data-source rule excluded
+ * it while plugin-grid's bulk dialog included it), which is the standing
+ * evidence that a second spelling for one concept is a drift channel, not a
+ * convenience. The idiom survives verbatim as `{ type: 'user', name: 'owner' }`.
+ *
+ * ## Why this table lives in `@object-ui/core` and not in `@object-ui/fields`
+ *
+ * It was born in `packages/fields/src/field-type-alias.ts`, next to the widget
+ * map that is its first consumer, and `@object-ui/fields` still exports every
+ * name in this module so no consumer of that surface had to move. It was HOISTED
+ * here by objectui#4914, and for a measured reason rather than a tidiness one:
+ * the retirement gate has to run ahead of six predicate faces, and one of them
+ * — `operatorsForFieldType` / the filter row's control choice in
+ * `packages/components/src/custom/filter-builder.tsx` — lives in
+ * `@object-ui/components`, which `@object-ui/fields` DEPENDS ON (54 source
+ * files import from it). A `components → fields` import is a package cycle, so
+ * the six faces could not all read one table while that table lived in
+ * `fields`.
+ *
+ * The alternative was a second copy of the table inside `components`, and that
+ * is precisely what this file exists to make impossible: two tables means two
+ * `reportedRetiredTypes` sets, so one retired spelling logs its prescription
+ * TWICE — and the "fires once" half of the ruling would be false the day it
+ * landed. `@object-ui/core` is below all six faces' packages (it imports only
+ * `@object-ui/types`), and already owns the sibling cross-package field-type
+ * vocabulary — {@link EXPANDABLE_FIELD_TYPES} in `./expand-fields.js`, whose
+ * own docblock records what happened the last time this kind of table was
+ * hand-copied per consumer. One table, one home, seven consumers.
+ */
+export const RETIRED_FIELD_TYPES = Object.freeze({
+    owner: "[object-ui] Field type `owner` was RETIRED (objectui#4814). It was a synonym " +
+        "for `user` with no behavioral difference, and it is not a member of " +
+        "`@objectstack/spec`'s FieldType. Write the record-owner field as " +
+        "`{ type: 'user', name: 'owner' }` — the field NAME carries the ownership " +
+        "meaning, the type carries the widget. The `widget: 'field:owner'` spelling " +
+        "is retired with it.",
+});
+/**
+ * THE retirement gate — true when a spelling has been retired by this renderer.
+ *
+ * Ruled into existence by the maintainer on 2026-08-18 (objectui#4914, option
+ * B) as the ONE question every field-type predicate asks before it answers:
+ * "a retired spelling fires `reportRetiredFieldType` once and takes the
+ * established disposition, instead of riding the lookup-family paths or
+ * silently degrading."
+ *
+ * Quantified over the whole table rather than written per spelling, which is
+ * the entire point of having a gate at all: the next retirement closes every
+ * face the day it lands in {@link RETIRED_FIELD_TYPES}, instead of leaving each
+ * consumer open until someone notices it. `owner` survived objectui#4814 in
+ * thirteen more faces exactly because each one had hand-written its own
+ * membership list.
+ *
+ * `hasOwnProperty`, not `RETIRED_FIELD_TYPES[type]`: a `type` of
+ * `'constructor'` or `'toString'` reaches `Object.prototype` and would answer
+ * truthy through a plain index read.
+ *
+ * @param type - The spelling an author wrote (or a backend column declared).
+ * @returns `true` when the spelling is retired. Pure — it does NOT log; pair it
+ * with {@link reportRetiredFieldType} at the face that wants to be loud.
+ */
+export function isRetiredFieldType(type) {
+    if (typeof type !== 'string' || !type)
+        return false;
+    return Object.prototype.hasOwnProperty.call(RETIRED_FIELD_TYPES, type);
+}
+/**
+ * Spellings already reported this session, so a retired type inside a rendered
+ * list logs its prescription ONCE instead of once per row. The message is a
+ * fix instruction for an author, not a per-render event — a 1000-row grid
+ * repeating it 1000 times buries the very thing it is trying to surface.
+ *
+ * Module state, and that is load bearing now that SEVEN faces call the reporter
+ * (objectui#4914): the dedupe is per SPELLING, not per face, so a filter row
+ * whose column is refused by `operatorsForFieldType`, by the control chooser
+ * and by `normalizeFieldType` on the same render still prints one line.
+ */
+const reportedRetiredTypes = new Set();
+/**
+ * Report a retired field-type spelling loudly, once per spelling.
+ *
+ * @param fieldType - The spelling the author wrote.
+ * @returns `true` when `fieldType` is retired (whether or not this call was the
+ * one that logged), so callers can branch on it without a second table lookup.
+ */
+export function reportRetiredFieldType(fieldType) {
+    const prescription = isRetiredFieldType(fieldType) ? RETIRED_FIELD_TYPES[fieldType] : undefined;
+    if (!prescription)
+        return false;
+    if (!reportedRetiredTypes.has(fieldType)) {
+        reportedRetiredTypes.add(fieldType);
+        console.error(prescription);
+    }
+    return true;
+}
+/** Test seam — forget which spellings have been reported. */
+export function resetRetiredFieldTypeReports() {
+    reportedRetiredTypes.clear();
+}

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

@@ -9,47 +9,149 @@
  * 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.
- *
- * This is the same conversion three sibling blocks already inline privately
- * (`ObjectGantt` / `ObjectMap` / `ObjectCalendar`, byte-identical copies). It is
- * hoisted here because objectstack#7137 added two more read sites
- * (`object-timeline`, `record:line_items`), and a fifth and sixth private copy is
- * how the conversions start disagreeing. Collapsing the three existing copies
- * onto this one is deliberately NOT part of #7137 — it is tracked as
- * objectstack#7148.
- *
- * Two deliberate differences from those private copies, both of which make this
- * function more faithful to the declared contract rather than adding tolerance:
- *
- *  - **`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 require BOTH keys and silently drop such an entry, which loses an
+ * 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 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
+ * make this function more faithful to the declared contract rather than adding
+ * tolerance — and both are BEHAVIOUR CHANGES the migration delivered, not pure
+ * refactor:
+ *
+ *  - **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;