@object-ui/core 16.0.0 → 17.1.0

package/dist/utils/normalize-list-view.d.ts

@@ -0,0 +1,99 @@
+/**
+ * ObjectUI — list-view vocabulary canonicalization
+ * 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.
+ */
+/** ListView's toolbar density vocabulary — three steps, not the spec's five. */
+export type DensityMode = 'compact' | 'comfortable' | 'spacious';
+/** The spec's `RowHeightSchema` vocabulary. */
+export type RowHeight = 'compact' | 'short' | 'medium' | 'tall' | 'extra_tall';
+/**
+ * `densityMode` → `rowHeight`. The two vocabularies are not the same size: the
+ * spec has five row heights, ListView's toolbar offers three. Widening maps
+ * each density onto the spec value the renderer already resolves it back to
+ * (see {@link ROW_HEIGHT_TO_DENSITY_MODE}), so a fold followed by a read is a
+ * round trip — `spacious` → `tall` → `spacious`.
+ */
+export declare const DENSITY_MODE_TO_ROW_HEIGHT: Record<DensityMode, RowHeight>;
+/**
+ * `rowHeight` → `densityMode`, the read direction. Narrowing five values onto
+ * three is lossy by construction: `short` collapses into `compact` and
+ * `extra_tall` into `spacious`. Exported so the renderer and the persistence
+ * layer agree on the collapse instead of each hard-coding its own table.
+ */
+export declare const ROW_HEIGHT_TO_DENSITY_MODE: Record<RowHeight, DensityMode>;
+/**
+ * Tolerant reader for {@link ROW_HEIGHT_TO_DENSITY_MODE}. View metadata is
+ * user-authored, so `rowHeight` is not guaranteed to be one of the five spec
+ * values — an unknown one lands on `comfortable` rather than rendering an
+ * undefined density. Keeping the fallback here means every surface collapses
+ * the same way.
+ */
+export declare function rowHeightToDensityMode(rowHeight: unknown): DensityMode;
+/**
+ * ObjectUI's `list-view` node historically used a different vocabulary from
+ * `@objectstack/spec` for the same concepts (`fields` where the spec says
+ * `columns`, `viewType` where it says `type`, …). Issue #2231 closed the
+ * type-level fork; #2890 closes the vocabulary fork.
+ *
+ * Stored view metadata in user databases still carries the legacy keys, so the
+ * renderer cannot simply stop accepting them. Per AGENTS.md Commandment #0.1 the
+ * answer is NOT a per-read-site `??` fallback — those fossilize a second de-facto
+ * contract and drift apart (they already had: `ObjectGrid` preferred `columns`
+ * in one branch and `fields` in another). Instead legacy acceptance lives HERE,
+ * in one documented normalizer at the component boundary, mirroring
+ * `normalizeSchemaReferenceKeys` (object schemas) and the spec's own
+ * `normalizeVisibleWhen` / `normalizeFilterOperator` migration bridges.
+ *
+ * Note this cannot be a `z.preprocess` on `ListViewSchema`: nothing on the
+ * render path parses view metadata through zod (the zod schemas are used by the
+ * CLI validator, the VS Code extension and tests only), so a schema-level fold
+ * would never run. The guarantee comes from the call site instead — `ListView`
+ * normalizes before it reads anything.
+ *
+ * The fold is deliberately one-directional: the canonical key wins when both are
+ * present, and the legacy key is REMOVED from the result so a read-site that was
+ * missed fails loudly instead of quietly taking the legacy path. Like a spec
+ * migration bridge, this is expected to be dropped in a future major once stored
+ * metadata has been migrated.
+ *
+ * Non-mutating and allocation-frugal: returns the input by reference when there
+ * is nothing to fold, so `ListView`'s downstream `useMemo`s keep a stable
+ * dependency identity on the common (already-canonical) path.
+ *
+ * Currently folded:
+ *  - `fields` → `columns` (#2890 scope A step 1)
+ *  - `densityMode` → `rowHeight` (#2890 scope A step 2)
+ *  - the `show*` toolbar flags → `userActions` (#2890 scope A step 3), and
+ *    `showDescription` → `appearance.showDescription`. The canonical key wins
+ *    per-flag, so a view may carry `userActions` for some toggles and a legacy
+ *    flag for others. NOTE the fold does not apply any default: an absent flag
+ *    stays absent, because the defaults are per-toggle (search/sort/filter/
+ *    rowHeight/group default ON, hideFields/rowColor default OFF) and belong to
+ *    the renderer, not to the vocabulary bridge.
+ *  - `aria: { label, describedBy }` → the spec's `AriaProps`
+ *    (`{ ariaLabel, ariaDescribedBy }`), and `sharing: { visibility, enabled }`
+ *    → the spec's `ViewSharing` (`{ type }`) — #2890 scope A step 5. `aria.live`
+ *    survives untouched: it has no spec counterpart.
+ *  - `filters` → `filter` (#2890 scope A step 4). A key rename only: BOTH keys
+ *    carry an ObjectQL FilterNode array (`[['stage','=','won']]`) everywhere in
+ *    objectui — every consumer passes the value straight to `$filter`. The spec
+ *    types `filter` as `ViewFilterRule[]` (`{field, operator, value}` objects),
+ *    so objectui's field is typed from the spec but used as something else.
+ *    That mismatch is real and out of scope here; converting formats inside a
+ *    vocabulary fold would change what reaches the data source.
+ *  - `viewType`: a missing kind, or the view CATEGORY `'list'` that AI-authored
+ *    metadata stores and hosts forward verbatim, becomes the renderable `'grid'`
+ *    — otherwise it reaches the renderer's typeless default branch and shows as
+ *    a red "Unknown component type" box.
+ *  - each `columns` entry's IDENTITY — `name` / `fieldName` → the spec's `field`
+ *    (#3104). This one MIRRORS instead of deleting, for the reason given on
+ *    {@link normalizeColumnIdentities}: `columns` entries cross the package
+ *    boundary into host renderers, so dropping `name` from under them is a
+ *    breaking change with no inventory. Runs AFTER the `fields` → `columns` fold
+ *    above, so a view that spells its column list the legacy way still gets its
+ *    entries canonicalized.
+ */
+export declare function normalizeListViewSchema<T>(schema: T): T;

