npm - @exxatdesignux/ui - Versions diffs - 0.2.16 → 0.2.17 - Mend

@exxatdesignux/ui 0.2.16 → 0.2.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (89) hide show

package/CHANGELOG.md +11 -0
package/consumer-extras/cursor-skills/exxat-ds-skill/SKILL.md +148 -3
package/consumer-extras/cursor-skills/exxat-ds-skill/references/accessibility.md +142 -0
package/consumer-extras/cursor-skills/exxat-ds-skill/references/coach-marks.md +169 -0
package/consumer-extras/cursor-skills/exxat-ds-skill/references/data-table-pattern.md +382 -0
package/consumer-extras/cursor-skills/exxat-mono-ids/SKILL.md +56 -0
package/consumer-extras/cursor-skills/exxat-primary-nav-secondary-panel/SKILL.md +14 -0
package/package.json +3 -3
package/src/components/ui/banner.tsx +2 -0
package/src/components/ui/chart.tsx +57 -2
package/src/components/ui/sidebar.tsx +1 -0
package/template/.claude/skills/exxat-ds-skill/SKILL.md +1 -1
package/template/.cursor/rules/exxat-mono-ids.mdc +30 -0
package/template/AGENTS.md +18 -15
package/template/app/(app)/data-list/page.tsx +2 -2
package/template/app/(app)/question-bank/layout.tsx +18 -5
package/template/app/(app)/question-bank/new/page.tsx +58 -0
package/template/app/globals.css +108 -1
package/template/app/layout.tsx +41 -5
package/template/components/app-sidebar.tsx +68 -34
package/template/components/ask-leo-sidebar.tsx +0 -2
package/template/components/brand-color-picker.tsx +344 -0
package/template/components/compliance-list-view.tsx +33 -51
package/template/components/compliance-table.tsx +24 -0
package/template/components/data-table/index.tsx +68 -24
package/template/components/data-table/pagination.tsx +0 -1
package/template/components/data-table/types.ts +4 -1
package/template/components/data-table/use-table-state.ts +243 -94
package/template/components/data-views/data-row-list.tsx +183 -0
package/template/components/data-views/index.ts +7 -3
package/template/components/data-views/os-folder-glyph.tsx +8 -0
package/template/components/export-drawer.tsx +1 -1
package/template/components/exxat-product-logo.tsx +172 -317
package/template/components/invite-collaborators-drawer.tsx +5 -3
package/template/components/key-metrics.tsx +74 -46
package/template/components/new-placement-form.tsx +4 -2
package/template/components/new-question-composer.tsx +2208 -0
package/template/components/page-breadcrumb-trail.tsx +131 -0
package/template/components/page-header.tsx +2 -1
package/template/components/{data-views/placement-board-card.tsx → placement-board-card.tsx} +1 -1
package/template/components/placement-detail.tsx +1 -1
package/template/components/placements-board-view.tsx +1 -1
package/template/components/{data-list-client.tsx → placements-client.tsx} +9 -7
package/template/components/placements-list-view.tsx +18 -132
package/template/components/{data-list-table-cells.test.tsx → placements-table-cells.test.tsx} +2 -2
package/template/components/{data-list-table-cells.tsx → placements-table-cells.tsx} +1 -1
package/template/components/placements-table-columns.tsx +2 -2
package/template/components/{data-list-table.tsx → placements-table.tsx} +67 -58
package/template/components/product-switcher.tsx +26 -8
package/template/components/product-wordmark.tsx +285 -0
package/template/components/question-bank-client.tsx +20 -2
package/template/components/question-bank-hub-client.tsx +108 -115
package/template/components/question-bank-list-view.tsx +30 -54
package/template/components/question-bank-new-folder-sheet.tsx +1 -1
package/template/components/question-bank-secondary-nav.tsx +0 -3
package/template/components/question-bank-table.tsx +30 -5
package/template/components/rotations-empty-state.tsx +3 -0
package/template/components/secondary-panel.tsx +23 -3
package/template/components/settings-appearance-card.tsx +584 -141
package/template/components/site-header.tsx +36 -31
package/template/components/sites-list-view.tsx +31 -36
package/template/components/sites-table.tsx +24 -0
package/template/components/table-properties/drawer.tsx +1 -1
package/template/components/team-client.tsx +1 -1
package/template/components/team-list-view.tsx +34 -50
package/template/components/team-table.tsx +29 -3
package/template/components/templates/nested-secondary-panel-shell.tsx +8 -2
package/template/components/ui/dot-pattern.tsx +50 -26
package/template/components/ui/leo-icon.tsx +23 -3
package/template/contexts/product-context.tsx +51 -7
package/template/contexts/system-banner-context.tsx +112 -4
package/template/eslint.config.mjs +18 -0
package/template/hooks/use-sidebar-reflow-zoom.ts +21 -11
package/template/lib/data-list-persistence.ts +57 -257
package/template/lib/dev-log.test.ts +6 -5
package/template/lib/exxat-palette.json +1462 -0
package/template/lib/exxat-palette.ts +136 -0
package/template/lib/list-page-table-properties.ts +1 -1
package/template/lib/list-status-badges.ts +1 -1
package/template/lib/mailto.ts +29 -0
package/template/lib/placement-board-card-layout.ts +1 -1
package/template/lib/product-brand.ts +268 -0
package/template/lib/question-bank-authoring.ts +308 -0
package/template/lib/question-bank-nav.ts +44 -0
package/template/lib/raf-throttle.ts +45 -0
package/template/lib/table-state-lifecycle.ts +474 -0
package/template/next.config.mjs +156 -0
package/template/package.json +3 -3
package/template/stores/app-store.ts +46 -1

