toga-ai 1.0.377 → 1.0.379

package/knowledge/2.0/apps/_underscore/features/surface-resolver.md

@@ -6,7 +6,7 @@ project: _Underscore
 client: shared
 type: feature
 status: active
-updated: 2026-07-17
+updated: 2026-07-20
 owners: [jcardinal, apeterson]
 files:
   - _underscore/Model/Core/Surface.php
@@ -106,6 +106,21 @@ which surfaced latent resolution gaps in `_buildBundle`/`_resolveElement`:
 - `bundle.surface.titleMessageKey` is set from `titleMessageId`.
 - The 2nd `_loadMessages` return is merged into `$messageKeyById`; dangling message ids are logged.
 
+### Boolean labels — `messages.trueLabel` / `messages.falseLabel`
+Each resolved element now also emits **`messages.trueLabel`** and **`messages.falseLabel`**, sourced
+from the element's **`trueMessageId`** / **`falseMessageId`** (the unified boolean-label pair on
+`SurfaceElements` — see the [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md)).
+`_buildBundle`/`_serializeElement` collect those two ids into the same message batch and id→key remap
+as the other slots. **Additive + backward-compatible:** an element that sets neither id emits `null`
+for both, so existing surfaces are unchanged. This makes `Core.Messages` the single source of truth for
+Yes/No + Active/Inactive labels (no Vocabulary needed) so **BOOLEAN-`valueType` toggles render their
+caption and boolean status badges get a label**. Historically the serializer only emitted
+`label`/`tooltip`/`placeholder`/`disabledTooltip` and **silently dropped** `trueMessageId`/
+`falseMessageId` — SalesOrders never hit this because its status badge uses a Vocabulary and it has no
+boolean rows; the item-record modal (the first boolean consumer) exposed the gap. Rides in
+`_underscore`, so it takes effect only once the framework branch is deployed (framework is pulled at
+deploy).
+
 ## Vocabulary / label per-client relabeling (slugs are internal, labels are messages)
 
 Clients **never rename a Vocabulary**. `Vocabularies.slug` (`sales-order-status`) and
@@ -338,6 +353,14 @@ Core record grants + their logic-group expressions all evaluate `all`/`"1"`. The
   match Compass, a follow-up migration aligning both `meta` and `meta-group` to roles 1,3,4 is needed.
 
 ## Change history
+- 2026-07-20 — Extended the resolver to emit `messages.trueLabel`/`messages.falseLabel` per element,
+  sourced from `trueMessageId`/`falseMessageId` (collected into the same message batch + id→key remap);
+  additive + backward-compatible (unset → null). Closes a latent gap: the serializer historically emitted
+  only label/tooltip/placeholder/disabledTooltip and dropped the boolean-label ids, so BOOLEAN-valueType
+  toggles rendered blank and boolean status badges had no label — SalesOrders sidestepped it (Vocabulary
+  badge, no boolean rows); the item-record modal (first boolean consumer) surfaced it. Keeps Core.Messages
+  the single source of truth for Yes/No + Active/Inactive. Takes effect only once the `_underscore`
+  framework branch is deployed. (apeterson)
 - 2026-07-17 — Materialized the per-client sales-order button diffs (re-adding the overrides wiped in
   the earlier rebuild): Compass/CompassCanada ADMIN = all four record-action buttons visible + both
   `VISIBILITY_RULE`/`ENABLED_RULE` widened to `[pendingApproval, pendingInitialApproval]`, MANAGER =

package/knowledge/2.0/apps/dbchanges2/INDEX.md

