toga-ai 1.0.202 → 1.0.203

package/knowledge/2.0/apps/toga25-supply/INDEX.md

@@ -3,7 +3,8 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [TOGa 2.5 Supply — Architecture](architecture.md) | `toga25-supply` ("TOGa 2.5 Supply") is the **React/TypeScript frontend** for the 2.0 Supply application — an iteration and improvement of `toga2-supply`. | toga25-supply/src/main.tsx, toga25-supply/src/App.tsx, toga25-supply/src/routes.tsx, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/layout/, toga25-supply/src/pages/, toga25-supply/src/hooks/useTableCellInteractions.ts |
-| [Client-Configurable Fields (useClientFields / fieldsConfig)](features/client-configurable-fields.md) | The mechanism for config that **varies by client** (or client × role) — field overrides, filter buttons, group-by options, column pickers, layout toggles — with | toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/README.md |
+| [Action-Button Rule Engine (Flag / Rule grammar)](features/action-button-rule-engine.md) | A declarative, fully config-driven rule engine that resolves the boolean-ish flags (`isEnabled`, `isVisible`, `isComplete`) on SalesOrder action-button options. | toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
+| [Client-Configurable Fields (useClientFields / fieldsConfig)](features/client-configurable-fields.md) | The mechanism for config that **varies by client** (or client × role) — field overrides, filter buttons, group-by options, column pickers, layout toggles — with | toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/README.md, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/layout/VendorItemRecordModalLayout/viewModel/FIELDS/ |
 | [Column Visibility (URL-driven show/hide columns)](features/column-visibility.md) | A "Columns" header button that opens a modal listing every column from the table meta, lets the user show/hide columns, adjusts the table live, and persists the | toga25-supply/src/components/ColumnVisibilityModal/, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableData.tsx |
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |
 | [Record Modals & Nested Tables](features/record-modals-and-nested-tables.md) | The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and `PrimaryTable*Layout`. | toga25-supply/src/layout/ItemRecordModalLayout/, toga25-supply/src/layout/SalesOrderRecordModalLayout/, toga25-supply/src/layout/SalesOrderItemsTableLayout/, toga25-supply/src/layout/ItemFulfillmentModal/, toga25-supply/src/layout/GenericNestedTables/, toga25-supply/src/hooks/useTableCellInteractions.ts |

package/knowledge/2.0/apps/toga25-supply/features/action-button-rule-engine.md