package/dist/utils/normalize-list-view.js

@@ -0,0 +1,255 @@
+/**
+ * ObjectUI — list-view vocabulary canonicalization
+ * 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 { normalizeColumnIdentities } from './column-identity.js';
+/**
+ * `densityMode` → `rowHeight`. The two vocabularies are not the same size: the
+ * spec has five row heights, ListView's toolbar offers three. Widening maps
+ * each density onto the spec value the renderer already resolves it back to
+ * (see {@link ROW_HEIGHT_TO_DENSITY_MODE}), so a fold followed by a read is a
+ * round trip — `spacious` → `tall` → `spacious`.
+ */
+export const DENSITY_MODE_TO_ROW_HEIGHT = {
+    compact: 'compact',
+    comfortable: 'medium',
+    spacious: 'tall',
+};
+/**
+ * `rowHeight` → `densityMode`, the read direction. Narrowing five values onto
+ * three is lossy by construction: `short` collapses into `compact` and
+ * `extra_tall` into `spacious`. Exported so the renderer and the persistence
+ * layer agree on the collapse instead of each hard-coding its own table.
+ */
+export const ROW_HEIGHT_TO_DENSITY_MODE = {
+    compact: 'compact',
+    short: 'compact',
+    medium: 'comfortable',
+    tall: 'spacious',
+    extra_tall: 'spacious',
+};
+/**
+ * Tolerant reader for {@link ROW_HEIGHT_TO_DENSITY_MODE}. View metadata is
+ * user-authored, so `rowHeight` is not guaranteed to be one of the five spec
+ * values — an unknown one lands on `comfortable` rather than rendering an
+ * undefined density. Keeping the fallback here means every surface collapses
+ * the same way.
+ */
+export function rowHeightToDensityMode(rowHeight) {
+    if (typeof rowHeight === 'string' && rowHeight in ROW_HEIGHT_TO_DENSITY_MODE) {
+        return ROW_HEIGHT_TO_DENSITY_MODE[rowHeight];
+    }
+    return 'comfortable';
+}
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/**
+ * Legacy toolbar-visibility flags → their `userActions` key (#2890 scope A
+ * step 3). The spec documents `userActions` as "which interactive actions are
+ * available to users in the view toolbar", and already carries `rowHeight` —
+ * objectui's `showDensity` under its spec name. `group` / `hideFields` /
+ * `rowColor` are the same kind of toggle and are named after the config key
+ * they gate (`grouping`, `hiddenFields`, `rowColor`), pending promotion into
+ * `UserActionsConfigSchema` upstream.
+ */
+const SHOW_FLAG_TO_USER_ACTION = {
+    showSearch: 'search',
+    showSort: 'sort',
+    showFilters: 'filter',
+    showDensity: 'rowHeight',
+    showGroup: 'group',
+    showHideFields: 'hideFields',
+    showColor: 'rowColor',
+};
+/**
+ * Legacy `sharing.visibility` → the spec's `ViewSharing.type`. The spec models
+ * two ownership kinds; objectui's four-value audience enum collapses onto them:
+ * only `private` is personal, everything wider is collaborative.
+ */
+const VISIBILITY_TO_SHARING_TYPE = {
+    private: 'personal',
+    team: 'collaborative',
+    organization: 'collaborative',
+    public: 'collaborative',
+};
+/** Legacy ARIA spellings → the spec's `AriaProps` keys. */
+const ARIA_KEY_ALIASES = {
+    label: 'ariaLabel',
+    describedBy: 'ariaDescribedBy',
+};
+/**
+ * ObjectUI's `list-view` node historically used a different vocabulary from
+ * `@objectstack/spec` for the same concepts (`fields` where the spec says
+ * `columns`, `viewType` where it says `type`, …). Issue #2231 closed the
+ * type-level fork; #2890 closes the vocabulary fork.
+ *
+ * Stored view metadata in user databases still carries the legacy keys, so the
+ * renderer cannot simply stop accepting them. Per AGENTS.md Commandment #0.1 the
+ * answer is NOT a per-read-site `??` fallback — those fossilize a second de-facto
+ * contract and drift apart (they already had: `ObjectGrid` preferred `columns`
+ * in one branch and `fields` in another). Instead legacy acceptance lives HERE,
+ * in one documented normalizer at the component boundary, mirroring
+ * `normalizeSchemaReferenceKeys` (object schemas) and the spec's own
+ * `normalizeVisibleWhen` / `normalizeFilterOperator` migration bridges.
+ *
+ * Note this cannot be a `z.preprocess` on `ListViewSchema`: nothing on the
+ * render path parses view metadata through zod (the zod schemas are used by the
+ * CLI validator, the VS Code extension and tests only), so a schema-level fold
+ * would never run. The guarantee comes from the call site instead — `ListView`
+ * normalizes before it reads anything.
+ *
+ * The fold is deliberately one-directional: the canonical key wins when both are
+ * present, and the legacy key is REMOVED from the result so a read-site that was
+ * missed fails loudly instead of quietly taking the legacy path. Like a spec
+ * migration bridge, this is expected to be dropped in a future major once stored
+ * metadata has been migrated.
+ *
+ * Non-mutating and allocation-frugal: returns the input by reference when there
+ * is nothing to fold, so `ListView`'s downstream `useMemo`s keep a stable
+ * dependency identity on the common (already-canonical) path.
+ *
+ * Currently folded:
+ *  - `fields` → `columns` (#2890 scope A step 1)
+ *  - `densityMode` → `rowHeight` (#2890 scope A step 2)
+ *  - the `show*` toolbar flags → `userActions` (#2890 scope A step 3), and
+ *    `showDescription` → `appearance.showDescription`. The canonical key wins
+ *    per-flag, so a view may carry `userActions` for some toggles and a legacy
+ *    flag for others. NOTE the fold does not apply any default: an absent flag
+ *    stays absent, because the defaults are per-toggle (search/sort/filter/
+ *    rowHeight/group default ON, hideFields/rowColor default OFF) and belong to
+ *    the renderer, not to the vocabulary bridge.
+ *  - `aria: { label, describedBy }` → the spec's `AriaProps`
+ *    (`{ ariaLabel, ariaDescribedBy }`), and `sharing: { visibility, enabled }`
+ *    → the spec's `ViewSharing` (`{ type }`) — #2890 scope A step 5. `aria.live`
+ *    survives untouched: it has no spec counterpart.
+ *  - `filters` → `filter` (#2890 scope A step 4). A key rename only: BOTH keys
+ *    carry an ObjectQL FilterNode array (`[['stage','=','won']]`) everywhere in
+ *    objectui — every consumer passes the value straight to `$filter`. The spec
+ *    types `filter` as `ViewFilterRule[]` (`{field, operator, value}` objects),
+ *    so objectui's field is typed from the spec but used as something else.
+ *    That mismatch is real and out of scope here; converting formats inside a
+ *    vocabulary fold would change what reaches the data source.
+ *  - `viewType`: a missing kind, or the view CATEGORY `'list'` that AI-authored
+ *    metadata stores and hosts forward verbatim, becomes the renderable `'grid'`
+ *    — otherwise it reaches the renderer's typeless default branch and shows as
+ *    a red "Unknown component type" box.
+ *  - each `columns` entry's IDENTITY — `name` / `fieldName` → the spec's `field`
+ *    (#3104). This one MIRRORS instead of deleting, for the reason given on
+ *    {@link normalizeColumnIdentities}: `columns` entries cross the package
+ *    boundary into host renderers, so dropping `name` from under them is a
+ *    breaking change with no inventory. Runs AFTER the `fields` → `columns` fold
+ *    above, so a view that spells its column list the legacy way still gets its
+ *    entries canonicalized.
+ */
+export function normalizeListViewSchema(schema) {
+    if (!schema || typeof schema !== 'object')
+        return schema;
+    const s = schema;
+    const legacyFields = s.fields;
+    const foldColumns = Array.isArray(legacyFields);
+    const legacyDensity = s.densityMode;
+    const foldRowHeight = typeof legacyDensity === 'string' && legacyDensity in DENSITY_MODE_TO_ROW_HEIGHT;
+    const legacyFilters = s.filters;
+    const foldFilter = Array.isArray(legacyFilters);
+    const legacyFlags = Object.keys(SHOW_FLAG_TO_USER_ACTION).filter((k) => typeof s[k] === 'boolean');
+    const foldDescription = typeof s.showDescription === 'boolean';
+    const aria = isRecord(s.aria) ? s.aria : undefined;
+    const foldAria = !!aria && Object.keys(ARIA_KEY_ALIASES).some((k) => aria[k] !== undefined);
+    const sharing = isRecord(s.sharing) ? s.sharing : undefined;
+    const foldSharing = !!sharing && (sharing.visibility !== undefined || sharing.enabled !== undefined);
+    const viewType = s.viewType;
+    const defaultViewKind = !viewType || viewType === 'list';
+    // The columns array the identity fold will see — mirroring the `foldColumns`
+    // precedence below (canonical `columns` wins; otherwise the legacy `fields`
+    // that is about to become it). `normalizeColumnIdentities` returns its input
+    // by reference when every entry is already canonical, so this comparison is
+    // also the "is there anything to do" test.
+    const columnsSource = Array.isArray(s.columns)
+        ? s.columns
+        : foldColumns
+            ? legacyFields
+            : undefined;
+    const foldedColumns = normalizeColumnIdentities(columnsSource);
+    const foldColumnIdentity = foldedColumns !== columnsSource;
+    if (!foldColumns && !foldRowHeight && !foldFilter && !legacyFlags.length &&
+        !foldDescription && !foldAria && !foldSharing && !defaultViewKind &&
+        !foldColumnIdentity) {
+        return schema;
+    }
+    const next = { ...s };
+    if (foldColumns) {
+        if (!Array.isArray(next.columns))
+            next.columns = legacyFields;
+        delete next.fields;
+    }
+    // After the `fields` → `columns` rename, so a legacy-spelled column LIST gets
+    // its per-entry identities canonicalized in the same pass.
+    if (foldColumnIdentity)
+        next.columns = foldedColumns;
+    if (foldRowHeight) {
+        if (typeof next.rowHeight !== 'string') {
+            next.rowHeight = DENSITY_MODE_TO_ROW_HEIGHT[legacyDensity];
+        }
+        delete next.densityMode;
+    }
+    if (foldFilter) {
+        if (!Array.isArray(next.filter))
+            next.filter = legacyFilters;
+        delete next.filters;
+    }
+    if (legacyFlags.length) {
+        const ua = { ...(isRecord(next.userActions) ? next.userActions : {}) };
+        for (const flag of legacyFlags) {
+            const key = SHOW_FLAG_TO_USER_ACTION[flag];
+            if (typeof ua[key] !== 'boolean')
+                ua[key] = s[flag];
+            delete next[flag];
+        }
+        next.userActions = ua;
+    }
+    if (foldDescription) {
+        const appearance = {
+            ...(isRecord(next.appearance) ? next.appearance : {}),
+        };
+        if (typeof appearance.showDescription !== 'boolean') {
+            appearance.showDescription = s.showDescription;
+        }
+        delete next.showDescription;
+        next.appearance = appearance;
+    }
+    if (foldAria && aria) {
+        const nextAria = { ...aria };
+        for (const [legacy, canonical] of Object.entries(ARIA_KEY_ALIASES)) {
+            if (nextAria[canonical] === undefined && aria[legacy] !== undefined) {
+                nextAria[canonical] = aria[legacy];
+            }
+            delete nextAria[legacy];
+        }
+        next.aria = nextAria;
+    }
+    if (foldSharing && sharing) {
+        const nextSharing = { ...sharing };
+        if (nextSharing.type === undefined) {
+            const visibility = typeof sharing.visibility === 'string' ? sharing.visibility : undefined;
+            // `enabled: true` with no audience is under-specified legacy input. It
+            // used to render the share badge titled "private", so it maps to
+            // `personal` — preserving what the user saw rather than adopting the
+            // spec's `collaborative` default and silently relabeling the badge.
+            const resolved = visibility
+                ? VISIBILITY_TO_SHARING_TYPE[visibility]
+                : sharing.enabled === true
+                    ? 'personal'
+                    : undefined;
+            if (resolved)
+                nextSharing.type = resolved;
+        }
+        delete nextSharing.visibility;
+        delete nextSharing.enabled;
+        next.sharing = nextSharing;
+    }
+    if (defaultViewKind)
+        next.viewType = 'grid';
+    return next;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+/** A cell value reduced to something two rows can be ordered by. */
+export type SortValue = string | number | boolean | null;
+export interface SortValueOptions {
+    /**
+     * `id → label` map for relational columns whose cell value is still a RAW id
+     * because the surface resolves labels client-side instead of asking the
+     * server for `$expand` (RelatedList does exactly this). When the raw value
+     * has an entry, the label the cell renders becomes the sort key.
+     */
+    labels?: Record<string, string>;
+}
+/**
+ * Reduce one cell value to the primitive a client-side sort should order by.
+ *
+ * - empty (`null` / `undefined` / `''`) → `null`, so callers can place blanks
+ *   consistently rather than sorting `undefined` against a string;
+ * - a `labels` hit (by the raw id) wins — that IS the string in the cell;
+ * - an expanded reference record resolves through {@link getRecordDisplayName},
+ *   the ONE shared display-name resolver (ADR-0079), so the sort key and the
+ *   lookup cell agree on which field names a record;
+ * - arrays join their resolved parts, mirroring how a multi-value cell reads;
+ * - primitives pass through unchanged (numbers stay numbers, so a number column
+ *   still sorts numerically rather than lexicographically).
+ */
+export declare function getSortValue(value: unknown, options?: SortValueOptions): SortValue;
+/**
+ * Compare two {@link SortValue}s **ascending**.
+ *
+ * Callers negate the result for descending, which is also why blanks are placed
+ * last here rather than "always last": negating moves them to the front, the
+ * same convention the inline comparators this replaces already had.
+ *
+ * Same-typed values compare in their own domain (numbers numerically, booleans
+ * false-before-true); anything else falls back to a locale-aware string compare
+ * with `numeric: true`, so `Item 2` precedes `Item 10`.
+ */
+export declare function compareSortValues(a: SortValue, b: SortValue): number;
+/**
+ * Convenience wrapper: reduce both cell values and compare them ascending.
+ *
+ * Prefer resolving the sort key ONCE per row (decorate → sort → undecorate)
+ * when sorting a whole collection — `getRecordDisplayName` walks the record, so
+ * calling it inside the comparator repeats that walk `O(n log n)` times.
+ */
+export declare function compareCellValues(a: unknown, b: unknown, options?: SortValueOptions): number;

package/dist/utils/sort-values.js

@@ -0,0 +1,125 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * sort-values — reduce a *cell value* to the primitive a CLIENT-SIDE sort should
+ * order by, and compare two of those primitives (objectui#3096).
+ *
+ * Why this exists: a relational column (`lookup` / `master_detail` / `tree` /
+ * `user` — see `EXPANDABLE_FIELD_TYPES`) does not hold the string its cell
+ * shows. Depending on the surface it holds either the `$expand`-ed related
+ * RECORD (`{ id, name, … }`) or a raw foreign-key id whose label was resolved
+ * separately. Both break the naive comparators these surfaces used to inline:
+ *
+ *   - `a[col] < b[col]` on two objects is ALWAYS false, so the comparator
+ *     collapses to the constant `1` and the "sort" permutes rows into an order
+ *     with no relation to anything on screen;
+ *   - `String(a[col])` on an object is `"[object Object]"` — every row compares
+ *     equal, so the sort silently does nothing;
+ *   - comparing raw ids (`rec_7f3…`) orders a column of human-readable names by
+ *     an opaque key, which reads to the user as "sorting is broken".
+ *
+ * Reducing the value to the label the cell renders makes a client-side sort
+ * order by what the user actually sees. This CANNOT fix a server `$orderby`,
+ * where the sort key is the stored id by construction — surfaces that sort on
+ * the server must instead not offer relational columns as sort keys (that half
+ * of #3096 lives at each entry point).
+ *
+ * Pure (no React / i18n), so every renderer package can share it.
+ */
+import { getRecordDisplayName } from './record-title.js';
+/**
+ * Reduce one cell value to the primitive a client-side sort should order by.
+ *
+ * - empty (`null` / `undefined` / `''`) → `null`, so callers can place blanks
+ *   consistently rather than sorting `undefined` against a string;
+ * - a `labels` hit (by the raw id) wins — that IS the string in the cell;
+ * - an expanded reference record resolves through {@link getRecordDisplayName},
+ *   the ONE shared display-name resolver (ADR-0079), so the sort key and the
+ *   lookup cell agree on which field names a record;
+ * - arrays join their resolved parts, mirroring how a multi-value cell reads;
+ * - primitives pass through unchanged (numbers stay numbers, so a number column
+ *   still sorts numerically rather than lexicographically).
+ */
+export function getSortValue(value, options) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    const labels = options?.labels;
+    if (typeof value === 'string') {
+        return labels?.[value] ?? value;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            return null;
+        // A numeric foreign key still deserves its resolved label.
+        return labels?.[String(value)] ?? value;
+    }
+    if (typeof value === 'boolean')
+        return value;
+    if (value instanceof Date) {
+        const time = value.getTime();
+        return Number.isNaN(time) ? null : time;
+    }
+    if (Array.isArray(value)) {
+        const parts = value
+            .map((entry) => getSortValue(entry, options))
+            .filter((entry) => entry !== null)
+            .map((entry) => String(entry));
+        return parts.length > 0 ? parts.join(', ') : null;
+    }
+    if (typeof value === 'object') {
+        const record = value;
+        // An expanded record can still carry a client-resolved label (the surface
+        // built its map from ids, the server expanded the same field).
+        const id = record.id ?? record._id;
+        if (id !== null && id !== undefined) {
+            const mapped = labels?.[String(id)];
+            if (mapped)
+                return mapped;
+        }
+        // `fallback: ''` so a record with nothing name-like reduces to `null`
+        // (sorted with the blanks) instead of the literal string "Untitled",
+        // which would bunch unrelated empty records under "U".
+        const name = getRecordDisplayName(undefined, record, { fallback: '' });
+        return name === '' ? null : name;
+    }
+    return String(value);
+}
+/**
+ * Compare two {@link SortValue}s **ascending**.
+ *
+ * Callers negate the result for descending, which is also why blanks are placed
+ * last here rather than "always last": negating moves them to the front, the
+ * same convention the inline comparators this replaces already had.
+ *
+ * Same-typed values compare in their own domain (numbers numerically, booleans
+ * false-before-true); anything else falls back to a locale-aware string compare
+ * with `numeric: true`, so `Item 2` precedes `Item 10`.
+ */
+export function compareSortValues(a, b) {
+    if (a === null && b === null)
+        return 0;
+    if (a === null)
+        return 1;
+    if (b === null)
+        return -1;
+    if (typeof a === 'boolean' && typeof b === 'boolean')
+        return (a ? 1 : 0) - (b ? 1 : 0);
+    if (typeof a === 'number' && typeof b === 'number')
+        return a - b;
+    return String(a).localeCompare(String(b), undefined, { numeric: true });
+}
+/**
+ * Convenience wrapper: reduce both cell values and compare them ascending.
+ *
+ * Prefer resolving the sort key ONCE per row (decorate → sort → undecorate)
+ * when sorting a whole collection — `getRecordDisplayName` walks the record, so
+ * calling it inside the comparator repeats that walk `O(n log n)` times.
+ */
+export function compareCellValues(a, b, options) {
+    return compareSortValues(getSortValue(a, options), getSortValue(b, options));
+}

package/dist/validation/index.d.ts

@@ -2,7 +2,15 @@
  * @object-ui/core - Validation Module
  *
  * Phase 3.5: Validation engine
- * ObjectStack Spec v2.0.1: Object-level validation
+ *
+ * Object-level validation. The rule vocabulary is owned by
+ * `@objectstack/spec/data` and derived in `@object-ui/types`; canonicity is
+ * carried by that derivation and its parity gate, not by this comment.
+ *
+ * The object-level rule ENGINE (`validators/`) is @deprecated (#3110) — the
+ * server is the single implementation of rule enforcement. Field/record SHAPE
+ * validation (`schema-validator.js`, `validation-engine.js`) is unaffected: it
+ * is client-side form validation, not a mirror of a server rule.
  */
 export * from './validation-engine.js';
 export * from './schema-validator.js';

package/dist/validation/index.js

@@ -2,7 +2,15 @@
  * @object-ui/core - Validation Module
  *
  * Phase 3.5: Validation engine
- * ObjectStack Spec v2.0.1: Object-level validation
+ *
+ * Object-level validation. The rule vocabulary is owned by
+ * `@objectstack/spec/data` and derived in `@object-ui/types`; canonicity is
+ * carried by that derivation and its parity gate, not by this comment.
+ *
+ * The object-level rule ENGINE (`validators/`) is @deprecated (#3110) — the
+ * server is the single implementation of rule enforcement. Field/record SHAPE
+ * validation (`schema-validator.js`, `validation-engine.js`) is unaffected: it
+ * is client-side form validation, not a mirror of a server rule.
  */
 export * from './validation-engine.js';
 export * from './schema-validator.js';

package/dist/validation/validators/index.d.ts

@@ -8,7 +8,13 @@
 /**
  * @object-ui/core - Validators
  *
- * ObjectStack Spec v2.0.1 compliant validators
+ * Publishes the @deprecated `ObjectValidationEngine` (#3110). Object-level
+ * validation rules are enforcement, and enforcement is single-implementation on
+ * the server (`objectql`'s rule-validator); objectui renders the server's
+ * rejection rather than predicting it, and pre-submit feedback belongs in a
+ * validate-only (dry-run) write. This barrel keeps the API exported for host
+ * applications that already depend on it — re-exporting is not wiring, and
+ * `validation-engine-stays-unwired.test.ts` enforces that distinction.
  *
  * @module validators
  * @packageDocumentation

package/dist/validation/validators/index.js

@@ -8,7 +8,13 @@
 /**
  * @object-ui/core - Validators
  *
- * ObjectStack Spec v2.0.1 compliant validators
+ * Publishes the @deprecated `ObjectValidationEngine` (#3110). Object-level
+ * validation rules are enforcement, and enforcement is single-implementation on
+ * the server (`objectql`'s rule-validator); objectui renders the server's
+ * rejection rather than predicting it, and pre-submit feedback belongs in a
+ * validate-only (dry-run) write. This barrel keeps the API exported for host
+ * applications that already depend on it — re-exporting is not wiring, and
+ * `validation-engine-stays-unwired.test.ts` enforces that distinction.
  *
  * @module validators
  * @packageDocumentation