package/template/contexts/product-context.tsx CHANGED Viewed

@@ -10,29 +10,73 @@
 import * as React from "react"
 import { useAppStore, type Product } from "@/stores/app-store"
+import { brandForProduct } from "@/lib/product-brand"
 export type { Product }
 export function useProduct() {
-  const product    = useAppStore(s => s.product)
-  const setProduct = useAppStore(s => s.setProduct)
-  return { product, setProduct }
+  const product               = useAppStore(s => s.product)
+  const setProduct            = useAppStore(s => s.setProduct)
+  const customProductBrand    = useAppStore(s => s.customProductBrand)
+  const setCustomProductBrand = useAppStore(s => s.setCustomProductBrand)
+  const productBrandColors    = useAppStore(s => s.productBrandColors)
+  const setProductBrandColor  = useAppStore(s => s.setProductBrandColor)
+  const hiddenProductIds      = useAppStore(s => s.hiddenProductIds)
+  const hideProduct           = useAppStore(s => s.hideProduct)
+  const showProduct           = useAppStore(s => s.showProduct)
+  return {
+    product,
+    setProduct,
+    customProductBrand,
+    setCustomProductBrand,
+    productBrandColors,
+    setProductBrandColor,
+    hiddenProductIds,
+    hideProduct,
+    showProduct,
+  }
 }
 export function ProductProvider({ children }: { children: React.ReactNode }) {
   const product = useAppStore(s => s.product)
+  const customProductBrand = useAppStore(s => s.customProductBrand)
+  const productBrandColors = useAppStore(s => s.productBrandColors)
   // Rehydrate from localStorage once — keeps SSR render matching server output.
   React.useEffect(() => {
     void useAppStore.persist.rehydrate()
   }, [])
-  // Sync theme class to <html> whenever product changes.
+  // Sync theme class to <html> whenever product (or its accent override) changes.
   React.useEffect(() => {
     const html = document.documentElement
-    html.classList.remove("theme-one", "theme-prism")
-    html.classList.add(product === "exxat-one" ? "theme-one" : "theme-prism")
-  }, [product])
+    html.classList.remove("theme-one", "theme-prism", "theme-assessment", "theme-custom")
+    // Effective brand colour for the active product — picks up any
+    // per-product override the user set in Settings → Appearance. Drives
+    // `--custom-product-brand-color` so `theme-custom` chrome retints.
+    const effectiveBrandColor = brandForProduct(product, customProductBrand, productBrandColors).brandColor
+    html.style.setProperty("--custom-product-brand-color", effectiveBrandColor)
+    // If the user has set a brand-colour override for the active product,
+    // flip to `theme-custom` so the chrome retints from
+    // `--custom-product-brand-color`. The hardcoded `theme-one / theme-prism
+    // / theme-assessment` classes (with bespoke hue formulas in
+    // `globals.css`) are still used for the **default** look of each
+    // built-in.
+    const hasAccentOverride = Boolean(productBrandColors[product])
+    let themeClass: "theme-one" | "theme-prism" | "theme-assessment" | "theme-custom"
+    if (hasAccentOverride) {
+      themeClass = "theme-custom"
+    } else if (product === "exxat-one") {
+      themeClass = "theme-one"
+    } else if (product === "exxat-prism") {
+      themeClass = "theme-prism"
+    } else if (product === "exxat-assessment" || (product === "exxat-custom" && !customProductBrand)) {
+      themeClass = "theme-assessment"
+    } else {
+      themeClass = "theme-custom"
+    }
+    html.classList.add(themeClass)
+  }, [customProductBrand, product, productBrandColors])
   return <>{children}</>
 }