@@ -0,0 +1,119 @@
+---
+title: Action-Button Rule Engine (Flag / Rule grammar)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-06-25
+owners: [apeterson]
+files:
+  - toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts
+  - toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx
+related:
+  - client-configurable-fields.md
+  - ../architecture.md
+---
+
+## What it is
+
+A declarative, fully config-driven rule engine that resolves the boolean-ish flags
+(`isEnabled`, `isVisible`, `isComplete`) on SalesOrder action-button options. Every such
+flag is a **`Flag`** — either a static `true`/`false` or a **`Rule`** tree evaluated against
+the order's runtime state. Because the entire grammar is data, the backend can ship a rule
+tree verbatim and adding or re-gating a button becomes a pure config change with no frontend
+code edit. This is the realization of the long-stated goal that SalesOrders action-button
+config be completely field-driven and backend-suppliable.
+
+## How it works
+
+The engine lives in `src/pages/SalesOrders/helpers/evaluateEnableRule.ts` and is applied by
+`buildPatchedTenantFields.ts`.
+
+### The grammar
+
+```ts
+type Flag = boolean | Rule | undefined;
+
+type Rule =
+  | { all: Rule[] }                          // AND — every child true
+  | { any: Rule[] }                          // OR  — at least one child true
+  | { not: Rule }                            // NOT
+  | { field: string; op: FieldOp; value? }   // dot-path predicate into RuleContext
+  | { type: string };                        // named domain primitive (rare)
+
+type FieldOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte"
+             | "in" | "nin" | "truthy" | "falsy";
+```
+
+- **Field predicates** address into the `RuleContext` by dot-path (e.g. `order._status`,
+  `currentStage.ApprovalTemplateStages.step`). `getByPath` walks the path with optional
+  chaining; a missing path yields `undefined`.
+- **`RuleContext`** is `{ order, currentStage?, stages? }`. `currentStage`/`stages` carry
+  approval-workflow state when available.
+- **Named rules** (`{ type }`) are bespoke leaf checks that a field predicate cannot express
+  — they live in the `NAMED_RULES` registry. Currently only `stepTwoAssigned` (walks the
+  approval stages to confirm a step-2 assignee exists). An unknown `type` resolves to `true`.
+
+### Resolution primitives
+
+- `evaluateRule(rule, ctx): boolean` — recursive evaluator over the combinators.
+- `resolveFlag(flag, ctx, fallback = false): boolean` — the single primitive behind every
+  flag. Static booleans pass through; an object is treated as a `Rule` and evaluated;
+  `undefined` returns `fallback`. The same prop can therefore be static for one client and
+  rule-driven for another with **no code change**.
+
+### Applying flags to tenant config
+
+`buildPatchedTenantFields({ tenantFields, context })` maps over
+`tenantFields.recordActionFields.actionOptions` and patches each option's resolvable flags:
+
+- `isEnabled` — via `resolveActionEnabled` (see back-compat below).
+- `isVisible` and `isComplete` — only patched when the key is present on the option, each via
+  `resolveFlag(..., false)`.
+
+It returns a new `tenantFields` with a patched `recordActionFields.actionOptions`. Callers:
+`useSalesOrderRecordModalLayoutModel.tsx` and `useApprovalModalViewModel.tsx`.
+
+### Back-compat shim
+
+The previous single-purpose `EnableRule` grammar (`alwaysEnabled`, `requireStepTwoAssigned`,
+`requireOrderField`, `statusIn`) is mapped onto the generic engine via `evaluateEnableRule`,
+so existing configs keep working while they migrate to `Rule`. `resolveActionEnabled` picks
+the path:
+
+1. `isEnabled` is an object → treat as a `Rule`, `resolveFlag`.
+2. else a separate `enableRule` exists → legacy `evaluateEnableRule`.
+3. else → return the static `isEnabled`.
+
+Retire the shim once all configs express flags as `Rule`.
+
+## Adding or re-gating a button
+
+1. **Pure config change (preferred):** edit the action option's `isEnabled` / `isVisible` /
+   `isComplete` in the per-client `recordActionFields` config to a static boolean or a `Rule`
+   tree. No code edit. The backend can ship the same tree.
+2. **New primitive check only:** if a gate genuinely can't be expressed as field predicates
+   + combinators (e.g. it must walk approval stages), add one entry to `NAMED_RULES` and
+   reference it as `{ type: "yourCheck" }`. This is the only expected reason to edit the
+   engine file.
+
+## Gotchas
+
+- **`recordActionFields` is the current key** (renamed from `approvalActionFields` /
+  `orderViewFields`-era naming). `buildPatchedTenantFields` reads
+  `recordActionFields.actionOptions`; missing config falls back to `[]`.
+- **`isVisible` / `isComplete` default to `false`** when present-but-undefined, while
+  `isEnabled` falls through to its static value. Don't assume a missing flag means "shown".
+- **The table row menu (`RowActionButtons.tsx`) reads raw config directly** and is
+  intentionally out of scope for rule-driven enablement — it does not go through
+  `buildPatchedTenantFields`.
+- **Prefer the `Rule` grammar over magic named keys.** Anything expressible as a field
+  comparison must stay config-only; adding to `NAMED_RULES` is the rare exception, not the
+  default.
+
+## Change history
+- 2026-06-25 — Documented the generic Flag/Rule engine: combinators, field predicates, named-rule registry, `resolveFlag`/`buildPatchedTenantFields`, and the legacy `EnableRule` back-compat shim. (apeterson)

package/knowledge/2.0/apps/toga25-supply/features/client-configurable-fields.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-06-23
+updated: 2026-06-25
 owners: [apeterson]
 files:
   - toga25-supply/src/fieldsConfig/index.ts
@@ -14,9 +14,12 @@ files:
   - toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/
   - toga25-supply/src/pages/Inventory/viewModel/FIELDS/
   - toga25-supply/src/pages/Inventory/README.md
+  - toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/
+  - toga25-supply/src/layout/VendorItemRecordModalLayout/viewModel/FIELDS/
 related:
   - ../architecture.md
   - column-visibility.md
+  - action-button-rule-engine.md
 ---
 
 ## What it is
@@ -28,10 +31,13 @@ and the `useClientFields()` hook.
 
 ## How it works
 
