@object-ui/core 17.2.0 → 17.3.0

package/dist/utils/predicate-fields.js

@@ -0,0 +1,163 @@
+/**
+ * ObjectUI — predicate field harvesting
+ * 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.
+ */
+/**
+ * Which record fields a view's PREDICATES read — the half of a view's field
+ * appetite that is not its columns.
+ *
+ * A list view projects what it DISPLAYS: `$select` is built from the column
+ * list (plus `id` and the expanded relation roots). That is correct for
+ * rendering and wrong for gating, because a `visible` / `disabled` /
+ * conditional-formatting predicate reads fields nobody put on screen — gating a
+ * row action on `record.owner` while showing Title / Status is the ordinary
+ * case, not an exotic one.
+ *
+ * The field then simply is not in the payload, and CEL does not treat an absent
+ * key as null: `record.owner == os.user.id` FAULTS with `No such key: owner`.
+ * Fault handling differs per surface and both answers are wrong — fail-CLOSED
+ * on the row kebab and the selection bar (the button silently disappears for
+ * everyone), fail-OPEN on the lenient paths (it appears for everyone). Nothing
+ * in either outcome points at a projection.
+ *
+ * Harvesting the names a predicate mentions and adding them to `$select` is
+ * what closes that. Note what it deliberately does NOT add: `$expand`. A
+ * predicate wants the stored foreign key, which is exactly what an unexpanded
+ * relation column already is — so a predicate-only relation field costs one
+ * more column and no extra round trip. (A relation that IS displayed still gets
+ * expanded for its label, and `toPredicateRecord` collapses it back for the
+ * predicate.)
+ */
+/**
+ * The columns the framework provisions on EVERY business object
+ * (`applySystemFields`) but does not publish in the object's `fields` metadata.
+ *
+ * They matter here because the most ordinary ownership predicate there is —
+ * `record.owner_id == os.user.id` — names one of them. Checking a harvested
+ * name against the declared fields alone would drop it, leaving the predicate
+ * with the same missing key the harvest exists to prevent.
+ *
+ * Deliberately the columns OBSERVED on a live payload rather than
+ * `SYSTEM_MANAGED_FIELD_NAMES` (`@object-ui/types`), which is the broader
+ * DISPLAY-oriented set and carries legacy aliases (`_id`, `createdAt`,
+ * `modified`, `space`) that are not columns anywhere. An alias in `$select` is
+ * exactly the unknown key the guard exists to keep out.
+ */
+export const PLATFORM_RECORD_COLUMNS = new Set([
+    'id',
+    'created_at', 'created_by',
+    'updated_at', 'updated_by',
+    'owner_id', 'organization_id', 'owning_business_unit_id',
+]);
+/**
+ * Whether a harvested name is safe to put in a `$select` projection: either the
+ * object declares it, or it is one of the platform columns every object has.
+ *
+ * The check is not pedantry — an unknown key is not ignored by every backend
+ * (the cloud multi-tenant runtime answers with an EMPTY result set), so without
+ * it one typo'd predicate could blank a whole list.
+ */
+export function isProjectableField(name, declaredFields) {
+    if (PLATFORM_RECORD_COLUMNS.has(name))
+        return true;
+    return !!declaredFields && typeof declaredFields === 'object' && name in declaredFields;
+}
+/**
+ * `record.x` / `data.x` — the two record-scoped spellings every surface binds.
+ * A bare `x` is deliberately NOT harvested: at predicate scope a bare
+ * identifier is just as likely to be `features`, `os`, `user` or a CEL builtin,
+ * and there is no way to tell without resolving. Authors are already directed
+ * to the prefixed form on every surface (a bare field reference throws on the
+ * record-header path), so this covers the documented spelling.
+ */
+const RECORD_REF = /\b(?:record|data)\.([A-Za-z_][A-Za-z0-9_]*)/g;
+/** Pull the CEL source out of any of the shapes a predicate is authored in. */
+function predicateSource(pred) {
+    if (typeof pred === 'string')
+        return pred.trim() || null;
+    if (pred && typeof pred === 'object') {
+        const src = pred.source;
+        if (typeof src === 'string')
+            return src.trim() || null;
+    }
+    return null;
+}
+/**
+ * Collect the record field names referenced by a set of predicates.
+ *
+ * Accepts predicates in every authored shape (bare CEL string, the
+ * `{ dialect, source }` envelope, `null`/`undefined`/boolean — the last three
+ * contribute nothing). Returns names in first-seen order, deduplicated.
+ *
+ * The result is a set of CANDIDATES, not verified fields: a typo'd predicate
+ * yields a name this object does not have. Callers must intersect it with the
+ * object's declared fields before putting it in a query — an unknown key in
+ * `$select` is not ignored by every backend (the cloud runtime answers with an
+ * empty result set), which would turn a typo into a blank list.
+ */
+export function collectPredicateFieldRefs(predicates) {
+    const out = [];
+    const seen = new Set();
+    for (const pred of predicates) {
+        const source = predicateSource(pred);
+        if (!source)
+            continue;
+        RECORD_REF.lastIndex = 0;
+        for (let m = RECORD_REF.exec(source); m; m = RECORD_REF.exec(source)) {
+            const name = m[1];
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            out.push(name);
+        }
+    }
+    return out;
+}
+/**
+ * Every predicate a list-ish view carries, flattened for
+ * {@link collectPredicateFieldRefs}.
+ *
+ * One reader so the projection cannot fall behind the surfaces: each entry here
+ * is a place a predicate is actually evaluated against a row — conditional
+ * formatting, the row kebab (custom defs AND the built-in Edit/Delete
+ * overrides), the selection bar, and the object's declared actions.
+ *
+ * `objectActions` is deliberately the object's WHOLE action set rather than
+ * only the ones this view promotes. Narrowing it would mean re-running the
+ * name resolution `resolveLegacyRowActions` / `resolveBulkActions` already do,
+ * at a point in the fetch where the view's `rowActions` / `bulkActions` lists
+ * have not been folded yet — and the two directions of error are not
+ * symmetric: an extra column costs bytes, a missing one silently breaks the
+ * predicate that needed it.
+ */
+export function listViewPredicates(view) {
+    const preds = [];
+    for (const rule of view.conditionalFormatting ?? []) {
+        if (!rule || typeof rule !== 'object')
+            continue;
+        const r = rule;
+        preds.push(r.condition, r.expression);
+        // The native `{ field, operator, value }` shape names its field directly;
+        // spell it as a `record.` reference so the one harvester handles it.
+        if (typeof r.field === 'string' && r.field)
+            preds.push(`record.${r.field}`);
+    }
+    for (const list of [view.rowActionDefs, view.bulkActionDefs, view.objectActions]) {
+        for (const def of list ?? []) {
+            if (!def || typeof def !== 'object')
+                continue;
+            const d = def;
+            preds.push(d.visible, d.disabled);
+        }
+    }
+    for (const override of Object.values(view.userActions ?? {})) {
+        if (!override || typeof override !== 'object')
+            continue;
+        const o = override;
+        preds.push(o.visibleWhen, o.disabledWhen);
+    }
+    return preds;
+}

