toga-ai 1.0.162 → 1.0.164

package/knowledge/1.0/apps/library/INDEX.md

@@ -9,3 +9,4 @@
 | [NetSuite SuiteQL/REST API Reference](features/netsuite-suiteql-api-reference.md) | General working reference for the Agilant NetSuite integration: how to authenticate, how SuiteQL behaves, and the confirmed schema of the tables/columns/codes w | library/app/api/netsuite/rest.php, library/ssl/netsuite_ec_key.pem |
 | [NetSuite SuiteQL/REST Shim — Field Semantics](features/netsuite-suiteql-rest-shim.md) | `App_Api_Netsuite_Rest` is the REST/SuiteQL replacement for the deprecated NetSuite SOAP toolkit. | library/app/api/netsuite/rest.php |
 | [Startech PC Matic B2B Sync (library)](features/startech-pcmaticb2b-sync.md) | `library/app/api/toga2.php` handles bidirectional ticket sync for PC Matic B2B between TOGaDesk 1.0 and TOGA 2.0. | library/app/api/toga2.php |
+| [App_Api_Toga2 — TOGa2 API Client & 1.0↔2.0 Sync Bridge](features/toga2-api-client-and-bridge.md) | `App_Api_Toga2` (`library/app/api/toga2.php`, ~8400 lines) is the **1.0-side client for the TOGa 2 (`_underscore`/api2) public API** *and* the home of the cross | library/app/api/toga2.php, worker/crons/toga2/aig/sync_togasupply_aig.php, worker/crons/toga2/wje/sync_togasupply_wje.php |

package/knowledge/1.0/apps/library/features/toga2-api-client-and-bridge.md

