jattac.libs.web.zest-button 1.4.0 → 1.5.0

package/docs/features/zest-button-dropdown-options/BRS.md

@@ -1,213 +0,0 @@
-# BRS — ZestButton dropdown options (split button)
-
-## Metadata
-
-| Field | Value |
-|-------|-------|
-| Status | Complete |
-| Task Type | Feature |
-| Author | Claude (collaborating with repo owner) |
-| Created | 2026-07-28 |
-| Last Updated | 2026-07-28 |
-| Approved | Yes — user approved full scope as drafted, 2026-07-28 |
-
-### Implementation notes
-
-See `test-reports/CHANGE_MANIFEST_dropdown-options.md` for the full file list, four implementation deviations from this document's original Technical Design (each empirically discovered, not guessed), and the coverage-regression fix. All 9 acceptance criteria satisfied; 81/81 tests pass; coverage 97.21% (up from the prior 95.38% baseline).
-
----
-
-## Problem Statement
-
-**As a** developer using ZestButton, **I want** a way to attach a set of optional secondary actions to a button that already has one obvious default action, **so that** the button visually communicates "there's more here" and gives users a dedicated, discoverable way to reach those alternatives without cluttering the UI with several separate buttons.
-
----
-
-## Business Value / Impact
-
-Several places in Jattac products need "primary action + a few situational alternatives" (e.g. Save / Save & Close / Save As, Export / Export as CSV / Export as PDF). Today that either forces multiple separate buttons or a bespoke one-off menu per screen. A first-class ZestButton capability makes this consistent, accessible, and reusable everywhere ZestButton already is.
-
----
-
-## Acceptance Criteria
-
-### 1: Split-button rendering
-
-- **Given** `zest.dropdownOptions` is a non-empty array
-- **When** `ZestButton` renders
-- **Then** it renders as two visually-fused segments sharing one pill shape: the existing button content/behavior on the left, and a chevron ("more options") segment on the right, separated by a subtle divider
-- **And** when `dropdownOptions` is absent or empty, `ZestButton` renders exactly as it does today — zero visual or behavioral change (this is the core regression constraint for every other AC)
-
-### 2: Main segment always fires the default action directly
-
-- **Given** the split-button variant is rendered
-- **When** the user clicks/taps/keyboard-activates the main (left) segment
-- **Then** it behaves exactly like today's `ZestButton` `onClick` — no menu involvement, no extra click required. The dropdown never intercepts or delays the primary action.
-
-### 3: Chevron segment opens/closes the menu
-
-- **Given** the split-button variant is rendered
-- **When** the user clicks/taps/keyboard-activates (Enter/Space) the chevron segment
-- **Then** a menu listing `dropdownOptions` opens, positioned relative to the button with automatic collision/flip handling (opens upward instead of downward, or shifts horizontally, when there's insufficient viewport space) — provided by `@radix-ui/react-dropdown-menu`, not hand-rolled
-- **And** clicking the chevron again, pressing Escape, or clicking/tapping outside closes it
-- **And** the chevron rotates/reflects open vs. closed state visually (CSS-only transition, no animation library)
-
-### 4: Each menu item is independent but DRY
-
-- **Given** a `dropdownOptions` entry with its own `busyOptions`/`successOptions`/`confirmOptions`
-- **When** that item is activated
-- **Then** it goes through the *same* `useBusyState`/`useConfirmation` hooks the main button already uses — each item is its own hook instance (via a new internal `ZestDropdownMenuItem` sub-component, since React's rules of hooks forbid calling hooks in a loop at the parent level), not a re-implementation of busy/confirm logic
-- **And** an item with no `busyOptions`/`confirmOptions` behaves like a plain synchronous menu action: selecting it calls `onClick` and closes the menu immediately (today's Radix default)
-- **And** an item with `busyOptions.handleInternally` (default `true`, matching the main button's existing default) keeps the menu open on that row, shows the same spinner/checkmark/shake feedback the main button uses, then closes automatically once the success/fail state settles
-- **And** an item with `confirmOptions` keeps the menu open through the full "Confirm X (5s)" countdown flow (identical semantics to the main button's confirm flow today), only closing once the confirmed action actually runs or the countdown expires
-
-### 5: Full accessibility
-
-- **Given** the split-button variant
-- **Then** the chevron trigger has `aria-haspopup="menu"`, `aria-expanded`, and an accessible name (`zest.dropdownAriaLabel`, default `"More options"`, always overridable since it has no visible text)
-- **And** the menu uses proper `role="menu"`/`role="menuitem"` semantics (via Radix, not authored by hand)
-- **And** keyboard interaction works fully: Tab reaches the chevron as a separate stop after the main button, Enter/Space opens it, Arrow Up/Down moves between items, Escape closes and returns focus to the chevron
-- **And** while the menu is open, the existing `isDefault` document-level Enter-key listener (`UI/ZestButton.tsx`'s `useEffect` that clicks `buttonRef` on Enter) is suppressed — Enter while the menu is open must operate on the highlighted menu item (Radix's own behavior), not re-trigger the main action underneath it
-
-### 6: Mobile-first, desktop-aware
-
-- **Given** the split-button variant on a touch viewport
-- **Then** the chevron segment meets a minimum 44×44px touch target (WCAG 2.5.5 / matches the intent of the prior "improve ZestButton mobile hit area" work), even at `size="sm"`
-- **And** on desktop/pointer input, the chevron segment is visually proportionate to the button's `size` (`sm`/`md`/`lg`) rather than always occupying the mobile-minimum footprint
-
-### 7: Visual integration with the existing variant system
-
-- **Given** any combination of `visualOptions.variant` (`standard`/`success`/`danger`), `size` (`sm`/`md`/`lg`), `buttonStyle` (`solid`/`outline`/`text`/`dashed`), and `theme` (`light`/`dark`/`system`)
-- **Then** the chevron segment and the menu itself render consistently themed — no hardcoded colors independent of the variant/theme system (this is the concrete gap identified in `jattac.Libs.Web.OverflowMenu`, which hardcodes teal via Framer Motion inline styles that can't be overridden; this feature must not repeat that mistake)
-
-### 8: Disabled/busy propagation across the whole control
-
-- **Given** the split-button variant
-- **When** the main segment is busy (internally-handled async click in flight) OR any menu item is busy
-- **Then** the *entire* control (main segment + chevron) is disabled — no firing a second action from either segment while one is already in flight
-- **And** the existing `disabled` prop, when explicitly passed, disables both segments as it does today for the single button
-
-### 9: New dependency
-
-- **Given** this feature requires menu positioning/dismiss/a11y mechanics
-- **Then** `@radix-ui/react-dropdown-menu` is added as a `peerDependency` + `devDependency`, and added to both `external` arrays in `rollup.config.mjs` — following the exact precedent already established for `react-icons` in this repo, so it's never bundled into `dist/` and consumers control their own version
-- **And** no other new dependency is introduced (no Framer Motion, no `@radix-ui/react-popover` — this repo's existing CSS-module + hooks approach covers everything else)
-
----
-
-## Out of Scope
-
-- Nested/submenus (dropdown items are a flat list; `jattac.Libs.Web.OverflowMenu` supports nesting, this feature does not need to and will not)
-- Any change to `jattac.Libs.Web.OverflowMenu` itself, or reusing it as a dependency (evaluated and rejected — see decision log)
-- A "menu-only" button mode where the main segment doesn't have its own default action — every split button has a real default action per the user's stated requirement
-- Reordering/drag-and-drop of menu items
-- Icons-within-menu-items styling beyond what `semanticType`/`icon` already provide on the main button today
-- Any change to `ZestButton`'s existing (non-dropdown) behavior — AC 1's "zero change when `dropdownOptions` is absent" is the hard boundary
-
----
-
-## Technical Design
-
-### New dependency
-
-| Package | Type | Purpose |
-|---|---|---|
-| `@radix-ui/react-dropdown-menu` | `peerDependency` + `devDependency`, externalized in `rollup.config.mjs` | Menu positioning (collision/flip), dismiss-on-outside-click/Escape, WAI-ARIA menu semantics, keyboard nav — used directly (not via `jattac.Libs.Web.OverflowMenu`) |
-
-### New types (`UI/ZestButton.tsx`, additive)
-
-```ts
-export interface ZestDropdownOption {
-  key?: string;
-  label: React.ReactNode;
-  icon?: React.ReactNode;
-  disabled?: boolean;
-  semanticType?: SemanticType;
-  onClick?: (e: Event) => void | Promise<void>;
-  busyOptions?: BusyOptions;
-  successOptions?: SuccessOptions;
-  confirmOptions?: ConfirmOptions;
-}
-```
-
-`ZestCustomProps` gains two new optional fields: `dropdownOptions?: ZestDropdownOption[]` and `dropdownAriaLabel?: string` (default `"More options"`).
-
-### New files
-
-```
-UI/ZestDropdownTrigger.tsx      — the chevron segment; wraps Radix's DropdownMenu.Trigger (asChild) around ZestButton's own themed button markup
-UI/ZestDropdownMenuItem.tsx     — one menu row; internally calls useBusyState/useConfirmation exactly like ZestButton.tsx does today (AC 4's DRY-via-shared-hooks requirement)
-UI/hooks/useDropdownDisclosure.ts — thin wrapper around Radix's open/onOpenChange state, exposing the open flag ZestButton.tsx needs to suppress the isDefault Enter-key effect (AC 5)
-Styles/ZestButton.module.css    — extended (not replaced) with chevron/menu/divider classes, matching this repo's existing CSS-module + identity-obj-proxy-testable approach
-```
-
-### Modified files
-
-- `UI/ZestButton.tsx` — additive only: renders the chevron trigger + menu when `dropdownOptions` is present; the `isDefault` `useEffect` gains the open-menu guard from AC 5. No existing branch of the current render/click logic changes when `dropdownOptions` is absent (AC 1).
-- `package.json` — new peer/dev dependency.
-- `rollup.config.mjs` — `@radix-ui/react-dropdown-menu` added to both `external` arrays (JS bundle config and the `.d.ts` bundle config), matching the existing `react`/`react-dom`/`react-icons` entries exactly.
-
-### Pattern precedent
-
-`jattac.Libs.Web.OverflowMenu` (sibling repo, `D:\work\nyingi\code\systems\jattac-web-libs\jattac.Libs.Web.OverflowMenu`) already depends on `@radix-ui/react-dropdown-menu` in production — this is a proven, already-trusted-in-this-org package, just consumed directly instead of through that repo's opinionated (non-themeable) wrapper.
-
----
-
-## Edge Cases
-
-### Menu item busy while main button is also mid-confirmation
-**Scenario:** User opens the menu while the main button's own `confirmOptions` countdown is active.
-**Expected:** AC 8 disables the whole control while *busy*, but a pending confirm countdown on the main segment is not "busy" (mirrors today's single-button semantics, where `wasSuccessful`/`wasFailed`/`internalBusy` — not `awaitingConfirm` — drive `isDisabled`). The menu remains openable during a pending confirm; opening it does not cancel the main segment's countdown.
-
-### Zero dropdownOptions after filtering
-**Scenario:** Caller passes `dropdownOptions: []` (explicit empty array, not `undefined`).
-**Expected:** Same as AC 1's "absent" case — no chevron segment rendered. An empty array is not treated differently from `undefined`.
-
-### Rapid open/close while a menu item is busy
-**Scenario:** A menu item's async `onClick` is in flight (menu held open by AC 4); user presses Escape or clicks outside.
-**Expected:** The menu closes on dismissal regardless of the in-flight promise — the promise still runs to completion and still updates that item's busy/success/fail state internally, it's just not visible until/unless the menu is reopened. No dangling state or memory leak (existing `useBusyState`/`useConfirmation` cleanup-on-unmount behavior, already tested in `__tests__/hooks/`, covers this as long as the item component doesn't literally unmount when the menu closes — confirm during implementation whether Radix unmounts closed menu content by default, and force-mount if so, so item state survives close/reopen within one page session).
-
----
-
-## Dependencies
-
-### Internal
-- Builds on the existing `useBusyState`/`useConfirmation`/`useZestConfig` hooks and `Styles/ZestButton.module.css` conventions — no changes required to any of them.
-
-### External
-- `@radix-ui/react-dropdown-menu` (new, see Technical Design).
-
----
-
-## Risks and Open Questions
-
-### Risks
-- Radix's `DropdownMenu.Content` renders into a portal by default — needs a sensible default portal target (`document.body`) with an optional override prop for consumers using shadow DOM/iframes, otherwise CSS custom properties (theme forcing) that rely on ancestor selectors may not reach the portaled menu. Needs verifying during implementation, not just assumed.
-- `@radix-ui/react-dropdown-menu`'s peer range for React needs checking against this repo's `react: ">=16.8.0"` peer floor before finalizing the `package.json` entry — if Radix's floor is higher (e.g. requires React 16.8+ hooks, which is fine, but some Radix packages have crept their stated minimums up in recent majors), the two peer ranges must be reconciled or documented as a floor bump.
-
-### Open Questions
-- None blocking — flagged risks above will be resolved empirically during implementation (installed, checked, and reported), not guessed.
-
----
-
-## Regression Prevention
-
-### For Features
-
-**New Tests Required:**
-- Every AC above (1–9) gets at least one behavioral test in `__tests__/ZestButton.test.tsx` or a new `__tests__/ZestDropdownMenuItem.test.tsx` / `__tests__/hooks/useDropdownDisclosure.test.ts`, following this repo's existing test conventions (real assertions, fake timers for confirm/busy timing, `identity-obj-proxy` for CSS modules).
-- A dedicated regression test asserting AC 1's "zero behavior change when `dropdownOptions` is absent" — re-running (not duplicating) a representative slice of the existing 52-test suite against a build with the new prop wired in but unused.
-
----
-
-## Definition of Done
-
-- [ ] BRS approved by user
-- [ ] All acceptance criteria pass (new tests green, full existing 52-test suite still green)
-- [ ] `npm run build` clean (no new TS diagnostics, no new bundle-size surprises from an accidentally-inlined Radix dependency — verify `external` actually excluded it)
-- [ ] No coverage regression from the current baseline (`test-reports/coverage-baseline.json`)
-- [ ] No unsolicited changes outside this BRS's scope
-- [ ] Code matches existing patterns (hooks-per-concern, CSS modules, `identity-obj-proxy`-testable styling)
-- [ ] Change manifest produced
-- [ ] Self review passed with all PASS items
-- [ ] `docs/guidelines/ai-knowledge.md` and `docs/guidelines/decision-log.md` updated

package/docs/guidelines/AI_ARCHITECTURE.md

@@ -1,455 +0,0 @@
-# Architectural Rules
-
-Business behaviour is more important than implementation.
-
----
-
-# Composition
-
-Composition SHALL be preferred over modification of existing code.
-
-Decision process:
-
-Can composition reasonably solve the problem?
-
-YES
-
-Use composition.
-
-NO
-
-Continue.
-
-Does existing code violate business behaviour?
-
-YES
-
-Modify existing code.
-
-NO
-
-Continue.
-
-Would composition become unreasonable?
-
-YES
-
-Modify existing code.
-
-NO
-
-Use composition.
-
-When composition is chosen, the new code MUST NOT alter the behaviour of existing code.
-
-Composition means addition, not modification.
-
----
-
-# Existing Code
-
-Existing code SHALL NOT be rewritten merely because another implementation is preferred.
-
-Do not replace architecture.
-
-Do not modernise code.
-
-Do not rename symbols.
-
-Do not move files.
-
-Do not reformat unrelated code.
-
-Do not optimise speculative bottlenecks.
-
----
-
-# Behaviour
-
-Existing behaviour is assumed correct unless:
-
-• failing tests prove otherwise
-
-OR
-
-• user explicitly requests behavioural change
-
----
-
-# Scope
-
-Only modify code necessary to complete the requested task.
-
-Never perform opportunistic refactors.
-
----
-
-# Simplicity
-
-Choose the smallest correct change.
-
-Smaller changes reduce regression risk.
-
----
-
-# Unknowns
-
-When uncertain:
-
-Stop.
-
-Explain uncertainty.
-
-Never guess business rules.
-
----
-
-# Absolute Prohibitions
-
-The following MUST NOT be done unless explicitly instructed by the user.
-
-## Dependencies
-
-Do NOT change package versions, SDK versions, or tool versions.
-
-Do NOT add NuGet packages, npm packages, pip packages, Cargo crates, Go modules, or any other dependencies.
-
-Do NOT remove dependencies.
-
-## Configuration
-
-Do NOT modify configuration files (appsettings.json, .env, docker-compose.yml, app.config, web.config, or any other config).
-
-Do NOT modify environment variables.
-
-Do NOT modify secrets or secret references.
-
-## CI/CD and Infrastructure
-
-Do NOT modify CI/CD pipelines, build scripts, or deployment configurations.
-
-Do NOT modify GitHub Actions, Azure DevOps pipelines, or any other CI configuration.
-
-Do NOT modify Docker files or container configurations.
-
-Do NOT modify infrastructure-as-code files.
-
-## Database
-
-Do NOT modify database migrations.
-
-Do NOT modify database schema.
-
-Do NOT modify stored procedures.
-
-Do NOT modify database scripts.
-
-Do NOT create new database tables or columns.
-
-## Code Changes
-
-Do NOT add comments unless explicitly instructed.
-
-Do NOT add logging unless explicitly instructed.
-
-Do NOT add error handling (try-catch, null checks, defensive code) unless explicitly instructed.
-
-Do NOT add TODO comments.
-
-Do NOT add comments about code that needs improvement.
-
-Do NOT change method signatures, return types, or public API surface.
-
-Do NOT change access modifiers (private to public, etc.).
-
-Do NOT change synchronous code to asynchronous.
-
-Do NOT add async/await where it was not present.
-
-Do NOT add ConfigureAwait(false).
-
-Do NOT add null-forgiving operators (!) to silence warnings.
-
-Do NOT add #pragma disable to silence warnings.
-
-Do NOT add SuppressMessage attributes.
-
-Do NOT add Obsolete attributes.
-
-Do NOT add EditorBrowsable(Never).
-
-Do NOT add InternalsVisibleTo for test projects.
-
-Do NOT add blanket try-catch blocks.
-
-Do NOT swallow exceptions.
-
-Do NOT change exception types.
-
-Do NOT change return values.
-
-## Formatting and Naming
-
-Do NOT rename variables, methods, classes, or any other symbols.
-
-Do NOT reorder methods, properties, fields, or any other members.
-
-Do NOT reformat code that was not part of the request.
-
-Do NOT change whitespace or line breaks in unrelated code.
-
-Do NOT change using directives or import statements.
-
-Do NOT change namespace declarations.
-
----
-
-# Change Justification
-
-Every change you make MUST be directly traceable to a specific requirement in the user's request.
-
-If you cannot draw a direct line from the user's words to the change, do not make the change.
-
-If you are unsure whether a change is required, ask the user.
-
----
-
-# Rollback
-
-Every change MUST be independently revertible.
-
-Do not create changes that depend on each other unless they are part of the same logical unit.
-
-If a change cannot be independently reverted, document this in the change manifest.
-
----
-
-# Project-Specific Architecture — Lattice Admin Web
-
-These are the concrete conventions of this repository. They are the "pattern discovery" reference required by AI_WORKFLOW.md Step 8 — match new code to these before inventing anything new.
-
-## Stack
-
-Next.js (App Router), TypeScript, React class components for stateful pages.
-
-## Project layout
-
-Features live under `app/admin/` (admin-only) or `app/` (shared). Each feature contains:
-- `page.tsx` — Next.js route entry point
-- `Data/IModel.ts` — TypeScript interface mirroring the backend model
-- `Data/ModelApiAccessor.ts` — HTTP calls to the backend
-- `State/ModelRepository.ts` — extends `RepositoryBase`, holds reactive state
-- `State/ModelLogic.ts` — extends `LogicBase`, contains all business logic
-- `UI/ModelManager.tsx` — the page component
-
-## Page entry pattern
-
-```tsx
-"use client";
-import ManagerAccount from "@/app/account/UI/ManagerAccount";
-import FooManager from "./UI/FooManager";
-
-export default function FooPage() {
-  return (
-    <ManagerAccount>
-      <FooManager />
-    </ManagerAccount>
-  );
-}
-```
-
-## State management
-
-```ts
-// Repository — holds only state, no logic
-export default class FooRepository extends RepositoryBase {
-  items: IFoo[] = [];
-}
-
-// Logic — all async operations go here
-const logic = new FooLogic(); // instantiated at module level, outside the component
-
-export default class FooLogic extends LogicBase<FooRepository, IFoo> {
-  repository = new FooRepository();
-  model = {} as IFoo;
-
-  async initializeAsync() {
-    await this.runner(async () => {
-      this.repository.items = await new FooApiAccessor().getAllAsync();
-    });
-  }
-}
-```
-- `runner()` handles the `busy` flag automatically — always use it for async operations
-- Logic is instantiated at module level (outside the component class), not inside it
-
-## Components
-
-- Stateful pages use `PureComponent` class components with `logic.setRerender(() => this.forceUpdate())` in `componentDidMount`
-- `componentDidMount` must call `logic.initializeAsync()`
-- Use `FrostedGlassOverlay show={logic.repository.busy}` to block interaction during loads
-- Use `PageContainer title="..." subtitle="..."` as the top-level wrapper
-
-## API accessors
-
-```ts
-export default class FooApiAccessor extends ApiAccessor {
-  constructor() {
-    super({ controller: "foo", backendService: "fua" }); // or "lattice"
-  }
-
-  async getAllAsync(): Promise<IFoo[]> {
-    return await this.getUnwrappedAsync<IFoo[]>({ url: "items" });
-  }
-
-  async createAsync(payload: Omit<IFoo, "id">): Promise<void> {
-    await this.postWithUnwrappedResponseAsync({ url: "items", body: payload });
-  }
-}
-```
-- `fetchData` supports only `"GET"` and `"POST"` — there is no DELETE method
-- Delete operations must POST to a delete endpoint: `postWithUnwrappedResponseAsync({ url: "items/delete/${id}", body: {} })`
-- URL segments must match the backend controller route exactly (controller class name minus "Controller", lowercase)
-
-## UI components
-
-| Need | Component |
-|---|---|
-| Page layout | `PageContainer` with `title` and `subtitle` |
-| Sidepane layout | `ZestResponsiveLayout` with `sidePane` prop |
-| Buttons | `ZestButton` with `visualOptions={{ variant: "success" \| "danger" \| "info" }}` |
-| Text inputs | `ZestTextbox` — use `isMultiline` + `rows` for textareas, `stretch` for full width |
-| Dropdowns | `SelectWrapper` — always use this, never a raw `<select>` |
-| Forms | See form system section below |
-| Tables | `ResponsiveTable` with `data` and `columnDefinitions` (each with `cellRenderer` + `displayLabel`) |
-| Action rows | `ActionBar` |
-| Loading overlay | `FrostedGlassOverlay show={logic.repository.busy}` |
-
-## Form system
-
-All forms use the component system from `@/app/Forms/Form/UI/Form`. Never style inputs or form layouts with raw inline styles.
-
-### Component hierarchy
-
-```
-Form
-  FormSection?          ← optional named section (title + subtle background, good for long standalone forms)
-    FormControlGroup?   ← optional titled group (dashed border header, good for sidepane sections)
-      FormRow           ← horizontal flex row, wraps on small screens
-        FormControlGroup  ← one input+label unit; min-width 250px so it auto-wraps when space runs out
-          FormLabel       ← shows label + required asterisk by default
-          {input}         ← ZestTextbox, SelectWrapper, checkbox etc.
-```
-
-### Rules
-
-**Always use `FormRow` to place related fields side by side.** Never stack items that logically belong together by leaving them as sequential block elements — use `FormRow` so they share a row when space allows and wrap gracefully on narrow screens.
-
-**Every input must be wrapped in `FormControlGroup > FormLabel + input`.** No bare inputs, no bare labels.
-
-**Mark optional fields.** `FormLabel` adds `*` by default (required). Add `optional` prop for non-required fields:
-```tsx
-<FormLabel optional>Description</FormLabel>
-```
-
-**Use `FormControlGroup title="..."` to group related fields in a sidepane.** This renders a dashed section header — use it instead of `FormSection` inside sidepanes where vertical space is at a premium:
-```tsx
-<FormControlGroup title="Trigger Settings">
-  <FormRow>
-    <FormControlGroup>...</FormControlGroup>
-    <FormControlGroup>...</FormControlGroup>
-  </FormRow>
-</FormControlGroup>
-```
-
-**Use `FormSection` for standalone full-page forms** where sections need more visual weight (title + `#f9fafb` background panel).
-
-**Use `SelectWrapper` for all dropdowns**, including static option lists:
-```tsx
-const RISK_LEVELS = [
-  { value: "High", label: "High" },
-  { value: "Critical", label: "Critical" },
-];
-
-<SelectWrapper
-  data={RISK_LEVELS}
-  selectedResolver={(r) => r.value === item.riskLevel}
-  valueResolver={(r) => r.value}
-  labelResolver={(r) => r.label}
-  onChange={(selected) => update({ riskLevel: selected[0]?.value ?? "High" })}
-  isClearable={false}
-  isSearchable={false}
-/>
-```
-
-**Full-width fields** (long text, description, multiline) go in a standalone `FormControlGroup` outside a `FormRow` — they naturally fill 100% width. Use `stretch` on `ZestTextbox`:
-```tsx
-<FormControlGroup>
-  <FormLabel optional>Description</FormLabel>
-  <ZestTextbox type="text" stretch value={...} onChange={...} />
-</FormControlGroup>
-```
-
-**Number inputs** go in `FormRow` with their peers — never alone as a block element:
-```tsx
-<FormRow>
-  <FormControlGroup>
-    <FormLabel>Threshold (events)</FormLabel>
-    <ZestTextbox type="number" value={...} onChange={...} />
-  </FormControlGroup>
-  <FormControlGroup>
-    <FormLabel>Window (days)</FormLabel>
-    <ZestTextbox type="number" value={...} onChange={...} />
-  </FormControlGroup>
-</FormRow>
-```
-
-**Checkboxes** — no styled component exists; use native `<input type="checkbox">` inside `FormControlGroup`:
-```tsx
-<FormControlGroup>
-  <FormLabel>Enabled</FormLabel>
-  <input
-    type="checkbox"
-    checked={item.isEnabled}
-    onChange={(e) => update({ isEnabled: e.target.checked })}
-    style={{ width: 16, height: 16, marginTop: 6 }}
-  />
-</FormControlGroup>
-```
-
-### Sidepane form reference layout
-
-For a sidepane create/edit form, structure fields in this order:
-1. Identity fields (name, code, key identifier) — `FormRow` with type/category/risk selector
-2. Optional descriptive fields — standalone full-width `FormControlGroup`
-3. Related configuration fields — `FormControlGroup title="..."` wrapping a `FormRow`
-4. Long text fields (messages, notes) — `FormControlGroup title="..."` wrapping individual full-width fields
-5. Toggle/boolean fields — `FormRow` of checkboxes
-6. Help/instruction panel — `<div>` with `background: #f9fafb`, 11px text, business-language explanations
-
-## Sidepane pattern
-
-```tsx
-<ZestResponsiveLayout
-  sidePane={{
-    visible: !!this.state.itemForSidePane,
-    title: this.#isEditing ? `Edit — ${item.name}` : "Add Item",
-    pane: this.#sidePaneContent ?? <></>,
-    onClose: () => this.setState({ itemForSidePane: undefined }),
-  }}
-  desktopSidePaneWidth="500px"
-  enableBounceAnimation={false}
-  detailPane={<>...table and action bar...</>}
-/>
-```
-- Never use modals for create/edit forms — always use the sidepane
-- Sidepane title adapts: "Add X" for new, "Edit — {name}" for existing
-
-## Navigation
-
-New admin pages must be registered in `app/account/UI/MenuItems/AdminMenuItemsProvider.tsx` under the correct parent group.
-
-## Routing
-
-- Admin pages: `app/admin/[feature]/page.tsx`
-- Route segments must be kebab-case