toga-ai 1.0.247 → 1.0.248

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

@@ -8,5 +8,5 @@
 | [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 |
-| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts |
+| [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J | toga25-supply/src/surface/useFetchSurfaceMeta.ts, toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/actionRegistry.ts, toga25-supply/src/surface/componentRegistry.tsx, toga25-supply/src/surface/SurfaceActionBar.tsx, toga25-supply/src/surface/SurfaceSection.tsx, toga25-supply/src/surface/resolve.ts, toga25-supply/src/surface/types.ts, toga25-supply/src/surface/index.ts, toga25-supply/src/pages/Login/LoginPage.tsx, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/Items/ItemsPage.tsx, toga25-supply/src/pages/Items/viewModel/useItemsPageViewModel.tsx, toga25-supply/src/pages/VendorItems/VendorItemsPage.tsx, toga25-supply/src/pages/VendorItems/viewModel/useVendorItemsPageViewModel.tsx, toga25-supply/src/pages/Inventory/Inventory.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/index.ts, toga25-supply/src/fieldsConfig/index.ts |
 | [Cypress Testing Harness (component + e2e)](workflows/cypress-testing.md) | The Cypress test harness for the `toga25-supply` frontend, bootstrapped from scratch (`cypress` was already a dependency but there was no config, no `cypress/` | toga25-supply/cypress.config.ts, toga25-supply/cypress/tsconfig.json, toga25-supply/cypress/support/component.tsx, toga25-supply/cypress/support/component-index.html, toga25-supply/cypress/support/e2e.ts, toga25-supply/cypress/support/commands.ts, toga25-supply/cypress/support/fixtures.ts, toga25-supply/cypress/support/mocks/useApprovalModalViewModel.ts, toga25-supply/cypress/component/SalesOrderApprovalModalsLayout.cy.tsx, toga25-supply/cypress/component/RecordApprovalModalLayout.cy.tsx, toga25-supply/cypress/component/EnterPoNumberModal.cy.tsx, toga25-supply/cypress/e2e/salesOrderApproval.cy.ts |

package/knowledge/2.0/apps/toga25-supply/features/surface-frontend.md

@@ -7,7 +7,7 @@ client: shared
 type: feature
 status: active
 updated: 2026-06-30
-owners: [jcardinal]
+owners: [jcardinal, apeterson]
 files:
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
   - toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts
@@ -15,6 +15,7 @@ files:
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts
   - toga25-supply/src/surface/evaluateSurfaceRule.ts
   - toga25-supply/src/surface/actionRegistry.ts
+  - toga25-supply/src/surface/componentRegistry.tsx
   - toga25-supply/src/surface/SurfaceActionBar.tsx
   - toga25-supply/src/surface/SurfaceSection.tsx
   - toga25-supply/src/surface/resolve.ts
@@ -50,16 +51,35 @@ feature flag — see below). Backend: [surface-resolver](../../_underscore/featu
   meta. Loading a different *record* into the same surface reuses cached meta. Builds the URL as
   `/surfaces/meta?slug=...` (query string), **not** `/surfaces/<slug>/meta` (the path form makes the
   engine parse the slug as a record uuid → 404 EV-6). Unwraps the bundle via **`extractBundle()`**,
-  which locates the bundle by its **structural fingerprint** (the `elements` array) across
-  `raw` / `raw.data` / `raw.data.<route-key>` — because V2 nests a scripted-API return value one
-  level deeper, under a route-keyed slot of `data` (e.g. `data.meta`, `data.surfaces`). On a malformed
-  payload it falls back to an empty-elements bundle so the page never crashes.
+  which uses a recursive **`findBundle(raw, predicate, depth=4)`** to walk the envelope (replacing the
+  old hard-coded `raw`/`raw.data`/`raw.data.<key>` probing) and locates the bundle by its
+  **structural fingerprint**: `looksLikeBundle` now requires **both** an `elements` array **and** a
+  `surface` descriptor object (not the `elements` array alone — see the decoy gotcha below).
+  `extractBundle(raw, slug)` then **prefers** the bundle whose `surface.slug === slug`, falling back to
+  first-found, so a stray sibling bundle can't win. `looksLikeGroup` requires the documented `group`
+  discriminator key so a single-bundle envelope is not mistaken for a group. On a malformed payload it
+  falls back to a safe empty bundle (empty `elements` + empty `messages`/`theme`/`vocabularies` maps)
+  so the page never crashes.
 - **`useFetchSurfaceMetaGroup(slugs[])`** — the grouped sibling of `useFetchSurfaceMeta`, for a screen
   needing many section surfaces at once. **Order-insensitive** (the slug list is normalized so cache
   hits don't depend on argument order), `staleTime: Infinity`, hits the grouped endpoint
   `GET /v2/surfaces/meta-group?slugs=...`, and extracts the `{surfaces}` map via `extractGroup()` /
   `looksLikeGroup()` (the same structural-fingerprint approach as `extractBundle`). Returns `{}` for
   unmigrated screens (`enabled:false`), so a non-roster client does no fetch.
+- **`componentRegistry`** (`src/surface/componentRegistry.tsx`) — the **presentation sibling** of
+  `actionRegistry`, both keyed by the surface meta's `action.key`. `actionRegistry` maps key→behavior
+  handler; `componentRegistry` maps key→custom React component. `SurfaceActionBar.renderElement` calls
+  `getSurfaceComponent(element.action?.key)` and renders the registered component (in a keyed Fragment)
+  **before** falling through to the default icon button — so `action.key` drives **both** which
+  component renders and its behavior, while `messages.label` supplies its text and clicks route through
+  the same `handle`→dispatch path. First entry: `"salesOrder.viewLog"` → `<ViewLogButton>`. Extending
+  is one surface element in meta + one registry entry (same model as `actionRegistry` and the Pattern-3
+  cell registry).
+- **element `config` vs `action.payload`.** Per-element `config` (`Record<string,unknown>|null`) is the
+  opaque element-level seed bag (the SurfaceElements JSON long-tail). At runtime the **backend resolver
+  merges the Action's own config with the element `config` to produce `action.payload`**, which is what
+  the FE consumes — the FE renderer never reads `element.config` directly. A separate surface-level
+  `surface.config` lives on the descriptor (e.g. Inventory's `groupByLabels`/`entityTags`).
 - **`evaluateSurfaceRule`** — the Tier-1 rule evaluator: a **frozen `all/any/none` + `{field,op,value}`
   grammar** that **throws on an unknown op** (generalized from the SalesOrders
   `buildPatchedTenantFields`/`evaluateEnableRule`/`resolveFlag` helpers). Evaluated client-side against
@@ -155,6 +175,25 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
 
 ## Gotchas
 
+- **The single-meta envelope can hide the real bundle behind a DECOY `elements: []`.** The V2 envelope
+  can arrive as `{ surfaces: { meta: <real-bundle> }, elements: [] }` — a decoy empty `elements: []`
+  sits at the top level with **no `surface` descriptor**. A `looksLikeBundle` check matching on
+  `Array.isArray(value.elements)` alone short-circuits on the decoy and never finds the real nested
+  bundle → the action bar renders nothing. Fix: `looksLikeBundle` must require **both** `elements` AND
+  a `surface` descriptor; use recursive `findBundle` + slug-preferring `extractBundle` (see How it
+  works). The durable backend follow-up is to confirm/stabilize the single-meta envelope contract.
+- **The surface `record` shape must match the rule field namespace — wrap as `{ order }`.** Seeded
+  Tier-1 rules namespace their field as `order._status`, so `getByPath(record, "order._status")` only
+  resolves if the host passes `record={{ order }}`. Passing the bare order object resolves to
+  `order.order._status` = undefined → every `in`/`eq` op is false → buttons hidden. The fix is at the
+  **host** (`SalesOrderTopBar.tsx`: `record={order ? { order } : null}`), **not** in
+  `evaluateSurfaceRule.ts` (the evaluator was correct).
+- **`tokens.icon` is a LITERAL FontAwesome icon name, not a theme-token slug.** Only `tokens.color` and
+  `tokens.bg` are theme slugs resolved via `resolveThemeToken(theme, ...)` (the `theme` map only holds
+  `color.status.*`/`bg.status.*` keys). `tokens.icon` is a direct name (e.g. `check`, `xmark`,
+  `clipboardListCheck`, `penToSquare`) and must be used as-is (`element.tokens?.icon ?? "check"`).
+  Running it through `resolveThemeToken` misses on every icon and silently falls back to `"check"` for
+  every button.
 - **Scripted-API GET return values land under `data.<scriptRoute>`, not `data` directly.** V2 nests a
   scripted-API return value inside the envelope under a route-keyed slot of `data` (e.g. `data.meta`,
   `data.surfaces`), one level deeper than a normal data fetch. The bundle hook unwraps this with
@@ -179,6 +218,17 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
   don't inherit Compass's shared base. Deleted the migrated section blocks from COMPASS/COMPASSCANADA/
   QUAD `orderViewFields.json` (data-wiring kept; DEFAULT intact). Action-bar/approval-modal still
   JSON. (jcardinal)
+- 2026-06-30 — Debugged + extended the client-side action-bar renderer (no client-specific work).
+  Fixed three rendering bugs: (1) the single-meta envelope's **decoy `elements: []`** masked the real
+  nested bundle — `looksLikeBundle` now requires `elements` AND a `surface` descriptor, with recursive
+  `findBundle(depth=4)` + slug-preferring `extractBundle` + `group`-discriminator `looksLikeGroup` +
+  safe empty `messages`/`theme`/`vocabularies` fallback (`useFetchSurfaceMeta.ts`); (2) Tier-1 rules
+  always false because the host passed the bare order object instead of the `{ order }` envelope the
+  `order.*` field namespace requires (`SalesOrderTopBar.tsx`); (3) every action icon rendered as
+  `check` because `tokens.icon` (a literal FA name) was wrongly run through `resolveThemeToken`
+  (`SurfaceActionBar.tsx`). Built `componentRegistry.tsx` — the presentation sibling of
+  `actionRegistry`, key→custom component (`salesOrder.viewLog` → `ViewLogButton`). Clarified element
+  `config` vs backend-merged `action.payload`. (apeterson)
 - 2026-06-29 — Migrated VendorItems (screen 2, recipe-exact) and Inventory (screen 3,
   **presentation-only by decision** — fetch topology stays JSON; only title/buttons/modal copy/entity
   tags moved). Fixed the "s.elements is not iterable" crash: `extractBundle()` now finds the bundle by

package/package.json

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