@@ -0,0 +1,173 @@
+---
+title: App_Api_Toga2 — TOGa2 API Client & 1.0↔2.0 Sync Bridge
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [jcardinal]
+files:
+  - library/app/api/toga2.php
+  - worker/crons/toga2/aig/sync_togasupply_aig.php
+  - worker/crons/toga2/wje/sync_togasupply_wje.php
+related:
+  - netsuite-suiteql-api-reference.md
+  - netsuite-suiteql-rest-shim.md
+  - ../../worker/features/netsuite-togasupply-per-client-sync.md
+  - ../architecture.md
+---
+
+## Summary
+
+`App_Api_Toga2` (`library/app/api/toga2.php`, ~8400 lines) is the **1.0-side client for the
+TOGa 2 (`_underscore`/api2) public API** *and* the home of the cross-framework sync routines
+that move data between the legacy 1.0 stack (TOGa, TOGaDesk) and 2.0 (TOGa Supply, TOGa Desk
+2.0). It plays two roles:
+
+1. **Transport** — `send()`/`authenticate()`/`sendUsingAccessToken()` plus an options DSL
+   (`fields`/`where`/`join`/`sort`) that lets 1.0 worker crons call the 2.0 REST API. This is
+   the same transport the NetSuite→TOGa Supply importer uses (see the per-client-sync doc).
+2. **Bridge sync routines** — `syncWithToga()` (2.0 → 1.0 TOGa) and `syncWithTogadesk()` (2.0 ⇄
+   1.0 TOGaDesk), invoked by thin per-client crons under `worker/crons/toga2/<client>/`.
+
+The `*FromNetsuite()` methods (`syncSalesOrderFromNetsuite`, etc.) also live in this class but
+belong to the NetSuite importer — documented in the per-client-sync doc, not here.
+
+## Key files / entry points
+
+- **`library/app/api/toga2.php`**
+  - **Transport:** `authenticate($uuidClient,$uuidApi,$apiSecret,$endpoint=null)`,
+    `send($uuidClient,$uuidApi,$apiSecret,$method,$route,$payload,$options=[],$throwOnError=true,$endpointOverride=null)`,
+    `sendUsingAccessToken(...)`, `authenticateUser(...)`.
+  - **Options DSL builders:** `assembleOptions`, `assembleOptionsFields`, `assembleOptionsWhere`,
+    `assembleOptionsJoin`, `assembleOptionsSort`.
+  - **Bridge 2.0→1.0:** `syncWithToga(...)` → `syncContactToToga1Customer`,
+    `syncEntitlementToToga1ServiceRequest`.
+  - **Bridge 2.0⇄1.0 TOGaDesk:** `syncWithTogadesk(...)` + its many sub-syncs
+    (`syncToga2TicketIntoTogadesk1{RepairOrder,Ticket}`, `syncTogaDesk1{RepairOrder,Ticket}IntoToga2Ticket`,
+    `syncToga2ContactIntoTogadesk1People`, `syncToga2ItemUnitIntoTogadesk1Asset`,
+    `syncToga2PredefinedReplyToTogadesk1TicketsPr`, `syncToga2TicketTeamsIntoTogadesk1Groups`,
+    `syncToga2TicketCategoryIntoTogadesk1CategorySubcategoryItem`, `sendTicketNotifications`).
+- **Per-client invokers** (worker, one folder per client, distinct from the `netsuite/` supply
+  wrappers): e.g. `worker/crons/toga2/aig/sync_togasupply_aig.php` (calls `syncWithToga` +
+  `syncWithTogadesk` for tickets), `worker/crons/toga2/wje/sync_togasupply_wje.php`
+  (TOGaDesk-only, all sub-syncs on). These run on tight schedules (AIG every 10 min, WJE every
+  2 min) under the standard worker boilerplate.
+
+## How it works
+
+### Transport (`authenticate` + `send`)
+
+- **Endpoint** comes from `App_Registry::get('config')['api']['_']` unless an override is passed
+  as the last arg (the bridge passes `self::$toga2ApiEndpoint`).
+- **Auth** posts `{client,api,secret}` to `/auth/api` and caches the returned `{access,refresh}`
+  in a static `self::$_tokens[$uuidApi]`. An expired access token is refreshed via `/auth/refresh`
+  with the refresh token. Both auth paths retry up to **10×** (1s sleep) before throwing.
+- **`send()`** authenticates, calls `sendUsingAccessToken()`, and on an **`EN-4`** message
+  (expired token) clears the cached access token and retries once. Connect/read timeouts are
+  generous (300s/900s) because list endpoints can be slow. A `usleep(200000)` throttle precedes
+  every call to be gentle on the API. Non-success responses throw unless `$throwOnError=false`.
+- Returns the decoded response object; callers read `->data->{resource}`, `->meta->nextPage`,
+  `->isSuccess`, `->status`, `->messages[].code`.
+
+### Options DSL (how 1.0 expresses 2.0 queries)
+
+`$options` is an assoc array assembled into the 2.0 query string:
+- `fields` — nested arrays become dotted paths (`['primaryContactAddress'=>['address'=>['line1']]]`
+  → `primaryContactAddress.address.line1`); spaces become `+`.
+- `where` — `['and'=>[['_updated'=>['>'=>$dt]]]]` compiles to `(_updated:gt:<urlenc>)`; operators
+  map (`>`→`gt`, `=`→`eq`, `in`/`notin` join with `:`); nestable `and`/`or` groups with parens.
+- `join`/`ojoin` — `[['LocationTypes'=>['LocationTypes.id'=>'Locations.locationTypeId']]]`.
+- `page`/`recordsPerPage`/`depth`/`calcDepth`/`key` pass through. Pagination is the universal
+  `for ($page=1,$nextPage=0; !is_null($nextPage); ++$page)` loop reading `meta->nextPage`.
+
+### `syncWithToga()` — 2.0 → 1.0 (TOGa)
+
+Signature: `(int $togaClientId, string $clientUuid, string $apiKey, string $apiSecret,
+bool $enabled2to1, bool $enabled1to2)`. When `enabled2to1`:
+- Pages 2.0 **`/contacts`** (for AIG, only those with `c_togaCustomerId IS NULL`) and upserts each
+  into the 1.0 client DB `Customers`/`Addresses` via `syncContactToToga1Customer`, then **writes
+  the new 1.0 id back** to the 2.0 contact's `c_togaCustomerId` (PUT `/contacts/{uuid}`).
+- Pages 2.0 **`/entitlements`** without a `c_togaServiceRequestId` and inserts 1.0
+  `ServiceRequests` (+ a `Contacts` row if needed) via `syncEntitlementToToga1ServiceRequest`.
+- The 1→2 direction (`enabled1to2`) is a stub (not yet implemented).
+- DB target is selected with `App_Model_Client::changeDbLinkToClientDatabase(getClientDatabaseNames()[$togaClientId])`.
+
+### `syncWithTogadesk()` — 2.0 ⇄ 1.0 (TOGaDesk)
+
+A large bi-directional sync gated by **two checkpoint parameters** stored in 2.0 via
+`/parameters`: `TOGADESK_LAST_TICKET_INTEGRATION_DATETIME` (newest 2.0 ticket pulled into 1.0)
+and `TOGA_LAST_TICKET_INTEGRATION_DATETIME` (newest 1.0 ticket pushed into 2.0). Each direction
+filters on records changed after its checkpoint, then advances it to the newest record seen.
+
+Signature takes `$integrationType` (`TICKETS` or `REPAIR_ORDERS`) plus **seven independent
+enable flags** and an optional `$monitorTogadeskDepartmentIds[]`:
+- **2.0 → TOGaDesk** (`$isEnabledToga2ToTogadeskIntegration`): pages 2.0 `/tickets` and
+  `/ticket-notes` changed since the checkpoint; routes each to
+  `syncToga2TicketIntoTogadesk1{RepairOrder|Ticket}` by `$integrationType`. Per-ticket exceptions
+  are caught and sent to Sentry so one bad ticket doesn't abort the batch.
+- **TOGaDesk → 2.0** (`$isEnabledTogadeskToToga2Integration`): queries the 1.0 `db_togadesk` DB
+  directly (SQL over `repair_orders`/`repair_order_history` or `tickets`/`tickets_replies`/`comments`,
+  using `GREATEST(...)` of reply/comment timestamps) for the client's department(s), then calls
+  `syncTogaDesk1{RepairOrder|Ticket}IntoToga2Ticket($id)`.
+- Five further one-way 2.0 → TOGaDesk sub-syncs, each its own flag: Contacts→People,
+  Items/Units→Assets, Predefined-Replies→TicketsPr, Ticket-Teams→Groups,
+  Ticket-Categories→Category/Subcategory/Items.
+- Finishes by PUT-ing both checkpoint parameters back to 2.0.
+
+## Data model
+
+- **2.0 side** is reached only through the API (never direct SQL): resources like `/contacts`,
+  `/entitlements`, `/tickets`, `/ticket-notes`, `/units`, `/parameters`, and the TOGa Supply
+  resources used by the importer.
+- **1.0 side** is written with direct SQL through `App_Database` against per-client link strings
+  (`db_toga`, `db_togadesk`), after `changeDbLinkToClientDatabase()`. Tables touched include
+  `Customers`, `Addresses`, `Contacts`, `ServiceRequests` (TOGa) and `repair_orders`,
+  `repair_order_history`, `tickets`, `tickets_replies`, `comments` (TOGaDesk).
+- **Checkpoints:** supply importer uses per-record-type `NETSUITE_*` keys (see per-client-sync
+  doc); the TOGaDesk bridge uses the two `*_LAST_TICKET_INTEGRATION_DATETIME` keys above. Both
+  live in the 2.0 client `Parameters` table and are read/written via `/parameters`.
+
+## Client variations
+
+- **Per-client credentials** (client/api/secret UUIDs) and TOGaDesk client/department IDs are
+  passed in by each cron — defined either as `App_Api_Toga2::{CLIENT_UUID_*,API_UUID_*,API_SECRET_*}`
+  class constants or as literals in the cron.
+- Behavior is tuned per client by which enable flags are passed: AIG runs `syncWithToga` +
+  TOGaDesk **tickets inbound only**; WJE runs TOGaDesk with **all** sub-syncs on. The
+  `syncWithToga` contact query has an explicit `$togaClientId === 15` (AIG) special case.
+
+## Gotchas / known issues
+
+- **🔐 Hardcoded credentials.** Every client's `CLIENT_UUID_*`, `API_UUID_*`, and `API_SECRET_*`
+  (plus the "True Workers" master keys) are committed as plaintext class constants at the top of
+  `toga2.php`. Treat them as **compromised-if-leaked**; do not reproduce the values in the KB,
+  tickets, or logs. Long-term they should move to config/SSM. (Observed 2026-06-23.)
+- **Two unrelated `sync_togasupply_<client>.php` families.** Files under
+  `worker/crons/toga2/netsuite/` are the **NetSuite supply importer** (`require` the common
+  engine). Files under `worker/crons/toga2/<client>/` (e.g. `aig/`, `wje/`) are this **bridge**
+  (`syncWithToga`/`syncWithTogadesk`). Same filename, different integration, different parameter
+  keys — they coexist harmlessly. Confirm which folder before editing.
+- **`syncWithToga` and the bridge build SQL by hand** with `App_Database::sqlEscape()` rather than
+  the `App_Model` layer; follow the surrounding escaping discipline when modifying.
+- **Per-record error isolation** in the TOGaDesk sync is via `try/catch` → `\Sentry\captureException`;
+  a thrown exception elsewhere (transport, checkpoint read) still aborts the whole run.
+- **PHP 7.2** target (prod worker/library) — no arrow functions, typed properties, `??=`, `match`.
+  Lint with `C:\xampp7\php\php.exe -l`.
+
+## Change history
+
+- 2026-06-23 — Initial documentation of the `App_Api_Toga2` transport (auth/token caching, options
+  DSL) and the 1.0↔2.0 bridge routines `syncWithToga` (Contacts/Entitlements → Customers/ServiceRequests)
+  and `syncWithTogadesk` (bi-directional ticket/repair-order/people/asset sync with dual checkpoint
+  parameters). Flagged the committed per-client API credentials. (jcardinal)
+
+## Related docs
+
+- [NetSuite → TOGa Supply Per-Client Sync](../../worker/features/netsuite-togasupply-per-client-sync.md)
+  — the importer that uses this class's transport and `*FromNetsuite()` methods.
+- [NetSuite SuiteQL/REST API Reference](netsuite-suiteql-api-reference.md) and
+  [SuiteQL/REST Shim](netsuite-suiteql-rest-shim.md) — the NetSuite side (`App_Api_Netsuite_Rest`).
+- [Library architecture](../architecture.md) — `App_Api` pattern, autoloader, `App_Database` layer.

