@exxatdesignux/ui 0.2.19 → 0.4.0

package/template/lib/library-nav.ts

@@ -0,0 +1,477 @@
+/**
+ * Library secondary nav + URL scope — demo “My” matches mock author rows.
+ */
+
+import type { LibraryItem } from "@/lib/mock/library"
+import type { LibraryFolder } from "@/lib/mock/library-folders"
+import { collectFolderDescendantIds } from "@/lib/mock/library-folders"
+
+/** Demo curator — “My items” filters `author` / `createdBy` to this value. */
+export const LIBRARY_NAV_MY_AUTHOR = "Owner A"
+
+export type LibraryNavScope = "all" | "my" | "folder"
+
+export interface LibraryNavState {
+  scope: LibraryNavScope
+  /** Set when `scope === "folder"` */
+  folderId: string | null
+}
+
+export const LIBRARY_ENTRY_PATH = "/library"
+
+/** Breadcrumb segment for the discovery hub — links from library / search shells back to `/library`. */
+export const LIBRARY_HUB_BREADCRUMB = {
+  label: "Library",
+  href: LIBRARY_ENTRY_PATH,
+} as const
+
+/** List hub with secondary nav, views, and table state. */
+export const LIBRARY_ALL_PATH = "/library/all"
+
+/**
+ * Same hub as the library (table + panel + tree) but intended for search landings (`?q=`).
+ * Keeps secondary panel + nav behavior aligned with {@link LIBRARY_ALL_PATH}.
+ */
+export const LIBRARY_LIST_PATH = "/library/list"
+
+/**
+ * Results from the discovery hub composer — same table stack as {@link LIBRARY_LIST_PATH} but a
+ * distinct URL so library “Search” and hub-driven search are not conflated.
+ */
+export const LIBRARY_HUB_FIND_PATH = "/library/find"
+
+/** @deprecated Use `LIBRARY_ALL_PATH` for scoped library routes. */
+export const LIBRARY_HUB_PATH = LIBRARY_ALL_PATH
+
+export const LIBRARY_LIBRARY_HUB_PATHS: readonly string[] = [
+  LIBRARY_ALL_PATH,
+  LIBRARY_LIST_PATH,
+  LIBRARY_HUB_FIND_PATH,
+]
+
+/** Library list search (`/list`) or hub discovery search (`/find`) — both use the dedicated search shell. */
+export function isLibraryDedicatedSearchPathname(pathname: string): boolean {
+  return pathname === LIBRARY_LIST_PATH || pathname === LIBRARY_HUB_FIND_PATH
+}
+
+/**
+ * Whether a secondary-nav row (All / My / folder / Search) matches the current URL + parsed nav.
+ * Used by `LibrarySecondaryNav` and the folder tree branch.
+ */
+export function isLibraryNavActive(
+  pathname: string,
+  nav: LibraryNavState,
+  scope: LibraryNavScope,
+  folderId?: string | null,
+): boolean {
+  const p = pathname.length > 1 && pathname.endsWith("/") ? pathname.slice(0, -1) : pathname
+  if (!LIBRARY_LIBRARY_HUB_PATHS.includes(p)) return false
+  if (scope === "all") {
+    if (isLibraryDedicatedSearchPathname(pathname)) return false
+    return nav.scope === "all"
+  }
+  if (scope === "my") {
+    if (isLibraryDedicatedSearchPathname(pathname)) return false
+    return nav.scope === "my"
+  }
+  if (scope === "folder" && folderId) {
+    return nav.scope === "folder" && nav.folderId === folderId
+  }
+  return false
+}
+
+/** Default secondary-nav selection — All questions (no `scope` query). */
+export const LIBRARY_DEFAULT_NAV: LibraryNavState = {
+  scope: "all",
+  folderId: null,
+}
+
+export function isLibraryDefaultNav(nav: LibraryNavState): boolean {
+  return nav.scope === "all" && nav.folderId === null
+}
+
+export function parseLibraryNav(searchParams: URLSearchParams): LibraryNavState {
+  const raw = (searchParams.get("scope") ?? "all").toLowerCase()
+  if (raw === "my") return { scope: "my", folderId: null }
+  if (raw === "folder") {
+    const rawId = searchParams.get("folderId") ?? searchParams.get("folder")
+    const folderId = typeof rawId === "string" ? rawId.trim() || null : null
+    return { scope: "folder", folderId }
+  }
+  if (raw === "all") return { ...LIBRARY_DEFAULT_NAV }
+  return { ...LIBRARY_DEFAULT_NAV }
+}
+
+/** Rewrite invalid or incomplete scope URLs back to the default All questions hub. Preserves list search params when present. */
+export function libraryCanonicalNavHref(searchParams: URLSearchParams): string | null {
+  const raw = searchParams.get("scope")
+  if (!raw) return null
+  const lowered = raw.toLowerCase()
+  const q = searchParams.get("q")?.trim() || null
+  const fav = searchParams.get("fav") === "1"
+  const deckClinical = searchParams.get("deck") === "clinical"
+  const preserved = {
+    q,
+    ...(fav ? { fav: true as const } : {}),
+    ...(deckClinical ? { deck: "clinical" as const } : {}),
+  }
+  if (lowered === "my") return null
+  if (lowered === "folder") {
+    const folderId = searchParams.get("folderId") ?? searchParams.get("folder")
+    return folderId ? null : libraryNavHref({ scope: "all", ...preserved })
+  }
+  if (lowered === "all") return null
+  return libraryNavHref({ scope: "all", ...preserved })
+}
+
+/** Breadcrumb + title for `SiteHeader` / `PageHeader` (matches secondary nav scopes). */
+export interface LibraryHubHeaderModel {
+  title: string
+  breadcrumbs?: { label: string; href?: string }[]
+}
+
+/** Back link for `/library/new` — icon + parent label in `SiteHeader` (`back` prop). */
+export function newQuestionBackNav(
+  folders: LibraryFolder[],
+  folderId?: string,
+): { label: string; href: string } {
+  if (folderId) {
+    const folder = folders.find(f => f.id === folderId)
+    if (folder) {
+      return {
+        label: folder.name,
+        href: libraryNavHref({ scope: "folder", folderId: folder.id }),
+      }
+    }
+  }
+  return {
+    label: LIBRARY_HUB_BREADCRUMB.label,
+    href: libraryNavHref({ scope: "all" }),
+  }
+}
+
+/** Ancestor-only breadcrumbs for `/library/new` (current page is the PageHeader title). */
+export function newQuestionBreadcrumbs(
+  folders: LibraryFolder[],
+  folderId?: string,
+): { label: string; href: string }[] {
+  if (folderId) {
+    const folder = folders.find(f => f.id === folderId)
+    if (folder) {
+      return [
+        {
+          label: folder.name,
+          href: libraryNavHref({ scope: "folder", folderId: folder.id }),
+        },
+      ]
+    }
+  }
+  return [
+    {
+      label: LIBRARY_HUB_BREADCRUMB.label,
+      href: LIBRARY_HUB_BREADCRUMB.href,
+    },
+  ]
+}
+
+export function libraryHubHeaderModel(
+  folders: LibraryFolder[],
+  nav: LibraryNavState,
+): LibraryHubHeaderModel {
+  if (nav.scope === "my") {
+    return {
+      breadcrumbs: [{ label: LIBRARY_HUB_BREADCRUMB.label, href: LIBRARY_HUB_BREADCRUMB.href }],
+      title: "My items",
+    }
+  }
+  if (nav.scope === "folder" && nav.folderId) {
+    const name = folders.find(f => f.id === nav.folderId)?.name ?? "Folder"
+    return {
+      breadcrumbs: [{ label: LIBRARY_HUB_BREADCRUMB.label, href: LIBRARY_HUB_BREADCRUMB.href }],
+      title: name,
+    }
+  }
+  return {
+    breadcrumbs: [{ label: LIBRARY_HUB_BREADCRUMB.label, href: LIBRARY_HUB_BREADCRUMB.href }],
+    title: "All items",
+  }
+}
+
+export function filterLibraryItemsByNav(
+  items: LibraryItem[],
+  folders: LibraryFolder[],
+  nav: LibraryNavState,
+): LibraryItem[] {
+  if (nav.scope === "all") return items
+  if (nav.scope === "my") {
+    return items.filter(
+      i => i.author === LIBRARY_NAV_MY_AUTHOR || i.createdBy === LIBRARY_NAV_MY_AUTHOR,
+    )
+  }
+  if (nav.scope === "folder" && nav.folderId) {
+    const allowedFolderIds = collectFolderDescendantIds(folders, nav.folderId)
+    return items.filter(i => allowedFolderIds.has(i.folderId))
+  }
+  return items
+}
+
+/** Mock folder id for the Favorites bucket (see `DEFAULT_LIBRARY_FOLDERS`). */
+export const LIBRARY_FAVORITES_FOLDER_ID = "fld-favorites"
+
+/** Root folder id for the mock “Folder 1” tree (`fld-skills-lab` is a child). */
+export const LIBRARY_CLINICAL_ROOT_FOLDER_ID = "fld-clinical"
+
+/**
+ * Client-side “AI / hub” free-text filter — same scan as `useTableState` toolbar search
+ * (`Object.values` → string → lowercase `includes`).
+ */
+export function filterLibraryItemsByFreeText(items: LibraryItem[], q: string): LibraryItem[] {
+  const t = q.trim()
+  if (!t) return items
+  const needle = t.toLowerCase()
+  return items.filter(row =>
+    Object.values(row).some(v => String(v ?? "").toLowerCase().includes(needle)),
+  )
+}
+
+export function isLibraryItemFavorite(item: LibraryItem): boolean {
+  return item.folderId === LIBRARY_FAVORITES_FOLDER_ID || item.isStarred === true
+}
+
+/** When a mock row lives in the Favorites folder, toggling off moves it here (no “original folder” yet). */
+const LIBRARY_UNFAVORITE_FALLBACK_FOLDER_ID = "fld-science"
+
+/** Demo toggle for `isStarred` / Favorites folder membership (offline mock only). */
+export function toggleLibraryItemFavorite(item: LibraryItem): LibraryItem {
+  if (isLibraryItemFavorite(item)) {
+    if (item.folderId === LIBRARY_FAVORITES_FOLDER_ID) {
+      return {
+        ...item,
+        folderId: LIBRARY_UNFAVORITE_FALLBACK_FOLDER_ID,
+        isStarred: false,
+      }
+    }
+    return { ...item, isStarred: false }
+  }
+  return { ...item, isStarred: true }
+}
+
+export function filterLibraryItemsByFavoritesOnly(items: LibraryItem[]): LibraryItem[] {
+  return items.filter(isLibraryItemFavorite)
+}
+
+/**
+ * Mock “Featured deck” (`deck=clinical`): items under the Folder 1 tree **or**
+ * demo categories Category 1 / Category 3 (so list landings can show a coherent slice).
+ */
+export function filterLibraryItemsByClinicalDeckMock(
+  items: LibraryItem[],
+  folders: LibraryFolder[],
+): LibraryItem[] {
+  const inClinicalTree = collectFolderDescendantIds(folders, LIBRARY_CLINICAL_ROOT_FOLDER_ID)
+  const topicMatch = new Set(["Category 1", "Category 3"])
+  return items.filter(
+    i => inClinicalTree.has(i.folderId) || topicMatch.has(i.topic),
+  )
+}
+
+export type LibraryLandingFilterState = {
+  hubFreeText: string
+  favOnly: boolean
+  clinicalDeck: boolean
+}
+
+/**
+ * Nav scope + optional dedicated search routes (`/library/list`, `/library/find`) landing filters (`q`, `fav`, `deck`).
+ * When `hubFreeText` is non-empty but matches no rows, hub text is ignored so the scoped list still shows.
+ */
+export function applyLibraryHubDisplayFilters(
+  items: LibraryItem[],
+  folders: LibraryFolder[],
+  nav: LibraryNavState,
+  landing: LibraryLandingFilterState | null,
+): LibraryItem[] {
+  let rows = filterLibraryItemsByNav(items, folders, nav)
+  if (!landing) return rows
+  let afterText = filterLibraryItemsByFreeText(rows, landing.hubFreeText)
+  if (landing.hubFreeText.trim() && afterText.length === 0) {
+    afterText = rows
+  }
+  rows = afterText
+  if (landing.favOnly) rows = filterLibraryItemsByFavoritesOnly(rows)
+  if (landing.clinicalDeck) rows = filterLibraryItemsByClinicalDeckMock(rows, folders)
+  return rows
+}
+
+/** True when hub `q` is non-empty but matches no rows under the current nav (before fav/deck). */
+export function libraryHubTextMatchesNothing(
+  items: LibraryItem[],
+  folders: LibraryFolder[],
+  nav: LibraryNavState,
+  landing: LibraryLandingFilterState | null,
+): boolean {
+  if (!landing?.hubFreeText.trim()) return false
+  const navRows = filterLibraryItemsByNav(items, folders, nav)
+  return filterLibraryItemsByFreeText(navRows, landing.hubFreeText).length === 0
+}
+
+export function patchLibraryUrlSearchParams(
+  sp: URLSearchParams,
+  patch: {
+    q?: string | null
+    fav?: boolean | null
+    deckClinical?: boolean | null
+  },
+): URLSearchParams {
+  const next = new URLSearchParams(sp.toString())
+  if (patch.q !== undefined) {
+    const t = patch.q?.trim() ?? ""
+    if (t) next.set("q", t)
+    else next.delete("q")
+  }
+  if (patch.fav !== undefined) {
+    if (patch.fav) next.set("fav", "1")
+    else next.delete("fav")
+  }
+  if (patch.deckClinical !== undefined) {
+    if (patch.deckClinical) next.set("deck", "clinical")
+    else next.delete("deck")
+  }
+  return next
+}
+
+/** Build {@link LIBRARY_LIST_PATH} query consistently (nav + hub search + mock toggles). */
+export function libraryListSearchHref(
+  nav: LibraryNavState,
+  opts: { q?: string | null; fav?: boolean; deckClinical?: boolean },
+): string {
+  return libraryNavHref({
+    scope: nav.scope,
+    folderId: nav.folderId,
+    searchLanding: true,
+    q: opts.q,
+    fav: opts.fav,
+    deck: opts.deckClinical ? "clinical" : undefined,
+  })
+}
+
+/** Favorites bucket — same folder scope on library, list, or hub-find; preserves `q` / mock toggles on dedicated search routes. */
+export function libraryFavoritesFolderHref(pathname: string, currentSearch: URLSearchParams): string {
+  const onList = pathname === LIBRARY_LIST_PATH
+  const onHubFind = pathname === LIBRARY_HUB_FIND_PATH
+  const q = currentSearch.get("q")
+  const fav = currentSearch.get("fav") === "1"
+  const deckClinical = currentSearch.get("deck") === "clinical"
+  return libraryNavHref({
+    scope: "folder",
+    folderId: LIBRARY_FAVORITES_FOLDER_ID,
+    ...(onList ? { searchLanding: true } : onHubFind ? { hubFind: true } : {}),
+    q,
+    ...(fav ? { fav: true as const } : {}),
+    ...(deckClinical ? { deck: "clinical" as const } : {}),
+  })
+}
+
+/** “Search” secondary nav — {@link LIBRARY_LIST_PATH} without `?q=` (always the search landing). Preserves `fav` / `deck` when set. */
+export function librarySearchLandingNavHref(
+  nav: LibraryNavState,
+  currentSearch: URLSearchParams,
+): string {
+  const listNav: LibraryNavState =
+    nav.scope === "folder" ? LIBRARY_DEFAULT_NAV : nav
+  return libraryListSearchHref(listNav, {
+    fav: currentSearch.get("fav") === "1" ? true : undefined,
+    deckClinical: currentSearch.get("deck") === "clinical" ? true : undefined,
+  })
+}
+
+/** True when the dedicated search shell should show the “Search” nav row as current (not browsing a folder there). */
+export function isLibrarySearchNavActive(pathname: string, nav: LibraryNavState): boolean {
+  if (pathname !== LIBRARY_LIST_PATH && pathname !== LIBRARY_HUB_FIND_PATH) return false
+  if (nav.scope === "folder" && nav.folderId) return false
+  return true
+}
+
+/**
+ * Hub scope link that preserves list-only params (`q`, `fav`, `deck`) when the user is already
+ * on {@link LIBRARY_LIST_PATH}; folder / “My” targets use the library path per product rule.
+ */
+export function libraryHubScopeHref(
+  pathname: string,
+  currentSearch: URLSearchParams,
+  patch: { scope: LibraryNavScope; folderId?: string | null },
+): string {
+  const onList = pathname === LIBRARY_LIST_PATH
+  const onHubFind = pathname === LIBRARY_HUB_FIND_PATH
+  const q = currentSearch.get("q")
+  const fav = currentSearch.get("fav") === "1"
+  const deckClinical = currentSearch.get("deck") === "clinical"
+  const landingBits = {
+    q,
+    ...(fav ? { fav: true as const } : {}),
+    ...(deckClinical ? { deck: "clinical" as const } : {}),
+  }
+  if (patch.scope === "my" || (patch.scope === "folder" && patch.folderId)) {
+    return libraryNavHref({
+      scope: patch.scope,
+      folderId: patch.folderId,
+      searchLanding: false,
+    })
+  }
+  if (patch.scope === "all") {
+    return libraryNavHref({
+      scope: "all",
+      ...(onList ? { searchLanding: true } : onHubFind ? { hubFind: true } : {}),
+      ...landingBits,
+    })
+  }
+  return libraryNavHref({ scope: "all", searchLanding: false })
+}
+
+/** Build `/library` href with optional query + hash (hash without leading `#`). */
+export function libraryNavHref(opts: {
+  scope: LibraryNavScope
+  folderId?: string | null
+  hash?: string
+  /**
+   * Hub / panel search string (`?q=`). On {@link LIBRARY_LIST_PATH} and {@link LIBRARY_HUB_FIND_PATH}
+   * this filters rows via {@link applyLibraryHubDisplayFilters} — **not** the DataTable toolbar
+   * (toolbar stays independent on those routes).
+   */
+  q?: string | null
+  /** Mock list filter: `fav=1` — favorites folder or `isStarred` rows. */
+  fav?: boolean
+  /** Mock list filter: `deck=clinical` — see {@link filterLibraryItemsByClinicalDeckMock}. */
+  deck?: "clinical" | null
+  /**
+   * When true, links use {@link LIBRARY_LIST_PATH} (library “Search” in secondary nav).
+   * Scoped folder / mine links should use `searchLanding: false` (library path).
+   */
+  searchLanding?: boolean
+  /**
+   * When true, links use {@link LIBRARY_HUB_FIND_PATH} (discovery hub composer submit).
+   * Do not combine with `searchLanding` — hub find wins if both are set.
+   */
+  hubFind?: boolean
+}): string {
+  const base =
+    opts.hubFind === true
+      ? LIBRARY_HUB_FIND_PATH
+      : opts.searchLanding === true
+        ? LIBRARY_LIST_PATH
+        : LIBRARY_ALL_PATH
+  const sp = new URLSearchParams()
+  if (opts.scope === "my") sp.set("scope", "my")
+  if (opts.scope === "folder" && opts.folderId) {
+    sp.set("scope", "folder")
+    sp.set("folderId", opts.folderId)
+  }
+  const trimmedQ = opts.q?.trim()
+  if (trimmedQ) sp.set("q", trimmedQ)
+  if (opts.fav) sp.set("fav", "1")
+  if (opts.deck === "clinical") sp.set("deck", "clinical")
+  const qs = sp.toString()
+  const h = opts.hash?.replace(/^#/, "")
+  const hashPart = h ? `#${h}` : ""
+  return qs ? `${base}?${qs}${hashPart}` : `${base}${hashPart}`
+}

package/template/lib/library-recent-searches.ts

@@ -0,0 +1,22 @@
+import { createDedicatedSearchRecentsController } from "@/lib/dedicated-search-recents"
+
+const controller = createDedicatedSearchRecentsController("library", {
+  storageKey: "exxat-ds.library.recent-searches.v1",
+  eventName: "exxat-library-recent-searches",
+})
+
+export const LIBRARY_RECENT_SEARCHES_EVENT = controller.eventName
+
+export const libraryDedicatedSearchRecents = controller
+
+export function readLibraryRecentSearches(): string[] {
+  return controller.read()
+}
+
+export function recordLibraryRecentSearch(query: string): void {
+  controller.record(query)
+}
+
+export function clearLibraryRecentSearches(): void {
+  controller.clear()
+}

package/template/lib/{question-bank-supported-views.ts → library-supported-views.ts}

@@ -1,12 +1,11 @@
 import type { DataListViewType } from "@/lib/data-list-view"
 
-/** Views implemented in `QuestionBankTable` — keep in sync with `ListPageConnectedViewBody` renderers. */
-export const QUESTION_BANK_SUPPORTED_VIEWS = [
+/** Views implemented in `LibraryTable` — keep in sync with `ListPageConnectedViewBody` renderers. */
+export const LIBRARY_SUPPORTED_VIEWS = [
   "table",
   "list",
   "board",
   "dashboard",
-  "calendar",
   "folder",
   "panel",
   "tree-panel",

package/template/lib/list-page-table-properties.ts

@@ -1,48 +1 @@
-/**
- * Connects ListPageTemplate “View → Edit” to a surface that hosts TablePropertiesDrawer
- * (PlacementsTable, TeamTable, ComplianceTable, …). Import from `@/components/table-properties`
- * or use here — see `createListPageEditViewHandler`.
- *
- * View **labels** for tabs and Properties are centralized in `@/lib/data-list-view`
- * (`DATA_LIST_VIEW_TILES`, `dataListViewLabel`, `dataListViewIcon`).
- */
-
-import * as React from "react"
-
-import { dataListViewIcon, type DataListViewType } from "@/lib/data-list-view"
-import { isDataListSurfaceViewType } from "@/lib/data-list-view-registry"
-
-export { isDataListSurfaceViewType }
-
-/** Minimal ref API any list/table surface exposes for the shared Properties drawer. */
-export interface OpenTablePropertiesHandle {
-  openPropertiesDrawer: () => void
-}
-
-export interface CreateListPageEditViewHandlerOptions {
-  /** Delay before opening Properties after switching to table (ms). Default 160. */
-  switchDelayMs?: number
-}
-
-/**
- * Returns `ListPageTemplate`’s `onEditView` handler: optionally coerces the tab to `table`
- * when the view type is unknown, then calls `ref.current.openPropertiesDrawer()`.
- */
-export function createListPageEditViewHandler(
-  tableRef: React.RefObject<OpenTablePropertiesHandle | null>,
-  options?: CreateListPageEditViewHandlerOptions
-) {
-  const delay = options?.switchDelayMs ?? 160
-  return (
-    tab: { viewType: string },
-    { updateTab }: { updateTab: (patch: { viewType?: DataListViewType; icon?: string }) => void }
-  ) => {
-    const mustSwitchToTableSurface = !isDataListSurfaceViewType(tab.viewType)
-    if (mustSwitchToTableSurface) {
-      updateTab({ viewType: "table", icon: dataListViewIcon("table") })
-    }
-    window.setTimeout(() => {
-      tableRef.current?.openPropertiesDrawer()
-    }, mustSwitchToTableSurface ? delay : 0)
-  }
-}
+export * from "@exxatdesignux/ui/lib/list-page-table-properties"

package/template/lib/list-status-badges.ts

@@ -1,19 +1,24 @@
 /**
- * Shared status chip labels, tint classes, and FA icon names for product list hubs
- * (Question bank, list hub, future entities), plus related chips (dashboard **task priority**).
+ * Shared status chip tints + dashboard task-priority chips.
  *
- * Labels use **sentence / title case** (e.g. "Due soon", "Under Review"). Do **not** add **`uppercase`**.
+ * **Rendering primitive:** `ListHubStatusBadge` (`components/list-hub-status-badge.tsx`)
+ * for any status chip on a list hub. Map your domain statuses onto
+ * `LIST_HUB_STATUS_TINT_*` below before introducing new colors.
  *
- * **Rendering:** Use **`ListHubStatusBadge`** from `@/components/list-hub-status-badge`.
- * Task priority → **`TaskPriorityBadge`**.
+ * **Reference consumers:** `columns-showcase.tsx` (catalog),
+ * `library-board-view.tsx` (board card status row), `task-priority-badge.tsx`
+ * (dashboard task chips).
  *
- * **Semantic tints:** Map domain statuses onto **`LIST_HUB_STATUS_TINT_*`** before inventing new colors.
- * **Icon-on-tinted-disc** (insights / activity): **`TintedIconDisc`** + **`--icon-disc-*`** in **`app/globals.css`**.
+ * **Icon-on-tinted-disc** (insights / activity rows): `TintedIconDisc` + `--icon-disc-*`
+ * in `app/globals.css`.
+ *
+ * Labels stay **sentence / title case** (e.g. "Due soon", "Under review"). Do **not**
+ * add `uppercase`.
  */
 
-// ─── Semantic variants (reuse for new entities) ─────────────────────────────
+// ─── Semantic variants (reuse for every entity) ─────────────────────────────
 //
-// **Light washes** (same visual weight as before) + **darker ink** via `--chip-*` for WCAG 1.4.3.
+// Light washes (same visual weight as before) + darker ink via `--chip-*` for WCAG 1.4.3.
 // Backgrounds stay subtle; contrast is carried by label + icon color, not heavier fills.
 
 export const LIST_HUB_STATUS_TINT_SUCCESS =
@@ -28,11 +33,11 @@ export const LIST_HUB_STATUS_TINT_NEUTRAL =
 export const LIST_HUB_STATUS_TINT_DANGER =
   "bg-destructive/15 text-[var(--chip-destructive)] border-destructive/20 dark:bg-destructive/15 dark:text-red-200"
 
-/** In-progress / review (distinct from warning where both appear). */
+/** In-progress / review — distinct from warning when both appear together (e.g. "Under review"). */
 export const LIST_HUB_STATUS_TINT_INFO =
   "bg-sky-500/15 text-[var(--chip-1)] border-sky-500/20 dark:bg-sky-500/15 dark:text-sky-100"
 
-// ─── Dashboard task priority (shared chip system) ──────────────────────────
+// ─── Dashboard task priority ────────────────────────────────────────────────
 
 export type TaskPriorityLevel = "high" | "medium" | "low"
 

package/template/lib/mock/dashboard.ts

@@ -16,7 +16,7 @@ export const DASHBOARD_METRICS: MetricItem[] = [
 export const DASHBOARD_INSIGHT: MetricInsight = {
   title:       "Throughput note",
   description: "Demo insight card — wire real KPIs from your product domain.",
-  href:        "/examples",
+  href:        "/dashboard",
   severity:    "warning",
   actionLabel: "Ask Leo",
 }