toga-ai 1.0.385 → 1.0.387

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

@@ -24,6 +24,7 @@
 | [Per-Client Database Connections & the Local Logs Trap](features/per-client-database-connections.md) | When `_underscore` serves a request for a client it opens **three distinct per-client database connections**, not one. | _underscore/Database.php, _underscore/ApiRequest.php, _underscore/Model/Client/Logs/Api.php |
 | [Recursive Item Fulfillments (upstream mirroring)](features/recursive-item-fulfillments.md) | In a multi-tier supply chain a sales order (SO) spawns a purchase order (PO) that becomes another SO downstream, and so on. | _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Client/ItemFulfillmentItem.php, _underscore/Model/Client/ItemFulfillmentItemUnit.php, _underscore/Model/Client/ItemFulfillmentPackage.php, _underscore/Model/Compass/AdvanceShippingNotice.php, dbchanges2/Core/2026-02-13 - 75601 - RecursiveItemFulfillmentCreation.sql, dbchanges2/Core/2026-06-04 - RecursiveItemFulfillmentPut.sql, dbchanges2/Client_Compass/2026-07-02a - FixSA133377TrackingSerialAndDuplicateIF.sql |
 | [Surface Resolver (_Model_Core_Surface::resolve — replaces Page::meta)](features/surface-resolver.md) | The runtime for the platform-wide **Surface** UI presentation layer: 9 `_underscore` models plus a cached resolver, `_Model_Core_Surface::resolve(&$api, string | _underscore/Model/Core/Surface.php, _underscore/Model/Client/AclRecordScript.php, _underscore/Model/Core/RecordScript.php, dbchanges2/Core/2026-06-30a - SurfaceMetaGroupAndSalesOrderSections.sql, dbchanges2/Client/2026-06-30a - SurfaceMetaGroupAcl.sql, dbchanges2/Client_Quad/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Client_CompassCanada/2026-07-01a - GrantSurfacesMetaGroupScriptAcl.sql, dbchanges2/Core/2026-06-29b - SurfaceMetaPublicReadAcl.sql, dbchanges2/Client/2026-06-29c - SurfaceRecordScriptAcl.sql, dbchanges2/Core/2026-06-29c - SurfaceDebugPhpMethodFix.sql, dbchanges2/Client_Compass/2026-07-15f - SalesOrderRecordActionsRemoveDeadConfigRuleOverrides.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, _underscore/Model/Core/SurfaceElement.php, _underscore/Model/Core/Action.php, _underscore/Model/Core/Vocabulary.php, _underscore/Model/Core/VocabularyTerm.php, _underscore/Model/Core/Message.php, _underscore/Model/Client/SurfaceOverride.php, _underscore/Model/Client/MessageTranslation.php, _underscore/Model/Client/ThemeToken.php, _underscore/Model/Core/Page.php |
+| [Table-View Hyperlink Columns (meta → ACL → computed URL → render)](features/tableview-hyperlink-columns.md) | Any 2.0 table-view column can render its value as a clickable link instead of plain text. | _underscore/Model/Client/TableView.php, _underscore/Model/Client/TrackingNumber.php, api2/Component/Api/V2/V2.php, toga2-supply/src/api/toga.ts, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/formatTableData.tsx, toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/convertData.tsx, toga2-supply/src/components/ui/Tables/hooks/useDataTableState.tsx, dbchanges2/Client/2026-07-20 - TrackingNumberHyperlinkAndFieldPermission.sql |
 | [Tracking-Number Bridge Migration (ASN / Item Fulfillment / Item Receipt)](features/tracking-number-bridges.md) | Shipment tracking numbers used to live as **scalar FK columns** (`trackingNumberId`, `returnTrackingNumberId`) directly on the lowest-level "unit"/"item" tables | api2/Component/Api/V2/V2.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnit.php, _underscore/Model/Client/AdvanceShippingNoticeItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillmentItemUnits/TrackingNumber.php, _underscore/Model/Client/ItemFulfillment.php, _underscore/Model/Prudential/AdvanceShippingNotice.php, _underscore/Model/Compass/AdvanceShippingNotice.php, _underscore/Trait/Netsuite/ItemFulfillment.php, api2/Component/Api/Cxml/Cxml.php, dbchanges2/Client/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Core/2026-06-10 - TrackingNumberBridges.sql, dbchanges2/Client_Prudential/2026-06-15 - ItemFulfillmentTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Quad/2026-06-18a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19b - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Growrk/2026-07-13a - ItemFulfillmentItemReceiptTrackingNumberAclLogicGroups.sql, dbchanges2/Client_Nychh/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql, dbchanges2/Client_Quad/2026-06-19a - FixItemFulfillmentTableViewTrackingAndRoot.sql |
 | [Units for Items for Purchase Orders — Data Structure](features/units-for-items-for-purchase-orders.md) | Describes how unit (serialized inventory) data is linked to sales-order and purchase-order line items behind the `units-for-items-for-purchase-orders` TableView |  |
 | [Refreshing a Local Dev Database from Beta (dev-sandbox)](workflows/local-db-refresh-from-beta.md) | How to reset a local 2.0 dev database from the **beta / dev-sandbox** environment: dump each schema (`Core`, `Client_<Id>`, `Logs_<Id>`, …) from the beta host, | api2/Config/, _underscore/Loader.php, _underscore/Model/Client/BundleTranslation.php, api2/Component/Api/V2/V2.php, toga25-supply/sync_compasscanada_schema.sql |

package/knowledge/2.0/apps/_underscore/features/tableview-hyperlink-columns.md

@@ -0,0 +1,120 @@
+---
+title: Table-View Hyperlink Columns (meta → ACL → computed URL → render)
+framework: "2.0"
+repo: _underscore
+project: _Underscore
+client: shared
+type: feature
+status: active
+updated: 2026-07-20
+owners: ["bala"]
+files:
+  - _underscore/Model/Client/TableView.php
+  - _underscore/Model/Client/TrackingNumber.php
+  - api2/Component/Api/V2/V2.php
+  - toga2-supply/src/api/toga.ts
+  - toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/formatTableData.tsx
+  - toga2-supply/src/components/ui/Tables/PrimaryTable/helperFunctions/convertData.tsx
+  - toga2-supply/src/components/ui/Tables/hooks/useDataTableState.tsx
+  - dbchanges2/Client/2026-07-20 - TrackingNumberHyperlinkAndFieldPermission.sql
+related:
+  - ./acl-permission-chain.md
+  - ../../api2/features/tableview-apiwhereclause-row-filtering.md
+  - ../../api2/features/surface-meta-option.md
+  - ../../toga2-supply/architecture.md
+---
+
+## Summary
+
+Any 2.0 table-view column can render its value as a clickable link instead of plain text.
+The link URL comes from a **second** RecordField (`TableViewFields.hyperlinkRecordFieldId`)
+whose value is a URL — typically a computed `FIELD_SQL` field. The pipeline is
+platform-wide (all clients + the `BLANK_CLIENT_DATABASE` template), driven cross-repo:
+`_underscore` emits a `hyperlinkField` in the view meta **only if the caller's role has ACL
+field-read on the hyperlink field**, and `toga2-supply`'s shared `PrimaryTable` renders it.
+The single most common failure is the silent one — the meta drops `hyperlinkField` (and the
+column renders as plain text) when the ACL field-read grant is missing, not when anything is
+"broken."
+
+## How it works (end to end)
+
+1. **Config** — `TableViewFields.hyperlinkRecordFieldId` on a column points at the Core
+   RecordField whose value is the URL. `NULL` = no hyperlink (plain text).
+2. **Meta emission** — `_Model_Client_TableView::meta()` (`_underscore/Model/Client/TableView.php`)
+   emits `hyperlinkField` for a column **only when** the caller's role appears in
+   `$permittedRecordFields` for that `hyperlinkRecordFieldId` (~line 290). No field-read
+   permission → the value is silently nulled out and the column falls back to plain text.
+3. **ACL source** — field-read permissions live in **each CLIENT DB's `AclFieldPermissions`**
+   (the `TrackingNumbers` record's `aclDatabase` is CLIENT), keyed by
+   `(recordFieldId, roleId)`. `api2/Component/Api/V2/V2.php::getAclFieldPermissions()` loads
+   them. See [ACL Permission Chain](./acl-permission-chain.md) for the full field-vs-record
+   authorization model.
+4. **Frontend request** — `toga2-supply/src/api/toga.ts` adds `hyperlinkField` to the data
+   request and stores the resolved URL on the row as `` data[`${slug}_hyperlink`] ``.
+5. **Frontend render** — the shared `PrimaryTable` draws the link (see below).
+
+## Computed URL: `TrackingNumbers._hyperlink`
+
+- `_Model_Client_TrackingNumber::_hyperlink()` is a `FIELD_SQL` computed field:
+  `CONCAT(ShippingCarriers.urlLinkPrefix, TrackingNumbers.number)`.
+- It is **`NULL` when the carrier has no `urlLinkPrefix`**, so a tracking number for a carrier
+  without a link prefix gracefully renders as plain text rather than a dead link.
+
+## Shared Core ids (identical across every environment)
+
+- **RecordField 339** = `TrackingNumbers.number`
+- **RecordField 1272** = `TrackingNumbers._hyperlink`
+- Core RecordField ids are shared/identical across environments, so migrations key off them
+  directly (no per-tenant id lookup).
+- **Role ids**: only `1` (Base), `2` (Developer), `3` (API) are identical across every client;
+  ids `>= 4` diverge per client. **Base (1) is the universal role** that carries the
+  tracking-number read grant in every client — which is why the ACL grant targets Base.
+
+## Frontend render (toga2-supply PrimaryTable)
+
+- `convertData.tsx` — `generateDynamicConfig` sets `hasHyperlink: Boolean(item.hyperlinkField)`;
+  `ColumnConfig` gained `hasHyperlink?: boolean`.
+- `useDataTableState.tsx` — `TableFieldValues` gained optional `hyperlinkField?: string`.
+- `formatTableData.tsx` — a cell branch renders the value as
+  `<a target="_blank" rel="noopener noreferrer" ...>` (Tailwind `text-supply-blue-500 underline`)
+  wrapped in the same `flex/items-center` container as base cells for alignment; falls back to
+  plain text otherwise. The branch:
+  - runs **before** the `hasSuffix` branch (so hyperlink columns link even at a suffix index),
+  - is guarded by `rawConfig.isVisible !== false` (invisible columns are skipped),
+  - restricts `href` to `http(s)` URLs only (`/^https?:\/\//i`) as defense-in-depth,
+  - **takes precedence over the copy-button branch** — the tracking column now links instead of
+    offering copy-to-clipboard.
+
+## The ACL migration that unblocks it
+
+`dbchanges2/Client/2026-07-20 - TrackingNumberHyperlinkAndFieldPermission.sql` (in `Client/`,
+so it runs against every client DB + the BLANK template), keyed off shared Core RecordField ids:
+
+1. `UPDATE TableViewFields SET hyperlinkRecordFieldId = 1272 WHERE recordFieldId = 339 AND
+   hyperlinkRecordFieldId IS NULL`, scoped to the two views `item-fulfillments-for-sales-orders`
+   and `item-fulfillments-for-sales-order-items`.
+2. `INSERT INTO AclFieldPermissions` granting READ on `1272` to the Base role (`roleId 1`),
+   `isWritable 0`, via `FROM DUAL` + `NOT EXISTS` (idempotent).
+
+The `TableViewFields` link alone is **not** enough — without the Base `AclFieldPermissions`
+grant the meta silently omits `hyperlinkField` and the tracking column stays plain text. That
+missing grant was the actual blocker.
+
+## Key rules / gotchas
+
+- A missing `AclFieldPermissions` read grant on the hyperlink RecordField makes the meta drop
+  `hyperlinkField` **silently** — the column just renders as plain text, with no error. Check the
+  ACL grant first when a configured hyperlink column isn't linking.
+- Hyperlink resolution needs a URL-valued field; if the computed field is `NULL` (e.g. carrier
+  with no `urlLinkPrefix`) the cell correctly falls back to plain text.
+- Grant to Base (roleId 1), not a per-client role id — Base is the only universally-present role
+  that holds the read grant across all tenants.
+
+## Change history
+- 2026-07-20 — Added the missing `PrimaryTable` render path so table-view columns with a
+  `hyperlinkField` draw as `<a>` links (previously rendered plain text / copy button); hardened
+  for branch precedence, column visibility, and `http(s)`-only `href`. Added the cross-client
+  migration linking `TrackingNumbers.number` → `_hyperlink` and granting Base ACL read on
+  `_hyperlink` (1272), which was the real blocker. Documented the end-to-end meta → ACL →
+  computed-URL → render mechanism and the shared Core RecordField / role ids. Driven by Compass
+  USA (tracking numbers as clickable carrier links); the mechanism is platform-wide. (bala)

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

