toga-ai 1.0.165 → 1.0.166

package/knowledge/2.0/apps/toga-blox/INDEX.md

@@ -0,0 +1,11 @@
+# toga-blox (TOGa Blox) — 2.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [TOGa Blox (toga-blox) Architecture](architecture.md) | `toga-blox` (npm package **`@agilant/toga-blox`**) is the **shared React + TypeScript component / template / utility library** reused across the 2.0 frontends — | toga-blox/package.json, toga-blox/src/components/index.ts, toga-blox/src/api/index.ts, toga-blox/src/templates/index.ts |
+| [AdvancedSelect (virtualized single/multi select)](features/advanced-select.md) | `AdvancedSelect<T>` is a **fully controlled, virtualized** single/multi select built from scratch (not react-select) on **`@tanstack/react-virtual`**, for large | toga-blox/src/components/AdvancedSelect/AdvancedSelect.tsx, toga-blox/src/components/AdvancedSelect/AdvancedSelect.types.ts, toga-blox/src/components/AdvancedSelect/AdvancedSelect.module.css |
+| [API client (axios wrapper, auth, table-data fetchers)](features/api-client.md) | `src/api/` is a thin **axios** wrapper that standardizes the **2.0 API envelope**, manages auth (Bearer + refresh), serializes complex query options, and provid | toga-blox/src/api/index.ts, toga-blox/src/api/axiosInstance.ts, toga-blox/src/api/apiFunctions.ts, toga-blox/src/api/auth.ts, toga-blox/src/api/genericApi.ts, toga-blox/src/api/types.ts, toga-blox/src/api/tableData |
+| [BaseInput (react-hook-form field factory)](features/base-input.md) | `BaseInput` is a **form-field factory** driven by react-hook-form. | toga-blox/src/components/BaseInput/BaseInput.tsx, toga-blox/src/components/BaseInput/BaseInput.types.ts, toga-blox/src/components/BaseInput/BaseInput.module.css, toga-blox/src/components/BaseInput/components |
+| [Primary Table templates (server/client, sizing, virtualization)](features/primary-table-templates.md) | `src/templates/PrimaryTable/` is the **production, wired-up table** built on the [Table component](table.md). | toga-blox/src/templates/PrimaryTable/PrimaryTable.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableServerTemplate.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableClientTemplate.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableHeaderCell.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableBodyCell.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableRow.tsx, toga-blox/src/templates/PrimaryTable/PrimaryTableExpandableRow.tsx, toga-blox/src/templates/PrimaryTable/types.ts |
+| [TableRecordModal (record-detail modal shell)](features/table-record-modal.md) | `TableRecordModal` is a **generic, presentational modal shell** for showing a single table record (row) in detail — typically opened from a table row click. | toga-blox/src/components/TableRecordModal/TableRecordModal.tsx, toga-blox/src/components/TableRecordModal/index.ts, toga-blox/src/components/TableRecordModal/tableRecordModal.module.css |
+| [Table component (cells, action cells, filters & sorts, hooks, theming)](features/table.md) | The `Table` component (`src/components/Table/`) is the **TanStack Table v8** building block behind the [Primary Table templates](primary-table-templates.md). | toga-blox/src/components/Table/index.ts, toga-blox/src/components/Table/types.ts, toga-blox/src/components/Table/utils/buildTanstackColumns.tsx, toga-blox/src/components/Table/utils/resolveCellType.tsx, toga-blox/src/components/Table/components/cellTypes, toga-blox/src/components/Table/components/actionCells, toga-blox/src/components/Table/components/columnFiltersAndSorts, toga-blox/src/components/Table/hooks, toga-blox/src/components/Table/themeConfig |

package/knowledge/2.0/apps/toga-blox/architecture.md

