@i4e/invest4edu-access-core 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Shared access-control primitives for NeoFindesk: tenant keystone, role capabilities, reportee tree, feature flags, and the unified access engine (registry schema, snapshot resolver, visibleWhen).",
   "type": "module",
   "exports": {
@@ -14,7 +14,8 @@
     "./access-resolver": "./src/access-resolver.js",
     "./visible-when": "./src/visible-when.js",
     "./entitlement": "./src/entitlement.js",
-    "./entitlement-schema": "./src/entitlement-schema.js"
+    "./entitlement-schema": "./src/entitlement-schema.js",
+    "./grid-schema": "./src/grid-schema.js"
   },
   "scripts": {
     "test": "node --test test/"

package/src/access-resolver.js

@@ -12,7 +12,7 @@
  * Design: TDD-unified-access-and-subscription.md §4
  */
 
-import { parentCodeOf } from "./access-schema.js";
+import { parentCodeOf, PRODUCT_UI_MODES } from "./access-schema.js";
 
 /** Reasons a feature can be locked, surfaced so the UI can distinguish upsell from hard-deny. */
 export const ENTITLEMENT_REASONS = Object.freeze({
@@ -219,6 +219,12 @@ export function resolveAccessSnapshot({
       actions: [],
       entitlement,
       tracking: !!f.tracking_enabled,
+      // How this SCREEN should present product-keyed things it renders — distinct from
+      // `products` above, which is *reachability* ("this screen exists only for these
+      // products"). The two are independent: Open Orders is product-agnostic yet renders
+      // product tabs that must be filtered, so the behaviour cannot be derived from the
+      // constraint. Default 'none' keeps every existing screen rendering exactly as today.
+      product_ui: PRODUCT_UI_MODES.includes(f.product_ui) ? f.product_ui : "none",
     };
 
     if (f.feature_type === "screen") allowedScreens.push(f);

package/src/access-schema.js

@@ -23,6 +23,27 @@ export const REGISTRY_STATUSES = Object.freeze(["active", "dormant", "retired"])
 /** Per-feature enforcement ladder (mirrors the platform's off→warn→enforce doctrine). */
 export const ROLLOUT_MODES = Object.freeze(["off", "warn", "enforce"]);
 
+/**
+ * How a SCREEN presents the product-keyed things it renders — product tiles, product tabs, the
+ * product column on Add Order, scheme lists.
+ *
+ * Deliberately separate from `products[]` on the same feature, which is *reachability* ("this
+ * screen exists only for these products"). The two are independent and neither implies the other:
+ * Open Orders is product-agnostic (`products: []`, it serves every product) yet renders product
+ * tabs that must be filtered; Product Setup is equally agnostic and should hide nothing. Same
+ * reachability, opposite presentation — so this cannot be derived, it has to be declared.
+ *
+ *   none      render everything. The default, so every existing screen is unchanged.
+ *   filter    hide product-keyed items outside the caller's scope. For transactional screens.
+ *   readonly  show everything, but out-of-scope items are not interactive. For configuration
+ *             screens, where hiding a product reads as "the catalogue is broken" rather than as
+ *             "you may not touch this".
+ *
+ * This is presentation only. The server-side gate is what actually refuses a write — hiding a
+ * tile has never stopped a POST.
+ */
+export const PRODUCT_UI_MODES = Object.freeze(["none", "filter", "readonly"]);
+
 /** Grant effect. `deny` at the user level replaces the old `revoked_pages`. */
 export const GRANT_EFFECTS = Object.freeze(["allow", "deny"]);
 
@@ -96,6 +117,7 @@ export const ACCESS_FEATURE_DEF = Object.freeze({
     status: { type: "String", enum: REGISTRY_STATUSES, default: "active", index: true },
     kill_switch: { type: "String", enum: ["on", "off"], default: "off" },
     rollout_mode: { type: "String", enum: ROLLOUT_MODES, default: "off" },
+    product_ui: { type: "String", enum: PRODUCT_UI_MODES, default: "none" },
 
     // Survives an entitlement block (login, billing/checkout, profile) — see design §7.4.
     always_available: { type: "Boolean", default: false },
@@ -139,6 +161,7 @@ export default {
   FEATURE_TYPES,
   REGISTRY_STATUSES,
   ROLLOUT_MODES,
+  PRODUCT_UI_MODES,
   GRANT_EFFECTS,
   GRANT_SUBJECTS,
   FEATURE_CODE_PATTERN,

package/src/grid-schema.js

@@ -0,0 +1,231 @@
+/**
+ * DataGrid v2 config — @i4e/invest4edu-access-core (P4). Definitions + validator. No React, no DB.
+ *
+ * ONE config defines a listing end to end: where the rows come from, which columns exist and who
+ * sees each, the filters, the row/bulk actions, the export, and the summary cards. It lives in the
+ * shared package because three consumers must agree on it exactly — the UI renders it, v1 serves
+ * and re-evaluates it, and the admin screen edits it.
+ *
+ * ── Why it is strictly serialisable ──────────────────────────────────────────────────────────
+ * No functions anywhere. A column says `type: "currency"`, never `cell: (row) => …`. That is the
+ * single property that makes a grid storable, diffable, admin-editable and server-re-evaluable.
+ * The moment one config carries a callback, it can no longer be saved — and the whole model
+ * collapses back into per-screen code.
+ *
+ * ── Why access binding lives IN the config ───────────────────────────────────────────────────
+ * `feature_code` gates the grid, every action carries an `action_code`, and `visibleWhen` gates
+ * columns/filters/metrics. So "who may see this column" and "who may press this button" are
+ * answered by the same engine that answers "who may open this screen" — not by a second, parallel
+ * set of role checks inside a component.
+ *
+ * `source.collection` is what lets the SERVER apply tenant + product + record scope to the query
+ * (scopedMatch). Without it a grid could be pointed at a collection nobody has scoped.
+ *
+ * Design: nfd-ui-nextjs/IV-CodingAgent/specs/access-management/TDD-unified-access-and-subscription.md §8
+ */
+
+export const COLUMN_TYPES = Object.freeze([
+  "text", "number", "currency", "percent", "date", "datetime",
+  "boolean", "status-pill", "link", "actions", "inline-edit",
+]);
+
+export const FILTER_TYPES = Object.freeze([
+  "text", "select", "multiselect", "reference", "boolean", "exists", "daterange", "numberrange",
+]);
+
+export const AGGREGATIONS = Object.freeze(["sum", "avg", "count", "countWhere", "distinct", "raw"]);
+
+export const GRID_SCOPES = Object.freeze(["global", "account"]);
+
+/** The filter payload dialect the table and its summary endpoint MUST both speak. */
+export const FILTER_DIALECT = "grid-ast-v1";
+
+export const GRID_CONFIG_DEF = Object.freeze({
+  collection: "grid_configs",
+  fields: Object.freeze({
+    grid_code: { type: "String", required: true, index: true },
+    // Binds the whole grid to the access engine — no grid without a feature.
+    feature_code: { type: "String", required: true, index: true },
+    name: { type: "String" },
+    scope: { type: "String", enum: GRID_SCOPES, default: "global" },
+    // Set only on scope:'account' rows; the per-tenant override of a global config.
+    account_id: { type: "ObjectId", default: null, index: true },
+    config: { type: "Mixed", required: true },
+    // Bumped on every save. A saved user layout records the version it was made against, so the
+    // renderer can reconcile rather than break.
+    version: { type: "Number", default: 1 },
+    status: { type: "String", enum: ["active", "draft", "retired"], default: "draft" },
+    updated_by: { type: "ObjectId" },
+    updated_at: { type: "Date" },
+  }),
+  indexes: Object.freeze([
+    { keys: { grid_code: 1, scope: 1, account_id: 1 }, options: { unique: true } },
+  ]),
+});
+
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const FEATURE_CODE = /^[A-Z][A-Z0-9_]*(\.[A-Z][A-Z0-9_]*){1,2}$/;
+
+/**
+ * Validate a grid config. Returns `{ valid, errors[], warnings[] }`.
+ *
+ * Errors are things that would render a broken or unsafe grid; warnings are things that are legal
+ * but almost certainly a mistake. The admin screen must block on errors and show warnings — a
+ * config is edited by a human and saved straight into what everyone sees, so "it saved fine and
+ * then the screen was empty" is the failure mode this exists to prevent.
+ */
+export function validateGridConfig(config) {
+  const errors = [];
+  const warnings = [];
+  const err = (m) => errors.push(m);
+  const warn = (m) => warnings.push(m);
+
+  if (!isObj(config)) return { valid: false, errors: ["config must be an object"], warnings };
+
+  if (!config.grid_code) err("grid_code is required");
+  if (!config.feature_code) err("feature_code is required — a grid must bind to the access engine");
+  else if (!FEATURE_CODE.test(config.feature_code)) err(`feature_code "${config.feature_code}" must be MODULE.SCREEN[.ACTION]`);
+
+  // ── source ──────────────────────────────────────────────────────────────────────────────────
+  const src = config.source;
+  if (!isObj(src)) err("source is required");
+  else {
+    if (!src.endpoint) err("source.endpoint is required");
+    // Without a collection the server cannot apply tenant/product/record scope to this grid.
+    if (!src.collection) err("source.collection is required — the server needs it to scope the query");
+    if (src.filter_dialect && src.filter_dialect !== FILTER_DIALECT) {
+      err(`source.filter_dialect must be "${FILTER_DIALECT}"`);
+    }
+    if (!src.id_field) warn("source.id_field not set — defaulting to _id");
+  }
+
+  // ── columns ─────────────────────────────────────────────────────────────────────────────────
+  const cols = Array.isArray(config.columns) ? config.columns : [];
+  if (!cols.length) err("at least one column is required");
+  const seen = new Set();
+  cols.forEach((c, i) => {
+    const at = `columns[${i}]`;
+    if (!isObj(c)) return err(`${at} must be an object`);
+    if (!c.key) err(`${at}.key is required`);
+    else if (seen.has(c.key)) err(`${at}.key "${c.key}" is duplicated — keys address saved layouts`);
+    else seen.add(c.key);
+    if (!c.header) warn(`${at} ("${c.key}") has no header`);
+    if (!c.path && c.type !== "actions") err(`${at} ("${c.key}") needs a path`);
+    if (c.type && !COLUMN_TYPES.includes(c.type)) err(`${at}.type "${c.type}" is not a known type`);
+    // A callback here is the one thing that would make the config unstorable.
+    for (const k of Object.keys(c)) {
+      if (typeof c[k] === "function") err(`${at}.${k} is a function — configs must be serialisable`);
+    }
+  });
+  if (cols.length && !cols.some((c) => c.defaultVisible !== false)) {
+    err("every column is hidden by default — the grid would render empty");
+  }
+
+  // ── filters ─────────────────────────────────────────────────────────────────────────────────
+  (config.filters || []).forEach((f, i) => {
+    const at = `filters[${i}]`;
+    if (!f?.key) err(`${at}.key is required`);
+    if (f?.type && !FILTER_TYPES.includes(f.type)) err(`${at}.type "${f.type}" is not a known type`);
+    if (f?.type === "select" && !f.options && !f.ref) {
+      warn(`${at} ("${f.key}") is a select with neither options nor ref — it will render empty`);
+    }
+  });
+
+  // ── actions: each is a FEATURE, so it must carry a code ─────────────────────────────────────
+  const checkActions = (list, label) => (list || []).forEach((a, i) => {
+    const at = `${label}[${i}]`;
+    if (!a?.action_code) {
+      err(`${at} has no action_code — actions are gated features, an ungated action is a hole`);
+    } else if (!FEATURE_CODE.test(a.action_code)) {
+      err(`${at}.action_code "${a.action_code}" must be MODULE.SCREEN.ACTION`);
+    }
+    if (!a?.label) warn(`${at} has no label`);
+    // Destructive things must ask. Cheap to require, expensive to forget.
+    if (a?.kind === "mutation" && /delete|cancel|remove|revoke/i.test(a.action_code || "") && !a.confirm) {
+      warn(`${at} ("${a.action_code}") looks destructive but has no confirm`);
+    }
+  });
+  checkActions(config.rowActions, "rowActions");
+  checkActions(config.bulkActions, "bulkActions");
+
+  if (config.export && !config.export.action_code) {
+    err("export needs an action_code — exports are gated and meterable like any other action");
+  }
+
+  // ── summary ─────────────────────────────────────────────────────────────────────────────────
+  if (config.summary) {
+    const s = config.summary;
+    if (!Array.isArray(s.metrics) || !s.metrics.length) warn("summary has no metrics");
+    // The rule the MIS rollups taught us: cards and the table must answer the same question.
+    if (s.source === "endpoint" && !s.endpoint) {
+      err("summary.source is 'endpoint' but no summary.endpoint is set");
+    }
+    (s.metrics || []).forEach((m, i) => {
+      const at = `summary.metrics[${i}]`;
+      if (!m?.key) err(`${at}.key is required`);
+      if (m?.agg && !AGGREGATIONS.includes(m.agg)) err(`${at}.agg "${m.agg}" is not a known aggregation`);
+      if (m?.agg && m.agg !== "count" && !m.path) err(`${at} ("${m.key}") needs a path for agg "${m.agg}"`);
+      if (m?.agg === "countWhere" && !m.where) err(`${at} ("${m.key}") is countWhere with no where clause`);
+    });
+  }
+
+  // ── pagination / sort ───────────────────────────────────────────────────────────────────────
+  if (config.pagination) {
+    const p = config.pagination;
+    if (p.defaultSize && Array.isArray(p.pageSizes) && !p.pageSizes.includes(p.defaultSize)) {
+      err(`pagination.defaultSize ${p.defaultSize} is not one of pageSizes`);
+    }
+  }
+  if (config.defaultSort?.key && !seen.has(config.defaultSort.key)) {
+    err(`defaultSort.key "${config.defaultSort.key}" is not a column key`);
+  }
+  if (config.totalsRow?.perColumn) {
+    config.totalsRow.perColumn.forEach((t, i) => {
+      if (!seen.has(t.key)) err(`totalsRow.perColumn[${i}].key "${t.key}" is not a column key`);
+    });
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Reconcile a user's saved layout against the current config.
+ *
+ * A layout is preference, never permission — so this drops anything the user may no longer see and
+ * fills gaps from the config. It cannot fail: the worst case is that the layout contributes nothing
+ * and the user gets the default grid.
+ *
+ * @param {Object} config              the grid config
+ * @param {Object|null} layout         the user's saved layout
+ * @param {string[]|null} permittedKeys column keys the access engine allows (null = all)
+ */
+export function applyLayout(config, layout, permittedKeys = null) {
+  const cols = Array.isArray(config?.columns) ? config.columns : [];
+  const allowed = permittedKeys ? new Set(permittedKeys) : null;
+  // Permission first, preference second. Reversing these would let a stale layout pin access.
+  const visible = cols.filter((c) => !allowed || allowed.has(c.key));
+
+  const saved = Array.isArray(layout?.columns) ? layout.columns.filter((k) => visible.some((c) => c.key === k)) : null;
+  const ordered = saved && saved.length
+    ? [
+      ...saved.map((k) => visible.find((c) => c.key === k)),
+      // Columns added to the config since the layout was saved stay available, just not pinned.
+      ...visible.filter((c) => !saved.includes(c.key)).map((c) => ({ ...c, defaultVisible: false })),
+    ]
+    : visible;
+
+  return {
+    columns: ordered.filter(Boolean),
+    filters: layout?.filters ?? {},
+    sort: layout?.sort ?? config?.defaultSort ?? null,
+    pageSize: layout?.pageSize ?? config?.pagination?.defaultSize ?? 25,
+    // True when the layout referenced something that no longer exists — the UI can offer a reset
+    // instead of leaving someone confused by a view that silently lost columns.
+    stale: !!(layout?.columns && saved && saved.length !== layout.columns.length),
+  };
+}
+
+export default {
+  COLUMN_TYPES, FILTER_TYPES, AGGREGATIONS, GRID_SCOPES, FILTER_DIALECT,
+  GRID_CONFIG_DEF, validateGridConfig, applyLayout,
+};