@@ -10,6 +10,7 @@
 | [POST + JSON-body args for scripted APIs](features/scripted-api-post-body-args.md) | The V2 engine can run a Record Script (scripted API) for a **POST** request, and a scripted API can receive its arguments from the **JSON request body** instead | api2/Component/Api/V2/V2.php |
 | [Surface action-state via the surface=<slug> request option (M2M-safe)](features/surface-meta-option.md) | An opt-in V2 engine request option, `surface=<slug>`, that attaches per-record UI action state (`isVisible`/`isEnabled`) to a GET response **under `meta.surface | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Surface.php |
 | [TableView row-filtering via apiWhereClause (options.where grammar, end to end)](features/tableview-apiwhereclause-row-filtering.md) | `TableViews.apiWhereClause` (TEXT, nullable) is the sanctioned, code-free way to restrict or exclude rows from a 2.0 table view. | api2/Component/Api/V2/V2.php, _underscore/Model/Client/TableView.php, toga2-supply/src/api/toga.ts |
+| [TableView field/column metadata (TableViewFields, hidden projected columns)](features/tableview-field-metadata.md) | The columns of a 2.0 table view are defined by DB metadata, not code. | _underscore/Model/Client/TableView.php, api2/Component/Api/V2/V2.php, dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql |
 | [Tickets API (/v2/tickets)](features/tickets-api.md) | The generic ticket endpoint of the 2.0 REST API. | Component/Api/V2/V2.php |
 | [V2 API error/message codes (EV/EZ troubleshooting map)](features/v2-api-error-codes.md) | The V2 JSON engine (`Component/Api/V2/V2.php`) returns short **message codes** in the response `error` field, grouped by family: `EN-*` authentication, `EZ-*` a | api2/Component/Api/V2/V2.php |
 | [AWS CodePipeline Deployment via CodeConnections (GitHub → Elastic Beanstalk)](workflows/codepipeline-codeconnections-deploy.md) | 2.0 apps (`api2`, `_underscore`) are deployed through **AWS CodePipeline**. |  |

package/knowledge/2.0/apps/api2/features/tableview-apiwhereclause-row-filtering.md

@@ -14,6 +14,7 @@ files:
   - toga2-supply/src/api/toga.ts
 related:
   - ../../../clients/compass-usa/features/item-fulfillment-tracking-tableview.md
+  - tableview-field-metadata.md
 ---
 
 ## Summary

package/knowledge/2.0/apps/api2/features/tableview-field-metadata.md

@@ -0,0 +1,97 @@
+---
+title: TableView field/column metadata (TableViewFields, hidden projected columns)
+framework: "2.0"
+repo: api2
+project: API
+client: shared
+type: feature
+status: active
+updated: 2026-07-20
+owners: [apeterson]
+files:
+  - _underscore/Model/Client/TableView.php
+  - api2/Component/Api/V2/V2.php
+  - dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql
+related:
+  - tableview-apiwhereclause-row-filtering.md
+  - ../../toga25-supply/features/meta-driven-table-data.md
+---
+
+## Summary
+
+The columns of a 2.0 table view are defined by DB metadata, not code. Per-client tables
+`Client_*.TableViews` / `TableViewFields` / `TableViewJoins` declare the view, its columns, and its
+joins; the frontend consumes the emitted meta (see
+[meta-driven-table-data](../../toga25-supply/features/meta-driven-table-data.md)). Adding or altering
+a column is a **dbchanges2 migration**, not a code change. A `TableViewFields` row with
+`isVisible=0` is still fetched into the row projection but renders **no column** — the sanctioned way
+to make a field available to frontend logic (e.g. a resolver that needs an fk uuid) without showing
+it.
+
+## Data model
+
+- **`Client_*.TableViews`** — one row per view (per client DB, e.g. `Client_Nychh`).
+- **`Client_*.TableViewFields`** — one row per **column** of a view. Key columns: `recordFieldId`
+  (which field this column shows), `tableViewJoinId` (which join in the view the field is reached
+  through), `slug` (the frontend/tanstack column id), `isVisible` (0 = projected-but-hidden).
+- **`Client_*.TableViewJoins`** — the view's joins; also drive `options.join`/`ojoin` on the data
+  request (see [tableview-apiwhereclause-row-filtering](tableview-apiwhereclause-row-filtering.md)).
+
+### `recordFieldId` is a cross-DB reference into shared `Core.RecordFields`
+
+`TableViewFields.recordFieldId` does **not** point within the client DB — it references the
+**shared** `Core.RecordFields` table. In `Core`:
+
+- `Core.RecordFields.field` — the field-name column (the actual column/attribute name).
+- `Core.RecordFields.recordId` → `Core.Records` — the owning record/model.
+
+Reference ids observed for the `Items` record: **`Core.Records` id 21 = Items**, and
+**`Core.RecordFields` id 106 = `Items.uuid`**. (Look these up per field before writing a migration —
+do not assume ids across environments.)
+
+## Hidden (projected-but-not-rendered) columns
+
+A `TableViewFields` row with `isVisible=0` is still selected into the row's data projection but
+produces no rendered column (on the frontend, `buildTanstackColumns` filters by `isVisible`). This is
+the mechanism behind fields the UI needs but should not display — the existing hidden
+`inventorytype` / `Items.inventoryType` field on the inventory views is the precedent.
+
+Use case that drove this doc: the `items-for-purchase-orders` view's rows are sales-order **lines**,
+so `row.uuid` = `SalesOrderItems.uuid`. Opening the item-record modal needs the **catalog**
+`Items.uuid`. Adding a hidden `Items.uuid` column puts `row.Items.uuid` into the projection so the
+frontend `getModalUuid` resolver can open the catalog item (see
+[record-modals-and-nested-tables](../../toga25-supply/features/record-modals-and-nested-tables.md)).
+
+## How to add a hidden projected column (migration recipe)
+
+1. Find the `Core.RecordFields.id` for the field (join `Core.Records` on `recordId`, match on
+   `field`). e.g. `Items.uuid` → 106.
+2. Resolve `tableViewJoinId` — reuse the join through which the field is reached. For an already
+   joined table, resolve it from an existing `TableViewFields` row that joins the same table (the
+   hidden `inventorytype` Items-join field was the source in the reference migration).
+3. `INSERT INTO TableViewFields (recordFieldId, tableViewJoinId, slug, isVisible, …)` with
+   `isVisible=0` and a distinct `slug` (e.g. `itemUuid`). Make it **idempotent** with a
+   `WHERE NOT EXISTS (...)` guard so a re-run is a no-op.
+
+Cross-client field/column migrations live in **dbchanges2's `Client/` template folder**, not a
+per-client folder — the reference migration
+`dbchanges2/Client/2026-07-20 - ItemsUuidForPurchaseOrderItemsTableView.sql` adds the hidden
+`Items.uuid` column to the `items-for-purchase-orders` view and was verified against `Client_Nychh`.
+
+## Gotchas / known issues
+
+- **`recordFieldId` is cross-DB** — it indexes `Core.RecordFields`, not anything in the client DB.
+  Resolve the id in `Core`, but insert the `TableViewFields` row in the client DB.
+- **Don't assume `Core.RecordFields`/`Core.Records` ids are stable across environments** — look them
+  up by `field` name + record.
+- **Make column migrations idempotent** (`NOT EXISTS` guard) — they run per client DB.
+- **`isVisible=0` still costs a fetch** — the field is selected into the projection; only the render
+  is suppressed.
+
+## Change history
+
+- 2026-07-20 — Documented the backend TableView column-metadata model (per-client
+  `TableViews`/`TableViewFields`/`TableViewJoins`, `recordFieldId` → shared `Core.RecordFields`
+  cross-DB ref, `isVisible=0` projected-but-hidden columns) and the dbchanges2 recipe for adding a
+  hidden projected column, discovered while making the Inventory item-record modal open the catalog
+  `Items.uuid`. (apeterson)

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

@@ -8,7 +8,7 @@
 | [Client-Configurable Fields (useClientFields / fieldsConfig)](features/client-configurable-fields.md) | The mechanism for config that **varies by client** (or client × role) — field overrides, filter buttons, group-by options, column pickers, layout toggles — with | toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/README.md, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/layout/VendorItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/ |
 | [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 |
+| [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/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/record-modals-and-nested-tables.md

@@ -6,18 +6,23 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-06-23
+updated: 2026-07-20
 owners: [apeterson]
 files:
   - 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/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
 related:
   - ../architecture.md
   - meta-driven-table-data.md
+  - ../../api2/features/tableview-field-metadata.md
 ---
 
 ## What it is
@@ -107,6 +112,29 @@ A page-level `pageMeta` (from `useFetchPageMeta`) flows down for field-label ove
 view model builds `TableLevel[]` arrays, picks the active one via a URL param, and passes `levels`
 to `GenericNestedTables` with `key={activeGrouping.key}` to force remount and avoid stale state.
 
+### Decoupling "drill to child tier" from "open this record" on a swap level
+
+By default a `"swap"` level consumes the **whole-row click** (`getRowHref`) to drill to the next
+tier, which leaves no room for a per-row record modal. Two optional `TableLevel` hooks split the two
+interactions so both are reachable on one nested row (Inventory `items-for-purchase-orders` /
+`purchase-orders_items` levels are the reference):
+
+- **`buildSwapTriggerColumns(triggerSwap)`** — when present, the level renders a dedicated
+  first-column action button (Inventory's "See units": a `chevronsRight` icon wrapped in a toga-blox
+  `BaseToolTip`) whose click calls `triggerSwap`; the whole-row swap (`getRowHref`) is **disabled**
+  and inline child expansion is **suppressed while nested**, so a plain row click is free to open
+  `renderModal`. Net UX: chevron → child tier; row click → record modal. The Inventory hydrator
+  (`hydrateLevel`, role `"swap"`) wires `buildSwapTriggerColumns: makeSeeUnitsColumns` and
+  `renderModal` from the level's `modalKey`.
+- **`getModalUuid(row)`** — override which uuid the record modal opens for a row. `GenericTableLayout`
+  wraps `handleRowClick` to store `getModalUuid(row) ?? row.uuid` as the active/modal uuid. Needed
+  when the row's own `row.uuid` is not the uuid the target record endpoint expects — e.g. the
+  `items-for-purchase-orders` rows are sales-order **lines** (`row.uuid` = `SalesOrderItems.uuid`),
+  but the item-record modal must open the **catalog** item, so the hydrator sets
+  `getModalUuid: (row) => row?.Items?.uuid`. That requires the catalog uuid to be present in the row
+  projection: a **hidden (`isVisible=0`) `Items.uuid` column** is added to the table view — see
+  [tableview-field-metadata](../../api2/features/tableview-field-metadata.md).
+
 ## Pattern 6 — Create/edit record modal (form-driven)
 
 Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLayout/`). Form-driven