@@ -0,0 +1,123 @@
+---
+title: TOGa Blox (toga-blox) Architecture
+framework: "2.0"
+repo: toga-blox
+project: TOGa Blox
+client: shared
+type: architecture
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - toga-blox/package.json
+  - toga-blox/src/components/index.ts
+  - toga-blox/src/api/index.ts
+  - toga-blox/src/templates/index.ts
+related:
+  - features/table.md
+  - features/primary-table-templates.md
+  - features/table-record-modal.md
+  - features/base-input.md
+  - features/advanced-select.md
+  - features/api-client.md
+---
+
+## Summary
+
+`toga-blox` (npm package **`@agilant/toga-blox`**) is the **shared React + TypeScript
+component / template / utility library** reused across the 2.0 frontends — `toga2-view`,
+`toga2-supply`, `toga25-supply`, `toga2-commerce`, and `toga2-hub`. It is **not a PHP
+framework repo**: it has no `_underscore` backend code. It is filed under `2.0/` because
+every consumer is a 2.0 app, but structurally it is a standalone front-end package
+(`dependsOn: []`).
+
+It ships: presentational + data-aware **components** (`src/components/`), opinionated
+**templates** that wire components into ready-to-use screens (`src/templates/`, e.g.
+`PrimaryTable`, `Login`, `AddNotes`), a thin **API client** over axios + React Query
+(`src/api/`, `src/reactQuery/`), and **utilities** (`src/utils/`). It builds with `tsc`
+to `dist/` (not bundled), develops via Storybook, and tests with Vitest.
+
+**Critical rules:**
+- **The API client is inert until initialized.** A consumer **must** call
+  `createAxiosInstance({ baseURL, onLogout })` then `setAxiosInstance(instance)` once at
+  startup, or every `apiGet/Post/Put/Delete` throws "no axios instance registered". See
+  [api-client](features/api-client.md).
+- **`BaseInput` requires a react-hook-form `<FormProvider>` ancestor** — it calls
+  `useFormContext()` and throws outside one. See [base-input](features/base-input.md).
+- This is a **published library** — a breaking change to any exported prop/type ripples to
+  all five consuming apps at their next `@agilant/toga-blox` bump. Treat exported component
+  props and `src/api` signatures as a public contract; bump and publish via the beta flow.
+- Styling is **CSS Modules + CSS custom properties** (`var(--toga-*)`, `var(--baseInput-*)`,
+  etc.) injected by `themeConfig/ThemeProvider`. Skins/themes are selected by prop, colors by
+  CSS variables on `document.documentElement` — never hardcode palette values in components.
+
+## Package & build
+
+| Aspect | Detail |
+|---|---|
+| Name / type | `@agilant/toga-blox`, published to npm (beta tag for pre-release) |
+| Build | `npm run build` → `tsc` emit to `dist/` + copy `*.scss/*.css/*.module.css` + assets, then `scripts/fix-esm-imports.mjs` and `scripts/fix-asset-imports.mjs` post-process import paths |
+| Dev | `npm run dev` (nodemon rebuild) and `npm run blox` (Storybook on :6006) |
+| Test | `npm run test` (Vitest) |
+| CSS | `npm run build-css` (Tailwind → `dist/main.css`); components also use CSS Modules |
+
+Because the build is `tsc`-emit (not a bundler), **post-build scripts rewrite import
+specifiers** so the emitted ESM resolves correctly and asset imports point at `dist/assets`.
+A consumer installs the package and imports from `@agilant/toga-blox`.
+
+## Layout
+
+```
+src/
+├── components/      # the component catalog (Table, BaseInput, AdvancedSelect, TableRecordModal, …)
+│   └── index.ts     # public barrel — what consumers import
+├── templates/       # opinionated, wired-up screens
+│   ├── PrimaryTable/ # the production table template (server/client variants)
+│   ├── Login/
+│   └── AddNotes/
+├── api/             # axios client, auth, generic CRUD, table-data fetchers
+├── reactQuery/      # useApiQuery / useApiMutation wrappers + query helpers
+└── utils/           # formatters (currency, phone), endpoint resolution, etc.
+```
+
+**Components vs. templates.** A *component* (e.g. `BaseInput`, `AdvancedSelect`, the Table
+primitives) is a reusable building block. A *template* (e.g. `PrimaryTable`) composes
+components + hooks + the API client into a drop-in feature. The Table story is split across
+both: low-level pieces and cell/filter components live in `src/components/Table/`, while the
+fully-wired table lives in `src/templates/PrimaryTable/`. See
+[primary-table-templates](features/primary-table-templates.md).
+
+## Data layer
+
+`src/api/` is a thin wrapper over **axios** that standardizes the **2.0 API envelope**
+(`{ isSuccess, status, error, messages, data, meta, transactionId, ... }`), auto-injects a
+Bearer token + a per-request `transactionId`, and retries once on 401 via a refresh-token
+flow before logging out. `src/reactQuery/` wraps those helpers as `useApiQuery` /
+`useApiMutation`. Table data fetching (`src/api/tableData/`) serializes table view metadata
+(fields, joins, sorts, filters, pagination) into the API's query-string option format. Full
+detail in [api-client](features/api-client.md).
+
+## Theming
+
+`src/components/Table/themeConfig/ThemeProvider.tsx` wraps the app and injects a client
+`ClientTheme` (`{ id, name, vars }`) as CSS custom properties on `document.documentElement`.
+Components reference those variables in CVA variants and CSS Modules. Table supports named
+**skins** (`supply`, `desk`, `supply-nested`, `supply-modal-table`) selected by the `skin`
+prop. Form inputs theme via `--baseInput-*` variables.
+
+## Consumers
+
+`toga2-view`, `toga2-supply`, `toga25-supply`, `toga2-commerce`, `toga2-hub`. These apps
+talk to the 2.0 API (`api2` over `_underscore`); `toga-blox` is the shared presentation +
+client layer they all build on. (These consumers are not registered as `dependsOn` here —
+the dependency runs the other way, app → library; record it on the consuming app's doc when
+relevant.)
+
+## Related docs
+
+- [Table component](features/table.md) — cell types, action cells, filters/sorts, hooks, utils, theming.
+- [Primary Table templates](features/primary-table-templates.md) — the wired server/client table + measure-and-freeze sizing.
+- [TableRecordModal](features/table-record-modal.md) — the record-detail modal shell.
+- [BaseInput](features/base-input.md) — the react-hook-form field factory.
+- [AdvancedSelect](features/advanced-select.md) — virtualized single/multi select.
+- [API client](features/api-client.md) — axios wrapper, auth, table-data fetchers.

package/knowledge/2.0/apps/toga-blox/features/advanced-select.md

