@object-ui/core 16.1.0 → 17.1.0

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

package/dist/validation/validators/object-validation-engine.d.ts

@@ -6,23 +6,92 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * @object-ui/core - Object-Level Validation Engine
- *
- * ObjectStack Spec v2.0.1 compliant validation engine for object-level validation rules.
- * Supports all 9 validation types from the specification:
- * - ScriptValidation
- * - UniquenessValidation
- * - StateMachineValidation
- * - CrossFieldValidation
- * - AsyncValidation
- * - ConditionalValidation
- * - FormatValidation
- * - RangeValidation
+ * @object-ui/core - Object-Level Validation Engine — **DEPRECATED** (#3110)
+ *
+ * A client-side pre-check of the rules an object declares in
+ * `ObjectSchema.validations`. The authority is the server
+ * (`objectql/src/validation/rule-validator.ts`), which evaluates the same rules
+ * on the write path.
+ *
+ * ## Why this is deprecated rather than finished
+ *
+ * Validation rules are ENFORCEMENT, and enforcement is single-implementation on
+ * the server by design. `evaluator/fieldRules.ts` draws that line explicitly:
+ * PRESENTATION predicates (`visibleWhen` / `readonlyWhen` / `requiredWhen`) are
+ * evaluated client-side by delegating to the canonical `ExpressionEngine`,
+ * "rather than re-implementing a parallel evaluator" (ADR-0036). This module is
+ * that parallel evaluator, on the enforcement side of the line.
+ *
+ * #3103 converged its semantics onto the server rule-for-rule, with eight
+ * mutation-tested gates — and it STILL left a known divergence: the server
+ * carries ADR-0113's legacy-violation exemption (reject only when the merged
+ * state violates AND this write makes it worse, so a pre-existing violation on
+ * an old row passes), and this engine does not. Editing an unrelated field on a
+ * legacy row would be blocked here and accepted there. That is the argument in
+ * one line: mirroring cross-repo behaviour is structurally unreliable, not
+ * unreliable-this-time.
+ *
+ * ## What to use instead
+ *
+ * Let the write fail and render the server's rejection — it is already
+ * structured (`field` / `code` / `message`, plus a label since objectstack#3957).
+ * If pre-submit feedback is wanted, the answer is a **validate-only (dry-run)
+ * write** on the server: identical UX, zero parity risk, and it also covers the
+ * two rule kinds a client can never check — `unique` (needs the database) and
+ * `json_schema` (ajv lives server-side).
+ *
+ * Nothing here has been removed or changed in behaviour; existing callers keep
+ * working. `validation-engine-stays-unwired.test.ts` fails if a production
+ * module starts importing this one, so the decision is a mechanism rather than
+ * this comment (#3017).
+ *
+ * ## When to revisit
+ *
+ * Offline writes (`OfflineConfig`). With no server to ask, a client evaluator
+ * stops being redundant and becomes necessary. The precondition then is
+ * conformance fixtures shipped by `@objectstack/spec` — golden
+ * (rule, record, verdict) triples both repos run in CI — because that is the
+ * only thing that turns cross-repo parity into a mechanism instead of a habit.
+ * Reverse the decision in #3110 before reversing it here.
+ *
+ * ## Semantics (unchanged, for as long as this exists)
+ *
+ * The rule types come from `@object-ui/types`, which derives them from
+ * `@objectstack/spec/data` (objectstack#4115). Semantics mirrored from the
+ * server:
+ *
+ *  - **Polarity.** A `script` / `cross_field` `condition` and a `conditional`
+ *    `when` express the FAILURE condition: predicate TRUE ⇒ rule VIOLATED.
+ *  - **Fail-open on broken, fail-closed on violated.** A predicate that cannot
+ *    be evaluated (parse error, unknown identifier, unusable expression
+ *    envelope) is a broken rule, not a violated one — it is skipped, not
+ *    reported. Likewise a malformed `regex`.
+ *  - **Spec defaults, not falsy reads.** `active` defaults to `true` and
+ *    `events` to `['insert','update']` — they arrive absent from `/meta`
+ *    because the spec applies those defaults at parse time. Reading an absent
+ *    `active` as "off" would silently disable every rule authored without it.
+ *  - **`priority` orders execution** (lower first, stable).
+ *  - **`format` and `state_machine` only fire when the write TOUCHES the
+ *    field**, matching the server; emptiness and requiredness belong to the
+ *    field-shape validator.
+ *
+ * Two documented divergences from the server, both in the safe direction:
+ *
+ *  1. The default evaluator is a small non-CEL parser (see
+ *     `SimpleExpressionEvaluator`), so a predicate using real CEL constructs
+ *     evaluates to nothing and fails open. Pass a CEL-backed
+ *     `ValidationExpressionEvaluator` to close that gap.
+ *  2. `unique` / `async` / `range` rules are still dispatched. They are
+ *     @deprecated objectui-local variants that the spec's `ValidationRuleSchema`
+ *     rejects outright, so they cannot arrive from `/meta` — only a caller
+ *     building rules by hand can produce one.
  *
  * @module object-validation-engine
  * @packageDocumentation
  */
 import type { ObjectValidationRule } from '@object-ui/types';
+/** Write contexts a rule can run on. The spec retired `delete` (objectstack#3184). */
+export type ObjectValidationEvent = 'insert' | 'update';
 /**
  * Validation context for object-level validations
  */
@@ -56,63 +125,114 @@ export interface ValidationExpressionEvaluator {
     evaluate(expression: string, context: Record<string, any>): any;
 }
 /**
- * Object-Level Validation Engine
- * Implements ObjectStack Spec v2.0.1 validation framework
+ * Object-Level Validation Engine — the client pre-check described at the top of
+ * this module.
+ *
+ * @deprecated (#3110) Validation rules are enforcement, and enforcement is
+ * single-implementation on the server (`objectql`'s rule-validator). Render the
+ * server's rejection instead; for pre-submit feedback, use a validate-only
+ * (dry-run) write. Still functional and still correct as of #3103 — but it
+ * cannot stay in step with the server without a conformance-fixture mechanism
+ * that does not exist yet. See the module header.
  */
 export declare class ObjectValidationEngine {
     private expressionEvaluator;
     private uniquenessChecker?;
     constructor(expressionEvaluator?: ValidationExpressionEvaluator, uniquenessChecker?: (fields: string[], values: Record<string, any>, scope?: string, context?: ObjectValidationContext) => Promise<boolean>);
     /**
-     * Validate a record against a set of validation rules
+     * Validate a record against a set of validation rules.
+     *
+     * Rules run in `priority` order (lower first, stable within a priority), and
+     * only when `active` is not explicitly `false` and `events` covers this write
+     * context — reading the spec's defaults, not the falsiness of an absent key.
      */
-    validateRecord(rules: ObjectValidationRule[], context: ObjectValidationContext, event?: 'insert' | 'update' | 'delete'): Promise<ObjectValidationResult[]>;
+    validateRecord(rules: ObjectValidationRule[], context: ObjectValidationContext, event?: ObjectValidationEvent): Promise<ObjectValidationResult[]>;
     /**
-     * Validate a single rule
+     * Validate a single rule.
+     *
+     * `rule` is widened past `ObjectValidationRule` because a `conditional`'s
+     * `then` / `otherwise` branch may be any rule the SPEC's union admits —
+     * including `json_schema`, which this engine does not implement.
      */
     private validateRule;
     /**
-     * Validate script-based rule
+     * The evaluation scope for a predicate.
+     *
+     * The server binds `{ record, previous }`, so a spec-authored predicate reads
+     * `record.amount`. objectui's own rules have always been written against the
+     * bare field name (`amount`). Both are bound — the roots last so a field
+     * literally called `record` cannot shadow them.
      */
-    private validateScript;
+    private scopeFor;
+    /**
+     * Evaluate a `script` / `cross_field` predicate.
+     *
+     * Both variants share one path on the server, and so do they here. The
+     * predicate is the FAILURE condition: TRUE means the rule is violated. A
+     * predicate that cannot be evaluated is a BROKEN rule and fails open.
+     */
+    private validatePredicate;
     /**
      * Validate uniqueness constraint
      */
     private validateUniqueness;
     /**
-     * Validate state machine transitions
+     * Validate state machine transitions (ADR-0020).
+     *
+     * A flat `field` plus a `{ from: [allowedTo] }` map. Semantics mirror the
+     * server-side rule-validator:
+     *
+     *   INSERT
+     *   - no `initialStates` declared        → allow (legacy no-op)
+     *   - field absent from the write        → allow (requiredness is not our job)
+     *   - value empty                        → allow (ditto)
+     *   - value ∉ initialStates              → reject (the FSM entry point, #3165)
+     *
+     *   UPDATE
+     *   - field absent from the write        → allow (no transition to police)
+     *   - no prior record                    → allow (cannot reason)
+     *   - field unchanged, or cleared        → allow (no transition)
+     *   - `from` not declared in the map     → lenient allow (unconstrained)
+     *   - `to` ∉ transitions[from]           → reject
      */
     private validateStateMachine;
-    /**
-     * Validate cross-field constraints
-     */
-    private validateCrossField;
     /**
      * Validate async/remote validation
      */
     private validateAsync;
     /**
-     * Validate conditional rules
+     * Validate a conditional rule.
+     *
+     * Evaluates `when`, then recurses into `then` (TRUE) or `otherwise` (FALSE).
+     * The nested rule supplies the violation; an un-evaluable `when` is a broken
+     * rule and fails open. A branch whose own `active` is explicitly `false` is
+     * skipped, matching the server.
      */
     private validateConditional;
     /**
-     * Validate format/pattern
+     * Validate a field's format against `regex` and/or a named `format`.
+     *
+     * Mirrors the server: the rule only fires when the write TOUCHES the field and
+     * the value is non-empty (requiredness and type-shape belong to the
+     * field-level validator, so an absent or blank value is not a format
+     * violation). Both checks apply when both are declared. A `regex` that will
+     * not compile is a BROKEN rule — logged and skipped, never a violation.
      */
     private validateFormat;
     /**
      * Validate range constraints
      */
     private validateRange;
-    /**
-     * Get predefined regex pattern
-     */
-    private getPredefinedPattern;
 }
 /**
  * Default instance
+ *
+ * @deprecated (#3110) See `ObjectValidationEngine`.
  */
 export declare const defaultObjectValidationEngine: ObjectValidationEngine;
 /**
  * Convenience function to validate a record
+ *
+ * @deprecated (#3110) See `ObjectValidationEngine`.
  */
-export declare function validateRecord(rules: ObjectValidationRule[], context: ObjectValidationContext, event?: 'insert' | 'update' | 'delete'): Promise<ObjectValidationResult[]>;
+export declare function validateRecord(rules: ObjectValidationRule[], context: ObjectValidationContext, event?: ObjectValidationEvent): Promise<ObjectValidationResult[]>;