toga-ai 1.0.804 → 1.0.805

package/knowledge/2.0/apps/toga-blox/features/primary-table-templates.md

@@ -6,7 +6,7 @@ project: TOGa Blox
 client: shared
 type: feature
 status: active
-updated: 2026-08-31
+updated: 2026-09-14
 owners: [apeterson, tcox]
 files:
   - toga-blox/src/components/Table/themeConfig/toga.module.css
@@ -22,6 +22,7 @@ files:
 related:
   - ../architecture.md
   - table.md
+  - ../../toga25-supply/features/server-table-url-state.md
 ---
 
 ## Summary
@@ -132,6 +133,15 @@ runs unconditionally — it no longer no-ops while `isExpanded`.
 
 ## Gotchas
 
+- **`PrimaryTableServerTemplate` is FULLY controlled — its change handlers fire only on real user
+  interaction.** `state: { sorting, columnFilters }` is passed in and `manualSorting`,
+  `manualFiltering`, and `manualPagination` are all `true`, so `onSortingChange` /
+  `onColumnFiltersChange` **never fire on mount**. That is what makes it safe for the consumer to
+  mutate other URL state (e.g. reset `page` to 1) inside those handlers: no handler runs without
+  user intent, so a shared deep link like `?…_page=3` can never be clobbered on load. blox only
+  *reads* the view state; the app owns the URL. See
+  [toga25-supply server table URL state](../../toga25-supply/features/server-table-url-state.md).
+
 - **Never gate a hover affordance on a JS `mouseleave` inside a virtualized table.** `mouseleave`
   is not guaranteed to fire: a virtualized row can translate out from under a stationary cursor on
   wheel-scroll, and any early-return in the clear handler strands the "hovered" flag set. The toggle
@@ -164,6 +174,9 @@ runs unconditionally — it no longer no-ops while `isExpanded`.
   not the column set.
 
 ## Change history