package/knowledge/1.0/apps/worker/features/netsuite-togasupply-per-client-sync.md

@@ -16,6 +16,7 @@ files:
 related:
   - ../architecture.md
   - forecast2-netsuite-reconciliation.md
+  - ../../library/features/toga2-api-client-and-bridge.md
 ---
 
 ## Summary
@@ -161,3 +162,6 @@ Parameters are stored **per client DB** but accessed **through the TOGa2 API**,
 - [Worker architecture](../architecture.md) — cron dispatch, schedule-as-source-of-truth.
 - [Forecast2 NetSuite reconciliation](forecast2-netsuite-reconciliation.md) — sibling NetSuite
   sync surface (different target DB).
+- [App_Api_Toga2 — API Client & 1.0↔2.0 Bridge](../../library/features/toga2-api-client-and-bridge.md)
+  — the transport (`send`/`authenticate`/options DSL) and `*FromNetsuite()` methods this engine calls,
+  plus the separate `syncWithToga`/`syncWithTogadesk` bridge that shares the `sync_togasupply_*` filename.

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

@@ -0,0 +1,9 @@
+# toga25-supply (TOGa 2.5 Supply) — 2.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [TOGa 2.5 Supply — Architecture](architecture.md) | `toga25-supply` ("TOGa 2.5 Supply") is the **React/TypeScript frontend** for the 2.0 Supply application — an iteration and improvement of `toga2-supply`. | toga25-supply/src/main.tsx, toga25-supply/src/App.tsx, toga25-supply/src/routes.tsx, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/layout/, toga25-supply/src/pages/, toga25-supply/src/hooks/useTableCellInteractions.ts |
+| [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 |
+| [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 |

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

@@ -0,0 +1,115 @@
+---
+title: TOGa 2.5 Supply — Architecture
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: architecture
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - toga25-supply/src/main.tsx
+  - toga25-supply/src/App.tsx
+  - toga25-supply/src/routes.tsx
+  - toga25-supply/src/fieldsConfig/index.ts
+  - toga25-supply/src/fieldsConfig/useClientFields.ts
+  - toga25-supply/src/layout/
+  - toga25-supply/src/pages/
+  - toga25-supply/src/hooks/useTableCellInteractions.ts
+related:
+  - features/client-configurable-fields.md
+  - features/meta-driven-table-data.md
+  - features/column-visibility.md
+  - features/record-modals-and-nested-tables.md
+---
+
+## Summary
+
+`toga25-supply` ("TOGa 2.5 Supply") is the **React/TypeScript frontend** for the 2.0 Supply
+application — an iteration and improvement of `toga2-supply`. It is a Vite + React 18 SPA
+(react-router-dom 7, TanStack Query 5, react-hook-form 7) that talks to the 2.0 backend API
+(`_underscore`). It does **not** depend on `toga2-supply`; its components, table templates, and
+data hooks come from the shared in-house library **`@agilant/toga-blox`** (repo `toga-blox-npm`,
+currently consumed at `1.0.318-beta.37`).
+
+The app is **multi-client and meta-driven by design**. The same build serves many clients
+(Compass USA/Canada, NYC Health & Hospitals, Quad, Prudential, GroWrk, and others — there are
+per-client build scripts such as `nychh`, `compass`, `compasscanada`, `growrk`, `prudential`,
+`spglobal`, `bankofamerica`, `wmchealth`, `quad`). Almost nothing is hardcoded per client:
+table columns/labels come from server **table meta**, and client/role-specific UI config
+(filter buttons, group-by options, column pickers, layout toggles) is resolved at runtime
+through `src/fieldsConfig` + `useClientFields()`. Pages are thin; the real logic lives in
+per-page **view models** (`use*ViewModel` hooks) and reusable **layout** components that wrap
+toga-blox table/modal templates.
+
+**Critical rules:**
+- **Don't hardcode per-client behavior in components or view models** — resolve it through
+  `useClientFields()` / `src/fieldsConfig`, keyed by `clientSlug` (from `useHostnameStore`) ×
+  `role`. Every config must have a `DEFAULT` fallback or a client/role with no entry won't render.
+- **A table's pagination-vs-infinite-scroll mode is decided solely by `isPaginationEnabled` from
+  the table meta**, consumed via the single `useTableData` hook — never pick a data hook or
+  hardcode the mode per page.
+- **`@agilant/toga-blox` is symlinked from the local `toga-blox-npm` repo and the app consumes its
+  `dist/`** — after editing toga-blox source you MUST rebuild (`cd toga-blox-npm && npm run build`)
+  or the change won't reach runtime. Patching only `src` is a silent no-op.
+- **Source files in this repo use TAB indentation** — match exactly or string-replace edits fail.
+
+## Tech stack & entry points
+
+- **Build/dev:** Vite. `src/main.tsx` → `src/App.tsx`; routes in `src/routes.tsx`. Per-client
+  dev/build scripts in `package.json` (`dev`, `build`, plus `nychh`, `compass`, `growrk`, etc.).
+- **Data:** TanStack Query 5 (`@tanstack/react-query`). The canonical table query key prefix is
+  `["table-data", slug, …]`; a blanket `invalidateQueries({ queryKey: ["table-data"] })` refetches
+  any table after a mutation.
+- **Forms:** react-hook-form 7 (`FormProvider` + `BaseInput`), used by the create/edit record modals.
+- **Routing:** react-router-dom 7. URL search params are the primary state store for tables
+  (sorting, filters, pagination, active-row uuid, column visibility, nested-table swap keys).
+- **UI library:** `@agilant/toga-blox` provides `PrimaryTable*Layout`, `TableRecordModal`,
+  `BaseInput`, `BaseButton`, `DetailSection`, the `useTableData` hook, FontAwesome helpers, etc.
+
+## Directory layout (`src/`)
+
+- `pages/<Entity>/` — page component (thin) + `viewModel/` (the `use*PageViewModel` hook) +
+  per-page `FIELDS/<CLIENT>/*.json` client config + `hooks/` + `dummyData/` (column-width JSON).
+- `layout/<Thing>Layout/` — reusable table/modal layout wrappers around toga-blox templates,
+  each with its own `use*ViewModel`. Key ones: `SalesOrdersTableLayout`,
+  `SalesOrderRecordModalLayout`, `SalesOrderItemsTableLayout`, `ItemFulfillmentModal`,
+  `ItemRecordModalLayout`, `GenericNestedTables`, `RecordApprovalModalLayout`.
+- `fieldsConfig/` — `index.ts` (the `ClientFields` bundle + `FIELDS[clientSlug][role]` map) and
+  `useClientFields.ts` (resolves active client/role, falls back to `DEFAULT_CLIENT_FIELDS`).
+- `globalFieldsConfig/`, `hooks/`, `stores/` (e.g. `useHostnameStore`), `contexts/`, `utils/`,
+  `types/`, `api/`, `styles/`, `themeConfig.json`.
+
+## Architectural pillars (see feature docs)
+
+1. **Client/role-driven config** — runtime UI config without rebuilds. See
+   [client-configurable-fields](features/client-configurable-fields.md).
+2. **Meta-driven table data** — one `useTableData` hook; meta's `isPaginationEnabled` picks the
+   fetch strategy. See [meta-driven-table-data](features/meta-driven-table-data.md).
+3. **URL-driven column visibility** — shareable show/hide-columns, client-gated button. See
+   [column-visibility](features/column-visibility.md).
+4. **Layered modals over tables** — record modals, nested client/server tables, cell-click
+   modals, and the `GenericNestedTables` config-driven renderer. See
+   [record-modals-and-nested-tables](features/record-modals-and-nested-tables.md).
+
+## toga-blox relationship
+
+`@agilant/toga-blox` is the shared frontend component/template/utility library (repo
+`toga-blox-npm`). It is **not published to npm for this app's purposes** — the app is currently
+its primary consumer and resolves it via a symlinked `node_modules/@agilant/toga-blox` →
+`toga-blox-npm`. Because the app imports the built `dist/` (JS + `.d.ts`), any change to toga-blox
+**source** requires a rebuild before it is visible at runtime; in urgent cases the `dist/` files
+(and their `.d.ts`) have been patched directly. The `/update-blox` skill covers version bumps.
+
+## Conventions & gotchas
+
+- **Tabs, not spaces** for indentation in this repo's source.
+- **`BaseButton` is a default import:** `import BaseButton from "@agilant/toga-blox/dist/components/BaseButton/BaseButton.js"`.
+- **Per-consumer React Query cache scope:** when two components fetch the same record with
+  different field configs, share a `scope` discriminator in the query key so they don't clobber
+  each other's cached data (e.g. record modal vs. approval modal — `scope="record-modal"` vs
+  `scope="approval-modal"`). Including `additionalData` in the query key is mandatory for
+  WHERE-filtered modal tables, or React Query serves a stale unfiltered first render.
+- **Typecheck with `npx tsc --noEmit` / `npx tsc -b`** after changes; adding a required key to
+  `ClientFields` surfaces every bundle missing it.

package/knowledge/2.0/apps/toga25-supply/features/client-configurable-fields.md

@@ -0,0 +1,88 @@
+---
+title: Client-Configurable Fields (useClientFields / fieldsConfig)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - 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
+related:
+  - ../architecture.md
+  - column-visibility.md
+---
+
+## What it is
+
+The mechanism for config that **varies by client** (or client × role) — field overrides,
+filter buttons, group-by options, column pickers, layout toggles — without hardcoding it in
+the view model or rebuilding per client. All such config resolves through `src/fieldsConfig`
+and the `useClientFields()` hook.
+
+## How it works
+
+1. **Per-client JSON lives next to the consuming page**, under `FIELDS/<CLIENT>/`
+   (e.g. `src/pages/SalesOrders/viewModel/FIELDS/COMPASS/salesOrdersPageFields.json`). There is
+   **always a `DEFAULT/`** folder every client falls back to. `<CLIENT>` must match the hostname
+   `clientSlug` (uppercase — `COMPASS`, `NYCHH`, …).
+2. **`src/fieldsConfig/index.ts`** imports those JSON files and wires them into the
+   `ClientFields` bundle — a normalized `FIELDS[clientSlug][role]` map merged over `DEFAULT`.
+3. **`useClientFields()`** resolves the active `clientSlug` (from `useHostnameStore`) + `role`
+   (from `resolveRole`), looks up the bundle, falls back to `DEFAULT_CLIENT_FIELDS`, and caches
+   the result in React Query. It **always returns a defined bundle** (DEFAULT while loading/missing),
+   so reading `clientFields.yourKey` is safe without optional chaining — but guard array access.
+4. **The view model reads its slice:**
+   ```ts
+   const { fields: clientFields } = useClientFields();
+   const tenantFields = clientFields.salesOrdersPageFields; // your key
+   ```
+
+### By client × role vs. by client only
+
+- **Client × role** (e.g. `salesOrdersPageFields` — ADMIN vs MANAGER see different filter buttons):
+  the JSON is keyed by role at the top level (`{ "ADMIN": {...}, "MANAGER": {...} }`); use a
+  `pick*`/`merge*` helper to merge `DEFAULT[role]` with the client's `[role]`.
+- **Client only** (e.g. `inventoryGroupings` — every role sees the same group-by options): the JSON
+  is flat, and you **inject** it across every role bundle for that client rather than hand-writing
+  it into each. Author the map literal as `FIELDS_BASE` (typed `Omit<ClientFields, "yourKey">`),
+  then build `FIELDS` by mapping each `[clientSlug][role]` entry and grafting
+  `yourKey: BY_CLIENT[clientSlug] ?? DEFAULT_*`. Avoids editing all ~13 role bundles.
+  `DEFAULT_CLIENT_FIELDS` must also carry the new key (ultimate fallback).
+
+### Hydration (non-serializable bits)
+
+Keep JSON **serializable** — strings, enums, arrays. No JSX, no functions, no Tailwind classes.
+Anything non-serializable is referenced by an **enum key** and resolved in the view model via a
+registry that maps enum → real value (e.g. `MODAL_RENDERERS: Record<ModalKey, renderModal>`).
+This is the one place app-owned JSX is grafted back onto client-authored config. Clients never
+author JSX.
+
+## Adding a new client-configurable field
+
+1. Author the serializable JSON under `FIELDS/DEFAULT/<thing>.json` + a folder per overriding client.
+2. Declare the types next to the JSON (`FIELDS/index.ts`) and export the shape.
+3. Wire into `fieldsConfig/index.ts`: add the key to `ClientFields`, import each client's JSON,
+   add the value to **every** bundle + `DEFAULT_CLIENT_FIELDS` (or use the injection pattern).
+4. Consume in the view model via `useClientFields()`.
+5. Hydrate enum→value in the view model if the config references components/render callbacks.
+6. `npx tsc -b` — a new required `ClientFields` key surfaces every bundle missing it.
+
+## Gotchas
+
+- **Always provide `DEFAULT`.** Resolution order: `FIELDS[client]?.[role]` → `FIELDS[client]?.DEFAULT`
+  → `DEFAULT_CLIENT_FIELDS`. A client/role with no entry must still render.
+- **New client *file* = no code change** (just import/wiring). **New render style/modal type
+  (new enum value) = code change** in the hydration registry — that's the intended boundary
+  between client config and app rendering.
+- Worked examples: `salesOrdersPageFields` (client × role) and `inventoryGroupings` (client-only +
+  hydration; full write-up in `src/pages/Inventory/README.md`).
+
+## Change history
+- 2026-06-23 — Documented from the `add-client-fields` skill during initial knowledge seed. (apeterson)

package/knowledge/2.0/apps/toga25-supply/features/column-visibility.md

@@ -0,0 +1,98 @@
+---
+title: Column Visibility (URL-driven show/hide columns)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - 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
+related:
+  - ../architecture.md
+  - client-configurable-fields.md
+  - meta-driven-table-data.md
+---
+
+## What it is
+
+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 selection in the URL as a
+shareable link. The button's presence/label/icon — and the modal's entire copy — are driven per
+client × role via the FIELDS config. Built for pages using `PrimaryTableServerLayout` (the Sales
+Orders pattern). Reference: `ColumnVisibilityModal` + Sales Orders page/view model/data hook.
+
+## How the table renders columns (key facts)
+
+- The table meta (`TableViewMeta` / `DataTableMetaProp`) carries `fields: TableViewField[]`; each
+  field has a unique `slug` and an `isVisible`. `buildTanstackColumns` (toga-blox) **filters by
+  `isVisible`** before building columns, so the tanstack column `id` is the field `slug`. Hiding =
+  `isVisible: false` or removing the field — identical column set.
+- `getDataTableData` builds the API field list **from `meta.fields`**. So the meta used for
+  *fetching* must keep all fields; only the meta passed to the *table* should be visibility-adjusted.
+  **Keep two metas separate: fetch = full, display = adjusted.**
+
+## URL-state semantics
+
+Single param `cols` = comma-separated **visible** column slugs.
+- **Absent** → fall back to each field's default `isVisible`.
+- **Present (even empty)** → only the listed slugs are visible. Distinguish absent from empty with
+  `searchParams.has("cols")`, NOT truthiness (so "hide all" works):
+
+```ts
+const visibleSlugSet = searchParams.has("cols")
+  ? new Set((searchParams.get("cols") ?? "").split(",").filter(Boolean))
+  : null;
+const isFieldVisible = (f) => visibleSlugSet ? visibleSlugSet.has(f.slug) : f.isVisible;
+```
+
+## Steps
+
+1. **Reuse the modal.** `ColumnVisibilityModal` is generic and holds **zero hardcoded copy** —
+   props `{ isOpen, columns: { slug, label, visible }[], labels, icon, onApply(visibleSlugs),
+   onReset?, onClose }`. `labels` = `{ title, showAll, hideAll, reset, cancel, apply, close }`;
+   `icon` = `{ name, variant }`. It keeps pending state internally, commits only on Apply.
+2. **View model — derive visibility from URL.** Add `visibleSlugSet`/`isFieldVisible`,
+   `columnOptions` (`fields.map(f => ({ slug, label: f.label ?? f.slug, visible: isFieldVisible(f) }))`),
+   `displayTableMeta` (`{ ...meta, fields: fields.map(f => ({ ...f, isVisible: isFieldVisible(f) })) }` —
+   return THIS as the table meta; data hook keeps full meta), `columnVisibilityKey` (visible slugs
+   joined; remount key), and `applyColumnVisibility(slugs)`/`resetColumnVisibility()`.
+3. **Data hook — exclude `cols` from the query key.** Where the slug key is stripped from
+   `tableSearchParams`, also `filtered.delete("cols")` — else every toggle refetches.
+4. **Page — button + modal + remount key.** Local `isColumnsModalOpen` state; render the button
+   from client config; pass `columnsButton.modal.labels`/`.icon` to the modal; put
+   `key={columnVisibilityKey}` on the table layout (required — see gotcha).
+5. **Make button + all modal copy client-configurable** (mirrors `filterButtons`; see
+   [client-configurable-fields](client-configurable-fields.md)). Add a `columnsButton` block to each
+   role in `FIELDS/<CLIENT>/<page>Fields.json` (and to `DEFAULT` first). Resolve it off `tenantFields`
+   in the view model into `{ icon, labels }` with **per-key fallbacks living in the resolution layer**,
+   never in the component.
+6. **Verify:** `npx tsc --noEmit`, validate each JSON parses, click live (toggle, Apply, copy URL,
+   reload → state persists).
+
+## Gotchas
+
+- **No hardcoded copy in the component** — every user-facing string (incl. Close `aria-label`) is a
+  required `labels` prop from client FIELDS; fallbacks live in the view model's resolution, not the
+  component, not default prop values. Only structural glyphs (checkbox tick, close `xmark`) stay.
+- **Remount key is REQUIRED.** toga-blox's `PrimaryTableRow` memoizes
+  `useMemo(() => row.getVisibleCells(), [row])`; TanStack caches `row` by data, so a columns-only
+  change doesn't change `row` → stale cells. Symptom: **toggling off removes the header but leaves the
+  body column.** `key={columnVisibilityKey}` forces a fresh table instance — the only fix without
+  editing `node_modules`. Real upstream fix: repair that memo in toga-blox.
+- **Don't shrink the fetch meta** — adjust `isVisible` only on the table meta; `getDataTableData`
+  builds its field list from `meta.fields`.
+- **`cols` must be stripped from the data query** or every toggle refetches.
+- **`has("cols")` vs truthiness** — empty `cols` is a real "hide all" state, not "absent".
+- **Checkbox can't be a nested `<button>`** — the row is the clickable `<button>`; the checkbox is a
+  visual `<span aria-hidden>`. A button-in-button is invalid HTML and silently breaks clicks.
+- **Shareable-link trade-off** — an explicit `cols` set captures an exact view; columns added to the
+  meta later won't appear for an old link until Reset (intended).
+
+## Change history
+- 2026-06-23 — Documented from the `add-column-visibility` skill during initial knowledge seed. (apeterson)

package/knowledge/2.0/apps/toga25-supply/features/meta-driven-table-data.md

@@ -0,0 +1,176 @@
+---
+title: Meta-Driven Page & Table Setup
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - 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
+related:
+  - ../architecture.md
+  - column-visibility.md
+  - record-modals-and-nested-tables.md
+---
+
+## What it is
+
+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 settings), then fetches the *table
+data* — each step keyed by a slug, each hook supplied by `@agilant/toga-blox`. A developer wires a
+new page by composing these hooks in a view model; they never hand-build columns or choose a
+fetch strategy. `useSalesOrdersViewModel`
+(`src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx`) is the canonical example.
+
+## The flow (Sales Orders)
+
+```
+useSalesOrdersViewModel
+  │
+  │ 1. PAGE META  ── page slug "sales-orders-listing", app "supply"
+  ├─▶ useFetchPageMeta("sales-orders-listing", { app: "supply", enabled: true })   [toga-blox]
+  │       → pageMeta: PageMeta { settings: { sections, fields }, acl }
+  │         (field-label/section overrides + ACL for this page)
+  │
+  │ 2. TABLE SLUG  ── from the route, not from pageMeta
+  ├─▶ useSalesOrdersTableState() → useServerTableUrlState(slug, …)                 [app]
+  │       slug = location.pathname.replace("/", "")   // e.g. "salesorders"
+  │       also owns sorting / filters / page / recordsPerPage / activeRowUuid (URL state)
+  │
+  │ 3. TABLE META  ── table slug → columns + table settings
+  ├─▶ useTablePageMeta({ slug: tableState.slug })                                  [app wrapper]
+  │       └─ useFetchTablePageMeta({ slug })                                       [toga-blox]
+  │            → { table: TableViewMeta, nestedTable }, isLoadingFilterOptions, …
+  │              table.fields[]  = every column (TableViewField[])
+  │              table.{ slug, route, joins, sort, recordsPerPage,
+  │                      isPaginationEnabled, isInfiniteScrollingEnabled, apiWhereClause }
+  │
+  │ 4. MERGE LABELS  ── graft page-meta labels onto table fields
+  ├─▶ useAssignTableFieldLabels(fetchedTableViewMeta, pageMeta)                    [toga-blox]
+  │       → salesOrdersTableMeta: TableViewMeta | null
+  │
+  │ 5. TABLE DATA  ── same table slug → rows
+  └─▶ useTableData({ slug: tableState.slug, tableViewMeta: salesOrdersTableMeta,
+                     isPaginationEnabled: !!salesOrdersTableMeta?.isPaginationEnabled,
+                     sorting, columnFilters, page, recordsPerPage,
+                     searchParams, additionalData })                              [toga-blox]
+          → { records, isLoadingTableDataLoading, isFetching,
+              paginationMeta, fetchNextPage, hasNextPage }
+```
+
+The view model then returns `salesOrdersTableMeta` (after column-visibility adjustment — see
+[column-visibility](column-visibility.md)), `displayRecords`, the pagination/infinite wiring, and
+`tableSettings = { isPaginationEnabled }` for the `*TableLayout` to forward to
+`PrimaryTableServerLayout`.
+
+### Two slugs, two metas — keep them straight
+
+- **Page slug** (`"sales-orders-listing"`) is a literal passed to `useFetchPageMeta` and identifies
+  the *page* (its label overrides, sections, ACL). It does **not** identify the table.
+- **Table slug** (`tableState.slug`) identifies the *table* and is used for **both** the table-meta
+  fetch (step 3) and the table-data fetch (step 5) — they must match so the columns and the rows
+  describe the same table. In Sales Orders this slug is derived from the route pathname via
+  `useServerTableUrlState`, not read out of `pageMeta`.
+- `useAssignTableFieldLabels` is the bridge: it overlays the page meta's per-field labels
+  (`pageMeta.settings.fields[table][field].label`) onto the table meta's fields, so page-scoped
+  copy wins without re-fetching.
+
+## What's in the table meta (the columns)
+
+`useFetchTablePageMeta` returns `{ table, nestedTable }`. The `table` object is the `TableViewMeta`
+(alias of `DataTableMetaProp`) and carries:
+
+- `fields: TableViewField[]` — **every column**. Each field: `slug` (unique id / tanstack column
+  id), `label`, `isVisible`, `index`, `type` (`STRING | NUMBER | DATE | DATETIME | SELECT |
+  MULTISELECT | IMAGE | HYPERLINK | STATUS | CURRENCY | AVATAR | LINK | URGENCY | CLIENT |
+  STATUS_BADGE | BOOLEAN | null`), `isEditable`, `isSortable`, `isFilterable`, `isCopyable`,
+  `isExpandableCell`, `width`, `sticky` (`left|right|null`), `precision`, `casing`, `recordRoute`,
+  `hyperlinkField`, `imageUrlField`, `filterOptions`, `settings: { table, field, contextTable,
+  contextField }`, `selectIdentifierField`, `selectNameField`.
+- Table-level: `slug`, `route`, `table`, `joins[]`, `sort[]`, `recordsPerPage`, `apiWhereClause`,
+  `isPaginationEnabled`, `isInfiniteScrollingEnabled`.
+- `nestedTable` — a second `TableViewMeta | null` for nested/expand rows.
+
+`buildTanstackColumns` (toga-blox) builds columns from `fields`, filtering by `isVisible` (the
+tanstack column `id` is the field `slug`).
+
+## Pagination vs. infinite scroll is meta-driven too
+
+`useTableData` runs **both** a paginated `useQuery` and an infinite `useInfiniteQuery`, gating each
+with `enabled` on `isPaginationEnabled` so only the active one fetches, and returns one normalized
+shape (`records`, `paginationMeta` *or* `fetchNextPage`/`hasNextPage`). The view model passes only
+`isPaginationEnabled` (from the table meta); `PrimaryTable*Layout` derives
+`isInfiniteScrollingEnabled = !isPaginationEnabled`. So a table's mode comes from its meta, never a
+per-page hook choice. Other baked-in behavior: unified `["table-data", slug, …]` query key (a
+blanket `invalidateQueries({ queryKey: ["table-data"] })` refetches either mode); display params
+(`<slug>` active-row uuid, `cols`) stripped from the key/API call; generic record extraction (first
+array in `response.data`).
+
+## From toga-blox `dist` (reference)
+
+Everything in the pipeline except the route-derived table slug comes from `@agilant/toga-blox`. The
+app imports the built `dist/` — edits to toga-blox source require a rebuild (`cd toga-blox-npm &&
+npm run build`) before they reach runtime.
+
+| Export | `dist` path | Signature / role |
+|---|---|---|
+| `useFetchPageMeta` | `dist/hooks/useFetchPageMeta` | `(slug, { app, enabled?, onError? }) → { pageMeta: PageMeta \| null, labels, isLoading, isError, refetch }`. `PageMeta = { settings: { sections: MetaSections, fields: Record<string,any> }, acl }`. Page-level labels/sections/ACL. |
+| `useFetchTablePageMeta` | `dist/hooks/useFetchTablePageMeta` | `({ slug }) → { tableViewMeta: { table, nestedTable }, isLoadingFilterOptions, isLoadingTableDataLoading, isFetching }`. The columns + table settings. |
+| `useAssignTableFieldLabels` | `dist/hooks/useAssignTableFieldLabels` | `(fetchedTableViewMeta: { table? } \| null, pageMeta: { settings?: { fields? } } \| null) → TableViewMeta \| null`. Merges page-meta field labels onto table fields. |
+| `useTableData` | `dist/components/Table/hooks/useTableData` | `(UseTableDataOptions) → { records, isLoadingTableDataLoading, isFetching, paginationMeta, fetchNextPage, hasNextPage }`. Bimodal data fetch (see above). |
+| `TableViewMeta` (type) | `dist/components/Table/types` → `= DataTableMetaProp` | The `table`/`nestedTable` shape; `TableSkin = "supply" \| "desk" \| "supply-nested" \| "supply-modal-table"`. |
+| `TableViewField` (type) | `dist/api/index` | Per-column shape (see "What's in the table meta"). |
+
+App-side glue (NOT in toga-blox):
+- `useTablePageMeta` (`src/hooks/useTablePageMeta.ts`) — thin wrapper over `useFetchTablePageMeta`
+  that re-types `table`/`nestedTable` as `TableViewMeta | null` and re-exposes the rest unchanged.
+- `useSalesOrdersTableState` → `useServerTableUrlState` (`src/hooks/`) — derives the **table slug**
+  from the route pathname and owns URL-backed sorting/filters/pagination/active-row state.
+
+## Wiring a new page (recipe)
+
+1. `useFetchPageMeta("<page-slug>", { app: "supply", enabled: true })` → `pageMeta`.
+2. A table-state hook (`use<Page>TableState` → `useServerTableUrlState(slug, …)`) to get the table
+   `slug` + URL state (`sorting`, `columnFilters`, `page`, `recordsPerPage`, `searchParams`).
+3. `useTablePageMeta({ slug })` → `tableViewMeta` (columns + settings).
+4. `useAssignTableFieldLabels(tableViewMeta, pageMeta)` → the merged meta you hand to the table.
+5. `useTableData({ slug, tableViewMeta: merged, isPaginationEnabled: !!merged?.isPaginationEnabled,
+   sorting, columnFilters, page, recordsPerPage, searchParams, additionalData })` → rows.
+6. `tableSettings = useMemo(() => ({ isPaginationEnabled: merged?.isPaginationEnabled }), [merged])`.
+7. Return both pagination wiring (`paginationMeta`, `handlePageChange`, `handleRecordsPerPageChange`)
+   **and** infinite wiring (`fetchNextPage`, `hasNextPage`); forward all from the `*TableLayout` to
+   `PrimaryTableServerLayout`.
+
+## Gotchas
+
+- **Page slug ≠ table slug.** The page slug is a literal for `useFetchPageMeta`; the table slug
+  (route-derived here) drives table meta *and* table data — those two must use the **same** slug.
+- **Server meta currently returns `isPaginationEnabled: true` for every slug**, so all tables
+  paginate today. A table that should infinite-scroll needs the backend to return `false` for that
+  slug — the frontend no longer hardcodes it. (This is why VendorItems, historically infinite, now
+  paginates.)
+- **Don't shrink the fetch meta for column hiding.** `getDataTableData` builds its API field list
+  from `meta.fields`; adjust `isVisible` only on the *display* meta (see column-visibility).
+- **Infinite scroll needs a height-constrained scroll container** (`max-height` + `overflow-y: auto`);
+  inline-expanded nested tables where the page scrolls won't load more. Pagination is unaffected.
+- **`additionalData` must be in the query key** (it is, inside `useTableData`) — required for
+  WHERE-filtered modal tables or React Query serves a stale unfiltered first render.
+- **toga-blox edits need a rebuild** — the app consumes `dist/`; editing only `src` is a silent no-op.
+
+## Change history
+- 2026-06-23 — Refocused on the full page→table→data meta pipeline (page meta via `useFetchPageMeta`,
+  table meta via `useTablePageMeta`/`useFetchTablePageMeta`, label merge via
+  `useAssignTableFieldLabels`, data via `useTableData`), grounded in `useSalesOrdersViewModel`; added
+  a toga-blox `dist` reference table. (apeterson)
+- 2026-06-09→06-10 — Migration that established the bimodal `useTableData`: added it to toga-blox;
+  made `PrimaryTable*Layout` derive `isInfiniteScrollingEnabled`; migrated Items/SalesOrders/VendorItems
+  view models + `GenericNestedTables` + `ItemFulfillmentModal`; deleted per-page data hooks. (apeterson)

