toga-ai 1.0.229 → 1.0.230

package/knowledge/2.0/apps/toga25-supply/features/surface-frontend.md

@@ -46,7 +46,11 @@ feature flag — see below). Backend: [surface-resolver](../../_underscore/featu
 - **`useFetchSurfaceMeta`** — the single fetch-once/React-Query-cached choke point for a surface's
   meta. Loading a different *record* into the same surface reuses cached meta. Builds the URL as
   `/surfaces/meta?slug=...` (query string), **not** `/surfaces/<slug>/meta` (the path form makes the
-  engine parse the slug as a record uuid → 404 EV-6).
+  engine parse the slug as a record uuid → 404 EV-6). Unwraps the bundle via **`extractBundle()`**,
+  which locates the bundle by its **structural fingerprint** (the `elements` array) across
+  `raw` / `raw.data` / `raw.data.<route-key>` — because V2 nests a scripted-API return value one
+  level deeper, under a route-keyed slot of `data` (e.g. `data.meta`, `data.surfaces`). On a malformed
+  payload it falls back to an empty-elements bundle so the page never crashes.
 - **`evaluateSurfaceRule`** — the Tier-1 rule evaluator: a **frozen `all/any/none` + `{field,op,value}`
   grammar** that **throws on an unknown op** (generalized from the SalesOrders
   `buildPatchedTenantFields`/`evaluateEnableRule`/`resolveFlag` helpers). Evaluated client-side against
@@ -66,13 +70,14 @@ legacy pre-Surface fallback branches at the wired screens removed). Legacy per-s
 
 ## What's wired
 
-Login + sales-orders list + the sales-order modal + the **Items LIST** screen. The SalesOrder action
+Login + sales-orders list + the sales-order modal + the **Items**, **VendorItems**, and
+**Inventory** LIST screens. The SalesOrder action
 bar reproduces `orderViewFields.json` approve/deny/approvalWorkflow/viewLog/editOrder by delegating
 to the existing `onActionClick`/`onOpenLog` handlers. TABLE-type surfaces stay on the existing
 TableView pipeline via `tableViewSlug` (see [meta-driven-table-data](meta-driven-table-data.md)) —
 the Surface layer references the TableView, never replaces it.
 
-## Per-screen migration recipe (proven on SalesOrders + Items)
+## Per-screen migration recipe (proven on SalesOrders + Items + VendorItems + Inventory)
 
 The screen-by-screen full-app refactor follows one recipe:
 1. Seed the screen's surface(s) in a `Core/*SurfaceSeed.sql` — a TABLE surface that references the
