toga-ai 1.0.238 → 1.0.239

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

@@ -6,5 +6,6 @@
 | [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 |
+| [Config-Driven Expedited Shipping Gating (Cart)](features/expedited-shipping-gating.md) | On the toga2-commerce **Cart** page, expedited shipping options (**"2nd Day EOB"** and **"Next Day Air"**) are only offered in the *Shipping Method* dropdown wh | toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts, toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx, toga2-commerce/src/pages/Cart/CartPage.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/expedited-shipping-gating.md

@@ -0,0 +1,108 @@
+---
+title: Config-Driven Expedited Shipping Gating (Cart)
+framework: "2.0"
+repo: toga2-commerce
+project: TOGa Commerce
+client: shared
+type: feature
+status: active
+updated: 2026-06-30
+owners: [tcox]
+files:
+  - toga2-commerce/src/pages/Cart/helpers/shippingOptionGates.ts
+  - toga2-commerce/src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts
+  - toga2-commerce/src/pages/Cart/view/cartForm/CartForm.tsx
+  - toga2-commerce/src/pages/Cart/CartPage.tsx
+related:
+  - ../../../../clients/compass-usa/profile.md
+  - ../../../../clients/compass-canada/profile.md
+---
+
+## Summary
+On the toga2-commerce **Cart** page, expedited shipping options (**"2nd Day EOB"** and
+**"Next Day Air"**) are only offered in the *Shipping Method* dropdown when the cart contains
+a **computer kit**. Otherwise they are filtered out of the options, and any previously
+selected expedited method auto-resets to **"Standard Ground"**. The behavior is **config
+driven** — a tenant opts in per shipping-method field via an `optionGates` entry; there is no
+`if (clientSlug === ...)` branching. Omitting `optionGates` means expedited is always shown.
+
+Applies today to all three tenants: **COMPASS**, **COMPASSCANADA** (English + French), and
+**QUAD**.
+
+## Key files / entry points
+- `src/pages/Cart/helpers/shippingOptionGates.ts` (NEW) — pure helpers + types:
+  `ShippingOptionGate` / `ShippingOptionRule`, `filterShippingOptionsByGates`,
+  `getHiddenShippingOptionNames`, `evaluateShippingOptionRule`, `findShippingMethodField`
+  (resolves the shipping field by `valueKey`, **not** by index), `getBaseShippingOptionName` +
+  `SHIPPING_OPTION_LABEL_SEPARATOR`, and `STANDARD_GROUND_SHIPPING_NAME`.
+- `src/pages/Cart/viewModel/FIELDS/shared/shippingOptionGates.ts` (NEW) — the
+  `EXPEDITED_SHIPPING_GATE` config constant: `optionNames` `["2nd Day EOB","Next Day Air"]`,
+  `visibleWhen { item: "primaryItem", path: "item.itemCategory.name", operator: "equals",
+  value: "COMPUTERS" }`.
+- 15 `CARTPAGE.ts` files (COMPASS x4 roles, COMPASSCANADA ENGLISH x4 + FRENCH x4, QUAD x3) —
+  each shipping-method field opts in via `optionGates: [EXPEDITED_SHIPPING_GATE]`.
+- `src/pages/Cart/view/cartForm/CartForm.tsx` — filters `shippingMethodOptions` through the
+  gates (reactive on `cartData.cartBundles`) before the select renders; resolves the shipping
+  field via `findShippingMethodField`; uses `SHIPPING_OPTION_LABEL_SEPARATOR` for the
+  cost-suffix label.
+- `src/pages/Cart/CartPage.tsx` — the warning-modal effect derives expedited names from the
+  config gates; a NEW auto-reset effect (guarded on `dirtyFields.shippingMethod` + loaded
+  options) resets a now-hidden expedited selection back to Standard Ground.
+
+## How it works
+1. The config layer (`EXPEDITED_SHIPPING_GATE`) declares which option names are gated and the
+   condition under which they are *visible* (`visibleWhen`). A shipping-method field opts in by
+   listing the gate in `optionGates`.
+2. A **"computer kit"** is identified by the bundle's **PRIMARY item** —
+   `bundleItemGroup.slug === "primary"` — having `item.itemCategory.name === "COMPUTERS"`. This
+   reuses the same `{ item, path, operator, value }` rule vocabulary as the existing bundle-page
+   one-per-order limit (`evaluateCartQuantityRestriction.ts` + `restrictedQuantity` in
+   `BUNDLEDETAILSPAGE.json` / `CartOverlay/Bundle.tsx`). `value` may be a string **or** a
+   `string[]`, so qualifying categories stay editable in config without code changes.
+3. Cart contents are sourced from `useCartStoreZu` (`cartData.cartBundles`), so detection
+   reacts to add/remove. A computer kit plus a non-computer item (printer/accessory) still
+   shows expedited; removing the kit hides it.
+4. `CartForm` runs `filterShippingOptionsByGates` over the fetched options before rendering the
+   select; `CartPage` runs the auto-reset effect so an already-chosen expedited method does not
+   silently survive once it is no longer offered.
+
+This mirrors the toga2.5 / toga25-supply "named rule" / config-driven cart pattern: tenant
+behavior is expressed in config, not in code branches.
+
+## Gotchas
+- **Compass MacBook catalog categorization is INCONSISTENT, and it breaks the computer-kit
+  assumption.** Verified in prod `Client_Compass.Items`: MacBooks are spread across at least
+  **four** categories — `"APPLE LAPTOP"` (e.g. 14" MacBook Pro M5, partNumber `MDE54LL/A-S`),
+  `"COMPUTERS"` (14"/16" MacBook Pro M4, `MW2W3LLA-S` / `MX2X3LLA-S`), `"MAC & ACCESSORIES"`
+  (~18 older M1/M2 MacBook Air/Pro models), and `"PDC NEW HIRE - APPLE"`. The gate matches
+  `itemCategory.name === "COMPUTERS"` **only**, so MacBooks tagged `APPLE LAPTOP` /
+  `MAC & ACCESSORIES` do **not** qualify for expedited shipping (and would not trigger the
+  one-per-order limit either). Confirmed live on beta and prod: the "Compass 14\" Macbook"
+  kit's primary item resolves to `APPLE LAPTOP`. The backend assumption (Alex) was that all
+  MacBooks were already `COMPUTERS`; the data shows otherwise. **Team decision this session:**
+  keep the rule keyed to `COMPUTERS` only (intended). The fix is **catalog data
+  normalization** (or extending the config `value` list to
+  `["COMPUTERS","APPLE LAPTOP"]`) — it is *not* a code gap. Hand the categorization to the
+  catalog/data team.
+- **The gate is UI-only, not server-enforced.** Shipping methods come from `/shipping-methods`
+  (UPS carrier, fetched in `useCartViewModel`) and are filtered client-side. The gate is a
+  selection restriction, not order validation. Follow-up recommended: enforce
+  expedited-requires-kit at order submission in **api2**.
+- **Only the top-level primary item is scanned.** Nested child-bundle items are not inspected
+  for the computer category (consistent with the existing `checkCartContainsComputerKit`
+  detector). Fine today, but a miss if a `COMPUTERS` item ever lives only in a nested child
+  bundle.
+- **No automated test was added.** The repo has no unit-test runner (Cypress only). Verified
+  via `tsc -b` (clean, twice) and an independent maker≠checker code review. ESLint could not
+  run locally (missing `eslint-plugin-react-compiler` — environment issue).
+
+## Change history
+- 2026-06-30 — Built config-driven expedited-shipping gating: expedited methods shown only
+  when the cart holds a COMPUTERS-category computer kit, with auto-reset to Standard Ground
+  otherwise; tenant opt-in via `optionGates` (no client-slug branching). Code review fixed 3
+  findings: fail-open index read → resolve field by `valueKey`; substring `.includes` match →
+  base-name compare via `getBaseShippingOptionName`; edit-order silent-downgrade/load race →
+  reset guarded on dirty + loaded options. Documented the Compass MacBook category
+  inconsistency as a known gotcha (data-normalization item, not a code gap). (tcox)
+</content>
+</invoke>

package/knowledge/INDEX.md

@@ -27,7 +27,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **talos** (TOGa IQ) — 7 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) — 6 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
+- **toga2-commerce** (TOGa Commerce) — 7 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 7 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/compass-canada/profile.md

@@ -13,11 +13,12 @@ project: _Underscore
 client: compass-canada
 type: profile
 status: active
-updated: 2026-06-26
-owners: [jcardinal, bala]
+updated: 2026-06-30
+owners: [jcardinal, bala, tcox]
 files: []
 related:
   - ../compass-usa/profile.md
+  - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
 ---
 
 ## Summary
@@ -41,6 +42,11 @@ to but distinct from Compass USA. Like Compass USA it spans the **2.0** commerce
   (`1_…` transmit SOs to MITS, `2_…` transmit POs to vendors, `3_…` status from G&T cXML,
   `4_…` import G&T ASNs).
 
+## Storefront notes (toga2-commerce)
+- Runs the same `toga2-commerce` storefront (2.0, consumes api2), with English + French cart
+  configs (COMPASSCANADA ENGLISH / FRENCH). Cart expedited-shipping gating applies here too —
+  see [Config-Driven Expedited Shipping Gating](../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md).
+
 ## Notes
 - Customer language preference: `UserGlobalSettings.settingId = 2` (`en` / `fr-CA`); customer-
   facing emails are sent in EN or FR accordingly.

package/knowledge/clients/compass-usa/profile.md

@@ -12,11 +12,12 @@ project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-06-18
-owners: [jcardinal, bala]
+updated: 2026-06-30
+owners: [jcardinal, bala, tcox]
 files: []
 related:
   - features/asn-to-item-fulfillment.md
+  - ../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md
 ---
 
 ## Summary
@@ -32,7 +33,16 @@ separate, related client (see its own profile).
   Client-specific model overrides live under `_underscore/Model/Compass/`.
 - **1.0:** worker crons under `worker/crons/toga2/compass/` handle email-based imports and
   notifications.
-- Storefront: compass.togacommerce.com / compass.togahub.com.
+- Storefront: compass.togacommerce.com / compass.togahub.com. The storefront app repo is
+  **`toga2-commerce`** (2.0, consumes api2).
+
+## Storefront notes (toga2-commerce)
+- Cart expedited-shipping gating: expedited methods ("2nd Day EOB", "Next Day Air") are shown
+  only when the cart contains a COMPUTERS-category computer kit — see
+  [Config-Driven Expedited Shipping Gating](../../2.0/apps/toga2-commerce/features/expedited-shipping-gating.md).
+  **Known data issue:** many Compass MacBooks are categorized `APPLE LAPTOP` /
+  `MAC & ACCESSORIES`, not `COMPUTERS`, so those kits do **not** qualify for expedited — a
+  catalog-data normalization matter, not a code gap.
 
 ## Vendors & integrations
 - **Office Depot (ODP)** — vendor id 1. ASNs arrive via **cXML** (direct V2 API) and via the

package/package.json

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