package/knowledge/2.0/apps/toga25-supply/features/record-modals-and-nested-tables.md

@@ -0,0 +1,147 @@
+---
+title: Record Modals & Nested Tables
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+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/hooks/useTableCellInteractions.ts
+related:
+  - ../architecture.md
+  - meta-driven-table-data.md
+---
+
+## What it is
+
+The repo's family of modal + nested-table patterns layered over toga-blox `TableRecordModal` and
+`PrimaryTable*Layout`. Covers: row-click record modals, nested client/server tables inside a
+modal, cell-click modals, modal-contained server tables, the config-driven `GenericNestedTables`
+renderer, and form-driven create/edit record modals. The canonical examples live in
+`src/layout/*` (Sales Orders + Item). These six patterns are the load-bearing UI architecture for
+this app.
+
+## Pattern 1 — Row click opens a record modal (URL-driven)
+
+Page renders a `*TableLayout` and passes a `renderModal` prop. The table layout owns all state via
+`use*ViewModel` → `useServerTableUrlState`. Clicking a row sets `activeRowUuid` in the URL;
+`PrimaryTableServerLayout` calls `renderModal({ uuid, onClose })`, which renders the record modal
+wrapped in `TableRecordModal position="bottom"`.
+
+- `renderModal` is `({ uuid, onClose }) => ReactNode | null` — return `null` when `uuid` is falsy.
+- `onClose` clears the URL state (`handleModalClose`).
+- The record modal layout calls its own view model to fetch data for that uuid.
+- **Action-column modals** (e.g. approval) use a separate `useState<Record|null>` in the page,
+  rendered as a second `TableRecordModal position="center"` — not URL-driven.
+
+## Pattern 2 — Record modal contains a nested client-side table
+
+The record modal view renders e.g. `SalesOrderItemsTableLayout` with `displayRecords` from the
+parent view model. The nested table uses `PrimaryTableClientLayout` (data already in memory),
+`tableSkin="supply-modal-table"`, and its **own** slug + `useSearchParams` + `useServerTableUrlState`
+so URL-state namespacing doesn't collide with the outer table. Column widths come from
+`src/pages/<Entity>/dummyData/*.json`; `headerSpan` adds a spanning header above grouped columns.
+
+## Pattern 3 — Cell click within a nested table opens another modal
+
+Driven by the reusable hook `useTableCellInteractions` (`src/hooks/useTableCellInteractions.ts`),
+which owns all click/hover/style logic. Each table's view model only defines the registries:
+
+```ts
+const { activeModal, closeModal, handleTableClick, handleTableMouseOver,
+        handleTableMouseOut, applyClickableStyles } = useTableCellInteractions({
+  fields, cellClickRegistry, headerClickRegistry /* optional */, contextUuid /* optional */ });
+```
+
+- `cellClickRegistry[key]` (key matches the field's `onClick` in the table meta JSON):
+  `{ canOpen?(row), getModalSpec(row) => ({ key, uuid, row }) }`. `canOpen` is the single source
+  of "is this cell clickable?" — used by the click handler, hover styles, and cursor styles.
+- `headerClickRegistry[key]` (key matches the field's `headerOnClick`):
+  `{ getModalSpec(contextUuid) => ({ key, uuid, row }) }`.
+- Table meta JSON marks a field: `{ "name": "qtyFulfilled", "onClick": "openFulfilledModal",
+  "headerOnClick": "openAllFulfillments" }` — both independent.
+
+Layout setup: wrap the table in a div with `onClick={(e) => handleTableClick(e, displayRecords)}`
++ mouseover/out; re-apply styles on DOM changes via a `MutationObserver` calling
+`applyClickableStyles` (virtual scroll re-renders rows); render each modal as a sibling switching
+on `activeModal.key`. **Adding a clickable column = 3 edits:** meta JSON `onClick`, one
+`cellClickRegistry` entry, one `{activeModal?.key === "myKey" && <Modal/>}` block.
+
+## Pattern 4 — Modal containing a server-side table
+
+For modal tables needing server data, use `PrimaryTableServerLayout` inside `TableRecordModal
+position="bottom"`. The modal view model calls `useFetchTablePageMeta` + `useTablePageData`
+(or `useTableData`) with an `additionalData` WHERE filter, e.g. `{ slug: "SalesOrderItems.uuid",
+uuid: "<row-uuid>" }`. **`additionalData` MUST be in the query key** (in toga-blox) or React Query
+caches the unfiltered first render (uuid null) and never refetches. Guard with `isOpen={!!uuid}`;
+when uuid is null, `additionalData` returns `{}`. Typically `isPaginationEnabled: false` +
+`isInfiniteScrollingEnabled: true` (but see [meta-driven-table-data](meta-driven-table-data.md)).
+
+## Pattern 5 — `GenericNestedTables` (config-driven multi-level / swap tables)
+
+A config-driven renderer: declare an array of `TableLevel` objects instead of hand-wiring each
+level. Each level fetches its own meta + data and renders a `GenericTableLayout` (wraps
+`PrimaryTableServerLayout`). Reference: `src/pages/Inventory/`.
+
+`TableLevel` carries `fetchSlug`, `metaVariant`, `tableSkin`/`swapTableSkin`, `actionColumns`,
+`renderModal` (Pattern 1), `rowInteraction` (`"expand"` default | `"swap"`), `urlParamKey`
+(required for swap, unique per level), `getAdditionalData(parentUuid)`,
+`getSwapAdditionalData(selfUuid)`.
+
+- **`"expand"`** — clicking a row inline-expands the next level beneath it (filtered via
+  `getAdditionalData(parentUuid)`).
+- **`"swap"`** — clicking writes `urlParamKey=<rowUuid>`; the renderer makes that level the new
+  active root, filtered by `getSwapAdditionalData(selfUuid)` (using `swapTableSkin`).
+
+`additionalData` is produced per-level by callbacks (the WHERE-filter shape from Pattern 4). Each
+level runs its own `useServerTableUrlState` and strips its own slug key, isolating URL state.
+A page-level `pageMeta` (from `useFetchPageMeta`) flows down for field-label overrides. The page
+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.
+
+## Pattern 6 — Create/edit record modal (form-driven)
+
+Scaffold per the `ItemRecordModalLayout` pattern (`src/layout/ItemRecordModalLayout/`). Form-driven
+(react-hook-form + `FormProvider`), fields rendered through a section/field config + `DetailSection`
++ `BaseInput`, inside `TableRecordModal position="bottom" variant="expandable"`.
+
+```
+<Entity>RecordCreateModalLayout        ← owns form hook, mounts TableRecordModal
+  └─ <Entity>RecordCreate              ← FormProvider + form, renders sections
+       ├─ use<Entity>CreateForm        ← rhf state + apiPost submit
+       └─ use<Entity>RecordEditViewModel ← fetches advancedSelect options
+```
+
+- Form hook: `useForm({ defaultValues, mode: "onChange", reValidateMode: "onChange" })`; `onSubmit`
+  builds a payload (map relation objects to `.uuid`), `apiPost("/<entities>", payload)`, then
+  `queryClient.invalidateQueries({ queryKey: ["table-data"] })`, reset, `onCreated?.()`. Edit
+  variant: `form.reset(record)` in a `useEffect`, `apiPut`, expose `isEditing`/`onEnableEdit`/`onCancelEdit`.
+- Field types: `text`, `textArea`, `toggle`, `advancedSelect`, `advancedMultiSelect`; mark required
+  with `isRequired` + `showRequiredIndicator`; feed select options via `optionsByFieldUuid` keyed by
+  field `uuid`. The edit view model that supplies options is **reused** by both create and edit.
+- Page holds `isCreateOpen` state + a "New <Entity>" `BaseButton`, renders the layout with `isOpen`/`onClose`.
+
+## Gotchas
+
+- **Files use TABS** — match exactly or edits won't apply.
+- **`BaseButton` is a default import:** `@agilant/toga-blox/dist/components/BaseButton/BaseButton.js`.
+- **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.
+- **`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
+  (record modal vs. approval modal: the approval modal omitting item-image fields blanked the
+  record modal's images until scoping isolated the entries).
+
+## Change history
+- 2026-06-23 — Documented from CLAUDE.md Modal Patterns 1–5 + the `create-record-modal` skill during
+  initial knowledge seed. (apeterson)

package/knowledge/INDEX.md

@@ -27,6 +27,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 4 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 2 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 5 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 
 ## standalone framework
 
@@ -49,4 +50,5 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **Rate** (`rate`) → [clients/rate/INDEX.md](clients/rate/INDEX.md)
 - **Tow Foundation** (`tow-foundation`) → [clients/tow-foundation/INDEX.md](clients/tow-foundation/INDEX.md)
 - **Walmart Client Profile** (`walmart`) → [clients/walmart/INDEX.md](clients/walmart/INDEX.md)
+- **Wiss, Janney, Elstner Associates, Inc.** (`wje`) → [clients/wje/INDEX.md](clients/wje/INDEX.md)
 

package/knowledge/clients/wje/INDEX.md

@@ -0,0 +1,5 @@
+# Client: Wiss, Janney, Elstner Associates, Inc. `wje`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [Wiss, Janney, Elstner Associates, Inc.](profile.md) | 2.0 | Wiss, Janney, Elstner Associates, Inc. | worker/crons/toga2/wje/sync_togasupply_wje.php |

package/knowledge/clients/wje/profile.md

@@ -0,0 +1,30 @@
+---
+title: "Wiss, Janney, Elstner Associates, Inc."
+framework: "2.0"
+apps:
+  - worker
+  - library
+project: Library
+client: wje
+type: profile
+status: active
+updated: 2026-06-23
+owners: [jcardinal]
+files:
+  - worker/crons/toga2/wje/sync_togasupply_wje.php
+related:
+  - ../../1.0/apps/library/features/toga2-api-client-and-bridge.md
+---
+
+## Summary
+
+Wiss, Janney, Elstner Associates, Inc. (WJE) is a TOGa Desk client integrated through the
+**1.0↔2.0 TOGaDesk bridge** (`App_Api_Toga2::syncWithTogadesk`). The cron
+`worker/crons/toga2/wje/sync_togasupply_wje.php` runs every 2 minutes and enables the **full**
+set of bridge sub-syncs (tickets both directions, ticket-notes, contacts→people, items/units→
+assets, predefined-replies, ticket-teams→groups, ticket-categories) for TOGaDesk client id 153,
+department 269 (plus internal-tickets department 290). WJE requires a group on every ticket and
+falls back to a default group/agent when none is assigned.
+
+See the bridge feature doc for the mechanism. No NetSuite TOGa Supply importer runs for WJE
+(it is a help-desk integration, not a supply/procurement client).

package/knowledge/registry.json

@@ -158,9 +158,7 @@
     "project": "TOGa Commerce",
     "framework": "2.0",
     "role": "app",
-    "dependsOn": [
-      "api2"
-    ]
+    "dependsOn": ["api2"]
   },
   {
     "repo": "toga",
@@ -170,5 +168,12 @@
     "dependsOn": [
       "library"
     ]
+  },
+  {
+    "repo": "toga25-supply",
+    "project": "TOGa 2.5 Supply",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": []
   }
 ]

package/package.json

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