@@ -0,0 +1,73 @@
+---
+title: AdvancedSelect (virtualized single/multi select)
+framework: "2.0"
+repo: toga-blox
+project: TOGa Blox
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - toga-blox/src/components/AdvancedSelect/AdvancedSelect.tsx
+  - toga-blox/src/components/AdvancedSelect/AdvancedSelect.types.ts
+  - toga-blox/src/components/AdvancedSelect/AdvancedSelect.module.css
+related:
+  - ../architecture.md
+  - base-input.md
+---
+
+## Summary
+
+`AdvancedSelect<T>` is a **fully controlled, virtualized** single/multi select built from
+scratch (not react-select) on **`@tanstack/react-virtual`**, for large option sets. Features:
+client- or server-side search, infinite pagination, keyboard navigation, chips (multi),
+initials avatars, secondary labels, and error/dirty display. It is the select used by
+[`BaseInput`](base-input.md) for `advancedSelect` / `advancedMultiSelect`.
+
+## API (discriminated union by `mode`)
+
+`AdvancedSelectProps<T> = AdvancedSelectSingleProps<T> | AdvancedSelectMultiProps<T>`.
+
+Common (`AdvancedSelectBaseProps<T>`): `data: T[]`, `getOptionValue/getOptionLabel`
+(required), `getOptionSecondaryLabel?`, `showAvatar?` + `getOptionAvatarText?`,
+`findSpecificValue?` (async server search), `searchDebounceMs?` (350), `searchMinChars?` (3),
+`hasMorePages?` + `isFetchingMore?` + `fetchMoreData?` (infinite scroll), `rowHeight?` (36),
+`maxVisibleRows?` (8), `overscan?` (6), `errorMessage?`, `isFieldDirty?`, `isFieldError?`,
+`disabled?`, `valueKey?`, `onOpen/onClose/onClearInput?`.
+
+- **single**: `value: T | null | undefined`, `onSelect: (item: T | null, valueKey?) => void`.
+- **multi**: `value: T[]`, `onSelect: (items: T[], valueKey?) => void`.
+
+`AdvancedSelectOption<T> = { value, label, secondaryLabel?, item }`.
+
+## Behavior
+
+- **Data source**: `searchResults ?? data`. Mapped to internal options; selected values held
+  in a `Set` for O(1) lookup. **Selected items always float to the top** (stable order).
+- **Client search** (no `findSpecificValue`): filters `data` by `label.includes(query)`.
+  **Server search**: when `input.length >= searchMinChars`, debounced call, previous request
+  **aborted via `AbortController`**; pagination is disabled while search results are active.
+- **Infinite scroll**: when the virtualizer reaches the last row and `hasMorePages`, calls
+  `fetchMoreData()` (with a shimmer loader row).
+- **Keyboard**: ArrowUp/Down move `activeIndex`, Enter selects, Escape closes, Backspace on an
+  empty multi input removes the last chip. Single-select closes on pick and clears the search
+  text; multi keeps the menu open and re-focuses the input.
+- **Controlled**: selection state lives in the parent via `value`/`onSelect`; only UI state
+  (open, input text, activeIndex, searchResults) is local.
+- CSS Modules + CSS variables (shares `--baseInput*` dirty/error styling); shimmer keyframe for
+  the loading row.
+
+## Gotchas
+
+- **`renderOption` prop is declared but unused** — option rendering is hardcoded (primary +
+  secondary label, check/checkbox, avatar). Treat custom rendering as not yet supported.
+- Single-select with a `secondaryLabel` and menu closed shows a styled two-line value; the
+  native input collapses to width 0 (`.inputCollapsed`).
+- Selected-float-to-top is **not** configurable.
+- `mode` is checked at runtime (`mode === "multi"`) — mismatched value/onSelect types can slip
+  past TypeScript's union if cast.
+- No built-in required validation or full ARIA listbox/option roles (aria-labels on buttons only).
+
+## Change history
+- 2026-06-23 — Documented AdvancedSelect: virtualization, client/server search with abort, infinite scroll, keyboard nav, single/multi modes, and the unused `renderOption` caveat (apeterson).

package/knowledge/2.0/apps/toga-blox/features/api-client.md

