toga-ai 1.0.516 → 1.0.517

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

@@ -10,6 +10,6 @@
 | [Force Logout on Deployment (useDeploymentGuard)](features/force-logout-on-deployment.md) | On large deployments the backend bumps the Core parameter `META_LAST_REFRESH_DATETIME`. | toga25-supply/src/hooks/useDeploymentGuard.tsx, toga25-supply/src/App.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/GenericNestedTables.tsx, toga25-supply/src/layout/GenericNestedTables/GenericTableLayout.tsx, toga25-supply/src/pages/Inventory/viewModel/useInventoryPageViewModel.tsx, toga25-supply/src/pages/Inventory/viewModel/FIELDS/DEFAULT/inventoryGroupings.json, toga25-supply/src/hooks/useTableCellInteractions.ts, toga25-supply/src/hooks/useServerTableUrlState.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/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.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/SurfaceRowActions.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, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
+| [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/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx, 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/view/sections/SalesOrderNotesSection.tsx, toga25-supply/src/pages/SalesOrders/helpers/cleanOrder.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/index.ts, toga25-supply/src/surface/evaluateSurfaceRule.ts, toga25-supply/src/surface/resolveElementState.ts, toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrderRowRecordState.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/SurfaceRowActions.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, toga25-supply/src/layout/ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts, toga25-supply/src/layout/ItemRecordModalLayout/helpers/index.ts, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/ItemRecordModalLayout.tsx, toga25-supply/src/layout/ItemRecordModalLayout/components/ItemRecordView.tsx, toga25-supply/src/surface/useStatusColors.ts, toga25-supply/src/surface/SurfaceHeader.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/helpers/surfaceBundlesToDecisionFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
 | [AWS Amplify Multi-Environment Deployment](workflows/amplify-deployment.md) | How `toga25-supply` deploys to **all** of its environments on AWS Amplify from a **single shared `amplify.yml`**. | toga25-supply/amplify.yml, toga25-supply/src/api/api.ts, toga25-supply/src/hooks/useAuthenticationFlow.ts, toga25-supply/vite.config.ts, toga25-supply/package.json |
 | [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

@@ -6,9 +6,12 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-07-23
+updated: 2026-08-04
 owners: [jcardinal, apeterson]
 files:
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/sectionRenderers.tsx
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/helpers/getVisibleSections.ts
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/layoutComponents/SalesOrderApprovalSummaryGrid.tsx
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
   - toga25-supply/src/pages/SalesOrders/helpers/surfaceBundleToTenantFields.ts
   - toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts
@@ -384,6 +387,50 @@ now carry it (2026-07-21):
   onto `record.order`, mirroring the record-modal view model. Both FE surfaces now carry
   `order.currentStage`/`order.stages`/`order.purchaseOrderDetails`.
 
+## SalesOrders record modal — conditional two-layout split (approval vs standard)
+
+In approval stages the SO record modal needs a **materially different layout**, not just
+different styling: the approval-details card leads and is wide, Order Details + Bill To
+relocate *below* the Items table side-by-side, and Admin Notes moves to the top. This is a
+placement difference **across the DOM tree**, so it is implemented as a **component split at
+`SalesOrderView`** (branching on `isApprovalDetailsActive`), not prop-driven branching inside
+one grid. Shared machinery was extracted so both layouts reuse it rather than duplicating:
+
+- **`helpers/sectionRenderers.tsx`** (new) — `createSectionRenderers` factory exposes the
+  `detailSection`/`approvalDetails`/`locationCard`/`totalsCard` renderer map, extracted from the
+  grid so both the standard and approval grids share one renderer set.
+- **`helpers/getVisibleSections.ts`** (new) — extracted the `isVisible` + `visibilityRule` +
+  approval-suppression filter into one place.
+- **`layoutComponents/SalesOrderApprovalSummaryGrid.tsx`** (new, exported from the barrel) — the
+  approval-stage top grid: approval-details card spans 3 cols, order-summary totals 1 col
+  (`.approvalSummaryGrid` 4-col + `.approvalDetailsSpan` span-3, responsive).
+- **`SalesOrderSummaryGrid.tsx`** slimmed to delegate to the two helpers; **`SalesOrderView.tsx`**
+  swaps grid + renders AdminNotes at top in the approval branch; **`getDetailSections.tsx`**
+  (approval-only) relocates Order Details + Bill To below the Items table and suppresses the
+  below-items adminNotes since it moves to top.
+
+`isApprovalDetailsActive` drives **both** the grid swap and the section relocation, so the
+approval condition lives in exactly one place.
+
+### Boundary rule: grid geometry is FE presentation, NOT surface metadata
+**Surface owns content / visibility / order / ACL only. Column count and per-field colSpan are
+FE presentation and stay in code/CSS.** The approval-details card renders into a **fixed 2-col**
+`.approvalFieldsGrid` (`repeat(2, minmax(0,1fr))`) that reflows automatically as the surface
+hides/shows fields — `BaseDetailField` already spans via `--field-col-span`. If per-field colSpan
+is ever needed it becomes **deterministic FE logic keyed on `valueType`** (address / long-text =
+wide), identical for every client — never a surface attribute.
+
+A first attempt to surface-drive the 2-col layout via surface `config.columns` + element
+`config.colSpan` was **reverted**. The reason is durable and verifiable: the resolver's **CONFIG
+override REPLACES an element's whole `config` blob rather than merging it**
+(`_underscore/Model/Core/Surface.php` ~L827: `$config = $value`; see
+[surface-resolver](../../_underscore/features/surface-resolver.md)). Making per-client colSpan
+work would have required promoting it to a first-class `COL_SPAN` in the
+`SurfaceOverrides.attribute` ENUM + resolver + schema + a framework deploy — far too much
+machinery for "this box is two columns wide", which is exactly the signal that it belongs in the
+FE. Use this as the config/logic line for surface geometry questions: **presentation geometry →
+FE/CSS; content/visibility/order/ACL → Surface.**
+
 ## Gotchas
 
 - **A named predicate that FAILS OPEN silently enables a button when its data isn't fetched.**
@@ -497,6 +544,21 @@ now carry it (2026-07-21):
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-08-04 — **Built** a conditional two-layout split for the SalesOrders record modal
+  (approval vs standard), driven by `isApprovalDetailsActive` at `SalesOrderView`. In approval
+  stages the approval-details card leads (wide), Order Details + Bill To move below the Items
+  table side-by-side, and Admin Notes moves to the top — a placement difference across the DOM
+  tree, so a component split over prop branching. Extracted shared machinery: `sectionRenderers.tsx`
+  (`createSectionRenderers` factory: detail/approvalDetails/location/totals renderers),
+  `getVisibleSections.ts` (visibility + approval-suppression filter), and new
+  `SalesOrderApprovalSummaryGrid.tsx` (4-col grid, approval-details span-3). **DECISION/DISCOVERED:**
+  grid geometry (column count, per-field colSpan) is FE presentation, NOT surface metadata —
+  surface owns content/visibility/order/ACL only. The 2-col approval-details grid is fixed FE/CSS
+  that reflows as the surface hides/shows fields. A first attempt to surface-drive it via
+  `config.columns`/`config.colSpan` was reverted after finding the resolver's **CONFIG override
+  wholesale-REPLACES an element's `config` blob** (`_underscore/Model/Core/Surface.php` ~L827
+  `$config = $value`), so a first-class `COL_SPAN` ENUM + resolver + schema + deploy would be
+  needed — too much machinery, the signal it belongs in the FE. (apeterson)
 - 2026-07-23 — **DECISION + FIX: surface on/off per client is now 100% backend-driven — removed the FE
   roster entirely.** Deleted `SALES_ORDER_SURFACE_MIGRATED_CLIENTS = [COMPASS,COMPASSCANADA,QUAD]` from
   `surfaceBundleToTenantFields.ts` + `helpers/index.ts`; `useSalesOrderRecordModalLayoutModel.tsx` now

package/package.json

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