@exxatdesignux/ui 0.2.17 → 0.2.18

package/template/docs/kpi-flat-band-pattern.md

@@ -0,0 +1,57 @@
+# KPI flat band (`KeyMetrics` `variant="flat"`)
+
+> **Component:** `components/key-metrics.tsx` — **`flatMetricsHairlineClass`**, **`flatBandStyle`**.  
+> **Tokens:** `app/globals.css` — `--key-metrics-flat-*`.  
+> **Cursor:** `.cursor/rules/exxat-kpi-flat-band.mdc` · `.cursor/skills/exxat-kpi-flat-band/SKILL.md`  
+> **Related:** `docs/kpi-strip-max-four-pattern.md`, `docs/kpi-trend-pattern.md`
+
+## Intent
+
+List hubs and the main dashboard mix view use **`KeyMetrics variant="flat"`** as a **metrics strip without a surface**: users see KPI copy and deltas on the **page canvas**, with a **brand-colored glow** under the band only. This is **not** a card, tinted panel, or `gap-px` grid fill.
+
+## MUST
+
+1. **No band surface** — The `<section>` background is **only** `var(--key-metrics-flat-band-radial)`. **Do not** stack `--key-metrics-flat-band-linear`, opaque gradients, or `box-shadow` fills that read as a grey/lavender box.
+2. **Transparent cells** — `metricsCellSurfaceClassName` is **`bg-transparent`** for `variant="flat"`. **Do not** use `bg-background`, `bg-card`, or `gap-px` + `bg-border` / `bg-foreground/*` on the grid (that paints tile surfaces).
+3. **Hairlines = borders only** — Use **`flatMetricsHairlineClass(itemCount, metricsHalfWidthLayout)`** in `key-metrics.tsx`:
+   - **2 tiles:** `border-r` on the first cell only.
+   - **4 tiles, wide strip (default):** `border-r` on cells 1–3 (verticals between all columns); **no** horizontal rule.
+   - **4 tiles, narrow `@container` (&lt; 30rem, 2×2 grid):** odd-column `border-r` + `border-b` on the top row only (via `@[max-width:29.99rem]` overrides).
+4. **Divider color (OKLCH)** — `--key-metrics-flat-divider: color-mix(in oklch, var(--sidebar-border) 55%, transparent)`; apply on children with `[&>*]:border-[color:var(--key-metrics-flat-divider)]`. Dividers follow **active product** hue (`--sidebar-border`), not neutral grey alone.
+5. **Glow (OKLCH)** — Radial stops use `color-mix(in oklch, var(--brand-color) …%, transparent)` so **Exxat One / Prism / Assessment / `theme-custom`** each tint correctly. **Do not** hardcode rose/indigo literals on theme blocks unless documenting a one-off.
+6. **List page usage** — Prefer **`showHeader={false}`**, **`metricsSingleRow`** when four KPIs share one row; pass **`insight`** only when the insight rail is product-required (same row uses `lg:grid-cols-[3fr_2fr]`).
+7. **Cap at four tiles** — See **`docs/kpi-strip-max-four-pattern.md`**.
+
+## MUST NOT
+
+- Add **`--key-metrics-flat-band-linear`** back into `flatBandStyle` or hub inline styles (e.g. question-bank hub hero).
+- Use **`variant="card"`** on **`ListPageTemplate`** metrics when the design calls for a **flat strip** on the page background.
+- Duplicate KPI numbers in ad-hoc **`Card`** grids on the same hub.
+- Set **`variant="mutedSuffix"`** on product wordmarks to grey out the **suffix** in dark mode — suffix stays **Exxat pink** (`wordmarkColor`); see **`lib/product-brand.ts`**.
+
+## Tokens (`app/globals.css`)
+
+| Token | Role |
+|--------|------|
+| `--key-metrics-flat-band-radial` | Bottom brand glow (only layer on flat `<section>`) |
+| `--key-metrics-flat-band-shadow` | **`none`** for flat band (no faux surface lift) |
+| `--key-metrics-flat-cell-bg` | **`transparent`** |
+| `--key-metrics-flat-divider` | OKLCH hairline between cells |
+
+Dark mode (`.dark`): same rules — transparent cells, radial glow only, no linear fill to `--background`.
+
+## Reference implementations
+
+- `components/question-bank-client.tsx` — `KeyMetrics variant="flat" metricsSingleRow`
+- `components/dashboard-tabs.tsx` — mix view flat band + insight
+- `components/placements-client.tsx`, `team-client.tsx`, `compliance-client.tsx` — list hub metrics slot
+
+## Insight rail (flat + side-by-side)
+
+When **`insight`** is shown beside KPIs, the insight **`Card`** may keep its own surface; the **KPI grid** stays transparent. **Do not** add `lg:border-l` on the insight column for flat band — the insight card ring is the separator (`key-metrics.tsx`).
+
+## See also
+
+- **`docs/kpi-strip-max-four-pattern.md`**
+- **`docs/kpi-trend-pattern.md`**
+- **`docs/shell-surface-elevation-pattern.md`** — sidebar / secondary panel / page stack