@@ -3,5 +3,5 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Database Changes (dbchanges2) Repository Architecture](architecture.md) | `dbchanges2` is the **schema-migration / SQL change-set repository** for the entire 2.0 platform. | Core/, Client/, Client_<Tenant>/, Logs/, Logs_Client/, _modules/ |
-| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql |
+| [Surface Layer Schema (UI presentation/config tables)](features/surface-layer-schema.md) | The persistent schema for the platform-wide **Surface** UI presentation/configuration layer (see the `_underscore` [surface-resolver](../../_underscore/features | dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client_Compass/2026-06-25d - SalesOrderSurfaceClientSeed.sql, _underscore/Model/Client/ThemeToken.php, toga25-supply/src/themeConfig.json, dbchanges2/Core/2026-06-25a - SurfaceCoreTables.sql, dbchanges2/Core/2026-06-25b - SurfaceRecordsAndFields.sql, dbchanges2/Core/2026-06-25c - SalesOrderLoginSurfaceSeed.sql, dbchanges2/Core/2026-06-29a - ItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Core/2026-06-29d - VendorItemsSurfaceSeed.sql, dbchanges2/Core/2026-06-29e - InventorySurfaceSeed.sql, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Compass/2026-06-30a - SalesOrderDisplaySectionManagerOverrides.sql, dbchanges2/Client_CompassCanada/2026-06-30a - SalesOrderSurfaceManagerOverrides.sql, dbchanges2/Client_Quad/2026-06-30a - SalesOrderSurfaceClientOverrides.sql, dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql, dbchanges2/Client/2026-06-25b - SurfaceClientSeed.sql, dbchanges2/Client/2026-06-25c - SurfaceClientAcl.sql, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Core/2026-07-17h - Update - ClearApprovalsFilterButtonConfig.sql, dbchanges2/Client_Compass/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Compass/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql, dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql, dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql, dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql, dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql, dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql, dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql, dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql, dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql, dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql, dbchanges2/Core/2026-07-17 - README - RUN ORDER.md |
 | [2.0 New-Client Onboarding (manual process)](workflows/client-onboarding.md) | How to manually stand up a new 2.0 client (tenant). | Client/, Client_<Tenant>/, Core/, Logs_Client/ |

package/knowledge/2.0/apps/dbchanges2/features/surface-layer-schema.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-07-17
+updated: 2026-07-20
 owners: [jcardinal, apeterson]
 files:
   - dbchanges2/Client/2026-06-25a - SurfaceClientTables.sql
@@ -38,6 +38,19 @@ files:
   - dbchanges2/Client_CompassCanada/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql
   - dbchanges2/Client_Quad/2026-07-17a - SalesOrderApprovalActionsOverride.sql
   - dbchanges2/Client_Quad/2026-07-17b - SalesOrderApprovalsFilterButtonOverride.sql
+  - dbchanges2/Core/2026-07-20a - Update - HideAdminNotesSectionByDefault.sql
+  - dbchanges2/Core/2026-07-20b - Update - NotesSectionFieldElements.sql
+  - dbchanges2/Client_Compass/2026-07-20a - AdminNotesSectionVisibilityOverride.sql
+  - dbchanges2/Client_Compass/2026-07-20b - NotesSectionFieldsOverride.sql
+  - dbchanges2/Client_CompassCanada/2026-07-20a - AdminNotesSectionVisibilityOverride.sql
+  - dbchanges2/Client_CompassCanada/2026-07-20b - NotesSectionFieldsOverride.sql
+  - dbchanges2/Client_Quad/2026-07-20a - NotesSectionFieldsOverride.sql
+  - dbchanges2/Core/2026-07-20c - Update - VendorItemsToggleSurfaceSeed.sql
+  - dbchanges2/Client_Compass/2026-07-20c - ItemRecordEditButtonEnable.sql
+  - dbchanges2/Client_Compass/2026-07-20d - ItemRecordVendorItemsEnable.sql
+  - dbchanges2/Client_CompassCanada/2026-07-20c - ItemRecordEditButtonEnable.sql
+  - dbchanges2/Client_CompassCanada/2026-07-20d - ItemRecordVendorItemsEnable.sql
+  - dbchanges2/Core/2026-07-17 - README - RUN ORDER.md
 related:
   - ../../_underscore/features/surface-resolver.md
 ---
@@ -167,6 +180,68 @@ to `{}` so Core carries **no** `_status` default. Every client — even Quad, wh
 old default — now declares the full filter config via its own `CONFIG` override. This makes the Core
 seed a true neutral default for the filter button, matching the action-button rule above.
 
+## Display-section visibility — two patterns (marker vs field-driven)
+
+A record-modal **display SECTION**'s own `Surfaces.isVisible` can never be client-overridden (the
+cascade keys on `surfaceElementId`, never a Surface's own `isVisible` — see gotcha). Section
+visibility is therefore always carried by an **element**, in one of two patterns depending on whether
+the section has per-client field content:
+
+- **Marker pattern (whole-section on/off)** — a section with fixed content (invoices / shipments /
+  additional-order-details / admin-notes) carries a single hidden TEXT **`sectionVisibility` marker
+  element** (`config.role='sectionVisibility'`); that element's `isVisible` *is* the section's
+  visibility. A client flips the section by overriding the marker's `IS_VISIBLE`.
+- **Field-driven pattern (per-client field set)** — a section whose fields vary per client (notes)
+  models **each field as a real `FIELD` `SurfaceElement`** (the source of truth for that field's label
+  + visibility). No marker element: the FE **DERIVES** the section's visibility as "visible iff ≥1
+  field element is visible" (see
+  [surface-frontend](../../toga25-supply/features/surface-frontend.md)). This is the third section
+  pattern, alongside the card sections (`cardType` → grid renderer) and the marker toggles.
+
+### Core neutral default + client opt-in (admin-notes & notes, 2026-07-20)
+Both sections follow the Core-neutral-default → client-opt-in rule (the same rule as the action/filter
+buttons above): Core seeds the section **off**, each client opts in via a `SurfaceOverride`.
+
+- **admin-notes (marker pattern).** `Core/2026-07-20a` flips the admin-notes section's
+  `sectionVisibility` marker `isVisible=0`, so the section is **hidden by default**. Resolved
+  **id-agnostically** by `Surfaces.slug='admin-notes'` + `config.role='sectionVisibility'` (never a
+  hardcoded element id). **Compass + Compass Canada** opt the section back on with a client-wide
+  `IS_VISIBLE='1'` override on that same element (`Client_Compass/2026-07-20a`,
+  `Client_CompassCanada/2026-07-20a`); every other client stays hidden.
+- **notes (field-driven pattern).** `Core/2026-07-20b` migrates the two previously-hardcoded FE fields
+  (`reasonForRequest`, `shippingInstructions`) into two `FIELD` `SurfaceElements` under the `notes`
+  surface, both `isVisible=0` in Core (**default = neither field → the section is hidden**). Per-client
+  `IS_VISIBLE` overrides: **Quad → shippingInstructions only** (`Client_Quad/2026-07-20a`); **Compass +
+  Compass Canada → both** (`Client_Compass/2026-07-20b`, `Client_CompassCanada/2026-07-20b`).
+- **A note field's value binding is a nested-array lookup, not a flat column.** Note text lives in
+  `order.salesOrderNotes[]` (each entry has `salesOrderNoteType.slug` + `note`), not a flat order
+  field. Each notes `FIELD` element names its note type in **`config.noteTypeSlug`** (`request` /
+  `shipping`); the FE resolves `salesOrderNotes[].note` by that slug (client-agnostic). Per-client slug
+  variance is handled by a **`CONFIG` override** on the element (REPLACE semantics) — no FE change.
+
+### Item-record modal gating (Edit button + vendor-items table, 2026-07-20)
+The item-record modal's per-client gating uses the same Core-neutral-default → client-opt-in rule as
+the SalesOrder buttons/sections above, applied via two mechanisms:
+
+- **Header Edit button (existing element).** The `item-record-header` Edit button is seeded OFF in Core
+  (the neutral-default action-button rule — see the TRUE NEUTRAL DEFAULT section). Compass + Compass
+  Canada opt in with a client-wide `IS_VISIBLE='1'` override (`Client_*/2026-07-20c -
+  ItemRecordEditButtonEnable.sql`). The override resolves the element **id-agnostically** by
+  `renderType='BUTTON'` + `config.kind='itemEdit'` (never a hardcoded element id/uuid — those regenerate
+  per environment), `NOT EXISTS`-guarded, client-wide (`roleId`/`personaId` NULL).
+- **Vendor-items table (new dedicated toggle surface).** `Core/2026-07-20c -
+  VendorItemsToggleSurfaceSeed.sql` seeds a dedicated **`item-record-vendor-items`** SECTION surface
+  carrying a single hidden marker element (`config.role='sectionVisibility'`, the **marker pattern**
+  above), OFF in Core. The FE reads that marker's resolved `isVisible` as `vendorItemsEnabled` and
+  conditionally renders the vendor table (see
+  [surface-frontend](../../toga25-supply/features/surface-frontend.md)). Compass + Compass Canada opt in
+  via `Client_*/2026-07-20d - ItemRecordVendorItemsEnable.sql` (client-wide `IS_VISIBLE='1'` on the
+  marker, resolved by `Surfaces.slug='item-record-vendor-items'` + `config.role='sectionVisibility'`).
+
+Both clients' `c`/`d` overrides and the Core seed were added to `Core/2026-07-17 - README - RUN
+ORDER.md`. Verified working in the UI for both clients. (Boolean toggle/badge labels in this modal
+resolve through the resolver's new `trueLabel`/`falseLabel` emission — see the resolver doc.)
+
 ## ThemeTokens — per-tenant, physically isolated in each client DB
 
 `ThemeTokens` lives **inside each tenant's own database** (`Client_Compass.ThemeTokens`,
@@ -320,6 +395,26 @@ rule resumes.
   override is added). **Open follow-up.**
 
 ## Change history
+- 2026-07-20 — Applied the Core-neutral-default → client-opt-in pattern to the **item-record modal**.
+  Header Edit button seeded OFF in Core; Compass + Compass Canada opt in via `Client_*/2026-07-20c`,
+  resolving the element id-agnostically by `renderType='BUTTON'`+`config.kind='itemEdit'` (NOT EXISTS,
+  client-wide). New dedicated `item-record-vendor-items` toggle surface (`Core/2026-07-20c`) carrying a
+  `config.role='sectionVisibility'` marker (marker pattern, OFF in Core) that the FE reads as
+  `vendorItemsEnabled`; Compass + Compass Canada opt in via `Client_*/2026-07-20d` (resolved by
+  `Surfaces.slug`+`config.role`). All added to the `Core/2026-07-17 - README - RUN ORDER.md`; verified
+  in the UI for both clients. (apeterson)
+- 2026-07-20 — Applied the Core-neutral-default → client-opt-in pattern to two SalesOrder display
+  sections. **admin-notes** (marker pattern): `Core/2026-07-20a` hides it by default (marker
+  `isVisible=0`, resolved id-agnostically by `Surfaces.slug`+`config.role='sectionVisibility'`);
+  Compass + Compass Canada opt back in via a client-wide `IS_VISIBLE` override
+  (`Client_Compass`/`Client_CompassCanada/2026-07-20a`). **notes** (new field-driven pattern):
+  `Core/2026-07-20b` migrates the two hardcoded FE note fields into `FIELD` SurfaceElements (both
+  `isVisible=0` = neither by default), with per-client `IS_VISIBLE` overrides — Quad = shipping only
+  (`Client_Quad/2026-07-20a`), Compass + Compass Canada = both (`Client_*/2026-07-20b`). Documented the
+  two display-section visibility patterns (marker for whole-section on/off vs field-driven where the FE
+  derives section visibility from "≥1 field visible") and note-field value binding via
+  `config.noteTypeSlug` into `order.salesOrderNotes[]` (per-client slug variance via a `CONFIG`
+  override). (apeterson)
 - 2026-07-17 — Applied the Core-neutral-default → client-opt-in pattern to the sales-order action &
   filter buttons across Compass, CompassCanada, and Quad (`Client_*/2026-07-17a`+`b`). Cleared the
   Core approvals-filter `_status` default (`Core/2026-07-17h`) so every client declares its own filter

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/, 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/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/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 |
+| [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/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 |
 | [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-13
+updated: 2026-07-20
 owners: [jcardinal, apeterson]
 files:
   - toga25-supply/src/surface/useFetchSurfaceMeta.ts
@@ -16,6 +16,8 @@ files:
   - 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/actionRegistry.ts
@@ -37,6 +39,11 @@ files:
   - 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
 related:
   - ../../_underscore/features/surface-resolver.md
   - meta-driven-table-data.md
@@ -107,8 +114,8 @@ legacy pre-Surface fallback branches at the wired screens removed). Legacy per-s
 
 ## What's wired
 
-Login + sales-orders list + the sales-order modal + the **Items**, **VendorItems**, and
-**Inventory** LIST screens. The SalesOrder action
+Login + sales-orders list + the sales-order modal + the **item-record modal (VIEW, all clients)** +
+the **Items**, **VendorItems**, and **Inventory** LIST screens. The SalesOrder action
 bar reproduces `orderViewFields.json` approve/deny/approvalWorkflow/viewLog/editOrder by delegating
 to the existing `onActionClick`/`onOpenLog` handlers. TABLE-type surfaces stay on the existing
 TableView pipeline via `tableViewSlug` (see [meta-driven-table-data](meta-driven-table-data.md)) —
@@ -173,6 +180,31 @@ three bespoke renderers `detailSection`/`locationCard`/`totalsCard` are untouche
   `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.
+
+### `displayToggle` sections — marker vs field-driven (the notes section)
+`buildSection`'s `displayToggle` branch handles **two** shapes (mirroring the schema's two
+display-section patterns — see
+[surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md)):
+- **Field-carrying section (notes)** — the branch maps every `FIELD`-`renderType` element to a field
+  config via `elementToFieldConfig` (now carrying **`config.noteTypeSlug`**) and **DERIVES** the
+  section's `isVisible` as `fields.some(f => f.isVisible)` — no `sectionVisibility` marker needed. It
+  emits both `isVisible` and the `fields[]` array.
+- **Pure-toggle section (invoices / shipments / additional-order-details / admin-notes)** — no `FIELD`
+  elements, so it falls back to the single `sectionVisibility` marker element's `isVisible`.
+
+**`SalesOrderNotesSection`** consumes the field-driven shape: it renders **only the visible note
+slots** and resolves each value from `order.salesOrderNotes[]` by
+`salesOrderNoteType.slug === field.noteTypeSlug` (note text is a nested-array entry, not a flat order
+column). When no surface `fields` are supplied it falls back to the **legacy flat props**
+(`reasonForRequest` / `shippingInstructions`, flattened by `cleanOrder`) so non-migrated JSON clients
+still render — see the `cleanOrder` slug gotcha below.
+
+**Reusable pattern (field-driven display section):** for a section whose content varies per client,
+model each field as a `FIELD` element (label + visibility source of truth), derive section visibility
+from "≥1 field visible", and bind an array-derived value via element `config` (here `noteTypeSlug`)
+resolved on the FE. This is the presentation counterpart of the schema's field-driven pattern and the
+third section pattern alongside card sections (`cardType` → grid renderer) and marker toggles.
+
 - **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
