@exxatdesignux/ui 0.2.16 → 0.2.18

package/template/components/page-breadcrumb-trail.tsx

@@ -0,0 +1,131 @@
+"use client"
+
+import * as React from "react"
+import Link from "next/link"
+
+import { cn } from "@/lib/utils"
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from "@/components/ui/breadcrumb"
+
+export interface PageBreadcrumbTrailItem {
+  label: string
+  href?: string
+}
+
+export interface PageBreadcrumbBackProps {
+  /** Destination label (e.g. "Question hub") — shown after the back icon. */
+  label: string
+  href: string
+  className?: string
+}
+
+export interface PageBreadcrumbTrailProps {
+  /** Linkable ancestors (e.g. Question hub). */
+  items?: PageBreadcrumbTrailItem[]
+  /**
+   * Final segment in the trail. Omit when the current page is the `PageHeader`
+   * `<h1>` — use ancestors-only above the title (no duplicate label).
+   */
+  currentPage?: string
+  /**
+   * `header` — SiteHeader: ancestors + `currentPage` on one line.
+   * `content` — ancestors only, above `PageHeader` title.
+   */
+  variant?: "header" | "content"
+  className?: string
+}
+
+/**
+ * Single-step back nav — back icon + parent destination (no chevron trail).
+ * Use in `SiteHeader` for focused child routes (composer, wizard) where the
+ * page `<h1>` is the current title.
+ */
+export function PageBreadcrumbBack({ label, href, className }: PageBreadcrumbBackProps) {
+  return (
+    <Breadcrumb className={cn("min-w-0", className)}>
+      <BreadcrumbList className="gap-1.5 font-sans tracking-normal">
+        <BreadcrumbItem className="min-w-0">
+          <BreadcrumbLink asChild>
+            <Link
+              href={href}
+              className="group inline-flex min-w-0 max-w-full items-center gap-1.5 font-sans text-sm text-muted-foreground hover:text-interactive-hover-foreground"
+              aria-label={`Back to ${label}`}
+            >
+              <i
+                className="fa-light fa-arrow-left shrink-0 text-xs transition-transform group-hover:-translate-x-0.5"
+                aria-hidden="true"
+              />
+              <span className="truncate">{label}</span>
+            </Link>
+          </BreadcrumbLink>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  )
+}
+
+/**
+ * Product breadcrumb trail — one component for SiteHeader and in-page shells.
+ * Uses shadcn `Breadcrumb` primitives with Exxat site-header typography.
+ *
+ * For back-icon + parent label only, use {@link PageBreadcrumbBack}.
+ */
+export function PageBreadcrumbTrail({
+  items = [],
+  currentPage,
+  variant = "content",
+  className,
+}: PageBreadcrumbTrailProps) {
+  const isHeader = variant === "header"
+
+  return (
+    <Breadcrumb
+      className={cn("min-w-0", className)}
+      aria-label={isHeader ? undefined : "Breadcrumb"}
+    >
+      <BreadcrumbList
+        className={cn(
+          "gap-1.5 font-sans tracking-normal",
+          isHeader && "flex-nowrap overflow-hidden",
+        )}
+      >
+        {items.map((crumb, i) => (
+          <React.Fragment key={`${crumb.label}-${i}`}>
+            <BreadcrumbItem className="shrink-0">
+              {crumb.href ? (
+                <BreadcrumbLink asChild>
+                  <Link
+                    href={crumb.href}
+                    className="font-sans text-sm text-muted-foreground"
+                  >
+                    {crumb.label}
+                  </Link>
+                </BreadcrumbLink>
+              ) : (
+                <span className="font-sans text-sm text-muted-foreground">
+                  {crumb.label}
+                </span>
+              )}
+            </BreadcrumbItem>
+            {(currentPage != null || i < items.length - 1) && (
+              <BreadcrumbSeparator className="text-muted-foreground/50 [&>i]:text-xs" />
+            )}
+          </React.Fragment>
+        ))}
+        {currentPage != null ? (
+          <BreadcrumbItem className="min-w-0">
+            <BreadcrumbPage className="truncate font-sans text-sm font-medium">
+              {currentPage}
+            </BreadcrumbPage>
+          </BreadcrumbItem>
+        ) : null}
+      </BreadcrumbList>
+    </Breadcrumb>
+  )
+}

