toga-ai 1.0.185 → 1.0.186

package/knowledge/2.0/apps/toga2-commerce/INDEX.md

@@ -4,6 +4,7 @@
 |-----|---------|-------|
 | [TOGa Commerce (toga2-commerce / commerce2-react) Architecture](architecture.md) | `toga2-commerce` (npm package name **`commerce2-react`**, product name **TOGa Commerce**) is the customer-facing **B2B commerce storefront** of the 2.0 platform | src/main.tsx, src/App.tsx, src/routes.tsx, src/contexts/AuthContext.tsx, src/contexts/helpers/getLoginSettings.ts, src/api/axiosInstance.ts, src/stores/, src/themeConfig/ThemeContext.tsx, src/fieldsConfig/index.ts, src/hooks/useAssignClientFields.ts, vite.config.ts, package.json |
 | [Cart Notification Emails — duplicate prevention](features/cart-notification-emails.md) | On the cart "Notifications" section a user can add CC email addresses to an order. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/stores/useEmailOptionsStore.ts, src/stores/useCartSalesQuoteZu.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts |
+| [Cart Page — config-driven form architecture (current state + planned refactor)](features/cart-page-config-architecture.md) | The Cart page (`src/pages/Cart/`) is the most config-heavy page in `toga2-commerce`. | src/pages/Cart/CartPage.tsx, src/pages/Cart/view/cartForm/CartForm.tsx, src/pages/Cart/view/cartForm/CartFormSection.tsx, src/pages/Cart/view/cartForm/CartFormRenderer.tsx, src/pages/Cart/view/EditCart.tsx, src/pages/Cart/view/EditOrder.tsx, src/pages/Cart/viewModel/useEditOrderOrEditCartViewModel.ts, src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts, src/hooks/useAssignClientFields.ts |
 | [Client Fields — per-tenant / language / role content & config](features/client-fields.md) | Almost no user-facing text, field layout, or page config is hard-coded in `toga2-commerce`. | src/fieldsConfig/index.ts, src/fieldsConfig/getClientLoginFields.ts, src/fieldsConfig/clientFields/COMPASS.json, src/fieldsConfig/clientFields/COMPASSCANADA.json, src/fieldsConfig/clientFields/QUAD.json, src/hooks/useAssignClientFields.ts, src/hooks/useDynamicConditionalFieldOptions.ts, src/stores/useFieldsStore.ts, src/components/BaseDetailField/BaseDetailField.tsx |
 | [Multi-Tenant Resolution & Theming](features/multi-tenant-theming.md) | `toga2-commerce` serves multiple clients from one codebase. | src/themeConfig/themes.json, src/themeConfig/ThemeContext.tsx, src/themeConfig/types.ts, src/components/ThemeSwitcher/ThemeSwitcher.tsx, src/components/AuthLayout/AuthLayout.tsx, src/api/axiosInstance.ts, src/contexts/AuthContext.tsx, tailwind.config.js |
 | [AWS Amplify Build & Deploy (non-prod environments)](workflows/amplify-build-and-deploy.md) | How `toga2-commerce` (React + Vite, "commerce2-react") builds and deploys on **AWS Amplify**. | toga2-commerce/amplify.yml, toga2-commerce/.gitattributes, toga2-commerce/package.json, toga2-commerce/.github/workflows/sync-stage-environments.yml |

package/knowledge/2.0/apps/toga2-commerce/features/cart-notification-emails.md

@@ -14,7 +14,9 @@ files:
   - src/stores/useEmailOptionsStore.ts
   - src/stores/useCartSalesQuoteZu.ts
   - src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts
-related: []
+related:
+  - 2.0/apps/toga2-commerce/features/cart-page-config-architecture.md
+  - 2.0/apps/toga2-commerce/features/client-fields.md
 ---
 
 ## Summary

package/knowledge/2.0/apps/toga2-commerce/features/cart-page-config-architecture.md

