@i4e/invest4edu-access-core 0.32.0 → 0.34.0

package/src/visible-when.js

@@ -1,108 +1,108 @@
-/**
- * `visibleWhen` — ONE predicate language, ONE evaluator.
- * @i4e/invest4edu-access-core (unified access framework, P1)
- *
- * The same function gates nav items, screen actions, grid columns, filters, row/bulk actions,
- * exports and summary metrics. That is what makes "driven by product and roles" true across the
- * whole app instead of per-screen — and it means a rule is written once, in data, not in 139
- * hardcoded predicates.
- *
- * Client-side evaluation is UX ONLY. Servers MUST re-evaluate before returning data, projecting
- * columns, or building an export/summary — never trust a client-supplied column list.
- *
- * Design: TDD-unified-access-and-subscription.md §8.3
- */
-
-import { hasFeature, isUsable } from "./access-resolver.js";
-
-/**
- * Shape (every key optional; all present keys must pass — AND):
- * {
- *   features:         ["ORDERS.LIST"]          // caller must hold all of these
- *   actions:          ["ORDERS.LIST.CANCEL"]   // alias of features, reads better on actions
- *   entitled:         "TOOLS.AI_REPORT"        // must be allowed AND entitlement-unlocked
- *   products:         ["IVP003"]               // caller's product scope must intersect
- *   distributorLevel: ["D1","D2"]
- *   screenType:       "openorders" | ["a","b"]
- *   roles:            ["BROKER_ADMIN"]         // LEGACY escape hatch — lint-flagged, being removed
- *   anyOf:            [ {...}, {...} ]         // OR of nested predicates
- *   not:              { ... }                  // negation
- * }
- *
- * @param {Object|null|undefined} rule   absent/empty ⇒ visible (opt-in gating, not opt-out)
- * @param {Object} ctx { snapshot, productScope?, distributorLevel?, screenType?, roles? }
- */
-export function evaluateVisibleWhen(rule, ctx = {}) {
-  if (!rule || typeof rule !== "object") return true;
-
-  const snapshot = ctx.snapshot || null;
-  // A system admin (D27) resolves a fully-open snapshot, so feature/entitlement checks below
-  // pass naturally. Product/level predicates still evaluate — an admin seeing a D1-only column
-  // labelled for D1 would be misleading, not permissive.
-  const productScope = new Set(
-    (ctx.productScope || snapshot?.productScope || []).map(String),
-  );
-
-  const asArray = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
-
-  if (rule.features && !asArray(rule.features).every((c) => hasFeature(snapshot, c))) return false;
-  if (rule.actions && !asArray(rule.actions).every((c) => hasFeature(snapshot, c))) return false;
-  if (rule.entitled && !asArray(rule.entitled).every((c) => isUsable(snapshot, c))) return false;
-
-  if (rule.products) {
-    const want = asArray(rule.products).map(String);
-    if (want.length && !want.some((p) => productScope.has(p))) return false;
-  }
-
-  if (rule.distributorLevel) {
-    const lvl = ctx.distributorLevel ? String(ctx.distributorLevel) : null;
-    if (!lvl || !asArray(rule.distributorLevel).map(String).includes(lvl)) return false;
-  }
-
-  if (rule.screenType) {
-    const st = ctx.screenType ? String(ctx.screenType) : null;
-    if (!st || !asArray(rule.screenType).map(String).includes(st)) return false;
-  }
-
-  // LEGACY: kept only so migration can proceed screen-by-screen. New configs must not use it.
-  if (rule.roles) {
-    const held = new Set(asArray(ctx.roles || snapshot?.resolved_for?.roles).map(String));
-    if (!asArray(rule.roles).map(String).some((r) => held.has(r))) return false;
-  }
-
-  if (rule.anyOf) {
-    const branches = asArray(rule.anyOf);
-    if (branches.length && !branches.some((b) => evaluateVisibleWhen(b, ctx))) return false;
-  }
-
-  if (rule.not && evaluateVisibleWhen(rule.not, ctx)) return false;
-
-  return true;
-}
-
-/** Filter a list of `{visibleWhen}`-bearing config items (columns, metrics, actions, filters). */
-export function filterVisible(items = [], ctx = {}) {
-  return items.filter((i) => evaluateVisibleWhen(i?.visibleWhen, ctx));
-}
-
-/**
- * Apply `relabelWhen` overrides to a grid column — absorbs the imperative relabelling in
- * order-constants (e.g. d1/d2/d3_payout → "Net Income" for the matching distributor level).
- * First matching rule wins; the column is returned unchanged when nothing matches.
- */
-export function applyRelabel(column, ctx = {}) {
-  if (!column?.relabelWhen?.length) return column;
-  for (const r of column.relabelWhen) {
-    if (evaluateVisibleWhen(r?.when, ctx)) {
-      return { ...column, header: r.header ?? column.header, label: r.label ?? column.label };
-    }
-  }
-  return column;
-}
-
-/** Resolve a full column list: drop hidden ones, apply relabelling, preserve order. */
-export function resolveColumns(columns = [], ctx = {}) {
-  return filterVisible(columns, ctx).map((c) => applyRelabel(c, ctx));
-}
-
-export default { evaluateVisibleWhen, filterVisible, applyRelabel, resolveColumns };
+/**
+ * `visibleWhen` — ONE predicate language, ONE evaluator.
+ * @i4e/invest4edu-access-core (unified access framework, P1)
+ *
+ * The same function gates nav items, screen actions, grid columns, filters, row/bulk actions,
+ * exports and summary metrics. That is what makes "driven by product and roles" true across the
+ * whole app instead of per-screen — and it means a rule is written once, in data, not in 139
+ * hardcoded predicates.
+ *
+ * Client-side evaluation is UX ONLY. Servers MUST re-evaluate before returning data, projecting
+ * columns, or building an export/summary — never trust a client-supplied column list.
+ *
+ * Design: TDD-unified-access-and-subscription.md §8.3
+ */
+
+import { hasFeature, isUsable } from "./access-resolver.js";
+
+/**
+ * Shape (every key optional; all present keys must pass — AND):
+ * {
+ *   features:         ["ORDERS.LIST"]          // caller must hold all of these
+ *   actions:          ["ORDERS.LIST.CANCEL"]   // alias of features, reads better on actions
+ *   entitled:         "TOOLS.AI_REPORT"        // must be allowed AND entitlement-unlocked
+ *   products:         ["IVP003"]               // caller's product scope must intersect
+ *   distributorLevel: ["D1","D2"]
+ *   screenType:       "openorders" | ["a","b"]
+ *   roles:            ["BROKER_ADMIN"]         // LEGACY escape hatch — lint-flagged, being removed
+ *   anyOf:            [ {...}, {...} ]         // OR of nested predicates
+ *   not:              { ... }                  // negation
+ * }
+ *
+ * @param {Object|null|undefined} rule   absent/empty ⇒ visible (opt-in gating, not opt-out)
+ * @param {Object} ctx { snapshot, productScope?, distributorLevel?, screenType?, roles? }
+ */
+export function evaluateVisibleWhen(rule, ctx = {}) {
+  if (!rule || typeof rule !== "object") return true;
+
+  const snapshot = ctx.snapshot || null;
+  // A system admin (D27) resolves a fully-open snapshot, so feature/entitlement checks below
+  // pass naturally. Product/level predicates still evaluate — an admin seeing a D1-only column
+  // labelled for D1 would be misleading, not permissive.
+  const productScope = new Set(
+    (ctx.productScope || snapshot?.productScope || []).map(String),
+  );
+
+  const asArray = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
+
+  if (rule.features && !asArray(rule.features).every((c) => hasFeature(snapshot, c))) return false;
+  if (rule.actions && !asArray(rule.actions).every((c) => hasFeature(snapshot, c))) return false;
+  if (rule.entitled && !asArray(rule.entitled).every((c) => isUsable(snapshot, c))) return false;
+
+  if (rule.products) {
+    const want = asArray(rule.products).map(String);
+    if (want.length && !want.some((p) => productScope.has(p))) return false;
+  }
+
+  if (rule.distributorLevel) {
+    const lvl = ctx.distributorLevel ? String(ctx.distributorLevel) : null;
+    if (!lvl || !asArray(rule.distributorLevel).map(String).includes(lvl)) return false;
+  }
+
+  if (rule.screenType) {
+    const st = ctx.screenType ? String(ctx.screenType) : null;
+    if (!st || !asArray(rule.screenType).map(String).includes(st)) return false;
+  }
+
+  // LEGACY: kept only so migration can proceed screen-by-screen. New configs must not use it.
+  if (rule.roles) {
+    const held = new Set(asArray(ctx.roles || snapshot?.resolved_for?.roles).map(String));
+    if (!asArray(rule.roles).map(String).some((r) => held.has(r))) return false;
+  }
+
+  if (rule.anyOf) {
+    const branches = asArray(rule.anyOf);
+    if (branches.length && !branches.some((b) => evaluateVisibleWhen(b, ctx))) return false;
+  }
+
+  if (rule.not && evaluateVisibleWhen(rule.not, ctx)) return false;
+
+  return true;
+}
+
+/** Filter a list of `{visibleWhen}`-bearing config items (columns, metrics, actions, filters). */
+export function filterVisible(items = [], ctx = {}) {
+  return items.filter((i) => evaluateVisibleWhen(i?.visibleWhen, ctx));
+}
+
+/**
+ * Apply `relabelWhen` overrides to a grid column — absorbs the imperative relabelling in
+ * order-constants (e.g. d1/d2/d3_payout → "Net Income" for the matching distributor level).
+ * First matching rule wins; the column is returned unchanged when nothing matches.
+ */
+export function applyRelabel(column, ctx = {}) {
+  if (!column?.relabelWhen?.length) return column;
+  for (const r of column.relabelWhen) {
+    if (evaluateVisibleWhen(r?.when, ctx)) {
+      return { ...column, header: r.header ?? column.header, label: r.label ?? column.label };
+    }
+  }
+  return column;
+}
+
+/** Resolve a full column list: drop hidden ones, apply relabelling, preserve order. */
+export function resolveColumns(columns = [], ctx = {}) {
+  return filterVisible(columns, ctx).map((c) => applyRelabel(c, ctx));
+}
+
+export default { evaluateVisibleWhen, filterVisible, applyRelabel, resolveColumns };