+- 2026-09-14 — Recorded that the server template is fully controlled (`manual*` + passed-in
+  `state`), so its sort/filter handlers never fire on mount — the property a consumer relies on
+  when resetting pagination from inside those handlers. No code change. (apeterson)
 - 2026-08-31 — Host-tokenized the `supply`-skin table shadow: `.tableAndPaginationInner.supply` /
   `.tableWrapper.supply` now use `box-shadow: var(--primaryTable-box-shadow, 0 1px 3px rgba(0,0,0,0.1))`,
   adding `--primaryTable-box-shadow` to the host-token set (a design review needed the shadow gone and

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

@@ -11,6 +11,7 @@
 | [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 |
 | [Persisted React Query cache (localStorage `supply-chain-query-cache`)](features/persisted-query-cache.md) | `localStorage["supply-chain-query-cache"]` is **not a hand-written cache**. |
 | [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`. |
+| [Server Table URL State (page, sort, filters) — `useServerTableUrlState`](features/server-table-url-state.md) | `src/hooks/useServerTableUrlState.ts` is the app's single source of truth for a server-paged table's **view state**: page, records-per-page, sorting, column fil |
 | [Side navigation & default route — an empty nav renders a BLANK PAGE and gets reported as "cannot log in"](features/side-navigation-and-default-route.md) | The 2.5 side nav is **100% backend-driven** by the `navigation` surface bundle, and the same list also decides **which routes exist** and **where `/` lands**. |
 | [SSO redirect & public-vs-user session gating (useAuthenticationFlow)](features/sso-redirect-and-session-gating.md) | How 2.5 Supply decides, on every navigation, whether an anonymous visitor should be bounced to their client's SSO IdP instead of the local `/login` form. |
 | [Surface Frontend (DB-driven UI consumption, src/surface/)](features/surface-frontend.md) | The frontend consumer of the platform-wide Surface layer — DB-driven UI config fetched from `GET /v2/surfaces/meta?slug=<slug>` instead of statically-imported J |

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

@@ -23,6 +23,7 @@ related:
   - ../architecture.md
   - client-configurable-fields.md
   - meta-driven-table-data.md
+  - server-table-url-state.md
   - surface-frontend.md
   - transfer-orders-page.md
   - ../../dbchanges2/features/surface-layer-schema.md

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

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: feature
 status: active
-updated: 2026-08-28
+updated: 2026-09-14
 owners: [apeterson]
 files:
   - toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx
@@ -22,6 +22,7 @@ related:
   - column-visibility.md
   - record-modals-and-nested-tables.md
   - transfer-orders-page.md
+  - server-table-url-state.md
   - ../../_underscore/features/page-meta-context-field-settings.md
 ---
 
@@ -162,7 +163,10 @@ 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.
+  from the route pathname and owns URL-backed sorting/filters/pagination/active-row state. It is the
+  app's only writer of `<slug>_page`, and it resets the page to 1 on any filter/sort/page-size
+  change — the full param grammar and that rule live in
+  [server-table-url-state](./server-table-url-state.md).
 
 ## Wiring a new page (recipe)
 
@@ -198,6 +202,8 @@ App-side glue (NOT in toga-blox):
   raw camelCase slugs. Plan the label source before building the screen (see above).
 
 ## Change history
+- 2026-09-14 — Pointed the table-state bullet at the new `server-table-url-state` doc, which now
+  owns the `<slug>_*` param grammar and the reset-to-page-1 rule. No code change. (apeterson)
 - 2026-08-28 — Recorded that `_Model_Client_TableView::meta()` emits **no `label`** for a column, so
   every header comes from the page meta and `useAssignTableFieldLabels` **bails on a null `pageMeta`**
   (`if (!pageFields) return table`): a new list screen without a legacy `<slug>-listing` page-meta

package/knowledge/2.0/apps/toga25-supply/features/server-table-url-state.md

@@ -0,0 +1,147 @@
+---
+title: Server Table URL State (page, sort, filters) — `useServerTableUrlState`
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-09-14
+owners: [apeterson]
+files:
+  - toga25-supply/src/hooks/useServerTableUrlState.ts
+  - toga25-supply/src/hooks/useServerTableUrlState.test.ts
+  - toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts
+related:
+  - ../architecture.md
+  - meta-driven-table-data.md
+  - column-visibility.md
+  - record-modals-and-nested-tables.md
+  - ../../toga-blox/features/primary-table-templates.md
+  - ../../../standards/frontend.md
+---
+
+## What it is
+
+`src/hooks/useServerTableUrlState.ts` is the app's single source of truth for a server-paged
+table's **view state**: page, records-per-page, sorting, column filters, filter/sort ordering,
+and the active (clicked) row. It reads that state out of the query string and gives the page
+back handlers that write it. Every list page goes through it — Sales Orders via
+`useSalesOrdersTableState`, and the same shape for the other pages.
+
+All params are **namespaced by the table slug**, so two tables on one URL never collide.
+
+> It is the **only writer of `<slug>_page` in the whole app** (verified by grep across `src/`,
+> 2026-09-14). There is no second pagination code path to keep in sync. `useEntitySearch` is for
+> `advancedSelect` dropdown pickers and holds no pagination URL state; the only "search" on a
+> main table view is blox's per-column `HeaderFilterSearch`, which routes into
+> `handleColumnFiltersChange` here.
+
+## The param grammar
+
+| Param | Meaning |
+|---|---|
+| `<slug>_page` | current page (default `1`) |
+| `<slug>_recordsPerPage` | page size (default `15`) |
+| `<slug>_sort[i]` | sort at position `i`, value prefixed `+` asc / `-` desc |
+| `<slug>_<field>` | bare form = `includes` (substring match) |
+| `<slug>_<field>_starts` / `_ends` / `_eq` / `_excludes` | `startsWith` / `endsWith` / `exactly` / `excludes` |
+| `<slug>_<field>_in` | multi-select over a closed option set — **exact** values, one SQL `IN` |
+| `<slug>_<field>_between` / `_before` / `_after` / `_min` / `_max` | range params, collected into one `{ params }` filter value |
+| `<slug>_<field>_filter` | multi-chip text filter: comma-separated `mode:value` chips, values URL-encoded, all AND'd |
+| `<slug>_<field>_order` | the filter's display order (default `999`) |
+| `<slug>_actionOrder` | shared order of applied filter/sort chips |
+| `<slug>` (bare) | `activeRowUuid` — the open record modal |
+
+The reader loops `searchParams`, matches by suffix, and falls through to `includes` for the bare
+form — which is why the fall-through explicitly **excludes** `_order`, `_sort`, `_page`,
+`_recordsPerPage`, and `_actionOrder` so a control param is never mistaken for a filter. Add a new
+control param and you must add it to that exclusion list.
+
+### `_in` is exact, not `includes`
+
+`_in` used to alias the bare `includes` form, so picking `fulfilled` in a multi-select also matched
+`partiallyFulfilled`. It is now its own `mode = "in"` on the read side with a matching
+`case "in":` on the write side: exact values, serialized downstream as one SQL `IN`.
+
+## How it works — any result-changing param resets to page 1
+
+🚨 **This is the load-bearing rule of the hook.** A change to *which records the server returns* —
+a filter/search, a sort, or a page size — must send the user back to page 1.
+
+One helper, one home:
+
+```ts
+const FIRST_PAGE = "1";
+
+const resetToFirstPage = useCallback(
+    (prev: URLSearchParams) => { prev.set(`${slug}_page`, FIRST_PAGE); },
+    [slug],
+);
+```
+
+Called by all three result-changing handlers — `handleColumnFiltersChange`,
+`handleSortingChange`, `handleRecordsPerPageChange`.
+
+Two details that matter:
+
+1. **The reset is written inside the SAME `setSearchParams(prev => …)` updater** as the
+   filter/sort write. One history entry, one React Query refetch — so the back button undoes the
+   filter and the page together instead of leaving a half state.
+2. **`handleRowClick` deliberately does NOT reset.** Opening a record modal must not throw the
+   user back to page 1. Neither does `handlePageChange`, obviously.
+
+This is the concrete implementation of the rule in
+[`standards/frontend.md` §5](../../../standards/frontend.md) — a param that changes the query
+result belongs in the React Query key *and* resets to page 1.
+
+### Why an app-side reset is safe (it does not clobber deep links)
+
+blox's `PrimaryTableServerTemplate` builds the table **fully controlled**: `state: { sorting,
+columnFilters }` with `manualSorting` / `manualFiltering` / `manualPagination: true`. So
+`onColumnFiltersChange` / `onSortingChange` fire **only on real user interaction, never on mount**.
+Nothing runs a reset on load, which is what lets a shared `?…_page=3` URL survive. The app owns the
+URL state; blox only reads it. The fix therefore needed **no blox change, no publish, no pin bump**
+— confirmed by the install being a real registry copy (no symlink), pinned exactly.
+
+## Gotchas
+
+- **A "backend search returns nothing" report is usually this bug.** Symptom: user on page 2
+  searches for a PO number that lives on page 1 and gets an empty table. The front end sent the
+  new filter with `<slug>_page=2` still set, api2 paged the *new* (filtered) result set from page
+  2, and the single match — now on page 1 — fell outside the slice. It reads exactly like an api2
+  search defect and is not one. Check the query string before you open the API.
+- **Page size worked while search did not.** `handleRecordsPerPageChange` already reset the page;
+  the filter and sort handlers never did. If only *some* controls behave, suspect an incomplete
+  reset rather than a data-layer problem.
+- **Clearing all filters also resets to page 1** — by decision, see below. Do not re-add an
+  `if (next.length > 0)` guard around the reset.
+- **The hook's filter read/write block is a merge hot spot but not a conflict magnet.** Two
+  independent fixes landed in it within days (the page reset, and the `_in` exact-match change a
+  few lines away) and `git merge` resolved them clean with both surviving. Verify both markers by
+  grep after such a merge rather than assuming a loss.
+
+## Tests
+
+Co-located `src/hooks/useServerTableUrlState.test.ts` (Vitest). The reset rule is covered by 8
+cases, every one **seen to fail before the fix** (5 red on the original code): filter applied,
+multi-chip text filter applied, filters cleared, one of two filters removed, sort applied, sort
+cleared, records-per-page changed, and the negative control — **row click must NOT reset**.
+
+Type-check with `npx tsc --noEmit -p tsconfig.app.json`. Bare `npx tsc --noEmit` is a silent no-op
+in this repo (references-only root config — see `standards/frontend.md` §2).
+
+## Decisions
+
+- **2026-09-14 — clearing filters DOES reset to page 1. The opposite was tried and reversed.**
+  Mid-session the reverse was implemented (keep the page on a filter clear, on the reasoning that
+  clearing only widens the result set so page 3 still exists), verified with a mutation test, then
+  deliberately undone. Final behavior: **every** filter change resets, including a full clear.
+  Recorded so nobody re-litigates it or re-adds the guard thinking it was an oversight.
+
+## Change history
+- 2026-09-14 — Documented the hook as its own subject. Added `resetToFirstPage` so filters, sorts,
+  and page-size changes all return to page 1 (fixes "search on page 2 finds nothing", TRUE-81877);
+  recorded the reversed keep-the-page-on-clear decision; noted `_in` is now exact-match not
+  `includes`; deleted ~104 lines of commented-out dead `activeRowUuid`/handler variants from the
+  bottom of the file (503 → 399 lines). (apeterson)

package/knowledge/2.0/apps/toga25-supply/workflows/cypress-testing.md

@@ -6,7 +6,7 @@ project: TOGa 2.5 Supply
 client: shared
 type: workflow
 status: active
-updated: 2026-09-03
+updated: 2026-09-14
 owners: [apeterson]
 files:
   - toga25-supply/cypress.config.ts
@@ -253,10 +253,11 @@ Every `cy:*` script goes through **`node scripts/cypress.mjs`** — see the firs
 
 - **Vitest is the other half.** `npm test` (`vitest run`) currently has **one failing test file**:
   `src/hooks/useTalosSurface.test.ts` fails with
-  `TypeError: Unknown file extension ".css"` on `@agilant/toga-blox/dist/global.css`. 89 tests pass
-  across the other 13 files. **Pre-existing** — the file was last touched in commit `604a779` and
-  the Cypress work changed neither it nor `vitest.config.ts`. Needs a separate fix (Vitest CSS
-  handling for blox imports).
+  `TypeError: Unknown file extension ".css"` on `@agilant/toga-blox/dist/global.css` — the suite
+  fails to **load**, so it is silently skipped in full. **Pre-existing** — the file was last
+  touched in commit `604a779` and the Cypress work changed neither it nor `vitest.config.ts`.
+  Re-confirmed on a clean tree 2026-09-14, with every other file green (148/148 on
+  `_sandbox-client`). Needs a separate fix (Vitest CSS handling for blox imports).
 - **No other mechanical guardrails exist in this repo:** no `.github/workflows`, no husky, no
   lint-staged. The only `.git/hooks/pre-commit` is a machine-local `code-review-graph` shim that
   always exits 0 and is not checked in.
@@ -264,6 +265,9 @@ Every `cy:*` script goes through **`node scripts/cypress.mjs`** — see the firs
   `SurfaceOverrides IS_VISIBLE` row in `dbchanges2`; the fixture only simulates the grant.
 
 ## Change history
+- 2026-09-14 — Re-confirmed the `useTalosSurface.test.ts` / blox `dist/global.css` Vitest load
+  failure on a clean tree and refreshed the pass counts (148/148 on the rest). Still unfixed; it
+  silently costs one whole suite. No code change. (apeterson)
 - 2026-09-03 — **Rebuilt the harness from scratch on `TRUE-81735`** (the `TRUE-79813` harness this
   doc used to describe was never merged and is stranded there). New shape: all `/v2` calls stubbed,
   four tenants (COMPASS/COMPASSCANADA/NYCHH/QUAD), the three-axes model (client = baseUrl, role =

package/knowledge/2.0/standards/frontend.md

@@ -5,12 +5,13 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-09-03
+updated: 2026-09-14
 owners: [jcardinal, apeterson]
 files: []
 related:
   - ../apps/toga25-supply/architecture.md
   - ../apps/toga-blox/architecture.md
+  - ../apps/toga25-supply/features/server-table-url-state.md
   - frontend-deploy.md
   - backend-php.md
 ---
@@ -220,7 +221,18 @@ you are in.
   explicitly cleared" are different states. Use `searchParams.has(key)`, not a truthiness check on
   the value.
 - **A param that changes the query result MUST be part of the React Query key.** Page, sort, and
-  filters belong in the key so a change refetches (and resets to page 1).
+  filters belong in the key so a change refetches.
+- **A param that changes WHICH RECORDS the server returns MUST also reset the page to 1** — in the
+  **same** `setSearchParams(prev => …)` updater as the change itself, so the two land in one
+  history entry and one refetch. This covers filters/search, sort, and page size. It does **not**
+  cover opening a record (a row click must not throw the user back to page 1) or a presentation-only
+  param. Miss it and the app sends the new filter with the old page: the server pages the *new*
+  result set from page 2, the single match now on page 1 falls outside the slice, and the report
+  arrives as "the backend search returns nothing." Verified 2026-09-14 in `toga25-supply` — the
+  rule above was read as query-key-only, so `handleRecordsPerPageChange` reset the page while
+  `handleColumnFiltersChange` and `handleSortingChange` never did. Keep the reset in **one** helper
+  called by every result-changing handler, not inlined per handler. (See
+  `../apps/toga25-supply/features/server-table-url-state.md`.)
 - **A presentation-only param MUST be excluded from the key.** Column visibility changes what you
   see, not what the server returns — putting it in the key forces a pointless refetch. (See
   `../apps/toga25-supply/features/column-visibility.md`.)
@@ -785,6 +797,10 @@ Copy from there rather than reinventing.
 
 ## Change history
 
+- 2026-09-14 — Split §5's query-key bullet: reset-to-page-1 is now its own MUST (same
+  `setSearchParams` updater, one helper, row click excluded). It was previously a parenthetical
+  inside the query-key rule and went unimplemented for filters and sorts in toga25-supply for
+  months. (apeterson)
 - 2026-09-03 — §23 correction: replaced the two "seen to fail" worked examples. The first pass
   listed a guardrail check plus an **unverified** component-config mutation; both are now the two
   mutations that were actually run and observed red (a registry/fixture nav mismatch, and forcing

package/knowledge/INDEX.md

@@ -31,7 +31,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) — 13 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 21 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
-- **toga25-supply** (TOGa 2.5 Supply) — 20 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
+- **toga25-supply** (TOGa 2.5 Supply) — 21 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 14 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)
 

package/package.json

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