@@ -136,6 +164,15 @@ Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLay
 - **Submit payload diverges from form shape** — send relation `.uuid`, not the `{uuid,name}` object;
   confirm field names against the real POST/PUT contract.
 - **Nested tables need their own slug + URL-state isolation** or sibling tables clobber each other.
+- **A swap level's `urlParamKey` must NOT equal (or be a `${slug}_`-prefixed variant of) any level's
+  slug.** The record-modal / active-row state is stored in a URL param named **exactly** the table
+  slug (`src/hooks/useServerTableUrlState.ts`: `activeRowUuid = searchParams.get(slug)`, and
+  `handleRowClick` sets `?<slug>=<uuid>`). If a swap level's `urlParamKey` is the same string as a
+  level's fetchSlug/slug, a plain row click writes `?<slug>=<uuid>` which `GenericNestedTables` reads
+  as "swap active" and jumps to the child tier instead of opening the modal. Fix: give swap keys a
+  `swap-` **prefix** (`items-for-purchase-orders` → `swap-items-for-purchase-orders`). A `${slug}_…`
+  **suffix** can't be used because `useServerTableUrlState`'s columnFilters parser treats any
+  `${slug}_*` key as a column filter — hence a prefix.
 - **`additionalData` in the query key is mandatory** for WHERE-filtered modal tables (Pattern 4).
 - **Per-consumer cache `scope`** — two consumers fetching the same record with different field
   configs must use a `scope` discriminator in the query key or they overwrite each other's cache