@@ -0,0 +1,100 @@
+---
+title: API client (axios wrapper, auth, table-data fetchers)
+framework: "2.0"
+repo: toga-blox
+project: TOGa Blox
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - toga-blox/src/api/index.ts
+  - toga-blox/src/api/axiosInstance.ts
+  - toga-blox/src/api/apiFunctions.ts
+  - toga-blox/src/api/auth.ts
+  - toga-blox/src/api/genericApi.ts
+  - toga-blox/src/api/types.ts
+  - toga-blox/src/api/tableData
+related:
+  - ../architecture.md
+  - table.md
+---
+
+## Summary
+
+`src/api/` is a thin **axios** wrapper that standardizes the **2.0 API envelope**, manages
+auth (Bearer + refresh), serializes complex query options, and provides CRUD + table-data
+fetchers. `src/reactQuery/` wraps it as `useApiQuery` / `useApiMutation`.
+
+**The client is inert until initialized**: a consumer must call
+`createAxiosInstance({ baseURL, onLogout? })` then `setAxiosInstance(instance)` once at
+startup. Otherwise `apiGet/Post/Put/Delete` throw "no axios instance registered".
+
+## Core helpers (`apiFunctions.ts`)
+
+`apiGet<T>(route, options?, params?)`, `apiPost<T>(route, data, options?, params?)`,
+`apiPut<T>(...)`, `apiDelete<T>(...)`. `options` is serialized to a query string via
+`assembleOptions()` (reactQuery/queryHelpers): `fields` → comma list (nested → dot notation),
+`where` → `(field:op:value,AND/OR,…)` (ops: like/contains/starts/ends/in/between/ge/le/gt/lt/
+eq/ne/excludes), `join`/`ojoin` → `Table:a=b;…`, `sort` → `+field,-field`. `apiDelete` allows
+status < 500.
+
+## Axios instance (`axiosInstance.ts`)
+
+`createAxiosInstance({ baseURL, onLogout })`: `Content-Type: application/json`, `timeout
+180000` (3 min). Interceptors: (1) inject a per-request `transactionId` UUID; (2) inject
+`Authorization: Bearer <accessToken>` from localStorage, falling back to `fetchPublicToken()`;
+(3) on **401**, call `refreshAccessToken()` and retry once (`_retry` guard) — on failure call
+`onLogout` (default `performLogout()`, which clears tokens and redirects to `/`).
+
+## Auth (`auth.ts`)
+
+`performLogout`, `fetchPublicToken(baseURL)` (`POST /auth/public`), `refreshAccessToken(baseURL)`
+(`POST /auth/refresh` with refresh-token bearer), `validateEmailDomain(email)`,
+`submitLoginPassword(email, password, fields)` (`POST /auth/login`),
+`handleClientAuthentication(uuid)` (encrypted-uuid SAML/SSO). Tokens stored in localStorage
+(`accessToken`, `refreshToken`, `user`). `AuthResponse = { data: { tokens{access,refresh},
+user{firstName,lastName,uuid} }, messages? }`.
+
+## Generic CRUD (`genericApi.ts`)
+
+`getData(slug, fields?)` (auto-paginates at recordsPerPage 1000, returns flattened array;
+slug → camelCase response key), `saveData(slug, payload, returnPayloadDepth?)`,
+`updateData(slug, uuid, payload, returnPayloadDepth?)`, `deleteData(slug, uuid)`,
+`deleteAddress(uuid)`, `fetchCoreParameters()`. `returnPayloadDepth` appends `?depth=-1` for
+nested data.
+
+## Table data (`tableData/`)
+
+`getDataTableData(tableViewMeta, additionalData?, extraFields?, searchParams?, options?)` —
+builds the request from `DataTableMetaProp`: fields (incl. hyperlink/imageUrl), pagination
+(URL `${slug}_page` / `${slug}_recordsPerPage`), sorting (`${slug}_sort[i]=±field`), filtering
+(`${slug}_${field}_<op>` → `where.and[]`), joins (`table@alias` syntax for duplicate tables),
+plus `additionalData`, `_status`, and `apiWhereClause` — all AND-joined.
+`getDataTableMeta(slug)` (`GET /table-views/meta`), `getPageMeta(page, app)`,
+`getColumnFieldFilterOptions(recordRoute, options?, params?)`.
+
+## Envelope & types (`types.ts`)
+
+`ApiResponse<T> = { transactionId, timestamp, authority, audience{client,user,app}, isSuccess,
+status, error, messages[], meta{depth}, data: T }`. Other types: `Options`, `OptionsType`,
+`TableViewField` (slug vs `tableViewField` DB path, `type`, `isVisible/Editable/Sortable/
+Filterable`, `hyperlinkField`, `imageUrlField`, `sticky`, `precision`, …), `DataTableMetaProp`,
+`DataTableMetaFormatted`, `SamlData`. Base URL resolution via
+`utils/getEndpointFromEnvironment.ts` (env `VITE_API` / `VITE_API_<HOST>`; pattern
+`api.<env>.togahub.com`).
+
+## Gotchas
+
+- **Must `setAxiosInstance` before use** — otherwise every call throws.
+- Always check `response.isSuccess` before reading `data`; `data` keys are **camelCased slugs**
+  (`/sales-orders` → `data.salesOrders`).
+- `TableViewField.slug` (URL-safe) ≠ `tableViewField` (DB column path); `getDataTableData` maps
+  slug → DB field.
+- Only **401** auto-retries; other network errors need React Query `retry`.
+- 401 refresh needs a `refreshToken` in localStorage, else it logs out (hard redirect to `/`).
+- `transactionId` is injected automatically (request tracing); `depth=-1` returns hydrated nesting.
+
+## Change history
+- 2026-06-23 — Documented the API client: axios init contract, auth/refresh interceptors, query-option serialization, generic CRUD, table-data fetchers, and the 2.0 response envelope (apeterson).

package/knowledge/2.0/apps/toga-blox/features/base-input.md