package/dist/utils/predicate-record.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ObjectUI — predicate record normalization
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/** The two field-container shapes the metadata API serves. */
+export type FieldContainerLike = Record<string, {
+    type?: unknown;
+} | unknown> | readonly {
+    name?: unknown;
+    type?: unknown;
+}[] | null | undefined;
+/**
+ * Collapse `record`'s expanded relation values back to the ids they stand for.
+ *
+ * Returns the input BY REFERENCE when there is nothing to collapse — the common
+ * case (no schema, no relations, nothing expanded) allocates nothing and keeps
+ * the identity downstream `useMemo` deps rely on.
+ *
+ * `multiple: true` relations store an ARRAY of ids and expand element-wise, so
+ * an array is mapped element-wise too; a member that is not an expanded record
+ * (already an id) is left alone.
+ *
+ * @param record  A fetched row / detail record, as the payload delivered it.
+ * @param fields  The object's field definitions (`objectSchema.fields`), in
+ *                either served shape. Without them nothing is collapsed —
+ *                a caller that cannot name the relations must not guess.
+ */
+export declare function toPredicateRecord<T extends Record<string, unknown>>(record: T, fields: FieldContainerLike): T;
+export declare function toPredicateRecord<T extends Record<string, unknown>>(record: T | null | undefined, fields: FieldContainerLike): T | null | undefined;

package/dist/utils/predicate-record.js