-1. **Per-client JSON lives next to the consuming page**, under `FIELDS/<CLIENT>/`
-   (e.g. `src/pages/SalesOrders/viewModel/FIELDS/COMPASS/salesOrdersPageFields.json`). There is
-   **always a `DEFAULT/`** folder every client falls back to. `<CLIENT>` must match the hostname
-   `clientSlug` (uppercase — `COMPASS`, `NYCHH`, …).
+1. **Per-client JSON lives next to the consuming page _or layout_**, under `FIELDS/<CLIENT>/`
+   (e.g. `src/pages/SalesOrders/viewModel/FIELDS/COMPASS/salesOrdersPageFields.json`, or for a
+   record-modal layout `src/layout/ItemRecordModalLayout/viewModel/FIELDS/COMPASS/itemRecordViewFields.json`).
+   There is **always a `DEFAULT/`** folder every client falls back to. `<CLIENT>` must match the
+   hostname `clientSlug` (uppercase — `COMPASS`, `COMPASSCANADA`, `NYCHH`, …). Record-modal layouts
+   typically split their config per modal mode — `*ViewFields.json`, `*EditFields.json`,
+   `*CreateFields.json` — one file per mode, per client.
 2. **`src/fieldsConfig/index.ts`** imports those JSON files and wires them into the
    `ClientFields` bundle — a normalized `FIELDS[clientSlug][role]` map merged over `DEFAULT`.
 3. **`useClientFields()`** resolves the active `clientSlug` (from `useHostnameStore`) + `role`
@@ -64,6 +70,22 @@ registry that maps enum → real value (e.g. `MODAL_RENDERERS: Record<ModalKey,
 This is the one place app-owned JSX is grafted back onto client-authored config. Clients never
 author JSX.
 
+### Record-modal header & action config
+
+Record-modal layouts (`ItemRecordModalLayout`, `VendorItemRecordModalLayout`) now drive the
+modal's chrome from the same per-client JSON, not from the component:
+
+- **`header`** — `{ modalTag: { icon, iconStyle, title }, labelTemplate, statusBadge }`.
+  `labelTemplate` is a `"{dotted.path} literal"` string resolved against the record (same
+  `fillTemplate` convention as `optionLabelTemplate`). `statusBadge` is
+  `{ field, activeLabel, inactiveLabel }` — the component reads `record[field]` (e.g.
+  `isActive`) and renders the matching label. The component bakes in no titles or labels.
+- **`editItem`** — a `{ valueKey, kind: "button", label, icon, isVisible, isEnabled }` action
+  block. `isVisible` / `isEnabled` are `Flag`s, so the Edit button is gated declaratively per
+  client (e.g. visible+enabled for vendor items, hidden for the DEFAULT item view). These flags
+  resolve through the same engine as SalesOrder action buttons — see
+  [action-button-rule-engine.md](action-button-rule-engine.md).
+
 ## Adding a new client-configurable field
 
 1. Author the serializable JSON under `FIELDS/DEFAULT/<thing>.json` + a folder per overriding client.
@@ -81,8 +103,18 @@ author JSX.
 - **New client *file* = no code change** (just import/wiring). **New render style/modal type
   (new enum value) = code change** in the hydration registry — that's the intended boundary
   between client config and app rendering.
+- **Flat (un-wrapped) bundles need a fallback that tolerates the missing `DEFAULT` key.** Some
+  bundles wrap their config under a top-level `DEFAULT` key, others are authored flat. In
+  `fieldsConfig/index.ts`, derive the default defensively rather than assuming the wrapper exists:
+  `const DEFAULT_ORDER_VIEW_FIELDS = (defaultBundle as any).DEFAULT ?? (defaultBundle as any) ?? {};`
+  — fall through to the bundle itself, then `{}`, so a flat JSON file does not resolve to `undefined`.
 - Worked examples: `salesOrdersPageFields` (client × role) and `inventoryGroupings` (client-only +
-  hydration; full write-up in `src/pages/Inventory/README.md`).
+  hydration; full write-up in `src/pages/Inventory/README.md`); `itemRecordViewFields` /
+  `vendorItemRecordViewFields` are record-modal-layout examples living under `src/layout/.../viewModel/FIELDS/`.
 
 ## Change history
+- 2026-06-25 — Extended to record-modal layouts: per-mode `*ViewFields`/`*EditFields` JSON under `src/layout/.../viewModel/FIELDS/`, JSON-driven modal `header` (modalTag/labelTemplate/statusBadge) + `editItem` button gated via the Flag/Rule engine, and the flat-bundle defensive-default gotcha. (apeterson)
 - 2026-06-23 — Documented from the `add-client-fields` skill during initial knowledge seed. (apeterson)
+- 2026-06-25 — Client field JSON also lives under `src/layout/<Modal>/viewModel/FIELDS/<CLIENT>/`
+  (record-modal layouts; split per mode: View/Edit/Create). Documented the defensive
+  `?? (defaultBundle) ?? {}` fallback for flat (un-`DEFAULT`-wrapped) bundles. (apeterson)

package/knowledge/INDEX.md

@@ -27,7 +27,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 4 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 6 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
-- **toga25-supply** (TOGa 2.5 Supply) — 5 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 6 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 7 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 
 ## standalone framework

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.202",
+  "version": "1.0.203",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",