toga-ai 1.0.397 → 1.0.398

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

@@ -9,6 +9,6 @@
 | [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/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 |
+| [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 |
 | [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,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-07-20
+updated: 2026-07-21
 owners: [jcardinal, apeterson]
 files:
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
@@ -47,6 +47,8 @@ files:
   - 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
 related:
   - ../../_underscore/features/surface-resolver.md
   - meta-driven-table-data.md
@@ -344,6 +346,25 @@ shaped `{ order }`, so the predicate reads **`order.currentStage` / `order.stage
   `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.
+- **Vocabulary color tokens are unresolvable because the resolved bundle's `theme` map is empty —
+  resolve status-badge dot colors from the status endpoint's `colorHex` instead.** A resolved bundle
+  ships theme-token SLUGS on each vocabulary term (`tokens.color = "color.status.<slug>"`,
+  `tokens.bg = "bg.status.<slug>"`) but the bundle's `theme` map arrives as `{}`, so
+  `resolveThemeToken(theme, term.tokens?.color)` returns `undefined` and the status dot renders
+  colorless in the sales-order record-modal header. Fix: resolve the dot color from the
+  `sales-order-statuses` API's `colorHex` field keyed by slug — a `SurfaceVocabularyTerm.value` **IS**
+  the status slug, so it maps 1:1 to `sales-order-statuses[].slug`. The **`useStatusColors(vocabularySlug)`**
+  hook (`src/surface/useStatusColors.ts`) fetches `GET /v2/sales-order-statuses?fields=slug,colorHex&sort=sortOrder`
+  (session-cached via react-query, `staleTime`/`gcTime` Infinity, same pattern as `useFetchSurfaceMeta`)
+  and returns a `(slug) => "#RRGGBB" | undefined` resolver, gated by a
+  `VOCABULARY_COLOR_ROUTES = { "sales-order-status": "sales-order-statuses" }` map so it is reusable
+  for other STATUS vocabularies (walks the V2 envelope to find the row array, no hard-coded
+  `data.salesOrderStatuses`). `SurfaceHeader.tsx`'s BADGE branch was extracted into a
+  `SurfaceStatusBadge` sub-component (needed because `useStatusColors` is a hook) whose dot color is
+  `resolveStatusColor(term.value) ?? resolveThemeToken(theme, term.tokens?.color)` — `colorHex` wins,
+  the theme token remains a fallback if the `theme` map is ever populated. Label resolution and the
+  "no matching term → render nothing" behavior are unchanged. The legacy table path
+  (`PrimaryTable*Layout` via `statusTypes.json`) already used `colorHex` and was untouched.
 - **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
@@ -373,6 +394,17 @@ shaped `{ order }`, so the predicate reads **`order.currentStage` / `order.stage
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-07-21 — Fixed the surface-driven **status badge dot rendering colorless** in the sales-order
+  record-modal header: the resolved bundle ships vocabulary color TOKEN SLUGS
+  (`color.status.*`/`bg.status.*`) but its `theme` map is empty (`{}`), so `resolveThemeToken` returns
+  `undefined`. New **`useStatusColors(vocabularySlug)`** hook (`src/surface/useStatusColors.ts`)
+  resolves the dot color from the `sales-order-statuses` API's `colorHex` keyed by slug (a
+  `SurfaceVocabularyTerm.value` IS the status slug → 1:1 to `sales-order-statuses[].slug`);
+  session-cached via react-query, gated by a `VOCABULARY_COLOR_ROUTES` map for reuse across STATUS
+  vocabularies. `SurfaceHeader.tsx`'s BADGE branch extracted into a `SurfaceStatusBadge` sub-component
+  (hook use), dot color = `resolveStatusColor(term.value) ?? resolveThemeToken(...)` (colorHex wins,
+  theme token remains a fallback). Legacy table path (via `statusTypes.json`) already used `colorHex`,
+  untouched. `tsc --noEmit` clean. (apeterson)
 - 2026-07-20 — Documented the **two FE rule engines** (frozen surface Tier-1 `evaluateSurfaceRule`,
   which THROWS on `{type}` nodes, vs legacy `evaluateEnableRule` with `{type}` NAMED_RULES incl
   `stepTwoAssigned` reading `ctx.currentStage`/`ctx.stages`) and why the corrected Approve rule is

package/package.json

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