@exxatdesignux/ui 0.2.18 → 0.3.0

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

@@ -1,69 +1 @@
-/**
- * Maps `DataListViewType` to the UI surface pattern for list pages.
- *
- * **Data:** One `useTableState(fullRows, columns, …)` per tab; **filtered/sorted rows**
- * (`tableState.rows`) are the single source of truth for List, Board, and Dashboard.
- * Table view renders the same state via `DataTable`.
- *
- * | View        | Surface |
- * |------------|---------|
- * | `table`    | `DataTable` |
- * | `list`     | `DataTableToolbar` + list layout |
- * | `board`    | `DataTableToolbar` + board / kanban |
- * | `dashboard`| `DataTableToolbar` + KPI (`KeyMetrics`) + optional charts (`ChartCard`, Recharts, etc.) |
- * | `folder`   | `DataTableToolbar` + icon grid (macOS-Finder-style) |
- * | `panel`    | `DataTableToolbar` + resizable split (list / tree column + detail inspector) |
- */
-
-import type { DataListViewType } from "@/lib/data-list-view"
-
-/** What to render for the active view tab (routing / branching). */
-export type DataListViewRenderKind =
-  | "data-table"
-  | "list-with-toolbar"
-  | "board-with-toolbar"
-  | "dashboard-with-toolbar"
-  | "folder-with-toolbar"
-  | "panel-with-toolbar"
-  | "tree-panel-with-toolbar"
-
-/**
- * Stable classification for switch/if chains. **Every** `DataListViewType` maps to exactly one kind.
- * Use this so `dashboard` is never mistaken for `board` (a common bug when only `list` is special-cased).
- */
-export function getDataListViewRenderKind(view: DataListViewType): DataListViewRenderKind {
-  switch (view) {
-    case "table":
-      return "data-table"
-    case "list":
-      return "list-with-toolbar"
-    case "board":
-      return "board-with-toolbar"
-    case "dashboard":
-      return "dashboard-with-toolbar"
-    case "folder":
-      return "folder-with-toolbar"
-    case "panel":
-      return "panel-with-toolbar"
-    case "tree-panel":
-      return "tree-panel-with-toolbar"
-    default: {
-      const _x: never = view
-      return _x
-    }
-  }
-}
-
-export function usesDataTableComponent(view: DataListViewType): boolean {
-  return view === "table"
-}
-
-/** KPI band + optional charts — not the kanban board. */
-export function usesDashboardSurface(view: DataListViewType): boolean {
-  return view === "dashboard"
-}
-
-/** Shared toolbar (search, filters, properties); body differs by view. */
-export function usesToolbarWithFilteredRows(view: DataListViewType): boolean {
-  return view === "list" || view === "board" || view === "dashboard" || view === "folder" || view === "panel" || view === "tree-panel"
-}
+export * from "@exxatdesignux/ui/lib/data-list-view-surface"

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

@@ -1,38 +1 @@
-/**
- * Data list “view type” — shared by Properties drawer, ListPageTemplate tabs, and client state.
- *
- * **Single source of truth** for view labels/icons: use `DATA_LIST_VIEW_TILES` and
- * `dataListViewLabel` / `dataListViewIcon` on every page so Table / List / Board / Dashboard
- * stay consistent and stay wired to the same `useTableState` dataset (see `docs/data-views-pattern.md`).
- */
-export type DataListViewType = "table" | "list" | "board" | "dashboard" | "folder" | "panel" | "tree-panel"
-
-export const DATA_LIST_VIEW_TILES: readonly {
-  value: DataListViewType
-  label: string
-  icon: string
-}[] = [
-  { value: "table",     icon: "fa-table",         label: "Table view" },
-  { value: "list",      icon: "fa-list",          label: "List view" },
-  { value: "board",     icon: "fa-table-columns", label: "Board view" },
-  { value: "dashboard", icon: "fa-chart-mixed",   label: "Dashboard view" },
-  { value: "folder",    icon: "fa-grid-2",        label: "Folder view" },
-  { value: "panel",      icon: "fa-sidebar",      label: "List & details" },
-  { value: "tree-panel", icon: "fa-sitemap",      label: "Tree & details" },
-]
-
-/** User-facing name for tabs, Properties summary rows, and tooltips (not entity-specific). */
-export function dataListViewLabel(view: DataListViewType): string {
-  return DATA_LIST_VIEW_TILES.find(t => t.value === view)?.label ?? view
-}
-
-/** Font Awesome icon class (no prefix) for tab / toolbar state when view changes. */
-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)
-}
+export * from "@exxatdesignux/ui/lib/data-list-view"

