toga-ai 1.0.385 → 1.0.386

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

@@ -19,7 +19,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 - **_underscore** (_Underscore) _(framework core)_ — 35 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.386",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",