@@ -0,0 +1,120 @@
+/**
+ * ObjectUI — predicate record normalization
+ * 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.
+ */
+/**
+ * Bind a fetched record into an expression scope the way the SERVER binds it —
+ * a relation field is its stored foreign key, never the record it points at.
+ *
+ * ## Why a normalization step exists at all
+ *
+ * A `lookup` / `master_detail` / `user` / `tree` field stores an id. That is
+ * what the server's CEL engine sees in a validation rule, a sharing predicate
+ * or a flow condition, and it is what an author writes:
+ *
+ * ```
+ * visible: 'record.owner == os.user.id'
+ * ```
+ *
+ * The client does not necessarily see that. `$expand` (the `populate=` wire
+ * param) **replaces the id in place** with the whole related record, so the same
+ * field arrives as `'P1'` or as `{ id: 'P1', name: 'Website' }` depending on
+ * whether the surface happened to expand it — and views expand exactly the
+ * relations they show as COLUMNS (`buildExpandFields`), which is a display
+ * decision no predicate author participates in. Measured against a live
+ * runtime, one predicate over one field therefore has four different fates:
+ *
+ * | value in the payload            | `record.owner == "P1"` | `record.owner.id == "P1"` |
+ * |---------------------------------|------------------------|---------------------------|
+ * | `'P1'` (not expanded)           | **true**               | fault                     |
+ * | `{ id: 'P1', … }` (expanded)    | **false**              | true                      |
+ * | `null` (empty lookup)           | false                  | fault                     |
+ * | absent (outside `$select`)      | fault                  | fault                     |
+ *
+ * No spelling is right everywhere, and neither failure announces itself: a
+ * fault is fail-CLOSED on the row kebab / selection bar (button silently gone)
+ * and fail-OPEN on the lenient paths (button shown to everyone). That is the
+ * whole of "lookup fields cannot be used in expressions" — the author is not
+ * writing the predicate wrong, the operand means two things.
+ *
+ * Collapsing the expanded form back to its id is what makes the first column
+ * of that table the only one: `record.owner` is the id on every surface and on
+ * the server, so a predicate authored once reaches one verdict everywhere.
+ *
+ * ## Why it is schema-driven and not a shape sniff
+ *
+ * "An object carrying an `id` key" would also catch a genuine `json` field
+ * whose payload happens to have one, and silently change what
+ * `record.config.id` means. The object's own field types are the authority:
+ * only a field DECLARED relational (see `EXPANDABLE_FIELD_TYPES` — the same set
+ * that decides what gets expanded in the first place) is collapsed, so the two
+ * halves cannot disagree about which fields are relations.
+ */
+import { EXPANDABLE_FIELD_TYPES } from './expand-fields.js';
+/** Names of the fields this object declares as relations (`lookup` / …). */
+function relationFieldNames(fields) {
+    if (!fields || typeof fields !== 'object')
+        return null;
+    const out = new Set();
+    if (Array.isArray(fields)) {
+        for (const def of fields) {
+            const name = def?.name;
+            const type = def?.type;
+            if (typeof name === 'string' && EXPANDABLE_FIELD_TYPES.has(type))
+                out.add(name);
+        }
+    }
+    else {
+        for (const [name, def] of Object.entries(fields)) {
+            const type = def?.type;
+            if (EXPANDABLE_FIELD_TYPES.has(type))
+                out.add(name);
+        }
+    }
+    return out.size > 0 ? out : null;
+}
+/** The id an expanded related record is stored under, or `undefined`. */
+function expandedId(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const rec = value;
+    const id = rec.id ?? rec._id;
+    return typeof id === 'string' || typeof id === 'number' ? String(id) : undefined;
+}
+// Two overloads rather than one `: T`: a null/undefined record is passed
+// STRAIGHT THROUGH (a caller with no record loaded yet must be able to tell
+// that from an empty one — `page:header` binds the result into an eval scope
+// where `{}` and `undefined` are different answers). Declaring the return as
+// plain `T` would have been a lie the `as T` cast hid.
+export function toPredicateRecord(record, fields) {
+    if (!record || typeof record !== 'object')
+        return record;
+    const relations = relationFieldNames(fields);
+    if (!relations)
+        return record;
+    let out = null;
+    const write = (key, value) => {
+        if (!out)
+            out = { ...record };
+        out[key] = value;
+    };
+    for (const name of relations) {
+        if (!(name in record))
+            continue;
+        const value = record[name];
+        if (Array.isArray(value)) {
+            // Only rebuild the array when at least one member was expanded.
+            if (!value.some(v => expandedId(v) !== undefined))
+                continue;
+            write(name, value.map(v => expandedId(v) ?? v));
+            continue;
+        }
+        const id = expandedId(value);
+        if (id !== undefined)
+            write(name, id);
+    }
+    return (out ?? record);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/core",
-  "version": "17.2.0",
+  "version": "17.3.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -25,11 +25,11 @@
     }
   },
   "dependencies": {
-    "@objectstack/formula": "^17.0.0-rc.1",
-    "@objectstack/spec": "^17.0.0-rc.1",
+    "@objectstack/formula": "^17.0.0-rc.2",
+    "@objectstack/spec": "^17.0.0-rc.2",
     "lodash": "^4.18.1",
     "zod": "^4.4.3",
-    "@object-ui/types": "17.2.0"
+    "@object-ui/types": "17.3.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3",

package/dist/protocols/NotificationProtocol.d.ts

@@ -1,71 +0,0 @@
-/**
- * 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.
- */
-/**
- * @object-ui/core - Notification Protocol Bridge
- *
- * Converts spec-aligned Notification schemas into toast-compatible
- * objects that UI layers can render. Maps severity to variant,
- * position names, and resolves default notification configs.
- *
- * @module protocols/NotificationProtocol
- * @packageDocumentation
- */
-import type { Notification as SpecNotification, NotificationConfig, NotificationPosition } from '@object-ui/types';
-/** Fully resolved notification configuration. */
-export interface ResolvedNotificationConfig {
-    defaultPosition: NotificationPosition;
-    defaultDuration: number;
-    maxVisible: number;
-    stackDirection: 'up' | 'down';
-    pauseOnHover: boolean;
-}
-/** Toast-compatible representation of a spec Notification. */
-export interface ToastNotification {
-    title?: string;
-    description: string;
-    variant: string;
-    position: string;
-    duration: number;
-    dismissible: boolean;
-    actions: ToastAction[];
-}
-/** Toast-compatible action button. */
-export interface ToastAction {
-    label: string;
-    action: string;
-    variant: 'primary' | 'secondary' | 'link';
-}
-/**
- * Map a spec notification severity to a toast variant string.
- *
- * @param severity - Spec severity (info, success, warning, error)
- * @returns Toast variant (default, success, warning, destructive)
- */
-export declare function mapSeverityToVariant(severity: string): string;
-/**
- * Map a spec notification position (underscore-separated) to a
- * toast position string (hyphen-separated).
- *
- * @param position - Spec position (e.g. "top_right")
- * @returns Toast position (e.g. "top-right")
- */
-export declare function mapPosition(position: string): string;
-/**
- * Resolve a notification configuration by applying spec defaults.
- *
- * @param config - NotificationConfig from the spec
- * @returns Fully resolved notification configuration
- */
-export declare function resolveNotificationConfig(config: NotificationConfig): ResolvedNotificationConfig;
-/**
- * Convert a spec Notification to a toast-compatible object.
- *
- * @param notification - Spec Notification
- * @returns Toast-compatible notification with title, description, variant, etc.
- */
-export declare function specNotificationToToast(notification: SpecNotification): ToastNotification;

package/dist/protocols/NotificationProtocol.js

@@ -1,89 +0,0 @@
-/**
- * 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.
- */
-// ============================================================================
-// Severity → Variant Mapping
-// ============================================================================
-const SEVERITY_TO_VARIANT = {
-    info: 'default',
-    success: 'success',
-    warning: 'warning',
-    error: 'destructive',
-};
-/**
- * Map a spec notification severity to a toast variant string.
- *
- * @param severity - Spec severity (info, success, warning, error)
- * @returns Toast variant (default, success, warning, destructive)
- */
-export function mapSeverityToVariant(severity) {
-    return SEVERITY_TO_VARIANT[severity] ?? 'default';
-}
-// ============================================================================
-// Position Mapping
-// ============================================================================
-const POSITION_MAP = {
-    top_left: 'top-left',
-    top_center: 'top-center',
-    top_right: 'top-right',
-    bottom_left: 'bottom-left',
-    bottom_center: 'bottom-center',
-    bottom_right: 'bottom-right',
-};
-/**
- * Map a spec notification position (underscore-separated) to a
- * toast position string (hyphen-separated).
- *
- * @param position - Spec position (e.g. "top_right")
- * @returns Toast position (e.g. "top-right")
- */
-export function mapPosition(position) {
-    return POSITION_MAP[position] ?? 'top-right';
-}
-// ============================================================================
-// Notification Config Resolution
-// ============================================================================
-/**
- * Resolve a notification configuration by applying spec defaults.
- *
- * @param config - NotificationConfig from the spec
- * @returns Fully resolved notification configuration
- */
-export function resolveNotificationConfig(config) {
-    return {
-        defaultPosition: config.defaultPosition ?? 'top_right',
-        defaultDuration: config.defaultDuration ?? 5000,
-        maxVisible: config.maxVisible ?? 5,
-        stackDirection: config.stackDirection ?? 'down',
-        pauseOnHover: config.pauseOnHover ?? true,
-    };
-}
-// ============================================================================
-// Spec Notification → Toast
-// ============================================================================
-/**
- * Convert a spec Notification to a toast-compatible object.
- *
- * @param notification - Spec Notification
- * @returns Toast-compatible notification with title, description, variant, etc.
- */
-export function specNotificationToToast(notification) {
-    const actions = (notification.actions ?? []).map((a) => ({
-        label: a.label,
-        action: a.action,
-        variant: a.variant ?? 'primary',
-    }));
-    return {
-        title: notification.title,
-        description: notification.message ?? '',
-        variant: mapSeverityToVariant(notification.severity ?? 'info'),
-        position: mapPosition(notification.position ?? 'top_right'),
-        duration: notification.duration ?? 5000,
-        dismissible: notification.dismissible ?? true,
-        actions,
-    };
-}