package/template/lib/dev-log.ts

@@ -1,8 +1 @@
-/**
- * Logs only in development. Use for mock flows (export, submit) instead of raw console.log.
- */
-export function devLog(...args: unknown[]): void {
-  if (process.env.NODE_ENV === "development") {
-    console.log(...args)
-  }
-}
+export * from "@exxatdesignux/ui/lib/dev-log"

package/template/lib/editable-target.ts

@@ -1,10 +1 @@
-/**
- * True when focus is in a field where global shortcuts should not fire.
- */
-export function isEditableTarget(target: EventTarget | null): boolean {
-  const el = target as HTMLElement | null
-  if (!el) return false
-  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement)
-    return true
-  return el.getAttribute?.("contenteditable") === "true"
-}
+export { isEditableTarget } from "@exxatdesignux/ui/lib/editable-target"

package/template/lib/hub-connected-view-renderers.ts

@@ -0,0 +1,58 @@
+/**
+ * Typed `ListPageConnectedViewBody` renderers aligned with `supportedViewTypes`.
+ */
+
+import type * as React from "react"
+import type { DataListViewType } from "@/lib/data-list-view"
+import {
+  getDataListViewRenderKind,
+  type DataListViewRenderKind,
+} from "@/lib/data-list-view-registry"
+import type { ListPageConnectedViewRenderers } from "@/components/data-views/list-page-connected-view-body"
+
+/** Maps each `DataListViewType` to its `DataListViewRenderKind` (compile-time). */
+export type DataListViewRenderKindMap = {
+  table: "data-table"
+  list: "list-with-toolbar"
+  board: "board-with-toolbar"
+  dashboard: "dashboard-with-toolbar"
+  calendar: "calendar-with-toolbar"
+  folder: "folder-with-toolbar"
+  panel: "panel-with-toolbar"
+  "tree-panel": "tree-panel-with-toolbar"
+}
+
+export type HubRenderKindForViews<Supported extends readonly DataListViewType[]> =
+  DataListViewRenderKindMap[Supported[number]]
+
+export type HubConnectedViewRenderers<Supported extends readonly DataListViewType[]> = Partial<
+  Record<HubRenderKindForViews<Supported>, React.ReactNode | (() => React.ReactNode)>
+>
+
+/** Render kinds required for a hub's `supportedViewTypes` array. */
+export function hubRenderKindsForSupported(
+  supported: readonly DataListViewType[],
+): DataListViewRenderKind[] {
+  return supported.map(v => getDataListViewRenderKind(v))
+}
+
+/**
+ * Build renderers for `ListPageConnectedViewBody` and warn in dev when a supported view has no body.
+ */
+export function defineHubViewRenderers<Supported extends readonly DataListViewType[]>(
+  supported: Supported,
+  renderers: HubConnectedViewRenderers<Supported>,
+): ListPageConnectedViewRenderers {
+  if (process.env.NODE_ENV !== "production") {
+    for (const viewType of supported) {
+      const kind = getDataListViewRenderKind(viewType)
+      if (renderers[kind as HubRenderKindForViews<Supported>] == null) {
+        console.warn(
+          `[Exxat DS] Missing ListPageConnectedViewBody renderer for view "${viewType}" (${kind}). ` +
+            "Add it to defineHubViewRenderers or remove the view from supportedViewTypes.",
+        )
+      }
+    }
+  }
+  return renderers as ListPageConnectedViewRenderers
+}

package/template/lib/list-hub-supported-views.ts

@@ -0,0 +1,10 @@
+import type { DataListViewType } from "@/lib/data-list-view"
+
+/** Views implemented in `ListHubTable` — keep in sync with `ListPageConnectedViewBody` renderers. */
+export const LIST_HUB_SUPPORTED_VIEWS = [
+  "table",
+  "list",
+  "board",
+  "calendar",
+  "panel",
+] as const satisfies readonly DataListViewType[]

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