@@ -154,6 +191,12 @@ Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLay
   `/approval-decisions/{uuid}`.
 
 ## Change history
+- 2026-07-20 — Pattern 5: added `buildSwapTriggerColumns(triggerSwap)` and `getModalUuid(row)` to
+  `TableLevel` so a swap level's "drill to child tier" (a dedicated "See units" chevron) and
+  "open this record" (plain row click → `renderModal`) are decoupled, and a record modal can open a
+  different uuid than `row.uuid` (Inventory line rows open the catalog `Items.uuid`). Fixed a URL-param
+  collision — swap `urlParamKey` equal to a level slug hijacked the row-click into a swap; swap keys now
+  carry a `swap-` prefix — and documented the rule. (apeterson)
 - 2026-06-30 — Recorded two behaviors confirmed while building approval-modal tests: `poNumber`
   is handled by a separate `EnterPoNumberModal` (excluded from the approval layout), and the
   workflow vs single-decision submit payloads differ (string `"1"`/`"0"` + changed-stages-only +

package/knowledge/INDEX.md

@@ -17,9 +17,9 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 35 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 36 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 31 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
-- **api2** (API) — 12 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
+- **api2** (API) — 13 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
 - **toga2-supply** (TOGa Supply) — 3 doc(s) → [2.0/apps/toga2-supply/INDEX.md](2.0/apps/toga2-supply/INDEX.md)
 - **saml** (SAML SSO Gateway) — 3 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)

package/package.json

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