package/template/docs/kpi-strip-max-four-pattern.md

@@ -26,4 +26,5 @@ On **primary list hubs** (`ListPageTemplate` metrics slot) and on **dashboard
 ## See also
 
 - **`docs/kpi-trend-pattern.md`** — deltas, arrows, **`trendPolarity`**.
+- **`docs/kpi-flat-band-pattern.md`** — **`variant="flat"`** presentation (orthogonal to tile count).
 - **`.cursor/rules/exxat-kpi-max-four.mdc`**, **`.cursor/skills/exxat-kpi-max-four/SKILL.md`**

package/template/docs/shell-surface-elevation-pattern.md

@@ -0,0 +1,52 @@
+# Shell surface elevation (sidebar · secondary panel · page)
+
+> **Tokens:** `app/globals.css` — `--sidebar`, `--secondary-panel-bg`, `--background`, `--brand-tint*`.  
+> **Shell:** `components/templates/nested-secondary-panel-shell.tsx` — `bg-[var(--secondary-panel-bg)]`.  
+> **Cursor:** `.cursor/rules/exxat-primary-nav-secondary-panel.mdc` · `.cursor/skills/exxat-primary-nav-secondary-panel/SKILL.md`
+
+## Stack (back → front)
+
+| Level | Surface | Token / class | Notes |
+|-------|---------|---------------|--------|
+| **0** | Primary icon rail + app chrome | `--sidebar` (= `--brand-tint` on light product themes) | Darkest brand wash in the shell |
+| **1** | Nested secondary panel (Library, etc.) | `--secondary-panel-bg` | **Lighter** than level 0; **same product hue** |
+| **2** | Main page / inset content | `--background` | Lightest (white canvas light; dark charcoal dark) |
+
+**MUST** derive secondary panel fill from **`--brand-tint` / `--brand-tint-light`**, not a fixed rose or neutral grey. When the user selects **Exxat One**, both levels use **indigo hue ~286**; **Prism** uses **rose ~342**; **`theme-custom`** follows `--custom-product-brand-color` via `ProductProvider`.
+
+## OKLCH formulas (light)
+
+```css
+--sidebar: var(--brand-tint);
+--secondary-panel-bg: color-mix(in oklch, var(--background) 40%, var(--brand-tint-light) 60%);
+```
+
+## OKLCH formulas (dark)
+
+```css
+--secondary-panel-bg: color-mix(in oklch, var(--card) 32%, var(--brand-tint) 68%);
+```
+
+Per-product **dark** theme blocks (`.theme-one.dark`, `.theme-prism.dark`, …) set **`--brand-tint-light`** where needed so mixes stay on-hue.
+
+## Implementation
+
+- **`NestedSecondaryPanelShell`** — `bg-[var(--secondary-panel-bg)]`, `ring-sidebar-border` (not generic `ring-border` alone).
+- **Do not** set secondary panel to `bg-sidebar` (same as level 0 — loses elevation).
+- **Do not** use `color-mix(… var(--sidebar) …)` without brand tokens if it drifts from active product theme.
+
+## Product theme classes
+
+- **`theme-one`** / **`theme-prism`** / **`theme-assessment`** — built-in OKLCH brand scales in `globals.css`.
+- **`theme-custom`** — when user picks an accent in Settings; driven by `--custom-product-brand-color`.
+- **`ProductProvider`** — applies `theme-one` vs `theme-prism` vs `theme-custom`; accent override only when it **differs** from the product default (see `accentOverrideActive` in `contexts/product-context.tsx`).
+
+## Logo vs chrome
+
+- **Chrome** (sidebar, secondary panel, KPI glow) follows **`--brand-tint` / `--brand-color`** per product.
+- **Logo art** (mark + suffix) stays **Exxat pink** via `wordmarkColor` / `markGradient` in `lib/product-brand.ts` — recolouring a product in Settings changes **theme accent**, not corporate logo pink.
+
+## See also
+
+- **`docs/kpi-flat-band-pattern.md`** — flat KPI strip uses brand glow only, no surface
+- **`apps/web/AGENTS.md` §4.6** — secondary panel wiring