@@ -1,52 +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"
-
-/** Minimal ref API any list/table surface exposes for the shared Properties drawer. */
-export interface OpenTablePropertiesHandle {
-  openPropertiesDrawer: () => void
-}
-
-const SURFACE_VIEW_TYPES = new Set<DataListViewType>(["table", "list", "board", "dashboard"])
-
-/** True when `viewType` is one of the data-list surfaces that support TablePropertiesDrawer. */
-export function isDataListSurfaceViewType(viewType: string): viewType is DataListViewType {
-  return SURFACE_VIEW_TYPES.has(viewType as DataListViewType)
-}
-
-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/mock/navigation.tsx

@@ -131,14 +131,6 @@ export const NAV_PRIMARY: NavLinkItem[] = [
       },
     ],
   },
-  {
-    key: "data-list",
-    title: "List hub",
-    url: "/data-list",
-    icon:       <i className="fa-light fa-table" aria-hidden="true" />,
-    iconActive: <i className="fa-solid fa-table" aria-hidden="true" />,
-    badge: 24,
-  },
 ]
 
 // ── Documents section ───────────────────────────────────────────────────────

package/template/lib/mock/placements.ts

@@ -171,13 +171,6 @@ export function uniquePlacementFieldOptions(
   return [...set].sort((a, b) => a.localeCompare(b)).map(v => ({ value: v, label: v }))
 }
 
-export function placementsForPhase(
-  phase: "all" | PlacementPhase,
-): Placement[] {
-  if (phase === "all") return ALL_PLACEMENTS
-  return ALL_PLACEMENTS.filter((p) => p.placementPhase === phase)
-}
-
 export function getPlacementById(id: number): Placement | undefined {
   return ALL_PLACEMENTS.find(p => p.id === id)
 }

package/template/lib/placement-board-card-layout.ts

@@ -1,61 +1,63 @@
 /**
- * Board placement card layout — which fields appear by default per lifecycle tab,
+ * Board placement card layout — which fields appear on the card by default,
  * which keys are grouped into header / site / schedule blocks, and helpers to
- * resolve “active” fields when a column exists only on some tabs (e.g. status).
+ * resolve "active" fields against current column visibility.
+ *
+ * Previously parameterized by `lifecycleTabId` (all / upcoming / ongoing / completed).
+ * Lifecycle has been removed — one canonical card definition is used everywhere
+ * and the card falls back to existing row data when a column is hidden.
  */
 
 import type { ColumnDef } from "@/components/data-table/types"
 import type { Placement } from "@/lib/mock/placements"
 
-/** Mirrors PlacementLifecycleTabId without importing placements-table (avoids circular imports). */
-export type BoardCardLifecycleTabId = "all" | "upcoming" | "ongoing" | "completed"
+/** Default card fields — intersected with visible table columns (except header-only rules below). */
+export const DEFAULT_BOARD_CARD_KEYS: readonly string[] = [
+  "student",
+  "specialization",
+  "site",
+  "status",
+  "internship",
+  "start",
+  "duration",
+  "progressWeeksDone",
+  "endDate",
+  "daysUntilStart",
+  "completionDate",
+  "finalStatus",
+]
 
-/** Default card fields per tab — intersected with visible table columns (except header-only rules below). */
-export const DEFAULT_BOARD_CARD_KEYS: Record<BoardCardLifecycleTabId, readonly string[]> = {
-  all: ["student", "specialization", "site", "status", "internship", "start", "duration"],
-  upcoming: ["student", "specialization", "site", "status", "internship", "start", "daysUntilStart"],
-  ongoing: ["student", "specialization", "site", "status", "internship", "progressWeeksDone", "endDate"],
-  completed: ["student", "specialization", "site", "status", "internship", "completionDate", "finalStatus"],
-}
-
-export function scheduleKeysForTab(tab: BoardCardLifecycleTabId): readonly string[] {
-  switch (tab) {
-    case "all":
-      return ["start", "duration"]
-    case "upcoming":
-      return ["start", "daysUntilStart"]
-    case "ongoing":
-      return ["progressWeeksDone", "endDate"]
-    case "completed":
-      return ["completionDate", "finalStatus"]
-    default:
-      return []
-  }
-}
+export const SCHEDULE_KEYS: readonly string[] = [
+  "start",
+  "duration",
+  "daysUntilStart",
+  "progressWeeksDone",
+  "endDate",
+  "completionDate",
+  "finalStatus",
+]
 