@@ -0,0 +1,155 @@
+---
+title: Cart Page — config-driven form architecture (current state + planned refactor)
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-06-24
+owners: ["apeterson"]
+files:
+  - src/pages/Cart/CartPage.tsx
+  - src/pages/Cart/view/cartForm/CartForm.tsx
+  - src/pages/Cart/view/cartForm/CartFormSection.tsx
+  - src/pages/Cart/view/cartForm/CartFormRenderer.tsx
+  - src/pages/Cart/view/EditCart.tsx
+  - src/pages/Cart/view/EditOrder.tsx
+  - src/pages/Cart/viewModel/useEditOrderOrEditCartViewModel.ts
+  - src/pages/Cart/viewModel/FIELDS/*/*/*/CARTPAGE.ts
+  - src/hooks/useAssignClientFields.ts
+related:
+  - 2.0/apps/toga2-commerce/architecture.md
+  - 2.0/apps/toga2-commerce/features/client-fields.md
+  - 2.0/apps/toga2-commerce/features/cart-notification-emails.md
+  - 2.0/apps/toga25-supply/features/client-configurable-fields.md
+---
+
+## Summary
+
+The Cart page (`src/pages/Cart/`) is the most config-heavy page in `toga2-commerce`. As of
+`_production` it is **config-driven at the field level but hardcoded at the section level**, and it
+renders the cart through **two near-duplicate dual-mode forms** (cart-checkout vs edit-order). A
+config-driven refactor is **planned but not yet implemented** (see *Planned refactor* below). This
+doc records both the current architecture and the agreed target so the work can be picked up without
+re-deriving it. The cart consumes the per-tenant `CARTPAGE.ts` config resolved through
+`useAssignClientFields` — see [client-fields](client-fields.md) for that resolution model.
+
+## Current architecture (`_production`)
+
+```
+CartPage.tsx (~1052 lines)        owns useForm(), watched values, all handlers; picks EditCart vs EditOrder
+  ├─ EditCart.tsx (~596)          cart-checkout mode: sync useEffects + renders <CartForm> (~30 props)
+  └─ EditOrder.tsx (~665)         edit-order mode:    near-duplicate sync useEffects + renders <CartForm>
+       └─ CartForm.tsx (~1074)    HARDCODED section layout (summary / orderFor / shippingAddress /
+                                  costCenter / notifications / confirm) as JSX; calls CartFormSection per section
+            └─ CartFormSection.tsx (~296)   ALREADY config-driven: renders inputs from a `fields` prop,
+                                            honoring visibleWhen / inputButtons / labelButton / isEditable / inputType
+```
+
+`useEditOrderOrEditCartViewModel.ts` is a dispatcher hook that returns one view-model or the other
+based on `inEditMode`. `CartFormRenderer.tsx` exists only on the `implement-config` spike branch
+(reads `section.fields`); it is **not on `_production`**.
+
+### What is already config-driven (keep it)
+- **Field-level rendering** — `CartFormSection` maps over a section's input array and interprets
+  `visibleWhen`, `inputButtons`, `labelButton`, `isEditable`/`isVisible`, `inputType`
+  (advancedSelect / BaseInput / display variants). This mirrors toga2.5's `renderField`/`BaseInput`.
+- **Per-tenant `CARTPAGE.ts`** per client/language/role, resolved via `useAssignClientFields`
+  (React-Query cached) — the same resolution model as toga2.5's `useClientFields`.
+
+### What is NOT config-driven / is duplicated (the refactor target)
+- **Section layout is code, not config** — `CartForm.tsx` (~1074 lines) hardcodes which sections
+  exist and their order in JSX.
+- **The form is built twice** — `EditCart` and `EditOrder` share ~80% of their logic but are
+  separate files, each holding its own copy of the mount / orderFor-cascade / form-sync effects.
+- **Prop drilling** — `CartPage → EditCart/EditOrder → CartForm → CartFormSection` passes ~30 props
+  by hand.
+
+## Gotchas (current state — all pre-existing on `_production`)
+
+- **Config-key naming drift.** `CARTPAGE.ts` uses `inputs:` for the `orderFor` section but
+  `formFields:` for `shippingAddress` / `costCenter` / `notifications`, while `CartFormSection`
+  reads a `fields` prop. Three names for one concept; `CartForm` hand-maps each section's array into
+  the `fields` prop. This pre-existing drift is what tripped the prior spike. (Target: rename all to
+  a single `fields` key.)
+- **`useForm` is seeded with a hardcoded union of every client's fields.** `CartPage.tsx`
+  (~lines 230–258) calls `useForm` with one static `defaultValues` object that is the **union** of
+  all clients' fields, with the **COMPASS-only magic shipping-method UUID `087a9d0b-…` baked in**.
+  Two mode-change `reset()` effects (~lines 267, 282) re-seed from that same union shape. This is
+  wrong for per-client field sets: it registers fields a client never renders and bakes one client's
+  default into all of them, and risks RHF controlled/uncontrolled warnings.
+- **Client differences are hardcoded, not config.** Examples observed: COMPASS renders
+  `DuplicateKitGuardrail`, QUAD does not; COMPASS seeds the cart form (cost center / manager / emails)
+  from the order-for user, QUAD does not. These are per-client conditionals in cart code today.
+- `useAssignClientFields.ts` returns `FIELDS?.[clientName]?.[language]?.[role]` with no transform —
+  there is no fallback (a missing combo renders empty). See [client-fields](client-fields.md).
+
+## Planned refactor (DECIDED 2026-06-24 — plan only, not implemented)
+
+**Approach (Route B): rebuild the config-driven cart from the working `_production` branch**, using
+the broken `implement-config` spike branch only as a *reference blueprint* (its target-shaped files
+— `CartFormContext`, `CartFormRenderer`, `useCartFormViewModel`, `useCartFormSync`, standalone
+sections — are architecturally sound but mid-rename and non-functional; lift code where correct,
+do not finish that branch). Rationale: the spike's −3,940-line deletion silently dropped real
+behavior (email seeding, duplicate-email validation, edit-order cost-center/address). The risk is
+**behavior parity, not architecture**, so migrate in verifiable slices against the running
+`_production` app as the oracle. Target pattern = toga2.5 (`toga25-supply`): one form, section
+layout from config, state via context, consolidated sync effects.
+
+Plan document (in the toga2-commerce repo, not in the KB):
+`docs/reviews/implement-config-cart-refactor-PLAN.md`.
+
+Phases: **P0** pin a behavior oracle + inventory hardcoded client branches · **P1** behavior-neutral
+config-key rename (`inputs`/`formFields` → single `fields`) · **P2** `CartFormContext` to kill
+prop-drilling + config-derived form defaults · **P3** consolidate the dual view-models and the three
+sync effects into `useCartFormViewModel` + `useCartFormSync`, branching on `inEditMode` once · **P4**
+drive section layout from config (`type` + dispatch map with explicit fallback) + capability flags,
+then delete `CartForm`/`EditCart`/`EditOrder` · **P5** hydration memo + standards sweep (magic UUID
+removed from code, lives in config).
+
+### Key principle established — client behavior comes from config, never `if (client === ...)`
+
+A new client must be onboarded by **editing `CARTPAGE.ts`**, not by adding `clientSlug` branches to
+cart code. Two flavors, modeled exactly on toga2.5's SalesOrder approval pattern (config carries
+`approvalActionStatuses` + `approveButtonRule:{type:"requireStepTwoAssigned"}`; a pure
+`evaluateApproveRule(rule, ctx)` switch over a discriminated union in `useApprovalModalViewModel.tsx`
+interprets it — the component never knows it is COMPASS):
+
+1. **Capability flags** — pure on/off presence, no runtime data:
+   `capabilities.duplicateKitGuardrail.isEnabled` (COMPASS true, QUAD omits). The renderer reads the
+   flag to decide whether to mount `DuplicateKitGuardrail`.
+2. **Named rules** — conditional logic depending on runtime data, declared as `{ type }` and
+   evaluated generically: e.g. `orderForSeedRules: [{type:"seedCostCenterFromUser"}, …]` iterated by
+   an `applySeedRule` evaluator in `useCartFormSync` (mirrors `evaluateApproveRule`). QUAD omits the
+   rules → seeds nothing, no branch.
+
+### Config-derived form defaults (cart-specific extension of the toga2.5 pattern)
+
+The config already enumerates exactly the fields a client renders, so derive `useForm`
+`defaultValues` from it via a `buildCartDefaultValues(fields, ctx)` builder with three sources:
+- per-field `defaultValue` in config (where the COMPASS shipping UUID **moves to**; QUAD omits it);
+- type-derived empties (`text`/`textArea`→`""`, `checkbox`→`false`,
+  `select`/`advancedSelect`→`{uuid:"",name:""}`);
+- dynamic `defaultValueRules` reusing the same `{type}` rule shape
+  (e.g. `currentUserWhenNotEditable`, `fromSalesOrderErpEntity`).
+
+The two mode-change `reset()` effects call the **same builder** so defaults and rendered inputs can
+never drift. Noted honestly: toga2.5 uses a *static* `emptyItemDefaults` because its item-create form
+is a single shape; the cart is genuinely multi-shape per client, so config-derived defaults is a
+**cart-specific extension** of toga2.5's philosophy, not a literal copy.
+
+> The general "no `if (client === ...)` — drive client behavior from config via capability flags and
+> named rules evaluated by a generic evaluator" rule, applied across 2.0 React frontends beyond just
+> the cart, is being proposed as a team **standard** separately (senior-owned / pending approval).
+
+## Change history
+- 2026-06-24 — Initial: documented the current `_production` Cart architecture (field-level config
+  via `CartFormSection`, hardcoded section layout in `CartForm`, dual `EditCart`/`EditOrder` forms +
+  dispatcher VM, prop-drilling), its gotchas (config-key drift `inputs`/`formFields`/`fields`,
+  hardcoded union `defaultValues` with the COMPASS magic shipping UUID, hardcoded per-client
+  branches), and the DECIDED config-driven refactor approach (rebuild from `_production`, branch as
+  blueprint; capability flags + named rules à la toga2.5 approval; config-derived
+  `buildCartDefaultValues`). Plan only — not implemented (apeterson)
+</content>
+</invoke>

package/knowledge/2.0/apps/toga2-commerce/features/client-fields.md

@@ -22,6 +22,7 @@ related:
   - 2.0/apps/toga2-commerce/architecture.md
   - 2.0/apps/toga2-commerce/features/multi-tenant-theming.md
   - 2.0/apps/toga2-commerce/features/cart-notification-emails.md
+  - 2.0/apps/toga2-commerce/features/cart-page-config-architecture.md
 ---
 
 ## Summary

package/knowledge/INDEX.md

@@ -26,7 +26,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **talos** (TOGa IQ) — 6 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **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) — 5 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 6 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)
 - **toga-blox** (TOGa Blox) — 7 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 

package/knowledge/clients/quad/profile.md

@@ -5,6 +5,7 @@ apps:
   - _underscore
   - api2
   - toga2-supply
+  - toga2-commerce
   - dbchanges2
 project: _Underscore
 client: quad

package/package.json

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