@@ -192,6 +224,39 @@ three bespoke renderers `detailSection`/`locationCard`/`totalsCard` are untouche
 seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster seed fix is on hold
 (see [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md)).
 
+## Item-record modal (VIEW) — migrated via an adapter seam, ALL clients (no roster)
+
+The item-record modal's **VIEW** sections are now resolved from Surface for **every client** — unlike
+the SalesOrders modal, there is **no migration roster**. It mirrors the SalesOrders adapter-seam
+approach (config source moves JSON → Surface; the existing view is untouched):
+
+- **`surfaceBundleToItemViewFields()`** (`ItemRecordModalLayout/helpers/surfaceBundleToItemFields.ts`,
+  new; barrel `helpers/index.ts`) adapts the grouped Surface bundle into the
+  `{ header, editItem, sections, vendorItemsEnabled }` shape the view already consumed.
+- **`useItemRecordModalViewModel`** fetches the `item-record-*` surface group via
+  `useFetchSurfaceMetaGroup`, adapts it, and threads it into **`ItemRecordView`** as a **`viewFields`**
+  prop. The per-client JSON (`itemRecordViewFields`) is now a **fallback only** — used when the group
+  fails to resolve. **Edit mode stays JSON-driven (deferred).**
+- **Boolean labels** flow through `messages.trueLabel`/`messages.falseLabel` (added to
+  `SurfaceElementMessages` in `src/surface/types.ts`), which the resolver now emits from each element's
+  `trueMessageId`/`falseMessageId` (see
+  [surface-resolver](../../_underscore/features/surface-resolver.md)) — so BOOLEAN toggles/badges render
+  their caption instead of blank.
+
+**Per-client gating rides the Core-default-OFF → SurfaceOverride opt-in pattern** (the same
+"approvals-gate" shape used on SalesOrders — `elements.some(el => el.isVisible)`); the seed side lives
+in [surface-layer-schema](../../dbchanges2/features/surface-layer-schema.md):
+
+- **Header Edit button** — an element in `item-record-header`, matched **id-agnostically** by
+  `renderType='BUTTON'` + `config.kind='itemEdit'`. Core seeds it OFF; Compass / Compass Canada opt in.
+- **Vendor-items table** — a dedicated `item-record-vendor-items` **toggle surface** carrying a
+  `config.role='sectionVisibility'` marker element; the FE reads it as **`vendorItemsEnabled`** and
+  conditionally renders the vendor table in `ItemRecordView`. Core-OFF; Compass / Compass Canada opt in.
+
+> **Seed-intent to verify (flagged to the dev):** the Core item-record Pricing section seed now also
+> shows **`leasePrice`** for all clients, whereas the old DEFAULT JSON showed only unit price. Confirm
+> that is the intended seed shape.
+
 ## Gotchas
 
 - **The single-meta envelope can hide the real bundle behind a DECOY `elements: []`.** The V2 envelope