-/** Keys rendered in the title/header cluster (not as icon rows). Status + New only — not internship/specialization. */
-export function consumedKeysForCard(tab: BoardCardLifecycleTabId): Set<string> {
-  const schedule = scheduleKeysForTab(tab)
-  return new Set<string>(["student", "status", "site", ...schedule])
+/** Keys rendered in the title/header cluster (not as icon rows). */
+export function consumedKeysForCard(): Set<string> {
+  return new Set<string>(["student", "status", "site", ...SCHEDULE_KEYS])
 }
 
-export function isKeyInBoardWhitelist(tab: BoardCardLifecycleTabId, key: string): boolean {
-  return DEFAULT_BOARD_CARD_KEYS[tab].includes(key)
+export function isKeyInBoardWhitelist(key: string): boolean {
+  return DEFAULT_BOARD_CARD_KEYS.includes(key)
 }
 
 /**
- * Field is allowed on the card when it is in the tab whitelist, not hidden, and either
- * the column exists in this view and is visible, or the column does not exist (e.g. status on Upcoming)
- * — then we still show from row data for header/summary fields.
+ * Field is allowed on the card when it is in the whitelist, not hidden, and either
+ * the column exists in this view and is visible, or the column does not exist —
+ * then we still show from row data for header/summary fields.
  */
 export function isBoardFieldActive<Row extends Placement>(
   key: string,
-  tab: BoardCardLifecycleTabId,
   hiddenColKeys: Set<string>,
   boardColumns: ColumnDef<Row>[],
 ): boolean {
   if (hiddenColKeys.has(key)) return false
-  if (!isKeyInBoardWhitelist(tab, key)) return false
+  if (!isKeyInBoardWhitelist(key)) return false
   const hasCol = boardColumns.some(c => c.key === key)
   if (!hasCol) return true
   return boardColumns.some(c => c.key === key && !hiddenColKeys.has(c.key))
@@ -63,17 +65,15 @@ export function isBoardFieldActive<Row extends Placement>(
 
 /** Visible columns that pass whitelist (intersection). Order follows boardColumns. */
 export function filterColumnsForBoardCard<Row extends Placement>(
-  tab: BoardCardLifecycleTabId,
   visibleCols: ColumnDef<Row>[],
 ): ColumnDef<Row>[] {
-  return visibleCols.filter(c => isKeyInBoardWhitelist(tab, c.key))
+  return visibleCols.filter(c => isKeyInBoardWhitelist(c.key))
 }
 
 /** Body rows only: columns not consumed by title, header badges, site block, or schedule block. */
 export function remainingBodyColumns<Row extends Placement>(
-  tab: BoardCardLifecycleTabId,
   cardCols: ColumnDef<Row>[],
 ): ColumnDef<Row>[] {
-  const consumed = consumedKeysForCard(tab)
+  const consumed = consumedKeysForCard()
   return cardCols.filter(c => !consumed.has(c.key))
 }

package/template/lib/placements-supported-views.ts

@@ -0,0 +1,12 @@
+import type { DataListViewType } from "@/lib/data-list-view"
+
+/** Views implemented in `PlacementsTable` — keep in sync with the renderers passed to `HubTable`. */
+export const PLACEMENTS_SUPPORTED_VIEWS = [
+  "table",
+  "list",
+  "board",
+  "dashboard",
+  "folder",
+  "panel",
+  "tree-panel",
+] as const satisfies readonly DataListViewType[]

package/template/lib/question-bank-supported-views.ts

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

package/template/lib/raf-throttle.ts

@@ -1,45 +1 @@
-/**
- * Coalesce many calls to `fn` into one per animation frame.
- *
- * Use for high-frequency layout-reading event handlers (scroll, resize,
- * visualViewport, ResizeObserver) where the work must happen in a frame but
- * doing it on every event call (60+/s for resize, hundreds/s for capture
- * scrolls) wastes layout/paint cycles. The returned function exposes
- * `.cancel()` so effect cleanup can drop a pending frame.
- *
- * Pattern:
- *   const apply = () => { ...layout reads + setState... }
- *   const scheduled = rafThrottle(apply)
- *   window.addEventListener("scroll", scheduled, { passive: true, capture: true })
- *   return () => {
- *     scheduled.cancel()
- *     window.removeEventListener("scroll", scheduled, { capture: true })
- *   }
- */
-export function rafThrottle<TArgs extends unknown[]>(
-  fn: (...args: TArgs) => void,
-): ((...args: TArgs) => void) & { cancel: () => void } {
-  let rafId = 0
-  let lastArgs: TArgs | null = null
-
-  const scheduled = ((...args: TArgs) => {
-    lastArgs = args
-    if (rafId !== 0) return
-    rafId = requestAnimationFrame(() => {
-      rafId = 0
-      const a = lastArgs
-      lastArgs = null
-      if (a) fn(...a)
-    })
-  }) as ((...args: TArgs) => void) & { cancel: () => void }
-
-  scheduled.cancel = () => {
-    if (rafId !== 0) {
-      cancelAnimationFrame(rafId)
-      rafId = 0
-    }
-    lastArgs = null
-  }
-
-  return scheduled
-}
+export { rafThrottle } from "@exxatdesignux/ui/lib/raf-throttle"

package/template/lib/row-height.ts

@@ -1,10 +1,4 @@
-/**
- * Table row density — shared by Properties drawer tiles and useTableState.
- */
-export type RowHeight = "compact" | "default" | "comfortable"
-
-export const ROW_HEIGHT_TILES: readonly { value: RowHeight; label: string; icon: string }[] = [
-  { value: "compact",     label: "Compact",     icon: "fa-down-to-line" },
-  { value: "default",     label: "Default",     icon: "fa-arrows-up-down" },
-  { value: "comfortable", label: "Comfortable", icon: "fa-up-to-line" },
-]
+export {
+  ROW_HEIGHT_TILES,
+  type RowHeight,
+} from "@exxatdesignux/ui/lib/row-height"

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

@@ -1,9 +1,18 @@
-/** Cookie name persisted by `@exxatdesignux/ui` `SidebarProvider` (`setOpen`). */
-export const SIDEBAR_STATE_COOKIE_NAME = "sidebar_state"
+/**
+ * Cookie name persisted by `@exxatdesignux/ui` `SidebarProvider` (`setOpen`).
+ *
+ * Versioned (`_v2`) on 2026-05-21 to drop stale values written by the pre-fix
+ * code where incidental layout collapses clobbered the user's preference on
+ * every navigation. The legacy `sidebar_state` cookie (without `_v2`) is
+ * ignored on the server and actively deleted client-side on first mount.
+ */
+export const SIDEBAR_STATE_COOKIE_NAME = "sidebar_state_v2"
 
 /** Read desktop sidebar expanded state for SSR `defaultOpen` (matches client cookie restore). */
 export function sidebarDefaultOpenFromCookie(
   value: string | undefined,
 ): boolean {
+  // No cookie OR malformed value → default expanded.
+  // Only an exact `"false"` from the new cookie counts as a saved collapsed preference.
   return value !== "false"
 }

package/template/lib/sites-supported-views.ts

@@ -0,0 +1,10 @@
+import type { DataListViewType } from "@/lib/data-list-view"
+
+/** Views implemented in `SitesTable` — keep in sync with the renderers passed to `HubTable`. */
+export const SITES_SUPPORTED_VIEWS = [
+  "table",
+  "list",
+  "board",
+  "panel",
+  "dashboard",
+] as const satisfies readonly DataListViewType[]

package/template/lib/team-supported-views.ts

@@ -0,0 +1,10 @@
+import type { DataListViewType } from "@/lib/data-list-view"
+
+/** Views implemented in `TeamTable` — keep in sync with the renderers passed to `HubTable`. */
+export const TEAM_SUPPORTED_VIEWS = [
+  "table",
+  "list",
+  "board",
+  "panel",
+  "dashboard",
+] as const satisfies readonly DataListViewType[]

package/template/package.json

@@ -60,6 +60,7 @@
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3",
+    "@exxatdesignux/eslint-plugin": "workspace:*",
     "@next/bundle-analyzer": "16.2.6",
     "@tailwindcss/postcss": "^4.2.1",
     "@testing-library/jest-dom": "^6.9.1",

package/template/tests/setup.ts

@@ -1 +1,26 @@
 import "@testing-library/jest-dom/vitest"
+import { vi } from "vitest"
+
+// jsdom does not implement window.matchMedia — stub it for tests that use
+// useTableState (which calls useSyncExternalStore with a matchMedia listener)
+Object.defineProperty(window, "matchMedia", {
+  writable: true,
+  value: (query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  }),
+})
+
+// jsdom does not implement ResizeObserver — stub it for components that use
+// Radix UI primitives (Sheet, Tooltip, etc.) which call it internally.
+globalThis.ResizeObserver = class {
+  observe = vi.fn()
+  unobserve = vi.fn()
+  disconnect = vi.fn()
+}