@exxatdesignux/ui 0.2.19 → 0.3.0

package/template/components/placements-table.tsx

@@ -0,0 +1,934 @@
+"use client"
+
+/**
+ * PlacementsTable — placements hub composed on top of the centralized `<HubTable>`. Owns:
+ * placement-specific column defs / cells, board/list/folder/tree/panel/dashboard renderers,
+ * pagination chrome wrapping the table + list views, and the dashboard layout state.
+ *
+ * Single dataset rule: `HubTable` runs one `useTableState(rows, columns, …)`. Every renderer
+ * (board, list, folder, tree, panel, dashboard) reads `state.rows`/`state.pagedRows` — the same
+ * filtered/sorted/paged bag as the grid.
+ *
+ * View tabs drive `view` (table | list | board | …). One canonical column set + row bag —
+ * lifecycle segmentation has been removed; every tab sees the same placements.
+ */
+
+import * as React from "react"
+import dynamic from "next/dynamic"
+import { useRouter } from "next/navigation"
+import { cn } from "@/lib/utils"
+import { mailtoHref } from "@/lib/mailto"
+import { Button } from "@/components/ui/button"
+import { Tip } from "@/components/ui/tip"
+import { Skeleton } from "@/components/ui/skeleton"
+import { AvatarInitials } from "@/components/ui/avatar"
+import { CoachMark } from "@/components/ui/coach-mark"
+import { useCoachMark } from "@/hooks/use-coach-mark"
+import { DASHBOARD_CUSTOMIZE_COACH_STEPS } from "@/lib/dashboard-customize-coach-mark"
+import { KEY_METRICS_KPI_COUNT_DEFAULT } from "@/lib/dashboard-layout-merge"
+import {
+  ALL_DASHBOARD_CARDS,
+  DEFAULT_VISIBLE_CARDS,
+  DEFAULT_SPANS,
+  DEFAULT_CHART_TYPES,
+  loadDashboardLayout,
+  mergeDashboardLayout,
+  saveDashboardLayout,
+  type ChartType,
+  type DashboardLayout,
+} from "@/lib/data-view-dashboard-placements-layout"
+import { PlacementsBoardView, type PlacementsBoardColumnMenu } from "@/components/placements-board-view"
+import {
+  PlacementListRowContent,
+  PLACEMENT_LIST_ESTIMATE_ROW_PX,
+  PLACEMENT_LIST_VIRTUAL_ROWS_THRESHOLD,
+} from "@/components/placements-list-view"
+import {
+  FolderGridView,
+  ListPageTreePanelShell,
+  HubTable,
+  type HubTableHandle,
+  type HubTableRenderers,
+  type HubTableRendererArgs,
+} from "@/components/data-views"
+import { DataRowList } from "@/components/data-views/data-row-list"
+import { ListPageSplitHubChrome } from "@/components/data-views/list-page-split-hub-chrome"
+import { ListPageTreeColumnHeader } from "@/components/data-views/list-page-tree-column-header"
+import { FinderPanelView, type FinderGroup } from "@/components/data-views/finder-panel-view"
+import { ListPageSplitDetailsPlaceholder } from "@/components/data-views/list-page-split-details-placeholder"
+import { getConditionalRowBackground } from "@/lib/conditional-rule-match"
+import { isBoardFieldActive } from "@/lib/placement-board-card-layout"
+import { TablePropertiesDrawerButton } from "@/components/table-properties"
+import type { DataListViewType } from "@/lib/data-list-view"
+import {
+  DEFAULT_DATA_LIST_DISPLAY_OPTIONS,
+  type DataListDisplayOptions,
+} from "@/lib/data-list-display-options"
+import { StatusBadge } from "@/components/placements-table-cells"
+import { DataTable, DataTableToolbar } from "@/components/data-table"
+import { CountSyncer, PaginationBar } from "@/components/data-table/pagination"
+import type { ColumnDef, ConditionalRule } from "@/components/data-table/types"
+import { useTableState } from "@/components/data-table/use-table-state"
+import { ALL_PLACEMENTS, type Placement, type Status } from "@/lib/mock/placements"
+import {
+  getPlacementColumns,
+  PLACEMENT_DRAWER_LABEL,
+  PLACEMENT_EMPTY_COPY,
+} from "@/components/placements-table-columns"
+import { placementKpiInsightFromRows, placementKpiMetricsFromRows } from "@/lib/mock/placements-kpi"
+import { PLACEMENTS_SUPPORTED_VIEWS } from "@/lib/placements-supported-views"
+
+// ─── Dynamic dashboard charts section (heavy; loaded only on dashboard tab) ──
+
+const PlacementsDashboardChartsSection = dynamic(
+  () =>
+    import("@/components/data-view-dashboard-charts").then(mod => ({
+      default: mod.PlacementsDashboardChartsSection,
+    })),
+  {
+    ssr: false,
+    loading: () => (
+      <div className="mx-4 mb-8 mt-2 flex flex-col gap-3 border border-border rounded-xl p-6 lg:mx-6">
+        <Skeleton className="h-7 w-48 max-w-full" />
+        <Skeleton className="min-h-[200px] w-full rounded-lg" />
+        <Skeleton className="min-h-[200px] w-full rounded-lg" />
+      </div>
+    ),
+  },
+)
+
+// ─── Placement-specific tile for FolderGridView ──────────────────────────────
+
+function PlacementFolderTile({
+  row,
+  hiddenColKeys,
+  boardColumns,
+  conditionalRules,
+  onClick,
+}: {
+  row: Placement
+  hiddenColKeys: Set<string>
+  boardColumns: ColumnDef<Placement>[]
+  conditionalRules?: ConditionalRule[]
+  onClick: () => void
+}) {
+  const ruleBg = getConditionalRowBackground(row, conditionalRules, boardColumns)
+  const showStudent = isBoardFieldActive("student", hiddenColKeys, boardColumns)
+  const showStatus = isBoardFieldActive("status", hiddenColKeys, boardColumns)
+  const showSite = isBoardFieldActive("site", hiddenColKeys, boardColumns)
+  const showSpec = isBoardFieldActive("specialization", hiddenColKeys, boardColumns)
+  const showProgram = isBoardFieldActive("program", hiddenColKeys, boardColumns)
+  const name = showStudent ? row.student : `Placement ${row.id}`
+
+  const statusDotClass: Record<Status, string> = {
+    confirmed: "bg-success",
+    pending: "bg-warning",
+    "under-review": "bg-brand",
+    completed: "bg-muted-foreground",
+    rejected: "bg-destructive",
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className={`group relative flex flex-col items-center gap-2 rounded-xl border border-border bg-card p-4 text-left hover:border-interactive-hover hover:bg-interactive-hover/30 hover:shadow-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-all duration-100 cursor-pointer select-none w-full ${ruleBg}`}
+      aria-label={`Open ${name}`}
+    >
+      <div className="relative">
+        <AvatarInitials initials={row.initials} className="size-14 rounded-full text-lg font-semibold" />
+        {showStatus && (
+          <span className="absolute -bottom-0.5 -right-1 flex size-4 items-center justify-center rounded-full bg-card ring-2 ring-card" aria-hidden="true">
+            <span className={`size-2.5 rounded-full ${statusDotClass[row.status]}`} />
+          </span>
+        )}
+      </div>
+      <p className="w-full text-center text-[13px] font-medium text-foreground leading-tight line-clamp-2">{name}</p>
+      {showStatus && <StatusBadge status={row.status} />}
+      {(showSite || showSpec || showProgram) && (
+        <div className="flex w-full flex-col gap-0.5">
+          {showSite && (
+            <p className="truncate text-center text-[11px] text-muted-foreground leading-tight">
+              <i className="fa-light fa-building me-1" aria-hidden="true" />{row.site}
+            </p>
+          )}
+          {showSpec && <p className="truncate text-center text-[11px] text-muted-foreground leading-tight">{row.specialization}</p>}
+          {showProgram && <p className="truncate text-center text-[11px] text-muted-foreground leading-tight">{row.program}</p>}
+        </div>
+      )}
+    </button>
+  )
+}
+
+// ─── Placement-specific list row for FinderPanelView ─────────────────────────
+
+function PlacementFinderListRow({
+  row,
+  isSelected,
+  hiddenColKeys,
+  boardColumns,
+  conditionalRules,
+}: {
+  row: Placement
+  isSelected: boolean
+  hiddenColKeys: Set<string>
+  boardColumns: ColumnDef<Placement>[]
+  conditionalRules?: ConditionalRule[]
+}) {
+  const ruleBg = getConditionalRowBackground(row, conditionalRules, boardColumns)
+  const showStudent = isBoardFieldActive("student", hiddenColKeys, boardColumns)
+  const showSite = isBoardFieldActive("site", hiddenColKeys, boardColumns)
+  const name = showStudent ? row.student : `Placement ${row.id}`
+  return (
+    <div
+      className={`flex w-full min-w-0 items-center gap-3 transition-colors duration-75 ${
+        isSelected ? "bg-transparent text-accent-foreground" : cn("text-foreground", ruleBg)
+      }`}
+    >
+      <AvatarInitials
+        initials={row.initials}
+        className={cn(
+          "size-8 shrink-0 rounded-full text-[11px] font-semibold",
+          isSelected ? "ring-2 ring-accent-foreground/35" : "",
+        )}
+      />
+      <div className="min-w-0 flex-1">
+        <p className={cn("truncate text-[13px] font-medium leading-tight", isSelected ? "text-accent-foreground" : "text-foreground")}>
+          {name}
+        </p>
+        {showSite && (
+          <p className={cn("mt-0.5 truncate text-[11px] leading-tight", isSelected ? "text-accent-foreground/80" : "text-muted-foreground")}>
+            {row.site}
+          </p>
+        )}
+      </div>
+      {!isSelected && <StatusBadge status={row.status} />}
+    </div>
+  )
+}
+
+// ─── Placement-specific detail pane for FinderPanelView ──────────────────────
+
+function PlacementFinderDetail({
+  row,
+  hiddenColKeys,
+  boardColumns,
+}: {
+  row: Placement
+  hiddenColKeys: Set<string>
+  boardColumns: ColumnDef<Placement>[]
+}) {
+  const router = useRouter()
+  const show = (key: string) => isBoardFieldActive(key, hiddenColKeys, boardColumns)
+  return (
+    <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
+      <div className="flex shrink-0 items-start gap-4 border-b border-border px-5 py-4">
+        <AvatarInitials initials={row.initials} className="size-14 shrink-0 rounded-full text-lg font-semibold" />
+        <div className="min-w-0 flex-1">
+          <h2 className="text-base font-semibold text-foreground leading-tight">{row.student}</h2>
+          {show("program") && <p className="mt-0.5 text-[13px] text-muted-foreground">{row.program}</p>}
+          {show("status") && <div className="mt-2"><StatusBadge status={row.status} /></div>}
+        </div>
+        <Tip side="bottom" label="Open full detail page">
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            className="shrink-0"
+            onClick={() => router.push(`/data-list/${row.id}`)}
+            aria-label={`Open full detail for ${row.student}`}
+          >
+            <i className="fa-light fa-arrow-up-right-from-square text-[12px]" aria-hidden="true" />
+            Open
+          </Button>
+        </Tip>
+      </div>
+      <div className="min-h-0 flex-1 overflow-y-auto px-5 py-4">
+        <dl className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+          {show("email") && (
+            <div className="flex flex-col gap-0.5">
+              <dt className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground flex items-center gap-1.5">
+                <i className="fa-light fa-envelope text-[10px]" aria-hidden="true" /> Email
+              </dt>
+              <dd className="text-[13px]">
+                <a href={mailtoHref(row.email)} className="text-interactive-foreground hover:underline">{row.email}</a>
+              </dd>
+            </div>
+          )}
+          {show("site") && (
+            <div className="flex flex-col gap-0.5">
+              <dt className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground flex items-center gap-1.5">
+                <i className="fa-light fa-building text-[10px]" aria-hidden="true" /> Site
+              </dt>
+              <dd className="text-[13px] text-foreground">{row.site}</dd>
+            </div>
+          )}
+          {show("internship") && (
+            <div className="flex flex-col gap-0.5">
+              <dt className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground flex items-center gap-1.5">
+                <i className="fa-light fa-briefcase text-[10px]" aria-hidden="true" /> Internship
+              </dt>
+              <dd className="text-[13px] text-foreground">{row.internship}</dd>
+            </div>
+          )}
+          {show("specialization") && (
+            <div className="flex flex-col gap-0.5">
+              <dt className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground flex items-center gap-1.5">
+                <i className="fa-light fa-stethoscope text-[10px]" aria-hidden="true" /> Specialization
+              </dt>
+              <dd className="text-[13px] text-foreground">{row.specialization}</dd>
+            </div>
+          )}
+          {show("supervisor") && (
+            <div className="flex flex-col gap-0.5">
+              <dt className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground flex items-center gap-1.5">
+                <i className="fa-light fa-user-tie text-[10px]" aria-hidden="true" /> Supervisor
+              </dt>
+              <dd className="text-[13px] text-foreground">{row.supervisor}</dd>
+            </div>
+          )}
+          {show("start") && (
+            <div className="flex flex-col gap-0.5">
+              <dt className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground flex items-center gap-1.5">
+                <i className="fa-light fa-calendar text-[10px]" aria-hidden="true" /> Start Date
+              </dt>
+              <dd className="text-[13px] text-foreground">{row.start}</dd>
+            </div>
+          )}
+          {show("duration") && (
+            <div className="flex flex-col gap-0.5">
+              <dt className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground flex items-center gap-1.5">
+                <i className="fa-light fa-clock text-[10px]" aria-hidden="true" /> Duration
+              </dt>
+              <dd className="text-[13px] text-foreground">{row.duration}</dd>
+            </div>
+          )}
+          {row.placementPhase === "ongoing" && (
+            <div className="flex flex-col gap-0.5 sm:col-span-2">
+              <dt className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground flex items-center gap-1.5">
+                <i className="fa-light fa-chart-line text-[10px]" aria-hidden="true" /> Progress
+              </dt>
+              <dd className="text-[13px] text-foreground flex flex-col gap-1.5">
+                <span>{row.progressWeeksDone} / {row.progressWeeksTotal} weeks</span>
+                <div role="progressbar" aria-valuenow={row.progressWeeksDone} aria-valuemin={0} aria-valuemax={row.progressWeeksTotal}
+                  aria-label={`${row.progressWeeksDone} of ${row.progressWeeksTotal} weeks completed`}
+                  className="h-1.5 w-full overflow-hidden rounded-full bg-muted">
+                  <div className="h-full rounded-full bg-primary transition-all"
+                    style={{ width: `${Math.round((row.progressWeeksDone / Math.max(1, row.progressWeeksTotal)) * 100)}%` }} />
+                </div>
+              </dd>
+            </div>
+          )}
+          {row.siteAddress && (
+            <div className="flex flex-col gap-0.5 sm:col-span-2">
+              <dt className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground flex items-center gap-1.5">
+                <i className="fa-light fa-location-dot text-[10px]" aria-hidden="true" /> Site Address
+              </dt>
+              <dd className="text-[13px] text-foreground">{row.siteAddress}</dd>
+            </div>
+          )}
+        </dl>
+      </div>
+    </div>
+  )
+}
+
+// ─── Status groups for FinderPanelView ───────────────────────────────────────
+
+const STATUS_GROUPS: Array<{ id: Status | "all"; label: string; accent: string }> = [
+  { id: "all", label: "All", accent: "bg-muted-foreground" },
+  { id: "confirmed", label: "Confirmed", accent: "bg-success" },
+  { id: "pending", label: "Pending", accent: "bg-warning" },
+  { id: "under-review", label: "Under Review", accent: "bg-brand" },
+  { id: "rejected", label: "Rejected", accent: "bg-destructive" },
+  { id: "completed", label: "Completed", accent: "bg-muted-foreground/50" },
+]
+
+function buildStatusGroups(rows: Placement[]): FinderGroup[] {
+  return STATUS_GROUPS.map(sg => ({
+    id: sg.id,
+    label: sg.label,
+    accent: sg.accent,
+    count: sg.id === "all" ? rows.length : rows.filter(r => r.status === sg.id).length,
+  }))
+}
+
+// ─── Tree-view body (its own selection state) ────────────────────────────────
+
+function PlacementsTreeBody({
+  args,
+}: {
+  args: HubTableRendererArgs<Placement>
+}) {
+  const { state } = args
+  const listRows = state.rows as Placement[]
+  const boardColumns = state.displayCols.filter(c => c.key !== "select" && c.key !== "actions")
+  const [selectedId, setSelectedId] = React.useState<number | null>(() => listRows[0]?.id ?? null)
+
+  React.useEffect(() => {
+    if (selectedId == null) {
+      setSelectedId(listRows[0]?.id ?? null)
+      return
+    }
+    if (!listRows.some(r => r.id === selectedId)) {
+      setSelectedId(listRows[0]?.id ?? null)
+    }
+  }, [listRows, selectedId])
+
+  const selected = listRows.find(r => r.id === selectedId) ?? null
+
+  return (
+    <ListPageTreePanelShell
+      resizableGroupId="data-list-tree"
+      ariaLabel="Record outline and details"
+      tree={
+        <div className="flex min-h-0 flex-1 flex-col">
+          <ListPageTreeColumnHeader title="Records" />
+          {listRows.length === 0 ? (
+            <p className="p-3 text-sm text-muted-foreground">{PLACEMENT_EMPTY_COPY}</p>
+          ) : (
+            <ul
+              role="tree"
+              aria-label="Demo records"
+              className="min-h-0 flex-1 list-none space-y-0.5 overflow-y-auto py-1"
+            >
+              {listRows.map(row => {
+                const isSel = selectedId === row.id
+                return (
+                  <li key={row.id} role="none" className="py-0.5">
+                    <button
+                      type="button"
+                      role="treeitem"
+                      aria-selected={isSel}
+                      tabIndex={isSel ? 0 : -1}
+                      onClick={() => setSelectedId(row.id)}
+                      className={cn(
+                        "flex w-full min-h-8 items-center rounded-md px-3 py-2 text-left text-sm transition-colors duration-75",
+                        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
+                        isSel
+                          ? "bg-accent font-medium text-accent-foreground"
+                          : "text-foreground hover:bg-muted/50",
+                      )}
+                    >
+                      <span className="min-w-0 truncate">{row.student}</span>
+                    </button>
+                  </li>
+                )
+              })}
+            </ul>
+          )}
+        </div>
+      }
+      details={
+        selected ? (
+          <div className="flex min-h-0 flex-1 flex-col overflow-hidden bg-card">
+            <ListPageTreeColumnHeader title="Details" />
+            <div className="min-h-0 flex-1 overflow-y-auto">
+              <PlacementFinderDetail
+                row={selected}
+                hiddenColKeys={state.hiddenCols}
+                boardColumns={boardColumns}
+              />
+            </div>
+          </div>
+        ) : (
+          <ListPageSplitDetailsPlaceholder title="Nothing selected" />
+        )
+      }
+    />
+  )
+}
+
+// ─── Dashboard body (its own layout state) ───────────────────────────────────
+
+function PlacementsDashboardBody({
+  args,
+  columns,
+}: {
+  args: HubTableRendererArgs<Placement>
+  columns: ColumnDef<Placement>[]
+}) {
+  const { state, drawerToolbarProps, displayOptions } = args
+  const rows = state.rows as Placement[]
+
+  const dashboardKpi = React.useMemo(
+    () => ({
+      metrics: placementKpiMetricsFromRows(rows),
+      insight: placementKpiInsightFromRows(rows),
+    }),
+    [rows],
+  )
+
+  const [visibleCards, setVisibleCards] = React.useState<string[]>(DEFAULT_VISIBLE_CARDS)
+  const [cardOrder, setCardOrder] = React.useState<string[]>(ALL_DASHBOARD_CARDS.map(c => c.id))
+  const [cardSpans, setCardSpans] = React.useState<Record<string, 1 | 2>>(() => ({ ...DEFAULT_SPANS }))
+  const [cardChartTypes, setCardChartTypes] = React.useState<Record<string, ChartType>>(() => ({ ...DEFAULT_CHART_TYPES }))
+  const [keyMetricsKpiCount, setKeyMetricsKpiCount] = React.useState<number>(KEY_METRICS_KPI_COUNT_DEFAULT)
+  const [layoutEdit, setLayoutEdit] = React.useState(false)
+  const hydrated = React.useRef(false)
+  const baselineRef = React.useRef<DashboardLayout | null>(null)
+
+  React.useEffect(() => {
+    const saved = loadDashboardLayout()
+    const m = mergeDashboardLayout(saved)
+    setVisibleCards(m.visible)
+    setCardOrder(m.order)
+    setCardSpans(m.spans ?? { ...DEFAULT_SPANS })
+    setCardChartTypes(m.chartTypes ?? { ...DEFAULT_CHART_TYPES })
+    setKeyMetricsKpiCount(m.keyMetricsKpiCount ?? KEY_METRICS_KPI_COUNT_DEFAULT)
+    hydrated.current = true
+  }, [])
+
+  React.useEffect(() => {
+    if (!hydrated.current) return
+    saveDashboardLayout({
+      visible: visibleCards,
+      order: cardOrder,
+      spans: cardSpans,
+      chartTypes: cardChartTypes,
+      keyMetricsKpiCount,
+    })
+  }, [visibleCards, cardOrder, cardSpans, cardChartTypes, keyMetricsKpiCount])
+
+  const onResetLayout = React.useCallback(() => {
+    setVisibleCards(ALL_DASHBOARD_CARDS.map(c => c.id))
+    setCardOrder(ALL_DASHBOARD_CARDS.map(c => c.id))
+    setCardSpans({ ...DEFAULT_SPANS })
+    setCardChartTypes({ ...DEFAULT_CHART_TYPES })
+    setKeyMetricsKpiCount(KEY_METRICS_KPI_COUNT_DEFAULT)
+  }, [])
+
+  const onLayoutEditStart = React.useCallback(() => {
+    baselineRef.current = {
+      visible: [...visibleCards],
+      order: [...cardOrder],
+      spans: { ...cardSpans },
+      chartTypes: { ...cardChartTypes },
+      keyMetricsKpiCount,
+    }
+    setLayoutEdit(true)
+  }, [visibleCards, cardOrder, cardSpans, cardChartTypes, keyMetricsKpiCount])
+
+  const onLayoutEditCancel = React.useCallback(() => {
+    const b = baselineRef.current
+    if (b) {
+      setVisibleCards(b.visible)
+      setCardOrder(b.order)
+      setCardSpans(b.spans ?? { ...DEFAULT_SPANS })
+      setCardChartTypes(b.chartTypes ?? { ...DEFAULT_CHART_TYPES })
+      setKeyMetricsKpiCount(b.keyMetricsKpiCount ?? KEY_METRICS_KPI_COUNT_DEFAULT)
+    }
+    setLayoutEdit(false)
+  }, [])
+
+  const coach = useCoachMark({
+    flowId: "data-list-dashboard-customize",
+    steps: DASHBOARD_CUSTOMIZE_COACH_STEPS,
+    delay: 700,
+    dependsOnDismissedFlowId: "data-list-views-tour",
+  })
+
+  return (
+    <>
+      <CoachMark state={coach} />
+      {!layoutEdit ? (
+        <DataTableToolbar
+          state={state}
+          columns={columns}
+          searchable={displayOptions.showToolbarSearch}
+          renderFilterOptionValue={drawerToolbarProps.renderFilterOptionValue}
+          searchAriaLabel="Search rows"
+          toolbarSlot={s => (
+            <TablePropertiesDrawerButton
+              {...drawerToolbarProps}
+              state={s}
+              extraActions={
+                <Tip side="bottom" label="Edit dashboard layout on canvas">
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon-sm"
+                    aria-label="Edit dashboard layout"
+                    onClick={onLayoutEditStart}
+                    className="text-muted-foreground hover:text-interactive-hover-foreground hover:bg-interactive-hover"
+                  >
+                    <i className="fa-light fa-pen-ruler text-[13px]" aria-hidden="true" />
+                  </Button>
+                </Tip>
+              }
+            />
+          )}
+        />
+      ) : null}
+      <PlacementsDashboardChartsSection
+        placements={rows}
+        keyMetrics={dashboardKpi}
+        visibleCards={visibleCards}
+        cardOrder={cardOrder}
+        cardSpans={cardSpans}
+        cardChartTypes={cardChartTypes}
+        keyMetricsKpiCount={keyMetricsKpiCount}
+        layoutEditMode={layoutEdit}
+        onVisibleChange={setVisibleCards}
+        onOrderChange={setCardOrder}
+        onSpanChange={(id, span) => setCardSpans(prev => ({ ...prev, [id]: span }))}
+        onChartTypeChange={(id, t) => setCardChartTypes(prev => ({ ...prev, [id]: t }))}
+        onKeyMetricsKpiCountChange={setKeyMetricsKpiCount}
+        onResetLayout={onResetLayout}
+        onLayoutEditDone={() => setLayoutEdit(false)}
+        onLayoutEditCancel={onLayoutEditCancel}
+      />
+    </>
+  )
+}
+
+// ─── Board renderer body ─────────────────────────────────────────────────────
+
+function PlacementsBoardBody({
+  args,
+}: {
+  args: HubTableRendererArgs<Placement>
+}) {
+  const { state, displayOptions, drawerToolbarProps } = args
+  const columns = state.displayCols
+  const boardColumnMenu: PlacementsBoardColumnMenu = React.useMemo(
+    () => ({
+      filterableColumns: columns.filter(c => c.filter).map(c => ({ key: c.key, label: c.label })),
+      sortableColumns: columns.filter(c => c.sortable && c.sortKey).map(c => ({ key: c.key, label: c.label })),
+      groupableColumns: columns.filter(c => c.key !== "select" && c.key !== "actions").map(c => ({ key: c.key, label: c.label })),
+      groupBy: state.groupBy,
+      onAddFilter: state.addFilter,
+      onSortByField: (fieldKey, direction) => {
+        state.setSortRules(prev => {
+          const filtered = prev.filter(r => r.fieldKey !== fieldKey)
+          return [{ id: `sort-${Date.now()}`, fieldKey, direction }, ...filtered]
+        })
+      },
+      onToggleGroupBy: (fieldKey: string) => {
+        state.setGroupBy(prev => (prev === fieldKey ? null : fieldKey))
+      },
+      onOpenProperties: () => state.setSheetOpen(true),
+    }),
+    [columns, state],
+  )
+
+  return (
+    <PlacementsBoardView
+      placements={state.rows as Placement[]}
+      boardColumnMenu={boardColumnMenu}
+      boardDisplay={{
+        lineCount: displayOptions.boardLineCount,
+        showColumnLabels: displayOptions.showColumnLabels,
+        showColumnCounts: displayOptions.showBoardColumnCounts,
+        newCardAbove: displayOptions.boardNewCardAbove,
+      }}
+      hiddenColKeys={state.hiddenCols}
+      conditionalRules={drawerToolbarProps.conditionalRules}
+      boardColumns={state.displayCols.filter(c => c.key !== "select" && c.key !== "actions")}
+    />
+  )
+}
+
+// ─── Props ───────────────────────────────────────────────────────────────────
+
+export interface PlacementsTableProps {
+  view?: DataListViewType
+  onViewChange?: (view: DataListViewType) => void
+  /** Shared display options (persist at page level — all view types). */
+  displayOptions?: DataListDisplayOptions
+  onDisplayOptionsChange?: (patch: Partial<DataListDisplayOptions>) => void
+  /** Panel view: custom groups builder. If not provided, uses default placement status groups. */
+  panelGroupsBuilder?: (rows: Placement[]) => FinderGroup[]
+  /** Panel view: custom list row renderer. If not provided, uses default placement row rendering. */
+  panelRenderListRow?: (row: Placement, isSelected: boolean) => React.ReactNode
+  /** Panel view: custom detail pane renderer. If not provided, uses default placement detail rendering. */
+  panelRenderDetail?: (row: Placement) => React.ReactNode
+}
+
+/** Imperative handle — open Table Properties (table view only). */
+export type PlacementsTableHandle = HubTableHandle
+
+// ─── Public component ───────────────────────────────────────────────────────
+
+export const PlacementsTable = React.forwardRef<PlacementsTableHandle, PlacementsTableProps>(function PlacementsTable(
+  {
+    view = "table",
+    onViewChange,
+    displayOptions: displayOptionsProp,
+    onDisplayOptionsChange,
+    panelGroupsBuilder,
+    panelRenderListRow,
+    panelRenderDetail,
+  },
+  ref,
+) {
+  const router = useRouter()
+  const displayOptions = React.useMemo(
+    () => ({ ...DEFAULT_DATA_LIST_DISPLAY_OPTIONS, ...displayOptionsProp }),
+    [displayOptionsProp],
+  )
+
+  const columns = React.useMemo(() => getPlacementColumns(), [])
+  const tableData = ALL_PLACEMENTS
+
+  const renderFilterOptionValue = React.useCallback(
+    (fieldKey: string, value: string): React.ReactNode => {
+      if (fieldKey === "status") return <StatusBadge status={value as Status} />
+      const col = columns.find(c => c.key === fieldKey)
+      const opt = col?.filter?.options?.find(o => o.value === value)
+      return <span className="text-foreground">{opt?.label ?? value}</span>
+    },
+    [columns],
+  )
+
+  // ─ Pagination chrome (only TABLE + LIST views) ────────────────────────────
+  const [pagination, setPagination] = React.useState(false)
+  const [paginationPage, setPaginationPage] = React.useState(1)
+  const [paginationPageSize, setPaginationPageSize] = React.useState(10)
+  const [filteredCount, setFilteredCount] = React.useState(tableData.length)
+
+  React.useEffect(() => {
+    setFilteredCount(tableData.length)
+  }, [tableData])
+
+  const totalPages = Math.max(1, Math.ceil(filteredCount / Math.max(1, paginationPageSize)))
+  const safePage = Math.min(paginationPage, totalPages)
+
+  // Pagination only applies to TABLE + LIST views (board/dashboard/folder/panel/tree-panel
+  // are not paged). Cards/boards consume `state.rows` directly.
+  const paginationEligible = view === "table" || view === "list"
+  const paginationOverride =
+    pagination && paginationEligible ? { page: safePage, pageSize: paginationPageSize } : undefined
+
+  const onPageSizeChange = React.useCallback((n: number) => {
+    setPaginationPageSize(n)
+    setPaginationPage(1)
+  }, [])
+
+  // Renderers --------------------------------------------------------------
+  const renderers: HubTableRenderers<Placement> = {
+    "board-with-toolbar": (args) =>
+      args.toolbarShell(<PlacementsBoardBody args={args} />),
+    "list-with-toolbar": (args) => {
+      const { state, toolbarShell } = args
+      const listRows = pagination ? (state.pagedRows as Placement[]) : (state.rows as Placement[])
+      const boardColumns = state.displayCols.filter(c => c.key !== "select" && c.key !== "actions")
+      return (
+        <>
+          {pagination ? (
+            <CountSyncer
+              count={state.rows.length}
+              onSync={setFilteredCount}
+              onReset={() => setPaginationPage(1)}
+            />
+          ) : null}
+          {toolbarShell(
+            <>
+              <DataRowList<Placement>
+                rows={listRows}
+                getRowId={row => row.id}
+                ariaLabel="Placements"
+                emptyState={PLACEMENT_EMPTY_COPY}
+                virtualizeThreshold={PLACEMENT_LIST_VIRTUAL_ROWS_THRESHOLD}
+                estimatedRowHeight={PLACEMENT_LIST_ESTIMATE_ROW_PX}
+                renderRow={row => (
+                  <PlacementListRowContent
+                    row={row}
+                    hiddenColKeys={state.hiddenCols}
+                    boardColumns={boardColumns}
+                    conditionalRules={args.drawerToolbarProps.conditionalRules}
+                    onOpen={id => router.push(`/data-list/${id}`)}
+                  />
+                )}
+              />
+              {pagination ? (
+                <div className="mx-4 lg:mx-6 border-x border-b border-border rounded-b-lg overflow-hidden">
+                  <PaginationBar
+                    page={safePage}
+                    pageSize={paginationPageSize}
+                    total={filteredCount}
+                    pageSizeOptions={[10, 25, 50, 100]}
+                    onPageChange={setPaginationPage}
+                    onPageSizeChange={onPageSizeChange}
+                  />
+                </div>
+              ) : null}
+            </>,
+          )}
+        </>
+      )
+    },
+    "folder-with-toolbar": (args) => {
+      const { state, toolbarShell } = args
+      const boardColumns = state.displayCols.filter(c => c.key !== "select" && c.key !== "actions")
+      return toolbarShell(
+        <FolderGridView<Placement>
+          rows={state.rows as Placement[]}
+          getRowId={r => r.id}
+          ariaLabel="Demo folder view"
+          emptyContent={<p>{PLACEMENT_EMPTY_COPY}</p>}
+          renderTile={row => (
+            <PlacementFolderTile
+              row={row}
+              hiddenColKeys={state.hiddenCols}
+              boardColumns={boardColumns}
+              onClick={() => router.push(`/data-list/${row.id}`)}
+            />
+          )}
+        />,
+      )
+    },
+    "tree-panel-with-toolbar": (args) =>
+      args.toolbarShell(<PlacementsTreeBody args={args} />),
+    "panel-with-toolbar": (args) => {
+      const { state, toolbarShell } = args
+      const listRows = state.rows as Placement[]
+      const boardColumns = state.displayCols.filter(c => c.key !== "select" && c.key !== "actions")
+      const groups = panelGroupsBuilder ? panelGroupsBuilder(listRows) : buildStatusGroups(listRows)
+      return toolbarShell(
+        <ListPageSplitHubChrome aria-label={PLACEMENT_DRAWER_LABEL}>
+          <FinderPanelView<Placement>
+            embedded
+            groupsColumnTitle="Status"
+            groups={groups}
+            rows={listRows}
+            getRowId={r => r.id}
+            getRowGroupId={r => r.status}
+            defaultGroupId="all"
+            autoSaveId="finder-panel-view"
+            ariaLabel="Demo panel view"
+            emptyList={<p>{PLACEMENT_EMPTY_COPY}</p>}
+            renderListRow={
+              panelRenderListRow
+                ? panelRenderListRow
+                : (row, isSelected) => (
+                    <PlacementFinderListRow
+                      row={row}
+                      isSelected={isSelected}
+                      hiddenColKeys={state.hiddenCols}
+                      boardColumns={boardColumns}
+                    />
+                  )
+            }
+            renderDetail={
+              panelRenderDetail
+                ? panelRenderDetail
+                : row => (
+                    <PlacementFinderDetail
+                      row={row}
+                      hiddenColKeys={state.hiddenCols}
+                      boardColumns={boardColumns}
+                    />
+                  )
+            }
+          />
+        </ListPageSplitHubChrome>,
+      )
+    },
+    "dashboard-with-toolbar": (args) => <PlacementsDashboardBody args={args} columns={columns} />,
+  }
+
+  // Custom `tableRenderer` so pagination chrome (CountSyncer + PaginationBar) wraps the
+  // default DataTable when `pagination` is on. When off, falls back to a plain DataTable.
+  const tableRenderer = (args: HubTableRendererArgs<Placement>) => {
+    const { state } = args
+    return (
+      <>
+        {pagination ? (
+          <CountSyncer
+            count={state.rows.length}
+            onSync={setFilteredCount}
+            onReset={() => setPaginationPage(1)}
+          />
+        ) : null}
+        <div className="pb-6">
+          <DataTable<Placement>
+            data={tableData}
+            columns={columns}
+            getRowId={row => row.id}
+            getRowSelectionLabel={row => row.student}
+            selectable
+            searchable={displayOptions.showToolbarSearch}
+            showColumnHeaders={displayOptions.showColumnLabels}
+            defaultSort={{ key: "student" as const, dir: "asc" as const }}
+            emptyState={PLACEMENT_EMPTY_COPY}
+            renderFilterOptionValue={renderFilterOptionValue}
+            conditionalRules={args.drawerToolbarProps.conditionalRules}
+            onRowClick={row => router.push(`/data-list/${row.id}`)}
+            state={state}
+            hasFooter={pagination}
+            toolbarSlot={s => (
+              <TablePropertiesDrawerButton {...args.drawerToolbarProps} state={s} />
+            )}
+            bulkActionsSlot={(selected) => {
+              const count = selected.size
+              if (count === 0) return null
+              const contextId = "bulk-selection-context"
+              return (
+                <>
+                  <span id={contextId} className="sr-only">
+                    {count} {count === 1 ? "row" : "rows"} selected
+                  </span>
+                  <Button size="sm" variant="default" aria-describedby={contextId}>
+                    <i className="fa-light fa-circle-check" aria-hidden="true" /> Confirm
+                  </Button>
+                  <Button size="sm" variant="outline" aria-describedby={contextId}>
+                    <i className="fa-light fa-arrow-down-to-line" aria-hidden="true" /> Export
+                  </Button>
+                  <Button size="sm" variant="destructive" aria-describedby={contextId}>
+                    <i className="fa-light fa-trash" aria-hidden="true" /> Delete
+                  </Button>
+                </>
+              )
+            }}
+          />
+        </div>
+        {pagination ? (
+          <div className="mx-4 lg:mx-6 border-x border-b border-border rounded-b-lg overflow-hidden">
+            <PaginationBar
+              page={safePage}
+              pageSize={paginationPageSize}
+              total={filteredCount}
+              pageSizeOptions={[10, 25, 50, 100]}
+              onPageChange={setPaginationPage}
+              onPageSizeChange={onPageSizeChange}
+            />
+          </div>
+        ) : null}
+      </>
+    )
+  }
+
+  return (
+    <HubTable<Placement>
+      rows={tableData}
+      columns={columns}
+      view={view}
+      onViewChange={onViewChange}
+      supportedViewTypes={PLACEMENTS_SUPPORTED_VIEWS}
+      hubLabel={PLACEMENT_DRAWER_LABEL}
+      lifecycleTabLabel={PLACEMENT_DRAWER_LABEL}
+      searchAriaLabel="Search rows"
+      getRowId={row => row.id}
+      getRowSelectionLabel={row => row.student}
+      defaultSort={{ key: "student", dir: "asc" }}
+      emptyState={PLACEMENT_EMPTY_COPY}
+      onRowClick={row => router.push(`/data-list/${row.id}`)}
+      displayOptions={displayOptions}
+      onDisplayOptionsChange={onDisplayOptionsChange}
+      pagination={pagination}
+      onPaginationChange={setPagination}
+      paginationOverride={paginationOverride}
+      renderFilterOptionValue={renderFilterOptionValue}
+      renderers={renderers}
+      tableRenderer={tableRenderer}
+      handleRef={ref}
+    />
+  )
+})
+
+PlacementsTable.displayName = "PlacementsTable"
+
+export type { DataListViewType } from "@/lib/data-list-view"
+export { DATA_LIST_VIEW_TILES } from "@/lib/data-list-view"
+export type { DataListDisplayOptions } from "@/lib/data-list-display-options"