package/template/components/page-header.tsx

@@ -47,7 +47,7 @@ export interface PageHeaderProps {
   /** Primary page title — rendered as <h1> in Ivy Presto serif */
   title: string
   /** Short descriptor or date shown below the title (and below `accessInfo` when set) */
-  subtitle?: string
+  subtitle?: React.ReactNode
   /** Layout preset — `collaboration` enables access line + face row ahead of `actions`. */
   variant?: PageHeaderVariant
   /**
@@ -187,6 +187,7 @@ export function PageHeader({
         <h1
           className="text-2xl font-semibold tracking-tight leading-tight text-foreground"
           style={{ fontFamily: "var(--font-heading)" }}
+          suppressHydrationWarning
         >
           {title}
         </h1>

package/template/components/{data-views/placement-board-card.tsx → placement-board-card.tsx}

@@ -7,7 +7,7 @@
 import * as React from "react"
 import { cn } from "@/lib/utils"
 import type { Placement } from "@/lib/mock/placements"
-import { StatusBadge } from "@/components/data-list-table-cells"
+import { StatusBadge } from "@/components/placements-table-cells"
 import { AvatarInitials } from "@/components/ui/avatar"
 import { Badge } from "@/components/ui/badge"
 import {
@@ -173,7 +173,7 @@ export function BoardPlacementCard({
   onOpen: (id: number) => void
 }) {
   const lc = lineClampClass(lineCount)
-  const ruleBg = getConditionalRowBackground(row, conditionalRules)
+  const ruleBg = getConditionalRowBackground(row, conditionalRules, boardColumns)
 
   const visibleCols = boardColumns.filter(c => !hiddenColKeys.has(c.key))
   const showStudent = visibleCols.some(c => c.key === "student")

package/template/components/placement-detail.tsx

@@ -17,7 +17,7 @@ import {
 } from "@/components/ui/dropdown-menu"
 import { cn } from "@/lib/utils"
 import type { Placement } from "@/lib/mock/placements"
-import { StatusBadge as PlacementStatusBadge } from "@/components/data-list-table-cells"
+import { StatusBadge as PlacementStatusBadge } from "@/components/placements-table-cells"
 import { placementReadinessBadgeClass } from "@/lib/list-status-badges"
 
 // ─────────────────────────────────────────────────────────────────────────────

package/template/components/placements-board-view.tsx

@@ -27,7 +27,7 @@ import { type BoardCardLifecycleTabId } from "@/lib/placement-board-card-layout"
 import type { ConditionalRule } from "@/components/table-properties/types"
 import type { ColumnDef } from "@/components/data-table/types"
 import { Badge } from "@/components/ui/badge"
-import { BoardPlacementCard } from "@/components/data-views/placement-board-card"
+import { BoardPlacementCard } from "@/components/placement-board-card"
 import { BoardNewCardPlaceholder } from "@/components/data-views/board-card-primitives"
 
 const PHASE_COLUMNS: { phase: PlacementPhase; label: string; description: string }[] = [

package/template/components/{data-list-client.tsx → placements-client.tsx}

@@ -1,7 +1,9 @@
 "use client"
 
 /**
- * DataListClient — demo list hub on the reusable ListPageTemplate.
+ * PlacementsClient — placements hub composition on the reusable
+ * `ListPageTemplate`. Owns the per-page persisted layout (tabs, display
+ * options, show-metrics toggle) and mounts `PlacementsTable` per tab.
  *
  * Uses centralized exports from `@/components/data-views`.
  */
@@ -12,8 +14,8 @@ import { useSidebar }  from "@/components/ui/sidebar"
 import {
   ListPageTemplate,
   type ViewTab,
-  DataListTable,
-  type DataListTableHandle,
+  PlacementsTable,
+  type PlacementsTableHandle,
   type PlacementLifecycleTabId,
   type DataListViewType,
   dataListViewIcon,
@@ -127,7 +129,7 @@ const LIFECYCLE_OPTIONS = [
 // Component
 // ─────────────────────────────────────────────────────────────────────────────
 
-export function DataListClient() {
+export function PlacementsClient() {
   const router = useRouter()
   const { setOpen } = useSidebar()
   const [showMetrics, setShowMetrics] = React.useState(true)
@@ -135,7 +137,7 @@ export function DataListClient() {
   const [displayOptions, setDisplayOptions] = React.useState<DataListDisplayOptions>(DEFAULT_DATA_LIST_DISPLAY_OPTIONS)
   const [tabs, setTabs] = React.useState<ViewTab[]>(DEFAULT_TABS)
   const [activeTabId, setActiveTabId] = React.useState<string>(DEFAULT_TABS[0]?.id ?? "")
-  const tableRef = React.useRef<DataListTableHandle>(null)
+  const tableRef = React.useRef<PlacementsTableHandle>(null)
 
   const viewsTour = useCoachMark({
     flowId: "data-list-views-tour",
@@ -168,7 +170,7 @@ export function DataListClient() {
   React.useLayoutEffect(() => {
     const p = loadPageFromStorage()
     if (!p) return
-    setDisplayOptions(prev => ({ ...DEFAULT_DATA_LIST_DISPLAY_OPTIONS, ...p.displayOptions }))
+    setDisplayOptions({ ...DEFAULT_DATA_LIST_DISPLAY_OPTIONS, ...p.displayOptions })
     setShowMetrics(p.showMetrics)
     setTabs(p.tabs)
     const nextActive = p.tabs.some(t => t.id === p.activeTabId) ? p.activeTabId : (p.tabs[0]?.id ?? "")
@@ -226,7 +228,7 @@ export function DataListClient() {
       renderContent={(tab, updateTab) => {
         const phase = segmentFilterToPhase(tab.filterId)
         return (
-        <DataListTable
+        <PlacementsTable
           key={tab.id}
           ref={tableRef}
           view={tab.viewType}

package/template/components/placements-list-view.tsx

@@ -3,17 +3,19 @@
 /**
  * PlacementsListView — full-width row layout for the data list (vs table grid / board columns).
  * Shares column visibility + lifecycle rules with Table Properties via the same board column model.
- * Long lists use window scroll virtualization (TanStack Virtual) to limit DOM size.
+ *
+ * Shell (empty state + virtualization above 80 rows) comes from the generic
+ * `DataRowList` primitive in `components/data-views/`. This file owns only
+ * the placement-specific row body (column-driven field visibility).
  */
 
 import * as React from "react"
 import { useRouter } from "next/navigation"
-import { useWindowVirtualizer } from "@tanstack/react-virtual"
-import { cn } from "@/lib/utils"
 import type { Placement } from "@/lib/mock/placements"
-import { StatusBadge } from "@/components/data-list-table-cells"
+import { StatusBadge } from "@/components/placements-table-cells"
 import { Badge } from "@/components/ui/badge"
 import { ListPageBoardCard, ListPageBoardCardAvatar } from "@/components/data-views/list-page-board-card"
+import { DataRowList } from "@/components/data-views/data-row-list"
 import {
   type BoardCardLifecycleTabId,
   isBoardFieldActive,
@@ -23,7 +25,7 @@ import { getConditionalRowBackground } from "@/lib/conditional-rule-match"
 import type { ConditionalRule } from "@/components/table-properties/types"
 import type { ColumnDef } from "@/components/data-table/types"
 
-/** Above this count, the list is virtualized against the window scroll. */
+/** Above this count, `DataRowList` virtualizes against the window scroll. */
 const VIRTUAL_ROWS_THRESHOLD = 80
 /** Initial row height guess (px); `measureElement` refines for variable content. */
 const ESTIMATE_ROW_PX = 100
@@ -60,7 +62,7 @@ function PlacementListRowContent({
   conditionalRules: ConditionalRule[] | undefined
   onOpen: (id: number) => void
 }) {
-  const ruleBg = getConditionalRowBackground(row, conditionalRules)
+  const ruleBg = getConditionalRowBackground(row, conditionalRules, boardColumns)
   const showStudent = isBoardFieldActive("student", tab, hiddenColKeys, boardColumns)
   const showStatus = isBoardFieldActive("status", tab, hiddenColKeys, boardColumns)
   const showSite = isBoardFieldActive("site", tab, hiddenColKeys, boardColumns)
@@ -126,106 +128,6 @@ function PlacementListRowContent({
   )
 }
 
-function PlacementListRow({
-  row,
-  tab,
-  hiddenColKeys,
-  boardColumns,
-  conditionalRules,
-  onOpen,
-}: {
-  row: Placement
-  tab: BoardCardLifecycleTabId
-  hiddenColKeys: Set<string>
-  boardColumns: ColumnDef<Placement>[]
-  conditionalRules: ConditionalRule[] | undefined
-  onOpen: (id: number) => void
-}) {
-  return (
-    <li>
-      <PlacementListRowContent
-        row={row}
-        tab={tab}
-        hiddenColKeys={hiddenColKeys}
-        boardColumns={boardColumns}
-        conditionalRules={conditionalRules}
-        onOpen={onOpen}
-      />
-    </li>
-  )
-}
-
-function PlacementsListViewVirtualized({
-  rows,
-  lifecycleTabId,
-  hiddenColKeys,
-  boardColumns,
-  conditionalRules,
-  onOpen,
-}: {
-  rows: Placement[]
-  lifecycleTabId: BoardCardLifecycleTabId
-  hiddenColKeys: Set<string>
-  boardColumns: ColumnDef<Placement>[]
-  conditionalRules: ConditionalRule[] | undefined
-  onOpen: (id: number) => void
-}) {
-  const anchorRef = React.useRef<HTMLDivElement>(null)
-  const [scrollMargin, setScrollMargin] = React.useState(0)
-
-  const updateScrollMargin = React.useCallback(() => {
-    const el = anchorRef.current
-    if (!el) return
-    setScrollMargin(el.getBoundingClientRect().top + window.scrollY)
-  }, [])
-
-  React.useLayoutEffect(() => {
-    updateScrollMargin()
-    window.addEventListener("resize", updateScrollMargin)
-    return () => window.removeEventListener("resize", updateScrollMargin)
-  }, [updateScrollMargin, rows.length, lifecycleTabId])
-
-  const virtualizer = useWindowVirtualizer({
-    count: rows.length,
-    estimateSize: () => ESTIMATE_ROW_PX,
-    overscan: 8,
-    scrollMargin,
-  })
-
-  return (
-    <div ref={anchorRef} className="px-4 pb-8 pt-2 lg:px-6">
-      <ul
-        role="list"
-        className="relative m-0 w-full list-none p-0"
-        style={{ height: virtualizer.getTotalSize() }}
-      >
-        {virtualizer.getVirtualItems().map(vr => {
-          const row = rows[vr.index]
-          if (!row) return null
-          return (
-            <li
-              key={vr.key}
-              data-index={vr.index}
-              ref={virtualizer.measureElement}
-              className="absolute left-0 top-0 w-full pb-2"
-              style={{ transform: `translateY(${vr.start}px)` }}
-            >
-              <PlacementListRowContent
-                row={row}
-                tab={lifecycleTabId}
-                hiddenColKeys={hiddenColKeys}
-                boardColumns={boardColumns}
-                conditionalRules={conditionalRules}
-                onOpen={onOpen}
-              />
-            </li>
-          )
-        })}
-      </ul>
-    </div>
-  )
-}
-
 export interface PlacementsListViewProps {
   rows: Placement[]
   lifecycleTabId: BoardCardLifecycleTabId
@@ -246,32 +148,16 @@ export function PlacementsListView({
   const router = useRouter()
   const onOpen = React.useCallback((id: number) => router.push(`/data-list/${id}`), [router])
 
-  if (rows.length === 0) {
-    return (
-      <div className="px-4 py-16 text-center lg:px-6">
-        <p className="text-sm text-muted-foreground">{emptyCopy}</p>
-      </div>
-    )
-  }
-
-  if (rows.length >= VIRTUAL_ROWS_THRESHOLD) {
-    return (
-      <PlacementsListViewVirtualized
-        rows={rows}
-        lifecycleTabId={lifecycleTabId}
-        hiddenColKeys={hiddenColKeys}
-        boardColumns={boardColumns}
-        conditionalRules={conditionalRules}
-        onOpen={onOpen}
-      />
-    )
-  }
-
   return (
-    <ul className="flex list-none flex-col gap-2 px-4 pb-8 pt-2 lg:px-6">
-      {rows.map(row => (
-        <PlacementListRow
-          key={row.id}
+    <DataRowList<Placement>
+      rows={rows}
+      getRowId={row => row.id}
+      emptyState={emptyCopy}
+      ariaLabel="Placements"
+      virtualizeThreshold={VIRTUAL_ROWS_THRESHOLD}
+      estimatedRowHeight={ESTIMATE_ROW_PX}
+      renderRow={row => (
+        <PlacementListRowContent
           row={row}
           tab={lifecycleTabId}
           hiddenColKeys={hiddenColKeys}
@@ -279,7 +165,7 @@ export function PlacementsListView({
           conditionalRules={conditionalRules}
           onOpen={onOpen}
         />
-      ))}
-    </ul>
+      )}
+    />
   )
 }

package/template/components/{data-list-table-cells.test.tsx → placements-table-cells.test.tsx}

@@ -1,9 +1,9 @@
 import { describe, expect, it } from "vitest"
 import { render, screen } from "@testing-library/react"
 
-import { HireBadge, ReadinessBadge, StatusBadge } from "./data-list-table-cells"
+import { HireBadge, ReadinessBadge, StatusBadge } from "./placements-table-cells"
 
-describe("data-list-table-cells", () => {
+describe("placements-table-cells", () => {
   it("renders StatusBadge label for confirmed", () => {
     render(<StatusBadge status="confirmed" />)
     expect(screen.getByText("Confirmed")).toBeInTheDocument()

package/template/components/{data-list-table-cells.tsx → placements-table-cells.tsx}

@@ -1,7 +1,7 @@
 "use client"
 
 /**
- * Placement table cell primitives — extracted from data-list-table for reuse and easier testing.
+ * Placement table cell primitives — extracted from placements-table for reuse and easier testing.
  */
 
 import * as React from "react"

package/template/components/placements-table-columns.tsx

@@ -2,7 +2,7 @@
 
 /**
  * Placements lifecycle columns, empty states, and Properties drawer labels.
- * Owned by the placements data-list feature (`DataListClient` / `/data-list`), not `DataListTable`.
+ * Owned by the placements feature (`PlacementsClient` / `/data-list`); consumed by `PlacementsTable`.
  */
 
 import { Badge } from "@/components/ui/badge"
@@ -16,7 +16,7 @@ import {
   RowActions,
   StatusBadge,
   WeeksProgressCell,
-} from "@/components/data-list-table-cells"
+} from "@/components/placements-table-cells"
 import { uniquePlacementFieldOptions, type Placement } from "@/lib/mock/placements"
 import { formatDateUS } from "@/lib/date-filter"
 import type { PlacementLifecycleTabId } from "@/lib/placement-lifecycle"