feat(ui): shared migration primitives (UI migration PR 3) (#1122)

* feat(ui): shared migration primitives (UI migration PR 3)

The component kit every page migration (PR 4-8) builds on:

- ContextPicker: the one-per-page chip-dropdown context scope (convention
  8), right-aligned popover with checks and muted annotations
- FyPicker: fiscal-year picker on ContextPicker with the same controlled
  API and per-company localStorage key as FiscalYearSelector, which it
  replaces page by page from PR 4
- SplitButton: primary + caret menu, last-used mode persisted per user
  via ui_state.create_mode (lib/ui-state/client, unit-tested); nav
  persistence refactored onto the same helper
- ConfirmDialog: centered min-460px confirm-up-front dialog (convention
  10) with pending state on an awaitable onConfirm
- HelpPopover: 17px "?" after the H1 opening an anchored popover
  (convention 7); PageHeader gets a `help` slot
- AttnLine: the one-ochre-sentence attention pattern (convention 6) with
  optional inline action; new AA-safe --attn token pair
- RowStatus: chips-mark-exceptions helper (convention 5)
- SlideOver: right review panel, 480px, 18px inset, rounded, veil + Esc
  (convention 13), with header kicker / body / footer slots
- Stagger: .stagger-enter applied to the five target pages' list
  containers (bookkeeping, transactions, pending, invoices,
  supplier-invoices); structural loading.tsx added for supplier-invoices,
  customers, kpi, pending, deadlines

No page adopts the new pickers/dialogs yet: that is PR 4-8, one page per
PR against this kit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(ui): FyPicker chip must not double the Rakenskapsar label

Real fiscal periods are often named "Rakenskapsar 2026" already; only
prefix the label when the period name lacks it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

lib/ui-state/__tests__/client.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Tests for the client-side ui_state helpers: persistence POST shape,
+ * silent failure, and last-used split-button mode resolution.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { persistUiState, rememberCreateMode, resolveInitialMode } from '../client'
+
+const fetchMock = vi.fn()
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  fetchMock.mockResolvedValue({ ok: true })
+  vi.stubGlobal('fetch', fetchMock)
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('persistUiState', () => {
+  it('POSTs the patch to /api/user/ui-state', () => {
+    persistUiState({ nav_collapsed: true })
+    expect(fetchMock).toHaveBeenCalledWith('/api/user/ui-state', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ nav_collapsed: true }),
+    })
+  })
+
+  it('swallows network failures', () => {
+    fetchMock.mockRejectedValue(new Error('offline'))
+    expect(() => persistUiState({ nav_collapsed: false })).not.toThrow()
+  })
+})
+
+describe('rememberCreateMode', () => {
+  it('nests the mode under the surface key', () => {
+    rememberCreateMode('bookkeeping', 'mall')
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body)
+    expect(body).toEqual({ create_mode: { bookkeeping: 'mall' } })
+  })
+})
+
+describe('resolveInitialMode', () => {
+  const keys = ['tomt', 'mall', 'assistent'] as const
+
+  it('returns the persisted mode when valid', () => {
+    const uiState = { create_mode: { bookkeeping: 'mall' } }
+    expect(resolveInitialMode(uiState, 'bookkeeping', keys, 'tomt')).toBe('mall')
+  })
+
+  it('falls back when the persisted mode is stale', () => {
+    const uiState = { create_mode: { bookkeeping: 'removed-mode' } }
+    expect(resolveInitialMode(uiState, 'bookkeeping', keys, 'tomt')).toBe('tomt')
+  })
+
+  it('falls back when nothing is persisted', () => {
+    expect(resolveInitialMode(undefined, 'bookkeeping', keys, 'tomt')).toBe('tomt')
+    expect(resolveInitialMode({}, 'other', keys, 'assistent')).toBe('assistent')
+  })
+})

lib/ui-state/client.ts

@@ -0,0 +1,44 @@
+'use client'
+
+import type { UserUiState } from '@/types'
+
+/**
+ * Fire-and-forget persistence of a partial user_preferences.ui_state patch
+ * (nav collapse/folds, split-button last-used modes). Cosmetic preference
+ * data: a lost write self-corrects on the next change, so failures are
+ * swallowed deliberately.
+ */
+export function persistUiState(patch: Partial<UserUiState>): void {
+  void fetch('/api/user/ui-state', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(patch),
+  }).catch(() => {})
+}
+
+/**
+ * Remember the last-used mode of a split button (ui_state.create_mode),
+ * keyed per surface (e.g. 'bookkeeping' -> 'mall').
+ */
+export function rememberCreateMode(surface: string, mode: string): void {
+  persistUiState({ create_mode: { [surface]: mode } })
+}
+
+/**
+ * Resolve which split-button mode to show as primary on first render:
+ * the persisted last-used mode when it's still one of the valid options,
+ * otherwise the given fallback. Guards against stale persisted keys after
+ * an option is renamed or removed.
+ */
+export function resolveInitialMode<T extends string>(
+  uiState: UserUiState | undefined | null,
+  surface: string,
+  validKeys: readonly T[],
+  fallback: T,
+): T {
+  const persisted = uiState?.create_mode?.[surface]
+  if (persisted && (validKeys as readonly string[]).includes(persisted)) {
+    return persisted as T
+  }
+  return fallback
+}