package/template/lib/chunk-load-error.ts

@@ -0,0 +1,13 @@
+/** Detect stale Turbopack / webpack chunk failures after dev-server rebuilds. */
+export function isChunkLoadError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false
+  const err = error as { name?: string; message?: string }
+  const name = err.name ?? ""
+  const msg = err.message ?? ""
+  return (
+    name === "ChunkLoadError" ||
+    msg.includes("Failed to load chunk") ||
+    msg.includes("Loading chunk") ||
+    msg.includes("ChunkLoadError")
+  )
+}

package/template/lib/conditional-rule-match.ts

@@ -1,32 +1,97 @@
-import type { ConditionalRule } from "@/components/table-properties/types"
+import type { ConditionalRule, FilterTextMask } from "@/components/table-properties/types"
 
-/** First matching conditional rule background for a row (same logic as DataTable cells). */
+export type ConditionalColumnHint = {
+  key: string
+  sortKey?: string
+  filter?: { type?: string; textMask?: FilterTextMask }
+}
+
+function rowValueForRule<T extends Record<string, unknown>>(
+  row: T,
+  rule: ConditionalRule,
+  columns?: ConditionalColumnHint[],
+): string {
+  const col = columns?.find(c => c.key === rule.fieldKey)
+  const dataKey = (col?.sortKey ?? rule.fieldKey) as keyof T
+  return String(row[dataKey] ?? "")
+}
+
+function ruleHasActiveValues(
+  rule: ConditionalRule,
+  columns?: ConditionalColumnHint[],
+): boolean {
+  if (rule.values.length === 0) return false
+  const col = columns?.find(c => c.key === rule.fieldKey)
+  if (col?.filter?.type === "text") return (rule.values[0] ?? "").trim().length > 0
+  return true
+}
+
+function conditionalTextMatches(
+  cellVal: string,
+  needle: string,
+  op: "contains" | "not_contains",
+  textMask: FilterTextMask | undefined,
+) {
+  const v = cellVal.trim()
+  const n = needle.trim()
+  if (!n) return op === "not_contains"
+  if (textMask === "phone" || textMask === "zip") {
+    const nd = n.replace(/\D/g, "")
+    const hay = v.replace(/\D/g, "")
+    if (!nd) return op === "not_contains"
+    const hit = hay.includes(nd)
+    return op === "contains" ? hit : !hit
+  }
+  const hit = v.toLowerCase().includes(n.toLowerCase())
+  return op === "contains" ? hit : !hit
+}
+
+/** Whether a conditional rule matches a row (same logic as DataTable cells). */
+export function conditionalRuleMatchesRow<T extends Record<string, unknown>>(
+  row: T,
+  rule: ConditionalRule,
+  columns?: ConditionalColumnHint[],
+): boolean {
+  if (!ruleHasActiveValues(rule, columns)) return false
+  const v = rowValueForRule(row, rule, columns).trim()
+  const col = columns?.find(c => c.key === rule.fieldKey)
+  const textMask = col?.filter?.type === "text" ? col.filter.textMask : undefined
+  switch (rule.operator) {
+    case "is":
+      return rule.values.includes(v)
+    case "is_not":
+      return !rule.values.includes(v)
+    case "contains":
+      return rule.values.some(val => conditionalTextMatches(v, val, "contains", textMask))
+    case "not_contains":
+      return !rule.values.some(val => conditionalTextMatches(v, val, "contains", textMask))
+    default:
+      return false
+  }
+}
+
+/** First matching conditional rule background for a row (list/board row tint). */
 export function getConditionalRowBackground<T extends Record<string, unknown>>(
   row: T,
   rules: ConditionalRule[] | undefined,
+  columns?: ConditionalColumnHint[],
 ): string | undefined {
   if (!rules?.length) return undefined
   for (const rule of rules) {
-    const cellVal = String(row[rule.fieldKey as keyof T] ?? "")
-    const v = cellVal.trim()
-    switch (rule.operator) {
-      case "is":
-        if (rule.values.length > 0 && rule.values.includes(v)) return rule.bgColor
-        break
-      case "is_not":
-        if (rule.values.length > 0 && !rule.values.includes(v)) return rule.bgColor
-        break
-      case "contains":
-        if (rule.values.length > 0 && rule.values.some(val => v.toLowerCase().includes(val.toLowerCase())))
-          return rule.bgColor
-        break
-      case "not_contains":
-        if (rule.values.length > 0 && !rule.values.some(val => v.toLowerCase().includes(val.toLowerCase())))
-          return rule.bgColor
-        break
-      default:
-        break
-    }
+    if (conditionalRuleMatchesRow(row, rule, columns)) return rule.bgColor
   }
   return undefined
 }
