toga-ai 1.0.251 → 1.0.252

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/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 |
+| [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/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/SalesOrderView.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.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

@@ -11,7 +11,11 @@ owners: [jcardinal, apeterson]
 files:
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
   - toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.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/SalesOrderRecordModalLayout/view/SalesOrderView.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderSummaryGrid.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getDetailSections.tsx
   - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts
   - toga25-supply/src/surface/evaluateSurfaceRule.ts
   - toga25-supply/src/surface/actionRegistry.ts
@@ -56,15 +60,18 @@ feature flag — see below). Backend: [surface-resolver](../../_underscore/featu
   **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
+  first-found, so a stray sibling bundle can't win. 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
+  `GET /v2/surfaces/meta-group?slugs=...`, and extracts the SLUG-keyed `{surfaces}` map via the
+  recursive **`findSurfaceMap(raw, depth=5)`** — which walks the envelope tree and returns the
+  `surfaces` map whose **values look like bundles** (or an empty/null map), uniquely identifying the
+  inner slug-keyed map regardless of nesting or `data` wrapping. (`extractGroup`'s old
+  `data`/`data.<key>` probe and the `looksLikeGroup` `group`-discriminator check were both removed —
+  see the group-nesting gotcha below for why.) 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
@@ -154,6 +161,17 @@ three bespoke renderers `detailSection`/`locationCard`/`totalsCard` are untouche
   `getDetailSections` are untouched — **only the SOURCE of section config moves JSON → Surface.**
   Business logic stays in code: the recurring-lease `_totalLease` gate in the grid and approval
   gating are **not** moved. (Registered-renderer seam: *config describes, code decides.*)
+- **Full adapter-seam data path (verified this session, no direct `<SurfaceSection>`):**
+  `useFetchSurfaceMetaGroup(SALES_ORDER_SURFACE_SLUGS)` → `surfaceBundleToTenantFields(surfaces)` →
+  merged into `tenantFields` (roster clients only; `clientSlug` is the **uppercased** `getHostname()`
+  result matched against the roster) → **`buildPatchedTenantFields`** (which only overrides
+  `recordActionFields`, so it **preserves all surface section keys**) → `SalesOrderView` →
+  **`SalesOrderSummaryGrid`** (renders by `section.type` / `cardType`:
+  `detailSection`/`locationCard`/`totalsCard`, where `cardType` comes from `surface.config.cardType`)
+  + **`getDetailSections`** (reads `section.isVisible` for the `displayToggle` sections, which carry a
+  `sectionVisibility` marker element). **Decision (confirmed by the developer this session): KEEP the
+  adapter approach — do NOT replace it with a direct `<SurfaceSection>` swap.** The bespoke grid
+  renderers and the `TenantFields` seam are the deliberate integration point.
 - **Roster gate — `SALES_ORDER_SURFACE_MIGRATED_CLIENTS = [COMPASS, COMPASSCANADA, QUAD]`** (an
   in-code roster in `surfaceBundleToTenantFields.ts`; the view-model
   `useSalesOrderRecordModalLayoutModel.tsx` consults it). The view-model resolves sections from
@@ -182,6 +200,27 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
   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 GROUPED meta envelope double-nests the slug-keyed `surfaces` map under an OUTER route-keyed
+  `surfaces` slot — match by value shape, never grab the first `surfaces`.** The meta-group V2 envelope
+  mirrors single-meta's bundle nesting: the real SLUG-keyed map sits one level deeper under a ROUTE-keyed
+  outer slot — `{ surfaces: { "meta-group": { group, surfaces: { "order-details": bundle, … } } },
+  elements: [] }`. The old `extractGroup` grabbed the **first** `surfaces` it saw (the outer route-keyed
+  one, whose values are *group* objects, not bundles), so `surfaces["order-details"]` was `undefined`
+  and `surfaceBundleToTenantFields` produced `{}` — every migrated-client SalesOrders section vanished.
+  Fix: recursive **`findSurfaceMap(raw, depth=5)`** returns the `surfaces` map whose **values look like
+  bundles** (or null/empty), uniquely identifying the inner slug-keyed map regardless of nesting or
+  `data` wrapping. Verified by trace across 6 envelope shapes (double-nested, resolver-return-at-top,
+  simple, data-wrapped, null-child, empty). **Note:** an earlier attempt that required a top-level
+  `group` discriminator on the probed level (`looksLikeGroup`) broke the fetch (returned `{}`) because
+  the V2 envelope carries no top-level `group` at that level — `looksLikeGroup` was removed entirely.
+- **For migrated clients, a dropped (`surface: null`) display section silently vanishes — there is no
+  JSON fallback left.** Once a client's JSON section blocks are deleted (roster migration), a section
+  whose surface resolves to `surface: null` (a seed/ACL gap, e.g. `additional-order-details` /
+  `admin-notes` / `notes`) is dropped by `surfaceBundleToTenantFields` and the section disappears with
+  no fallback. That is a backend seed/ACL gap, **not** an FE bug. Separately, two sections are
+  intentionally gated in `getDetailSections`: `shipments` is **permanently hidden** (the view-model
+  hardcodes `shipmentsData: []` and `useShipments` is commented out; the section gates on
+  `shipmentsData.length > 0`), and `invoices` is data-gated on `invoiceData.length > 0`.
 - **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
@@ -210,6 +249,19 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-06-30 — Follow-up: fixed the GROUPED meta fetch returning `{}` (every migrated-client
+  SalesOrders section had vanished). The meta-group envelope double-nests the slug-keyed `surfaces`
+  map under an outer ROUTE-keyed `surfaces` slot; the old `extractGroup` grabbed the first (outer,
+  group-valued) `surfaces`. Replaced it with recursive `findSurfaceMap(depth=5)` that returns the
+  `surfaces` map whose values are bundle-shaped (verified across 6 envelope shapes). **Reverted the
+  earlier same-session `group`-discriminator `looksLikeGroup` change** — requiring a top-level `group`
+  broke the fetch; `looksLikeGroup` removed entirely. Verified the SalesOrders section migration is
+  fully wired via the adapter seam (`useFetchSurfaceMetaGroup` → `surfaceBundleToTenantFields` →
+  `buildPatchedTenantFields` (overrides only `recordActionFields`) → `SalesOrderSummaryGrid` /
+  `getDetailSections`) and confirmed the decision to KEEP the adapter over a direct `<SurfaceSection>`.
+  Documented why some sections stay hidden (`shipments` hardcoded empty; `invoices` data-gated; and a
+  dropped `surface: null` display section vanishes with no JSON fallback for migrated clients — a
+  seed/ACL gap). (apeterson)
 - 2026-06-30 — Migrated the SalesOrders record-modal sections onto Surface for the roster clients
   [COMPASS, COMPASSCANADA, QUAD] via the registered-renderer seam: added `useFetchSurfaceMetaGroup`
   (order-insensitive grouped `/surfaces/meta-group` fetch) + `surfaceBundleToTenantFields()` (adapts
@@ -221,7 +273,7 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
 - 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` +
+  `findBundle(depth=4)` + slug-preferring `extractBundle` +
   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

package/package.json

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