@object-ui/core 11.5.0 → 13.2.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @object-ui/core
 
+## 13.2.0
+
+### Patch Changes
+
+- @object-ui/types@13.2.0
+
+## 13.1.0
+
+### Patch Changes
+
+- @object-ui/types@13.1.0
+
+## 13.0.0
+
+### Patch Changes
+
+- Updated dependencies [619097e]
+  - @object-ui/types@13.0.0
+
+## 12.1.0
+
+### Patch Changes
+
+- Updated dependencies [c31874d]
+  - @object-ui/types@12.1.0
+
+## 12.0.0
+
+### Minor Changes
+
+- 226fde9: Cascading & role-gated `select` options (#2284).
+
+  `select` options now accept a per-option `visibleWhen` CEL predicate — the option
+  is offered only when it evaluates TRUE against the live record **plus
+  `current_user`** (same engine/env as a field-level `visibleWhen`). Combined with a
+  field-level `dependsOn`, this drives dependent selects (country → province → city)
+  and role/context gating with no bespoke matrix — the same primitives dependent
+  lookups (#2215) already use.
+
+  - `@object-ui/core` exposes `resolveVisibleOptions` / `isOptionGroupGated` /
+    `resolveDependsOnFields` / `isValueStillOffered` (evaluator), reusing the
+    canonical `evalFieldPredicate`.
+  - The form renderer narrows a dependent select's option list, gates the control
+    with a "Select {parent} first" hint while a `dependsOn` field is empty, and
+    clears a now-invalid value when the parent changes.
+  - The standalone `SelectField` widget applies the same resolution via
+    `dependentValues` + the global predicate scope.
+
+  Client-side hiding is UX, not authorization: gate authorization-sensitive option
+  values on the server too. Aligns with `@objectstack/spec` `SelectOption.visibleWhen`.
+
+### Patch Changes
+
+- Updated dependencies [226fde9]
+- Updated dependencies [e4de456]
+  - @object-ui/types@12.0.0
+
 ## 11.5.0
 
 ### Patch Changes

package/dist/evaluator/index.d.ts

@@ -8,6 +8,7 @@
 export * from './ExpressionContext.js';
 export * from './ExpressionEvaluator.js';
 export * from './fieldRules.js';
+export * from './optionRules.js';
 export * from './ExpressionCache.js';
 export * from './FormulaFunctions.js';
 export * from './SafeExpressionParser.js';

package/dist/evaluator/index.js

@@ -8,6 +8,7 @@
 export * from './ExpressionContext.js';
 export * from './ExpressionEvaluator.js';
 export * from './fieldRules.js';
+export * from './optionRules.js';
 export * from './ExpressionCache.js';
 export * from './FormulaFunctions.js';
 export * from './SafeExpressionParser.js';

package/dist/evaluator/optionRules.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+/**
+ * Client-side resolution of per-option visibility for `select` / `radio` /
+ * `multiselect` fields — cascading (dependent) options and role/context gating.
+ *
+ * An option carries an optional `visibleWhen` CEL predicate; the option is
+ * offered only when it evaluates TRUE against the live record + `current_user`
+ * (the SAME engine and binding environment as a field-level `visibleWhen`, via
+ * {@link evalFieldPredicate}). This expresses both:
+ *   - cascades — `record.country == 'cn'` (the dependent list narrows as the
+ *     controlling field changes), and
+ *   - role/context gating — `'admin' in current_user.roles`.
+ *
+ * A field declares which sibling fields its option list reacts to via
+ * `dependsOn` (aligns with `@objectstack/spec` Field.dependsOn — the same knob
+ * lookups use). While any dependency is empty the list is *gated*: we surface a
+ * "select the parent first" hint instead of an unfiltered set, mirroring the
+ * dependent-lookup UX (#2215).
+ *
+ * Evaluation is fail-open (a broken/absent predicate keeps the option) — the
+ * same safe default as field visibility. Client-side hiding is UX, not a
+ * security boundary: when an option is gated for access-control reasons the
+ * server must also reject writes of its value.
+ */
+import { type FieldRulePredicate } from './fieldRules.js';
+/**
+ * Minimal shape of a select/radio option this module reads. Deliberately has no
+ * index signature so richer option types (`SelectOption`, `SelectOptionMetadata`)
+ * remain structurally assignable — the helpers only read `value`/`visibleWhen`.
+ */
+export interface OptionLike {
+    label: string;
+    value: string;
+    /** Per-option visibility predicate (CEL). Omit = always available. */
+    visibleWhen?: FieldRulePredicate;
+}
+/** A field's `dependsOn` as authored: a bare name, or a list of names / `{field,param}`. */
+export type DependsOnInput = string | Array<string | {
+    field: string;
+    param?: string;
+}> | undefined | null;
+/**
+ * Normalize a field's `dependsOn` to the list of sibling field names it reacts
+ * to. The lookup-only `{field,param}` form contributes just its `field`.
+ */
+export declare function resolveDependsOnFields(dependsOn: DependsOnInput): string[];
+/**
+ * True when at least one `dependsOn` field is empty in the record — the option
+ * list is gated and the widget should prompt for the parent rather than show an
+ * unfiltered set. Returns false when there are no dependencies.
+ */
+export declare function isOptionGroupGated(dependsOn: DependsOnInput, record: Record<string, unknown>): boolean;
+/**
+ * Filter options by their per-option `visibleWhen` predicate, evaluated against
+ * the live `record` (+ optional `scope`, e.g. `{ current_user }`). Options with
+ * no predicate are always kept; a predicate that errors fails open (kept).
+ */
+export declare function resolveVisibleOptions<T extends OptionLike>(options: readonly T[] | undefined | null, record: Record<string, unknown>, scope?: Record<string, unknown>): T[];
+/**
+ * Whether a scalar field value is still valid given the currently-visible
+ * options — used to decide a cascade clear (parent changed, child's old choice
+ * no longer offered). An empty value is always "valid" (nothing to clear).
+ */
+export declare function isValueStillOffered(value: unknown, visibleOptions: readonly OptionLike[]): boolean;

package/dist/evaluator/optionRules.js

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+/**
+ * Client-side resolution of per-option visibility for `select` / `radio` /
+ * `multiselect` fields — cascading (dependent) options and role/context gating.
+ *
+ * An option carries an optional `visibleWhen` CEL predicate; the option is
+ * offered only when it evaluates TRUE against the live record + `current_user`
+ * (the SAME engine and binding environment as a field-level `visibleWhen`, via
+ * {@link evalFieldPredicate}). This expresses both:
+ *   - cascades — `record.country == 'cn'` (the dependent list narrows as the
+ *     controlling field changes), and
+ *   - role/context gating — `'admin' in current_user.roles`.
+ *
+ * A field declares which sibling fields its option list reacts to via
+ * `dependsOn` (aligns with `@objectstack/spec` Field.dependsOn — the same knob
+ * lookups use). While any dependency is empty the list is *gated*: we surface a
+ * "select the parent first" hint instead of an unfiltered set, mirroring the
+ * dependent-lookup UX (#2215).
+ *
+ * Evaluation is fail-open (a broken/absent predicate keeps the option) — the
+ * same safe default as field visibility. Client-side hiding is UX, not a
+ * security boundary: when an option is gated for access-control reasons the
+ * server must also reject writes of its value.
+ */
+import { evalFieldPredicate } from './fieldRules.js';
+/**
+ * Normalize a field's `dependsOn` to the list of sibling field names it reacts
+ * to. The lookup-only `{field,param}` form contributes just its `field`.
+ */
+export function resolveDependsOnFields(dependsOn) {
+    if (!dependsOn)
+        return [];
+    const arr = Array.isArray(dependsOn) ? dependsOn : [dependsOn];
+    return arr
+        .map((d) => (typeof d === 'string' ? d : d && typeof d === 'object' ? d.field : null))
+        .filter((f) => typeof f === 'string' && f.length > 0);
+}
+/** A value counts as "empty" (dependency unmet) when nullish, blank, or an empty array. */
+function isEmptyValue(v) {
+    return v === undefined || v === null || v === '' || (Array.isArray(v) && v.length === 0);
+}
+/**
+ * True when at least one `dependsOn` field is empty in the record — the option
+ * list is gated and the widget should prompt for the parent rather than show an
+ * unfiltered set. Returns false when there are no dependencies.
+ */
+export function isOptionGroupGated(dependsOn, record) {
+    const fields = resolveDependsOnFields(dependsOn);
+    return fields.some((f) => isEmptyValue(record[f]));
+}
+/**
+ * Filter options by their per-option `visibleWhen` predicate, evaluated against
+ * the live `record` (+ optional `scope`, e.g. `{ current_user }`). Options with
+ * no predicate are always kept; a predicate that errors fails open (kept).
+ */
+export function resolveVisibleOptions(options, record, scope) {
+    if (!options || options.length === 0)
+        return [];
+    return options.filter((o) => o?.visibleWhen == null ? true : evalFieldPredicate(o.visibleWhen, record, true, undefined, scope));
+}
+/**
+ * Whether a scalar field value is still valid given the currently-visible
+ * options — used to decide a cascade clear (parent changed, child's old choice
+ * no longer offered). An empty value is always "valid" (nothing to clear).
+ */
+export function isValueStillOffered(value, visibleOptions) {
+    if (isEmptyValue(value))
+        return true;
+    if (Array.isArray(value)) {
+        // Multi-select: valid only when every selected value is still offered.
+        return value.every((v) => visibleOptions.some((o) => o.value === v));
+    }
+    return visibleOptions.some((o) => o.value === value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/core",
-  "version": "11.5.0",
+  "version": "13.2.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -25,15 +25,15 @@
     }
   },
   "dependencies": {
-    "@objectstack/formula": "^11.5.0",
-    "@objectstack/spec": "^11.7.0",
+    "@objectstack/formula": "^14.3.0",
+    "@objectstack/spec": "^14.3.0",
     "lodash": "^4.18.1",
     "zod": "^4.4.3",
-    "@object-ui/types": "11.5.0"
+    "@object-ui/types": "13.2.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.10"
   },
   "keywords": [
     "objectui",