+
+/** Background for one table cell from conditional rules on that column. */
+export function getConditionalCellBackground<T extends Record<string, unknown>>(
+  row: T,
+  colKey: string,
+  rules: ConditionalRule[] | undefined,
+  columns?: ConditionalColumnHint[],
+): string | undefined {
+  if (!rules?.length) return undefined
+  const rule = rules.find(r => r.fieldKey === colKey)
+  if (!rule || !conditionalRuleMatchesRow(row, rule, columns)) return undefined
+  return rule.bgColor
+}

package/template/lib/data-list-view.ts

@@ -30,3 +30,9 @@ export function dataListViewLabel(view: DataListViewType): string {
 export function dataListViewIcon(view: DataListViewType): string {
   return DATA_LIST_VIEW_TILES.find(t => t.value === view)?.icon ?? "fa-table"
 }
+
+/** Add-view menu hint + `<Shortcut>` keys (1–9). Skipped in inputs via `useShortcut`. */
+export function dataListViewAddShortcut(index: number): string | undefined {
+  if (index < 0 || index > 8) return undefined
+  return String(index + 1)
+}

package/template/lib/sidebar-state-cookie.ts

@@ -0,0 +1,9 @@
+/** Cookie name persisted by `@exxatdesignux/ui` `SidebarProvider` (`setOpen`). */
+export const SIDEBAR_STATE_COOKIE_NAME = "sidebar_state"
+
+/** Read desktop sidebar expanded state for SSR `defaultOpen` (matches client cookie restore). */
+export function sidebarDefaultOpenFromCookie(
+  value: string | undefined,
+): boolean {
+  return value !== "false"
+}

package/template/lib/table-state-lifecycle.ts

@@ -229,7 +229,19 @@ function filterRecordKeys<T extends Record<string, unknown>>(obj: T, keys: Set<s
   return out
 }
 
-export function applyLifecyclePersisted(
+function sanitizeActiveFilters(
+  filters: ActiveFilter[],
+  columnKeys: Set<string>,
+): ActiveFilter[] {
+  return filters.filter(f => columnKeys.has(f.fieldKey))
+}
+
+function sanitizeSortRules(rules: SortRule[], columnKeys: Set<string>): SortRule[] {
+  return rules.filter(r => columnKeys.has(r.fieldKey))
+}
+
+/** Column layout only — keeps in-memory search / filters when the column set changes. */
+export function applyLifecycleColumnLayout(
   ts: TableStatePersistSlice,
   p: PersistedLifecycleV1,
   columnKeys: Set<string>,
@@ -241,11 +253,6 @@ export function applyLifecyclePersisted(
   const colWrap = filterRecordKeys(p.colWrap, columnKeys) as Record<string, boolean>
   const colMenuSearch = filterRecordKeys(p.colMenuSearch, columnKeys) as Record<string, string>
 
-  ts.setSortRules(p.sortRules)
-  ts.setSearch(p.search)
-  ts.setActiveFilters(p.activeFilters)
-  ts.setFilterConnectors(p.filterConnectors)
-  ts.setGroupBy(p.groupBy)
   ts.setColOrder(colOrder)
   ts.setHiddenCols(hidden)
   ts.setColWidths(colWidths)
@@ -254,6 +261,20 @@ export function applyLifecyclePersisted(
   ts.setColMenuSearch(colMenuSearch)
   ts.setRowHeight(p.rowHeight)
   ts.setShowGridlines(p.showGridlines)
+}
+
+export function applyLifecyclePersisted(
+  ts: TableStatePersistSlice,
+  p: PersistedLifecycleV1,
+  columnKeys: Set<string>,
+): void {
+  applyLifecycleColumnLayout(ts, p, columnKeys)
+
+  ts.setSortRules(sanitizeSortRules(p.sortRules, columnKeys))
+  ts.setSearch(p.search)
+  ts.setActiveFilters(sanitizeActiveFilters(p.activeFilters, columnKeys))
+  ts.setFilterConnectors(p.filterConnectors)
+  ts.setGroupBy(p.groupBy != null && columnKeys.has(p.groupBy) ? p.groupBy : null)
   ts.setFilterBarVisible(p.filterBarVisible)
   ts.setSearchOpen(p.searchOpen)
 }
@@ -427,20 +448,46 @@ export function useTableStateLifecycle<TExtras extends Record<string, unknown> |
     onLoadExtrasRef.current = onLoadExtras
   })
 
+  const columnKeysFingerprint = React.useMemo(
+    () => [...columnKeys].sort().join("\0"),
+    [columnKeys],
+  )
+
+  const loadedScopeRef = React.useRef<string | null>(null)
+  const appliedColumnFingerprintRef = React.useRef<string | null>(null)
+
   // ── Load ────────────────────────────────────────────────────────────────
   // useLayoutEffect so the rehydrated state paints in the first frame after
   // mount instead of flashing the unhydrated defaults first.
   React.useLayoutEffect(() => {
+    // Wait until column defs exist — applying persisted sort/filters against an
+    // empty key set would sanitize everything away and look like Properties broke.
+    if (columnKeys.size === 0) return
+
+    const scope = `${namespace}:${tabId}`
     const raw = loadLifecycleFromStorage(namespace, tabId)
+
+    if (loadedScopeRef.current !== scope) {
+      loadedScopeRef.current = scope
+      appliedColumnFingerprintRef.current = columnKeysFingerprint
+      if (!raw) return
+      applyLifecyclePersisted(tableState, raw, columnKeys)
+      const e = readLifecycleExtras<Record<string, unknown>>(raw)
+      onLoadExtrasRef.current?.(e as TExtras | Record<string, unknown> | undefined)
+      return
+    }
+
+    if (appliedColumnFingerprintRef.current === columnKeysFingerprint) return
+    appliedColumnFingerprintRef.current = columnKeysFingerprint
     if (!raw) return
-    applyLifecyclePersisted(tableState, raw, columnKeys)
-    const e = readLifecycleExtras<Record<string, unknown>>(raw)
-    onLoadExtrasRef.current?.(e as TExtras | Record<string, unknown> | undefined)
+    // Column defs changed (e.g. hub scope / dynamic filter options) — re-merge
+    // layout only; do not wipe in-memory filters the user set in Properties.
+    applyLifecycleColumnLayout(tableState, raw, columnKeys)
     // `tableState` is freshly returned each render; depending on it would
     // re-apply persisted state on every keystroke and undo edits. Depend only
-    // on the load scope (namespace + tabId + column set).
+    // on the load scope (namespace + tabId + column fingerprint).
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [namespace, tabId, columnKeys])
+  }, [namespace, tabId, columnKeysFingerprint])
 
   // ── Save ────────────────────────────────────────────────────────────────
   // Serialise + debounce on every persisted slice change. Don't depend on