@@ -0,0 +1,70 @@
+---
+title: BaseInput (react-hook-form field factory)
+framework: "2.0"
+repo: toga-blox
+project: TOGa Blox
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - toga-blox/src/components/BaseInput/BaseInput.tsx
+  - toga-blox/src/components/BaseInput/BaseInput.types.ts
+  - toga-blox/src/components/BaseInput/BaseInput.module.css
+  - toga-blox/src/components/BaseInput/components
+related:
+  - ../architecture.md
+  - advanced-select.md
+---
+
+## Summary
+
+`BaseInput` is a **form-field factory** driven by react-hook-form. Given a `Field` config
+object it renders the right input sub-component by `inputType` and wires validation, error
+display, and dirty-state styling through `useFormContext()`. **It must be rendered inside a
+react-hook-form `<FormProvider>`** or it throws.
+
+## API
+
+Exported default: `BaseInput: React.FC<BaseInputTypes>`. Two config surfaces:
+- **`field?: Field`** (BaseInput.types.ts) — the per-field config: `uuid`, `valueKey`,
+  `inputType`, `inputLabel`, `placeholder`, `isRequired`, `showRequiredIndicator`,
+  `characterLimit`, select data (`data`, `getOptionValue/Label/SecondaryLabel`,
+  `fetchMoreData`, `findSpecificValue`, `showAvatar`), etc.
+- **`BaseInputTypes`** top-level props — many duplicate `Field` keys (act as
+  fallbacks/overrides) plus styling-class props and toggle-specific props
+  (`toggleTextPosition`, `toggleActiveLabel`, etc.). `valueKey` is the one required prop.
+
+## Input types (switch on `inputType`)
+
+`text` → `BaseTextInput` (icon, `hasTypeCheck` number/currency regex, phone/currency
+formatters), `textArea` → `BaseTextareaInput` (char counter, max-height 5lh), `toggle` →
+`BaseToggle` (wraps `ToggleButton`), `checkbox` → `BaseCheckbox` (SVG check), `radio` →
+`BaseRadioInput` (SVG circles; options are `{value,label}[]`), `disabledSelect` →
+`DisabledSelect` (read-only + lock icon), `advancedSelect` / `advancedMultiSelect` →
+[`AdvancedSelect`](advanced-select.md) (single/multi). Legacy `BaseSelect`/`BaseMultiSelect`
+(react-select) exist but are **not** used by the factory.
+
+## Validation / state
+
+- Validation via react-hook-form `Controller` rules: required → "Required field."; text
+  `hasTypeCheck` patterns: number `/^[0-9]*\.?[0-9]*$/`, currency
+  `/^(\d+|\d{1,3}(,\d{3})+)(\.\d{1,2})?$/`.
+- Errors/dirty read from `formState.errors` / `dirtyFields`; UUID-scoped when
+  `requireUuidField`, else keyed by `valueKey`. `getNestedValue` walks dotted paths.
+- `BaseErrorMessage` renders the message; dirty fields get `--baseInputDirty-*` border, errors
+  `--baseInputError-*`. CSS Modules + CSS variables (`--baseInput-*`); shared sub-components in
+  `components/` (`BaseErrorMessage`, `CharacterLimitMessage`, `Option`, `SingleValue`,
+  `DropDownIndicator`, `MultiValueRemove`).
+
+## Gotchas
+
+- **Requires `<FormProvider>`** (uses `useFormContext()`).
+- `Field` keys and top-level props overlap; `Field` generally wins — don't set both expecting
+  the prop to override.
+- Currency formats **on blur**; phone formats **on keystroke**.
+- Missing `aria-required` / `aria-invalid` / `aria-describedby` — labels + visual asterisk only.
+
+## Change history
+- 2026-06-23 — Documented BaseInput as a react-hook-form field factory: input-type switch, validation/dirty handling, and the FormProvider requirement (apeterson).

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

@@ -0,0 +1,86 @@
+---
+title: Primary Table templates (server/client, sizing, virtualization)
+framework: "2.0"
+repo: toga-blox
+project: TOGa Blox
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - toga-blox/src/templates/PrimaryTable/PrimaryTable.tsx
+  - toga-blox/src/templates/PrimaryTable/PrimaryTableServerTemplate.tsx
+  - toga-blox/src/templates/PrimaryTable/PrimaryTableClientTemplate.tsx
+  - toga-blox/src/templates/PrimaryTable/PrimaryTableHeaderCell.tsx
+  - toga-blox/src/templates/PrimaryTable/PrimaryTableBodyCell.tsx
+  - toga-blox/src/templates/PrimaryTable/PrimaryTableRow.tsx
+  - toga-blox/src/templates/PrimaryTable/PrimaryTableExpandableRow.tsx
+  - toga-blox/src/templates/PrimaryTable/types.ts
+related:
+  - ../architecture.md
+  - table.md
+---
+
+## Summary
+
+`src/templates/PrimaryTable/` is the **production, wired-up table** built on the
+[Table component](table.md). Three entry points:
+
+- **`PrimaryTable`** — pure render component. Takes an already-built TanStack `table`
+  instance + `tableViewFieldMap` and renders header, body (virtualized), and pagination.
+- **`PrimaryTableServerTemplate`** — wraps `useTableSetup()`; **consumer owns** sorting,
+  filtering, and pagination state (passes `handleSortingChange`, `handleColumnFiltersChange`,
+  etc.). Use for server-side data.
+- **`PrimaryTableClientTemplate`** — wraps `useTableSetup()`; **owns state internally**
+  (sorting/filtering/pagination), `initialPageSize` default 15. Use for in-memory data.
+
+> Note: although referred to as "primary table templates **within Table**," the files live
+> at `src/templates/PrimaryTable/`, not under `src/components/Table/`.
+
+## Key props (`PrimaryTableProps`, types.ts)
+
+`table`, `tableViewFieldMap`, `skin` ("supply" | "desk" | "supply-nested" |
+"supply-modal-table"), `onRowClick`, `paginationMeta` + `handlePageChange` +
+`handleRecordsPerPageChange`, `isFetching`, `dirtyRows`, `activeRowUuid`, `tableSettings`
+({ isPaginationEnabled, isInfiniteScrollingEnabled }), `rowHeight`, `containerHeight`
+(default 750), `fetchNextPage` + `hasNextPage` (infinite scroll), `renderExpandedContent`,
+`headerSpan` (multi-row header), `showColumnBorders`, `resizableColumns`, `shrinkColumns`,
+`minColumnWidth` (number | per-column map).
+
+## Column sizing: measure-and-freeze
+
+Constants in `PrimaryTable.tsx`: `DEFAULT_MIN_COLUMN_WIDTH = 80`, `ABSOLUTE_MIN_COLUMN_WIDTH
+= 40`, `MIN_RESIZE_WIDTH = 40` (and `MIN_COLUMN_WIDTH = 120` from `buildTanstackColumns`).
+
+1. **Measure** — on first paint, measure header + widest body cell content per column
+   (`measureCellContentWidth`), store in `frozenWidths`; per-column floors in `contentFloors`.
+2. **Freeze** — apply `table-layout: fixed` + a `<colgroup>` of frozen pixel widths so columns
+   don't reflow while virtualizing. Resets when the leaf column set changes. Empty tables stay
+   on auto-layout.
+3. **Shrink-to-fit** — when `shrinkColumns` (modal tables), scale widths to container width
+   via `fitColumnsToContainer`, respecting `minColumnWidth` → `contentFloors` →
+   `DEFAULT_MIN_COLUMN_WIDTH`, clamped to `ABSOLUTE_MIN_COLUMN_WIDTH`; ResizeObserver re-fits.
+4. **Resize** — when `resizableColumns`, a header drag handle mutates `frozenWidths` only
+   (visual, local, resets on column change).
+
+## Rows & virtualization
+
+`PrimaryTableHeaderCell` (label + `SortIcon` with multi-sort index + filter UI dispatch by
+field type + resize handle + sticky edge divider), `PrimaryTableBodyCell` (`flexRender`,
+sticky styling, action-column detection via `meta.isActionColumn`), `PrimaryTableRow` (dirty/
+active/hover states; click handler ignores text-selection; renders expanded content row),
+`PrimaryTableExpandableRow` (adds chevron toggle). Body uses a virtualizer with top/bottom
+spacer rows computed from the virtualizer item `.start`/`.end` minus `scrollMargin`. The
+`supply-modal-table` skin **disables virtualization** (renders all rows, min-height 300px).
+Sticky columns use a `--sticky-offset` CSS variable summed from neighboring column widths.
+
+## Gotchas
+
+- Frozen widths measure only **mounted** rows; virtualized tables size from the first paint set.
+- `headerSpan` adds a separate top row (`colSpan`); only the leaf header row maps to colgroup.
+- Resize is non-persistent (local state, resets when columns change).
+
+## Change history
+- 2026-06-23 — Documented the three Primary Table entry points, measure-and-freeze sizing, virtualization, and sticky columns (apeterson).
+- 2026-06-22 — Added `shrinkColumns` / `minColumnWidth` shrink-to-fit for modal tables; freeze logic uses natural content width (apeterson).