@@ -87,8 +92,51 @@ Keep TABLE rendering on the existing TableView pipeline; only the chrome (action
 moves to Surface. A screen with no client/role/lang variance ships a single DEFAULT bundle (no
 Client overrides), as Items did.
 
+**VendorItems (screen 2)** followed the recipe exactly: `vendor-items-list` (TABLE → TableView 10,
+recordId 19) + `vendor-items-list-actions` (Refresh / Columns[hidden+disabled] / New Vendor Item),
+page+view-model rewired to resolve title+buttons from the bundle, dropped the
+`useClientFields`/`vendorItemsPageFields` dependency, deleted `vendorItemsPageFields.json` + its
+`fieldsConfig/index.ts` entry.
+
+**Inventory (screen 3) — presentation-only, by decision.** Only the page title, header buttons
+(Group by / Refresh), the Group-by modal copy, and the entity icon/color tag map moved to Surface.
+The `inventoryGroupings` `groupings[].levels[]` topology
+(`fetchSlug`/`role`/`additionalDataSlug`/`urlParamKey` driving `GenericNestedTables`) is **data-fetch
+wiring, not presentation**, so per the config/logic boundary it **stays as JSON**. The
+`inventory-list` surface carries `groupByLabels` + `entityTags` in its surface `config`, with
+**recordId+tableViewId NULL** (the page has no single backing Record — it composes
+purchase-orders/items/units via per-level fetchSlugs). Labels + `entityTags` were stripped from both
+DEFAULT and NYCHH `inventoryGroupings.json` (groupings kept) and marked `@deprecated`/optional in the
+`InventoryGroupingsConfig` type.
+
+**The config/logic line for migration:** move presentation (titles, button labels, icons, colors,
+modal copy, visibility/enable) to Surface; **leave data-fetch wiring (fetch slugs, roles, URL params,
+nested-table topology) in JSON/code.** Not every screen reduces to a generic `SurfaceSection` swap —
+see SalesOrders below.
+
+## SalesOrders remaining migration — bespoke, NOT a generic SurfaceSection swap (deferred)
+
+The SalesOrders detail migration is the plan's explicitly-deferred "blessed escape hatch"/approval
+work — it is bespoke-component + business-logic work, not a generic swap. `SalesOrderSummaryGrid` is
+fully tenant-data-driven through three **bespoke renderers**: `detailSection` (blox `DetailSection` +
+custom `renderField`), `locationCard` (`OrderSectionCard`, structured contact data), and `totalsCard`
+(blox `BaseTotals` **with client-specific recurring-lease business logic**:
+`_totalLease !== 0 → recurringKey` fields). The generic `SurfaceSection` (label/value) cannot
+represent `BaseTotals`/`OrderSectionCard`, and the early-seeded order-details/ship-to/bill-to/
+order-summary SECTION surfaces do **not** cleanly map onto the grid's arbitrary client-keyed section
+model. A faithful migration needs a **registered-renderer approach** keyed off surface element config
+(`detailSection`/`locationCard`/`totalsCard` → their components), with the lease logic staying in
+code/`_underscore`, plus reconciling those seeds and the Compass approval-modal state machine.
+**Deferred to a dedicated design-first session.**
+
 ## Gotchas
 
+- **Scripted-API GET return values land under `data.<scriptRoute>`, not `data` directly.** V2 nests a
+  scripted-API return value inside the envelope under a route-keyed slot of `data` (e.g. `data.meta`,
+  `data.surfaces`), one level deeper than a normal data fetch. The bundle hook unwraps this with
+  `extractBundle()` by structural fingerprint (the `elements` array). Consumers (`SurfaceSection`,
+  `SurfaceActionBar`) are hardened to bail to `null` unless `elements` is a real array, so a malformed
+  payload never crashes the page. (Root cause of the "s.elements is not iterable" runtime crash.)
 - **No feature flag, no fallback.** Surface is the enforced path; a missing/broken surface bundle
   does not silently fall back to legacy JSON — that path is deleted per screen as it migrates.
 - **Endpoint is query-string form** — `GET /v2/surfaces/meta?slug=...`, not `/surfaces/<slug>/meta`
@@ -99,6 +147,13 @@ Client overrides), as Items did.
   treat type-checking as pending. Runtime `GET /v2/surfaces/{slug}/meta` also not yet exercised.
 
 ## Change history
+- 2026-06-29 — Migrated VendorItems (screen 2, recipe-exact) and Inventory (screen 3,
+  **presentation-only by decision** — fetch topology stays JSON; only title/buttons/modal copy/entity
+  tags moved). Fixed the "s.elements is not iterable" crash: `extractBundle()` now finds the bundle by
+  its `elements`-array fingerprint across `raw`/`raw.data`/`raw.data.<route-key>` (V2 nests
+  scripted-API returns under `data.<scriptRoute>`), with an empty-bundle fallback + hardened
+  SurfaceSection/SurfaceActionBar guards. Recorded SalesOrders detail as deferred bespoke
+  (registered-renderer + lease logic + approval-modal) work. (jcardinal)
 - 2026-06-29 — DECISION: Surface is now enforced, not flagged — removed `VITE_SURFACE_ENABLED`/
   `SURFACE_ENABLED` (deleted `featureFlag.ts` + all gating/legacy-fallback branches). Fixed
   `useFetchSurfaceMeta` to the query-string endpoint `/surfaces/meta?slug=` (path form 404'd EV-6).

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 ## 2.0 framework
 
 - **_underscore** (_Underscore) _(framework core)_ — 17 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
-- **worker2** (Worker) — 21 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
+- **worker2** (Worker) — 22 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 7 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)

package/package.json

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