@@ -222,6 +287,14 @@ seeding NYCHH/Prudential/SPGlobal is deferred; the Client-DB prod cross-cluster
   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`.
+- **`cleanOrder.ts` flattens notes by the WRONG note-type slugs (latent blank-notes bug).**
+  `cleanOrder` builds the legacy flat `order.reasonForRequest` / `order.shippingInstructions` via
+  `getNoteBySlug(notes, "reasonForRequest")` / `("shippingInstructions")`, but the API's actual
+  `salesOrderNoteType.slug` values are **`request`** / **`shipping`**. So for any client whose notes
+  use the real slugs (e.g. Compass) those flat fields resolve to `""` and the legacy notes render
+  blank. The new field-driven notes path resolves by the element's `config.noteTypeSlug` (the correct
+  slug) so it is unaffected; the flat path only survives as the non-migrated-client fallback in
+  `SalesOrderNotesSection`. Fixing `cleanOrder`'s slugs is the durable follow-up for JSON clients.
 - **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
@@ -258,6 +331,30 @@ 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-07-20 — Migrated the **item-record modal VIEW** onto Surface for **ALL clients (no roster)** via
+  the adapter seam: new `surfaceBundleToItemViewFields()` adapts the `item-record-*` surface group
+  (`useFetchSurfaceMetaGroup`) into the existing `{header, editItem, sections, vendorItemsEnabled}`
+  shape, threaded into `ItemRecordView` as a `viewFields` prop with the per-client JSON
+  (`itemRecordViewFields`) as resolve-failure fallback only; edit mode stays JSON-driven (deferred).
+  Added `trueLabel`/`falseLabel` to `SurfaceElementMessages` (`src/surface/types.ts`) so BOOLEAN
+  toggles/badges render their caption (backend resolver now emits them). Per-client gating uses the
+  Core-default-OFF → SurfaceOverride opt-in pattern: header Edit button (`item-record-header`, matched
+  by `renderType='BUTTON'`+`config.kind='itemEdit'`) and a dedicated `item-record-vendor-items` toggle
+  surface (marker `config.role='sectionVisibility'` → FE `vendorItemsEnabled`), both opted into by
+  Compass / Compass Canada. Flagged: Core Pricing seed now also shows `leasePrice` for all clients
+  (verify seed intent). (apeterson)
+- 2026-07-20 — Made the SalesOrders `notes` display section **field-driven** per client.
+  `buildSection`'s `displayToggle` branch now handles field-carrying sections: it maps each `FIELD`
+  element to a field config (`elementToFieldConfig` now carries `config.noteTypeSlug`) and **derives**
+  section visibility as "≥1 field visible" — no `sectionVisibility` marker needed (pure-toggle sections
+  invoices/shipments/additional-order-details/admin-notes still fall back to their marker element).
+  `SalesOrderNotesSection` renders only the visible note slots and resolves each value from
+  `order.salesOrderNotes[].note` by `salesOrderNoteType.slug === config.noteTypeSlug`, with a legacy
+  flat-prop fallback for non-migrated JSON clients. Recorded the reusable field-driven-display-section
+  pattern (third section pattern, alongside card sections and marker toggles). Discovered a latent
+  blank-notes bug in `cleanOrder.ts` (flattens by the wrong slugs
+  `reasonForRequest`/`shippingInstructions` vs the API's actual `request`/`shipping`) — the surface
+  resolver reads by the correct slug and bypasses it. (apeterson)
 - 2026-07-13 — Fixed two SalesOrders row-actions bugs: (1) the portal dismiss overlay in
   `SurfaceRowActions.tsx` propagated an outside-click up the React component tree to the row handler
   and opened the record modal — added `e.stopPropagation()` (+ close) on the overlay `onClick`;

package/package.json

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