package/knowledge/2.0/apps/toga-blox/features/table-record-modal.md

@@ -0,0 +1,69 @@
+---
+title: TableRecordModal (record-detail modal shell)
+framework: "2.0"
+repo: toga-blox
+project: TOGa Blox
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - toga-blox/src/components/TableRecordModal/TableRecordModal.tsx
+  - toga-blox/src/components/TableRecordModal/index.ts
+  - toga-blox/src/components/TableRecordModal/tableRecordModal.module.css
+related:
+  - ../architecture.md
+  - table.md
+---
+
+## Summary
+
+`TableRecordModal` is a **generic, presentational modal shell** for showing a single table
+record (row) in detail — typically opened from a table row click. It handles **positioning,
+animation, backdrop, and lifecycle only**; the consumer supplies the record's field rendering
+via `children`. It does **not** render fields, manage edit/view modes, or provide
+accessibility/focus management — all of that is the consumer's responsibility.
+
+## API (props)
+
+`{ isOpen, onClose, position?, children, slideUpModalClassName?, variant?, isMaximized?,
+style? }`:
+
+- `isOpen: boolean`, `onClose: () => void` — controlled visibility.
+- `position?: "right" | "left" | "bottom" | "top" | "center"` (default `"right"`) — each has
+  its own slide animation and backdrop opacity (right/left 0.2, top/bottom 0.4, center 0.5 +
+  blur).
+- `children: ReactNode | ((onClose) => ReactElement)` — static content **or** a render-prop
+  function that receives `onClose` (avoids prop-drilling the close handler).
+- `variant?: "default" | "expandable"` + `isMaximized?` — expandable variant toggles width
+  between minimized (57%) and full (100%); `isMaximized` is ignored for other variants.
+- `slideUpModalClassName?` — arbitrary extra class merged onto the wrapper (misnomer: not
+  slide-up-specific). `style?` — inline override.
+
+## Behavior & styling
+
+- A single `useEffect` locks body scroll (`document.body.style.overflow = "hidden"`) while
+  open and restores it on close.
+- Backdrop click **always** calls `onClose` (not suppressible).
+- CSS Modules (`tableRecordModal.module.css`) with position keyframes (`slideFromRight/Left/
+  Top/Bottom`, `fadeScaleIn`, `fadeIn`) and CSS variables for dimensions
+  (`--tableRecordModal-right-width` default 480px, etc.).
+- Shares the `TableTheme` className-override type from `Table/themeConfig/types.ts`.
+
+## Relationship to Table
+
+No direct import coupling. The consuming app wires it: on `PrimaryTable`'s `onRowClick(row)`
+it opens the modal with `isOpen={!!selectedRow}` and renders the record inside `children`
+(often using the same `tableViewFields` metadata to format fields). `utils/resolveModalType.tsx`
+and `types.ts` are present but **empty/reserved** for a future field-type→renderer mapping.
+
+## Gotchas
+
+- **No portal** — renders inline in the React tree; a parent `overflow: hidden` can clip it.
+- **No focus trap / ARIA** (`role="dialog"`, `aria-modal`) — add in consumer.
+- **No modal stacking guard** — nested modals overwrite the saved body-overflow value.
+- CSS-variable defaults are hardcoded fallbacks; set vars on the DOM before mount to change sizes.
+
+## Change history
+- 2026-06-23 — Documented TableRecordModal as a generic modal shell: positions, render-prop children, body-scroll lock, and consumer-owned field rendering / a11y (apeterson).

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

