@exxatdesignux/ui 0.2.15 → 0.2.17

package/template/components/ui/dot-pattern.tsx

@@ -37,8 +37,32 @@ type Cloud = {
   delay: number
 }
 
-function rand(min: number, max: number) {
-  return min + Math.random() * (max - min)
+/**
+ * Tiny deterministic PRNG (mulberry32). We use a seeded RNG instead of
+ * `Math.random()` so the SVG attributes emitted on the server match the
+ * client's first paint — otherwise React reports a hydration mismatch and
+ * has to re-paint every drifting `<motion.circle>` on mount, which is both
+ * a perf cost and a visible jump.
+ */
+function mulberry32(seed: number): () => number {
+  let s = seed >>> 0
+  return () => {
+    s = (s + 0x6d2b79f5) >>> 0
+    let t = s
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+function hashString(str: string): number {
+  // Cheap FNV-1a-style hash. Stable across SSR + CSR for the same input.
+  let h = 2166136261
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i)
+    h = Math.imul(h, 16777619)
+  }
+  return h >>> 0
 }
 
 export function DotPattern({
@@ -59,33 +83,33 @@ export function DotPattern({
   const maskId = `${id}-mask`
   const gradId = `${id}-grad`
 
-  const clouds = React.useMemo<Cloud[]>(
-    () =>
-      Array.from({ length: glowCount }).map((_, i) => {
-        // Drift diagonally: bottom-right → top-left. Start/end partly off-canvas
-        // so the cloud enters and exits softly without a visible edge.
-        const startX = rand(85, 120)
-        const endX = rand(-20, 15)
-        const midX = (startX + endX) / 2 + rand(-6, 6)
+  const clouds = React.useMemo<Cloud[]>(() => {
+    const rng = mulberry32(hashString(`${id}|${glowCount}`))
+    const rand = (min: number, max: number) => min + rng() * (max - min)
+    return Array.from({ length: glowCount }).map((_, i) => {
+      // Drift diagonally: bottom-right → top-left. Start/end partly off-canvas
+      // so the cloud enters and exits softly without a visible edge.
+      const startX = rand(85, 120)
+      const endX = rand(-20, 15)
+      const midX = (startX + endX) / 2 + rand(-6, 6)
 
-        const startY = rand(85, 115)
-        const endY = rand(-15, 10)
-        const midY = (startY + endY) / 2 + rand(-4, 4)
+      const startY = rand(85, 115)
+      const endY = rand(-15, 10)
+      const midY = (startY + endY) / 2 + rand(-4, 4)
 
-        const duration = rand(8, 12)
-        // Offset clouds by half a cycle so one is arriving as the other leaves.
-        const delay = -(i / glowCount) * duration
+      const duration = rand(8, 12)
+      // Offset clouds by half a cycle so one is arriving as the other leaves.
+      const delay = -(i / glowCount) * duration
 
-        return {
-          key: i,
-          xs: [`${startX}%`, `${midX}%`, `${endX}%`],
-          ys: [`${startY}%`, `${midY}%`, `${endY}%`],
-          duration,
-          delay,
-        }
-      }),
-    [glowCount],
-  )
+      return {
+        key: i,
+        xs: [`${startX}%`, `${midX}%`, `${endX}%`],
+        ys: [`${startY}%`, `${midY}%`, `${endY}%`],
+        duration,
+        delay,
+      }
+    })
+  }, [glowCount, id])
 
   return (
     <svg

package/template/components/ui/leo-icon.tsx

@@ -618,14 +618,34 @@ function InteractiveIcon({ sz, reduced }: { sz: SZ; reduced: boolean }) {
   const onDown = React.useCallback(() => setPressed(true), [])
   const onUp = React.useCallback(() => setPressed(false), [])
 
+  // Track click-effect timers so unmounting (Ask Leo sidebar close) doesn't
+  // leave timers running that then call setState on an unmounted component.
+  const clickTimersRef = React.useRef<Set<ReturnType<typeof setTimeout>>>(new Set())
+  React.useEffect(() => {
+    const set = clickTimersRef.current
+    return () => {
+      for (const t of set) clearTimeout(t)
+      set.clear()
+    }
+  }, [])
+
+  const ringIdRef = React.useRef(0)
   const onClick = React.useCallback(() => {
     if (reduced) return
     setCast(true)
-    setTimeout(() => setCast(false), 720)
+    const tCast = setTimeout(() => {
+      clickTimersRef.current.delete(tCast)
+      setCast(false)
+    }, 720)
+    clickTimersRef.current.add(tCast)
 
-    const id = Date.now() + Math.random()
+    const id = ++ringIdRef.current
     setRings(prev => [...prev, id])
-    setTimeout(() => setRings(prev => prev.filter(r => r !== id)), 800)
+    const tRing = setTimeout(() => {
+      clickTimersRef.current.delete(tRing)
+      setRings(prev => prev.filter(r => r !== id))
+    }, 800)
+    clickTimersRef.current.add(tRing)
 
     spawnBurst(6)
   }, [reduced, spawnBurst])

package/template/contexts/product-context.tsx

@@ -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

@@ -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/docs/collaboration-access-pattern.md

@@ -2,6 +2,8 @@
 
 Shared UI for **who can access a hub** (face stack in the header) and **inviting people** (floating sheet). **Reference:** Question bank — `QuestionBankPageHeader`, `QuestionBankClient`, `InviteCollaboratorsDrawer`.
 
+**Folder-scoped question bank:** When the library URL selects a folder (`?scope=folder&folderId=`), the same header **⋯ More** menu also exposes **Customize folder** (name / color / icon) via **`QuestionBankNewFolderSheet`** mounted on **`QuestionBankClient`** so it works on every view tab. See **`docs/question-bank-hub-header-pattern.md`** and **`.cursor/rules/exxat-question-bank-hub-header.mdc`**.
+
 ## When to use
 
 - A list hub or library is **shared** across people (not a private directory).

package/template/docs/question-bank-hub-header-pattern.md

@@ -0,0 +1,25 @@
+# Question bank hub header — folder scope + Customize folder
+
+**Audience:** Engineers extending the question bank library hub (`QuestionBankClient`, `QuestionBankPageHeader`, URL scope).
+
+## Problem
+
+The library uses **`ListPageTemplate`** with multiple **view tabs** (table, panel, tree, …). **`QuestionBankNewFolderSheet`** (customize mode) is also used inside **`QuestionBankTable`** for some views (e.g. panel columns). If **Customize folder** exists only there, users on **table** or other tabs **cannot** open the sheet from a consistent chrome entry point when the URL is scoped to a folder (`?scope=folder&folderId=…`).
+
+## Pattern
+
+1. **`QuestionBankPageHeader`** exposes optional **`onCustomizeFolder?: () => void`**. When **`navState.scope === "folder"`** and **`navState.folderId`** is set, the hub client passes a callback that opens customize mode for the matching **`QuestionBankFolder`**.
+2. **`QuestionBankClient`** (or equivalent hub client) mounts **`QuestionBankNewFolderSheet`** **once** beside **`SecondaryPanelHubTemplate` / `ListPageTemplate`**, with local state for **`open`** and **`customizingFolder`**. Saving updates **`folders`** the same way as table-embedded customize flows.
+3. The header **⋯ More** menu order stays aligned with **§4.7**: **Invite people** (when collaboration variant) → **Customize folder** (when folder-scoped) → **Export** → **Show / hide metric section** (when applicable).
+
+## References
+
+| Piece | Location |
+|-------|-----------|
+| Header prop + menu item | `components/question-bank-page-header.tsx` |
+| Client wiring + sheet | `components/question-bank-client.tsx` |
+| URL scope | `lib/question-bank-nav.ts` (`parseQuestionBankNav`, `QuestionBankNavState`) |
+| Sheet UI | `components/question-bank-new-folder-sheet.tsx` |
+
+**Cursor rule:** `.cursor/rules/exxat-question-bank-hub-header.mdc`  
+**Handbook:** `AGENTS.md` §4.6 (folder-scoped hub chrome).

package/template/eslint.config.mjs

@@ -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-secondary-panel-hub-nav.ts

@@ -36,6 +36,11 @@ export interface UseSecondaryPanelHubNavOptions<TNav> {
   canonicalHref?: (searchParams: URLSearchParams) => string | null
   /** Re-open the secondary panel when the user returns to the default scope (e.g. All questions). */
   shouldReopenPanel?: (nav: TNav) => boolean
+  /**
+   * When set, auto-reopen only runs on these pathnames (e.g. library hub, not dedicated search landings).
+   * Omit to keep legacy behavior: any {@link hubPathnames} match may reopen the panel.
+   */
+  reopenPanelOnPathnames?: readonly string[]
 }
 
 /**
@@ -48,6 +53,7 @@ export function useSecondaryPanelHubNav<TNav>({
   parseNav,
   canonicalHref,
   shouldReopenPanel,
+  reopenPanelOnPathnames,
 }: UseSecondaryPanelHubNavOptions<TNav>) {
   const pathname = usePathname()
   const router = useRouter()
@@ -90,9 +96,19 @@ export function useSecondaryPanelHubNav<TNav>({
 
   React.useEffect(() => {
     if (!isHubPath || !shouldReopenPanel?.(navState)) return
+    if (reopenPanelOnPathnames?.length && !reopenPanelOnPathnames.includes(pathname)) return
     if (activePanel === panelId) return
     openPanel(panelId)
-  }, [activePanel, isHubPath, navState, openPanel, panelId, shouldReopenPanel])
+  }, [
+    activePanel,
+    isHubPath,
+    navState,
+    openPanel,
+    panelId,
+    pathname,
+    reopenPanelOnPathnames,
+    shouldReopenPanel,
+  ])
 
   return { navState, searchParamsKey, hubPathname, hubBasePath, pathname, isHubPath }
 }

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

@@ -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)
     }
   }, [])