package/template/contexts/system-banner-context.tsx CHANGED Viewed

@@ -43,6 +43,111 @@ export const DEFAULT_SYSTEM_BANNER_CONFIG: SystemBannerConfig = {
 const STORAGE_KEY = "exxat:system-banner-config"
+const ALLOWED_VARIANTS: ReadonlySet<SystemBannerVariant> = new Set([
+  "info",
+  "warning",
+  "error",
+  "success",
+  "promo",
+])
+const ALLOWED_EMPHASIS: ReadonlySet<SystemBannerEmphasis> = new Set([
+  "prominent",
+  "subtle",
+])
+/**
+ * Strip any `actionHref` whose URL scheme could execute script when the
+ * banner CTA is clicked (`javascript:`, `data:`, `vbscript:`, etc.).
+ *
+ * The banner UI renders `actionHref` as a plain `<a href>`, so a malicious
+ * value in `localStorage` — written by an extension, a victim of a
+ * same-origin bug elsewhere, or a future feature that accepts user input —
+ * would become a one-click XSS or open-redirect vector on every tab that
+ * receives the storage event. We accept only:
+ *
+ *   - Absolute http(s) URLs.
+ *   - Absolute mailto: / tel: URIs (banner CTAs sometimes deep-link these).
+ *   - Same-origin relative paths (`/foo`, `./bar`, `../baz`).
+ *   - The single legacy placeholder `"#"` shipped in the default config.
+ *
+ * Anything else collapses to `undefined`, which the banner treats as
+ * "no CTA link".
+ */
+function sanitizeActionHref(href: unknown): string | undefined {
+  if (typeof href !== "string") return undefined
+  const trimmed = href.trim()
+  if (!trimmed) return undefined
+  if (trimmed === "#") return trimmed
+  // Same-origin relative paths.
+  if (
+    trimmed.startsWith("/") ||
+    trimmed.startsWith("./") ||
+    trimmed.startsWith("../")
+  ) {
+    return trimmed
+  }
+  // Absolute URLs — only allow http(s) / mailto: / tel:.
+  try {
+    // Use a dummy base so `new URL` accepts both absolute and protocol-relative inputs.
+    const url = new URL(trimmed, "https://exxat.invalid")
+    if (
+      url.protocol === "http:" ||
+      url.protocol === "https:" ||
+      url.protocol === "mailto:" ||
+      url.protocol === "tel:"
+    ) {
+      return trimmed
+    }
+  } catch {
+    /* fallthrough to reject */
+  }
+  return undefined
+}
+/**
+ * Coerce an unknown JSON payload (from `localStorage` or a cross-tab
+ * `storage` event) into a `SystemBannerConfig`. Unknown fields are dropped,
+ * known fields are type-narrowed, and any string field is capped so a
+ * malformed/oversized payload cannot stall the renderer.
+ *
+ * Returns `null` when the payload cannot be coerced — callers fall back to
+ * the shipped default rather than render attacker-controlled content.
+ */
+function coerceConfig(raw: unknown): SystemBannerConfig | null {
+  if (!raw || typeof raw !== "object") return null
+  const r = raw as Record<string, unknown>
+  const str = (v: unknown, max = 280): string | undefined =>
+    typeof v === "string" ? v.slice(0, max) : undefined
+  const variant = ALLOWED_VARIANTS.has(r.variant as SystemBannerVariant)
+    ? (r.variant as SystemBannerVariant)
+    : DEFAULT_SYSTEM_BANNER_CONFIG.variant
+  const emphasis = ALLOWED_EMPHASIS.has(r.emphasis as SystemBannerEmphasis)
+    ? (r.emphasis as SystemBannerEmphasis)
+    : DEFAULT_SYSTEM_BANNER_CONFIG.emphasis
+  return {
+    enabled:
+      typeof r.enabled === "boolean"
+        ? r.enabled
+        : DEFAULT_SYSTEM_BANNER_CONFIG.enabled,
+    variant,
+    emphasis,
+    title: str(r.title, 120) ?? DEFAULT_SYSTEM_BANNER_CONFIG.title,
+    message: str(r.message, 280) ?? DEFAULT_SYSTEM_BANNER_CONFIG.message,
+    actionLabel: str(r.actionLabel, 60),
+    actionHref: sanitizeActionHref(r.actionHref),
+    dismissible:
+      typeof r.dismissible === "boolean"
+        ? r.dismissible
+        : DEFAULT_SYSTEM_BANNER_CONFIG.dismissible,
+  }
+}
 interface SystemBannerContextValue {
   config: SystemBannerConfig
   updateConfig: (patch: Partial<SystemBannerConfig>) => void
@@ -66,9 +171,8 @@ function readStored(): SystemBannerConfig {
   try {
     const raw = window.localStorage.getItem(STORAGE_KEY)
     if (!raw) return DEFAULT_SYSTEM_BANNER_CONFIG
-    const parsed = JSON.parse(raw) as Partial<SystemBannerConfig>
-    // Merge so newly-added fields in the default keep working for old payloads.
-    return { ...DEFAULT_SYSTEM_BANNER_CONFIG, ...parsed }
+    const coerced = coerceConfig(JSON.parse(raw))
+    return coerced ?? DEFAULT_SYSTEM_BANNER_CONFIG
   } catch {
     return DEFAULT_SYSTEM_BANNER_CONFIG
   }
@@ -95,11 +199,15 @@ export function SystemBannerProvider({ children }: { children: React.ReactNode }
   }, [config, hydrated])
   // Cross-tab sync — if you change the banner in one tab, others follow.
+  // The payload is treated as untrusted (an extension or future bug could
+  // write into the same key) so we route it through `coerceConfig` to drop
+  // unknown fields and `sanitizeActionHref` to refuse `javascript:` URLs.
   React.useEffect(() => {
     function onStorage(e: StorageEvent) {
       if (e.key !== STORAGE_KEY || !e.newValue) return
       try {
-        setConfig({ ...DEFAULT_SYSTEM_BANNER_CONFIG, ...JSON.parse(e.newValue) })
+        const coerced = coerceConfig(JSON.parse(e.newValue))
+        if (coerced) setConfig(coerced)
       } catch {
         /* ignore malformed payloads */
       }

package/template/eslint.config.mjs CHANGED Viewed

@@ -13,6 +13,24 @@ const eslintConfig = defineConfig([
     "build/**",
     "next-env.d.ts",
   ]),
+  {
+    rules: {
+      // Allow intentionally-unused args / vars / destructured props /
+      // generics when prefixed with `_`. This is the standard escape hatch
+      // for "I'm satisfying a callback signature but don't need this slot"
+      // — common in cell renderers (`(value, _row) => …`), destructured
+      // tuples (`const [_, setX] = useState()`), and generic constraints.
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+          caughtErrorsIgnorePattern: "^_",
+          destructuredArrayIgnorePattern: "^_",
+        },
+      ],
+    },
+  },
 ]);
 export default eslintConfig;

package/template/hooks/use-sidebar-reflow-zoom.ts CHANGED Viewed

@@ -1,6 +1,7 @@
 "use client"
 import * as React from "react"
+import { rafThrottle } from "@/lib/raf-throttle"
 /**
  * When true, the sidebar should **not** pin utilities + profile to the bottom — the whole
@@ -14,25 +15,34 @@ export function useSidebarReflowZoom(): boolean {
   React.useEffect(() => {
     const vv = window.visualViewport
+    // Cache the MediaQueryList — calling `matchMedia` on every compute() is
+    // measurable on pinch/zoom where visualViewport scroll fires per frame.
+    const mql = window.matchMedia("(max-height: 640px)")
     function compute() {
       const scale = vv?.scale ?? 1
-      const short = window.matchMedia("(max-height: 640px)").matches
+      const short = mql.matches
       const veryShort = window.innerHeight <= 420
-      setReflow(scale >= 1.99 || short || veryShort)
+      const next = scale >= 1.99 || short || veryShort
+      // Avoid unnecessary React re-renders when nothing changed.
+      setReflow(prev => (prev === next ? prev : next))
     }
     compute()
-    vv?.addEventListener("resize", compute)
-    vv?.addEventListener("scroll", compute)
-    window.addEventListener("resize", compute)
-    const mql = window.matchMedia("(max-height: 640px)")
-    mql.addEventListener("change", compute)
+    // rAF-coalesce: visualViewport.scroll can fire hundreds of times per second
+    // during pinch-zoom — without throttling we trigger setReflow + matchMedia
+    // per event. One sample per frame is enough for a layout breakpoint flag.
+    const scheduled = rafThrottle(compute)
+    vv?.addEventListener("resize", scheduled, { passive: true })
+    vv?.addEventListener("scroll", scheduled, { passive: true })
+    window.addEventListener("resize", scheduled, { passive: true })
+    mql.addEventListener("change", scheduled)
     return () => {
-      vv?.removeEventListener("resize", compute)
-      vv?.removeEventListener("scroll", compute)
-      window.removeEventListener("resize", compute)
-      mql.removeEventListener("change", compute)
+      scheduled.cancel()
+      vv?.removeEventListener("resize", scheduled)
+      vv?.removeEventListener("scroll", scheduled)
+      window.removeEventListener("resize", scheduled)
+      mql.removeEventListener("change", scheduled)
     }
   }, [])

package/template/lib/data-list-persistence.ts CHANGED Viewed

@@ -1,280 +1,80 @@
 /**
- * Persist Data list page UI: per-page shell (tabs, display options) and per–lifecycle-tab table state.
- * Keys are versioned so future migrations can bump `v` or the key suffix.
+ * @deprecated Placements-specific shim around the generic
+ * `@/lib/table-state-lifecycle`. New code SHOULD import the generic helpers
+ * (and the `useTableStateLifecycle` hook) directly. This file preserves the
+ * old API + the old storage key prefix (`exxat-ds:data-list:*`) so existing
+ * placements `localStorage` payloads continue to work during the migration.
  */
-import type { Dispatch, SetStateAction } from "react"
-import type { RowHeight } from "@/lib/row-height"
-import type { DataListDisplayOptions } from "@/lib/data-list-display-options"
-import type { ActiveFilter, ConditionalRule, SortRule } from "@/components/table-properties/types"
-import type { ViewTab } from "@/components/templates/list-page"
-import type { DataListViewType } from "@/lib/data-list-view"
-export const DATA_LIST_PAGE_STORAGE_KEY = "exxat-ds:data-list:page:v1"
+import {
+  applyLifecyclePersisted as applyLifecyclePersistedGeneric,
+  loadLifecycleFromStorage as loadLifecycleFromStorageGeneric,
+  loadPageFromStorage as loadPageFromStorageGeneric,
+  lifecycleStorageKey as lifecycleStorageKeyGeneric,
+  pageStorageKey,
+  parsePersistedLifecycle,
+  parsePersistedPage,
+  scheduleLifecycleSave as scheduleLifecycleSaveGeneric,
+  schedulePageSave as schedulePageSaveGeneric,
+  serializeLifecycle as serializeLifecycleGeneric,
+  type PersistedLifecycleV1,
+  type PersistedPageV1,
+  type TableStatePersistSlice,
+} from "@/lib/table-state-lifecycle"
+import type { ConditionalRule } from "@/components/table-properties/types"
+/** Legacy namespace — kept so existing placements payloads remain readable. */
+const PLACEMENTS_NAMESPACE = "data-list"
+export const DATA_LIST_PAGE_STORAGE_KEY = pageStorageKey(PLACEMENTS_NAMESPACE)
 export function lifecycleStorageKey(lifecycleTabId: string): string {
-  return `exxat-ds:data-list:lifecycle:v1:${lifecycleTabId}`
-}
-const LIFECYCLE_SAVE_DEBOUNCE_MS = 400
-const PAGE_SAVE_DEBOUNCE_MS = 400
-const lifecycleTimers = new Map<string, ReturnType<typeof setTimeout>>()
-const pageTimer: { t?: ReturnType<typeof setTimeout> } = {}
-export interface PersistedLifecycleV1 {
-  v: 1
-  sortRules: SortRule[]
-  search: string
-  activeFilters: ActiveFilter[]
-  filterConnectors: Record<string, "and" | "or">
-  groupBy: string | null
-  colOrder: string[]
-  hiddenCols: string[]
-  colWidths: Record<string, number>
-  colPins: Record<string, "left" | "right">
-  colWrap: Record<string, boolean>
-  colMenuSearch: Record<string, string>
-  rowHeight: RowHeight
-  showGridlines: boolean
-  filterBarVisible: boolean
-  searchOpen: boolean
-  conditionalRules: ConditionalRule[]
-  pagination: boolean
-  paginationPage: number
-  paginationPageSize: number
-}
-export interface PersistedPageV1 {
-  v: 1
-  displayOptions: DataListDisplayOptions
-  showMetrics: boolean
-  tabs: ViewTab[]
-  activeTabId: string
-}
-/** Narrow surface used to hydrate / snapshot table state without importing the hook implementation. */
-export interface TableStatePersistSlice {
-  sortRules: SortRule[]
-  search: string
-  activeFilters: ActiveFilter[]
-  filterConnectors: Record<string, "and" | "or">
-  groupBy: string | null
-  colOrder: string[]
-  hiddenCols: Set<string>
-  colWidths: Record<string, number>
-  colPins: Record<string, "left" | "right">
-  colWrap: Record<string, boolean>
-  colMenuSearch: Record<string, string>
-  rowHeight: RowHeight
-  showGridlines: boolean
-  filterBarVisible: boolean
-  searchOpen: boolean
-  setSortRules: Dispatch<SetStateAction<SortRule[]>>
-  setSearch: Dispatch<SetStateAction<string>>
-  setActiveFilters: Dispatch<SetStateAction<ActiveFilter[]>>
-  setFilterConnectors: Dispatch<SetStateAction<Record<string, "and" | "or">>>
-  setGroupBy: Dispatch<SetStateAction<string | null>>
-  setColOrder: Dispatch<SetStateAction<string[]>>
-  setHiddenCols: Dispatch<SetStateAction<Set<string>>>
-  setColWidths: Dispatch<SetStateAction<Record<string, number>>>
-  setColPins: Dispatch<SetStateAction<Record<string, "left" | "right">>>
-  setColWrap: Dispatch<SetStateAction<Record<string, boolean>>>
-  setColMenuSearch: Dispatch<SetStateAction<Record<string, string>>>
-  setRowHeight: Dispatch<SetStateAction<RowHeight>>
-  setShowGridlines: Dispatch<SetStateAction<boolean>>
-  setFilterBarVisible: Dispatch<SetStateAction<boolean>>
-  setSearchOpen: Dispatch<SetStateAction<boolean>>
-}
-const VIEW_TYPES: DataListViewType[] = ["table", "list", "board", "dashboard"]
-function isViewType(v: unknown): v is DataListViewType {
-  return typeof v === "string" && (VIEW_TYPES as string[]).includes(v)
+  return lifecycleStorageKeyGeneric(PLACEMENTS_NAMESPACE, lifecycleTabId)
 }
-function parseViewTab(raw: unknown): ViewTab | null {
-  if (!raw || typeof raw !== "object") return null
-  const o = raw as Record<string, unknown>
-  if (typeof o.id !== "string" || typeof o.label !== "string") return null
-  if (!isViewType(o.viewType)) return null
-  if (typeof o.icon !== "string" || typeof o.filterId !== "string") return null
-  return {
-    id: o.id,
-    label: o.label,
-    viewType: o.viewType,
-    icon: o.icon,
-    filterId: o.filterId,
-  }
+export {
+  parsePersistedLifecycle,
+  parsePersistedPage,
+  applyLifecyclePersistedGeneric as applyLifecyclePersisted,
+  type PersistedLifecycleV1,
+  type PersistedPageV1,
+  type TableStatePersistSlice,
 }
-export function parsePersistedPage(raw: string | null): PersistedPageV1 | null {
-  if (!raw) return null
-  try {
-    const j = JSON.parse(raw) as unknown
-    if (!j || typeof j !== "object") return null
-    const o = j as Record<string, unknown>
-    if (o.v !== 1) return null
-    if (!o.displayOptions || typeof o.displayOptions !== "object") return null
-    if (typeof o.showMetrics !== "boolean") return null
-    if (!Array.isArray(o.tabs) || typeof o.activeTabId !== "string") return null
-    const tabs = o.tabs.map(parseViewTab).filter((t): t is ViewTab => t !== null)
-    if (tabs.length === 0) return null
-    return {
-      v: 1,
-      displayOptions: o.displayOptions as DataListDisplayOptions,
-      showMetrics: o.showMetrics,
-      tabs,
-      activeTabId: o.activeTabId,
-    }
-  } catch {
-    return null
-  }
+export function loadLifecycleFromStorage(lifecycleTabId: string): PersistedLifecycleV1 | null {
+  return loadLifecycleFromStorageGeneric(PLACEMENTS_NAMESPACE, lifecycleTabId)
 }
-export function parsePersistedLifecycle(raw: string | null): PersistedLifecycleV1 | null {
-  if (!raw) return null
-  try {
-    const j = JSON.parse(raw) as unknown
-    if (!j || typeof j !== "object") return null
-    const o = j as Record<string, unknown>
-    if (o.v !== 1) return null
-    if (!Array.isArray(o.sortRules)) return null
-    if (typeof o.search !== "string") return null
-    if (!Array.isArray(o.activeFilters)) return null
-    if (!o.filterConnectors || typeof o.filterConnectors !== "object") return null
-    if (o.groupBy !== null && typeof o.groupBy !== "string") return null
-    if (!Array.isArray(o.colOrder)) return null
-    if (!Array.isArray(o.hiddenCols)) return null
-    if (!o.colWidths || typeof o.colWidths !== "object") return null
-    if (!o.colPins || typeof o.colPins !== "object") return null
-    if (!o.colWrap || typeof o.colWrap !== "object") return null
-    if (!o.colMenuSearch || typeof o.colMenuSearch !== "object") return null
-    if (typeof o.rowHeight !== "string") return null
-    if (typeof o.showGridlines !== "boolean") return null
-    if (typeof o.filterBarVisible !== "boolean") return null
-    if (typeof o.searchOpen !== "boolean") return null
-    if (!Array.isArray(o.conditionalRules)) return null
-    if (typeof o.pagination !== "boolean") return null
-    if (typeof o.paginationPage !== "number" || typeof o.paginationPageSize !== "number") return null
-    return o as unknown as PersistedLifecycleV1
-  } catch {
-    return null
-  }
+export function scheduleLifecycleSave(
+  lifecycleTabId: string,
+  payload: PersistedLifecycleV1,
+): void {
+  scheduleLifecycleSaveGeneric(PLACEMENTS_NAMESPACE, lifecycleTabId, payload)
 }
-function mergeColOrder(saved: string[], columnKeys: Set<string>): string[] {
-  const ordered = saved.filter(k => columnKeys.has(k))
-  for (const k of columnKeys) {
-    if (!ordered.includes(k)) ordered.push(k)
-  }
-  return ordered
+export function loadPageFromStorage(): PersistedPageV1 | null {
+  return loadPageFromStorageGeneric(PLACEMENTS_NAMESPACE)
 }
-function filterRecordKeys<T extends Record<string, unknown>>(obj: T, keys: Set<string>): T {
-  const out = { ...obj }
-  for (const k of Object.keys(out)) {
-    if (!keys.has(k)) delete out[k]
-  }
-  return out
+export function schedulePageSave(payload: PersistedPageV1): void {
+  schedulePageSaveGeneric(PLACEMENTS_NAMESPACE, payload)
 }
-export function applyLifecyclePersisted(
-  ts: TableStatePersistSlice,
-  p: PersistedLifecycleV1,
-  columnKeys: Set<string>,
-): void {
-  const colOrder = mergeColOrder(p.colOrder, columnKeys)
-  const hidden = new Set(p.hiddenCols.filter(k => columnKeys.has(k)))
-  const colWidths = filterRecordKeys(p.colWidths, columnKeys) as Record<string, number>
-  const colPins = filterRecordKeys(p.colPins, columnKeys) as Record<string, "left" | "right">
-  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)
-  ts.setColPins(colPins)
-  ts.setColWrap(colWrap)
-  ts.setColMenuSearch(colMenuSearch)
-  ts.setRowHeight(p.rowHeight)
-  ts.setShowGridlines(p.showGridlines)
-  ts.setFilterBarVisible(p.filterBarVisible)
-  ts.setSearchOpen(p.searchOpen)
+/**
+ * Placements lifecycle includes a few extra fields next to the table state.
+ * The generic serializer takes a free-form `extras` record; this thin
+ * adapter keeps the original call sites typed and ergonomic.
+ */
+export interface PlacementsLifecycleExtras extends Record<string, unknown> {
+  conditionalRules: ConditionalRule[]
+  pagination: boolean
+  paginationPage: number
+  paginationPageSize: number
 }
 export function serializeLifecycle(
   ts: TableStatePersistSlice,
-  extras: {
-    conditionalRules: ConditionalRule[]
-    pagination: boolean
-    paginationPage: number
-    paginationPageSize: number
-  },
+  extras: PlacementsLifecycleExtras,
 ): PersistedLifecycleV1 {
-  return {
-    v: 1,
-    sortRules: ts.sortRules,
-    search: ts.search,
-    activeFilters: ts.activeFilters,
-    filterConnectors: ts.filterConnectors,
-    groupBy: ts.groupBy,
-    colOrder: ts.colOrder,
-    hiddenCols: [...ts.hiddenCols],
-    colWidths: { ...ts.colWidths },
-    colPins: { ...ts.colPins },
-    colWrap: { ...ts.colWrap },
-    colMenuSearch: { ...ts.colMenuSearch },
-    rowHeight: ts.rowHeight,
-    showGridlines: ts.showGridlines,
-    filterBarVisible: ts.filterBarVisible,
-    searchOpen: ts.searchOpen,
-    conditionalRules: extras.conditionalRules,
-    pagination: extras.pagination,
-    paginationPage: extras.paginationPage,
-    paginationPageSize: extras.paginationPageSize,
-  }
-}
-export function loadLifecycleFromStorage(lifecycleTabId: string): PersistedLifecycleV1 | null {
-  if (typeof window === "undefined") return null
-  return parsePersistedLifecycle(localStorage.getItem(lifecycleStorageKey(lifecycleTabId)))
-}
-export function scheduleLifecycleSave(lifecycleTabId: string, payload: PersistedLifecycleV1): void {
-  if (typeof window === "undefined") return
-  const prev = lifecycleTimers.get(lifecycleTabId)
-  if (prev) clearTimeout(prev)
-  const t = setTimeout(() => {
-    lifecycleTimers.delete(lifecycleTabId)
-    try {
-      localStorage.setItem(lifecycleStorageKey(lifecycleTabId), JSON.stringify(payload))
-    } catch {
-      /* quota / private mode */
-    }
-  }, LIFECYCLE_SAVE_DEBOUNCE_MS)
-  lifecycleTimers.set(lifecycleTabId, t)
-}
-export function loadPageFromStorage(): PersistedPageV1 | null {
-  if (typeof window === "undefined") return null
-  return parsePersistedPage(localStorage.getItem(DATA_LIST_PAGE_STORAGE_KEY))
-}
-export function schedulePageSave(payload: PersistedPageV1): void {
-  if (typeof window === "undefined") return
-  if (pageTimer.t) clearTimeout(pageTimer.t)
-  pageTimer.t = setTimeout(() => {
-    pageTimer.t = undefined
-    try {
-      localStorage.setItem(DATA_LIST_PAGE_STORAGE_KEY, JSON.stringify(payload))
-    } catch {
-      /* quota */
-    }
-  }, PAGE_SAVE_DEBOUNCE_MS)
+  return serializeLifecycleGeneric(ts, extras)
 }

package/template/lib/dev-log.test.ts CHANGED Viewed

@@ -3,25 +3,26 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
 import { devLog } from "./dev-log"
 describe("devLog", () => {
-  const originalEnv = process.env.NODE_ENV
   beforeEach(() => {
     vi.spyOn(console, "log").mockImplementation(() => {})
   })
   afterEach(() => {
     vi.restoreAllMocks()
-    process.env.NODE_ENV = originalEnv
+    vi.unstubAllEnvs()
   })
   it("logs in development", () => {
-    process.env.NODE_ENV = "development"
+    // `process.env.NODE_ENV` is typed as readonly in modern Node typings; use
+    // Vitest's `stubEnv` so the test compiles without a `// @ts-expect-error`
+    // dance and auto-restores after `unstubAllEnvs()`.
+    vi.stubEnv("NODE_ENV", "development")
     devLog("hello", 1)
     expect(console.log).toHaveBeenCalledWith("hello", 1)
   })
   it("does not log in production", () => {
-    process.env.NODE_ENV = "production"
+    vi.stubEnv("NODE_ENV", "production")
     devLog("silent")
     expect(console.log).not.toHaveBeenCalled()
   })