@@ -0,0 +1,141 @@
+---
+title: Table component (cells, action cells, filters & sorts, hooks, theming)
+framework: "2.0"
+repo: toga-blox
+project: TOGa Blox
+client: shared
+type: feature
+status: active
+updated: 2026-06-23
+owners: [apeterson]
+files:
+  - toga-blox/src/components/Table/index.ts
+  - toga-blox/src/components/Table/types.ts
+  - toga-blox/src/components/Table/utils/buildTanstackColumns.tsx
+  - toga-blox/src/components/Table/utils/resolveCellType.tsx
+  - toga-blox/src/components/Table/components/cellTypes
+  - toga-blox/src/components/Table/components/actionCells
+  - toga-blox/src/components/Table/components/columnFiltersAndSorts
+  - toga-blox/src/components/Table/hooks
+  - toga-blox/src/components/Table/themeConfig
+related:
+  - ../architecture.md
+  - primary-table-templates.md
+  - api-client.md
+---
+
+## Summary
+
+The `Table` component (`src/components/Table/`) is the **TanStack Table v8** building block
+behind the [Primary Table templates](primary-table-templates.md). It is organized in layers:
+
+- **Primitives** — thin HTML wrappers (`Table`, `TableHead`, `TableBody`, `TableRow`,
+  `TableHeaderCell`, `TableCell`), exported from `src/components/Table/index.ts`.
+- **Column building** — `buildTanstackColumns()` turns a `TableViewField[]` (API metadata)
+  into TanStack `ColumnDef[]`; `resolveCellType()` picks the right cell renderer per field type.
+- **Cell types** (`components/cellTypes/`) — the renderers for each data type.
+- **Action cells** (`components/actionCells/`) — row-level action buttons (chevron, download).
+- **Filters & sorts** (`components/columnFiltersAndSorts/`) — per-column header filter/sort UI.
+- **Hooks** (`hooks/`) — data fetching (paginated/infinite), edit state, metadata, filter options.
+- **Theming** (`themeConfig/`) — `ThemeProvider` + skins + CSS variables.
+
+## Column building & cell resolution
+
+`utils/buildTanstackColumns.tsx` — `buildTanstackColumns({ tableViewFields, isEditable,
+updateCell, typeValues?, skin?, onNavigate?, userSettings?, columnWidths?, columnTypeConfig? })`
+returns `ColumnDef<any>[]`. Per visible field it sets `id = slug`, `header = label`,
+`enableSorting/Filtering`, a custom `filterFn` (`columnFilterFn` supports modes
+**startsWith, endsWith, exactly, includes, excludes**), an `accessorFn` that walks
+dot-notation paths (`related.field`), and a `cell` that delegates to `resolveCellType()`.
+
+**Column width precedence** (`buildTanstackColumns.tsx:112-123`): explicit `columnWidths`
+(set as both `size` and `minSize`) → `columnTypeConfig`/`COLUMN_TYPE_CONFIG` → field `width`
+→ default 200px size / `MIN_COLUMN_WIDTH` (=120, line 9) minSize. `COLUMN_TYPE_CONFIG`
+defaults: DATETIME_CREATED 160, STATUS 140, URGENCY 100, CLIENT 180.
+
+`utils/resolveCellType.tsx` maps `tableViewField.type` → a cell component and wraps it for
+alignment (CVA `cellWrapperVariants`), expandable, and copyable behavior. Empty/null values
+render `EmptyCell`. If `imageUrlField` is set, the URL is resolved separately and passed to
+`ImageCell`.
+
+## Cell types (`components/cellTypes/`)
+
+| Component | Type | Renders |
+|---|---|---|
+| `TableCell` / `TableHeaderCell` | generic | base `<td>` / `<th>` wrappers (forwardRef) |
+| `DateCell` | DATE/DATETIME | dayjs-formatted time (top) + date (bottom); optional `timeZone` (dayjs.tz); default `MM/DD/YYYY` + `hh:mm A` |
+| `CurrencyCell` | CURRENCY | `$` + `toLocaleString("en-US")` to `precision` |
+| `NumberCell` | NUMBER | localized number, `maximumFractionDigits = precision` |
+| `StatusCell` | STATUS | colored dot + label from `typeValues` (fallback `#CBD5E1`) |
+| `StatusBadgeCell` | STATUS_BADGE | filled badge, background from `typeValues` |
+| `UrgencyCell` | URGENCY | FontAwesome flag icon + label, colored |
+| `BooleanCell` | BOOLEAN | "Yes"/"No" with green (`#2CB224`) / red (`#FF2E54`) dot |
+| `EmptyCell` | — | em-dash placeholder |
+| `ImageCell` | IMAGE | image (or gray placeholder) + label |
+| `CopyableCell` | any | wraps content with copy-to-clipboard button (`buttonPosition` left/right) |
+| `ClientCell` / `UserAvatarCell` | CLIENT/AVATAR | hash-colored initials avatar + name |
+| `ExpandableCell` | text | truncates at `maxLength` (default 80) with show more/less |
+| `EditableCell` | edit mode | type-specific inline input (text/number/currency/date/boolean); commits on blur |
+
+## Action cells (`components/actionCells/`)
+
+`ChevronActionCell` (row expand/collapse; rotates on `isActive`) and `DownloadActionCell`
+(download button, `aria-label`, `stopPropagation`). Both take `{ row, onAction, isActive,
+isHovered, skin, isDisabled }`. They are inserted as columns via `buildActionColumn()` +
+`insertActionColumns()` (sorted by `position`: "start" → -∞, "end" → +∞, number → index).
+
+## Column filters & sorts (`components/columnFiltersAndSorts/`)
+
+Per-column header controls, each a popover trigger with `data-active` / `data-open`:
+
+- **`HeaderFilterSearch`** — text filter, 5 modes (startsWith/endsWith/exactly/includes/
+  excludes) chosen from a **mode dropdown that excludes the currently selected mode**.
+  **Tag-based**: confirmed values become removable tags (`activeTags`); `isActive =
+  activeTags.length > 0`. The mode dropdown is portalled to `document.body` with fixed
+  positioning recomputed on scroll. The search icon (solid when active, regular otherwise)
+  is hidden while the input is focused; both the trigger button and the icon span carry
+  `data-active`. The clear button must not widen the input row (fixed-width menu).
+- **`HeaderFilterRange`** — numeric, modes exactly/moreThan/lessThan + a range toggle
+  (min/max); emits `{ key, value }[]` (`eq`/`min`/`max`/`between`).
+- **`HeaderFilterMultiselect`** — checkbox list with "Select All"; emits comma-joined slugs.
+- **`HeaderFilterDate`** — calendar picker, modes exactly/before/after + range; converts
+  `MM/DD/YYYY` ↔ URL `YYYY-MM-DD`; calendar + mode dropdown both portalled.
+- **`HeaderFilterButton`** — generic trigger: shows a numbered badge when active with a
+  `filterIndex`, otherwise the search icon (`data-active`).
+- **`SortIcon`** — asc/desc/reset menu with a multi-sort index badge; button visibility keys
+  off current sort direction.
+
+## Hooks (`hooks/`)
+
+| Hook | Returns / does |
+|---|---|
+| `useTableSetup` | builds columns via `buildTanstackColumns` + `insertActionColumns`; memoized `updateCell`; tracks hovered row uuid |
+| `useTableData` | runs **either** paginated or infinite query by `isPaginationEnabled` (single source of truth); shared `["table-data", slug, …]` cache prefix; strips display-only URL params (`slug`, `cols`) so they don't refetch |
+| `useTablePageData` | paginated-only variant |
+| `useInfiniteTableData` | `useInfiniteQuery` + IntersectionObserver on a `sentinelRef` |
+| `useTableInfiniteScroll` | virtualizer-based "near end" trigger (lower-level alternative) |
+| `useTableEdit` | dirty-row tracking, dot-notation patch, `handleSave` calls `mutationFn` and updates the query cache, clears dirty + exits edit mode on success |
+| `useFetchTablePageMeta` | fetches table meta + fans out filter-option queries per field |
+| `useAssignTableFieldLabels` | merges page-level labels into field defs |
+| `useTableFieldFilterOptions` | filter options for a single field |
+
+## Theming (`themeConfig/`)
+
+`ThemeProvider` injects a `ClientTheme { id, name, vars }` as CSS variables on
+`document.documentElement`. `TableTheme` (types.ts) is a className-override map
+(`wrapper`, `headerCell`, `bodyRow`, `stickyLeft/Right`, `filterPopover`, …). Skins:
+`supply` (default), `desk`, `supply-nested` (compact, max-height 480px), `supply-modal-table`
+(modal: fixed heights, virtualization disabled). Design tokens are `--primaryTable-*` in
+`toga.module.css`.
+
+## Gotchas
+
+- `MIN_COLUMN_WIDTH = 120` is the shrink floor only for columns with **no** explicit width.
+- The filter `includes` mode treats comma-separated values as OR.
+- `EditableCell` currency formats **on blur**, phone formats **on keystroke**.
+- Cell type config (`columnTypeConfig` prop) overrides the hardcoded `COLUMN_TYPE_CONFIG`.
+
+## Change history
+- 2026-06-23 — Documented the Table component layers, cell types, filters/sorts, hooks, and theming (apeterson).
+- 2026-06-23 — `HeaderFilterSearch`: search icon hidden on input focus; `data-active` added to the icon span; clear button no longer widens the input (fixed-width menu); mode dropdown excludes the selected mode (apeterson).
+- 2026-06-22 — Column sizing reworked to measure-and-freeze using natural content width; `MIN_COLUMN_WIDTH` floor (120px) applies only when no explicit width is set (apeterson).

package/knowledge/INDEX.md

@@ -28,6 +28,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **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)
+- **toga-blox** (TOGa Blox) — 7 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)
 
 ## standalone framework
 

package/knowledge/registry.json

@@ -175,5 +175,12 @@
     "framework": "2.0",
     "role": "app",
     "dependsOn": []
+  },
+  {
+    "repo": "toga-blox",
+    "project": "TOGa Blox",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": []
   }
 ]

package/package.json

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