@exxatdesignux/ui 0.2.15 → 0.2.17

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

@@ -12,7 +12,7 @@
  * WCAG 2.1 AA:
  *  ✓ <h1> landmark — one per page (WCAG 1.3.1)
  *  ✓ Sufficient colour contrast ≥ 4.5:1 on title + subtitle (SC 1.4.3)
- *  ✓ Face stack: `role="group"` + aggregate `aria-label`; each face has a `Tooltip` name
+ *  ✓ Face row: `role="group"` + aggregate `aria-label`; each face has a `Tooltip` name
  */
 
 import * as React from "react"
@@ -23,6 +23,7 @@ import {
 } from "@/lib/collaborator-access"
 import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
 import { Button } from "@/components/ui/button"
+import { Separator } from "@/components/ui/separator"
 import {
   Tooltip,
   TooltipContent,
@@ -46,17 +47,17 @@ 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
-  /** Layout preset — `collaboration` enables access line + face stack ahead of `actions`. */
+  subtitle?: React.ReactNode
+  /** Layout preset — `collaboration` enables access line + face row ahead of `actions`. */
   variant?: PageHeaderVariant
   /**
    * Role / access copy or badges — rendered between the title and subtitle when
    * `variant="collaboration"` (e.g. lock icon + “Editors can modify”).
    */
   accessInfo?: React.ReactNode
-  /** People with access — shown as an overlapping face stack when `variant="collaboration"`. */
+  /** People with access — shown as a horizontal row of faces when `variant="collaboration"`. */
   collaborators?: PageHeaderCollaborator[]
-  /** Max faces before a `+N` chip — default 4 */
+  /** Max faces before a `+N` chip — default 3 */
   collaboratorDisplayLimit?: number
   /** Opens the invite collaborators sheet when a face, overflow chip, or empty-state CTA is activated. */
   onCollaboratorsOpen?: () => void
@@ -112,14 +113,13 @@ function PageHeaderCollaborationAccess({
       aria-label={names ? `People with access: ${names}` : "People with access"}
       className="flex shrink-0 items-center gap-2 sm:gap-2.5"
     >
-      <div className="flex -space-x-2 ps-0.5">
-        {visible.map((c, index) => (
+      <div className="flex shrink-0 items-center gap-1.5">
+        {visible.map(c => (
           <Tooltip key={c.id}>
             <TooltipTrigger asChild>
               <button
                 type="button"
-                className="relative rounded-full ring-2 ring-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-                style={{ zIndex: 10 + index }}
+                className="relative shrink-0 rounded-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
                 aria-label={`Open collaborators — ${c.name}`}
                 onClick={onOpenCollaborators}
                 disabled={!onOpenCollaborators}
@@ -140,7 +140,7 @@ function PageHeaderCollaborationAccess({
         {overflow > 0 && (
           <button
             type="button"
-            className="relative z-30 flex size-6 shrink-0 items-center justify-center rounded-full bg-muted text-xs font-medium tabular-nums text-muted-foreground ring-2 ring-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring sm:size-7"
+            className="flex size-6 shrink-0 items-center justify-center rounded-full bg-muted text-[11px] font-semibold tabular-nums text-muted-foreground ring-1 ring-border/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
             aria-label={`Open collaborators — ${overflow} more people with access`}
             onClick={onOpenCollaborators}
             disabled={!onOpenCollaborators}
@@ -159,7 +159,7 @@ export function PageHeader({
   variant = "default",
   accessInfo,
   collaborators,
-  collaboratorDisplayLimit = 4,
+  collaboratorDisplayLimit = 3,
   onCollaboratorsOpen,
   addCollaboratorLabel = COLLABORATION_HEADER_ADD_LABEL,
   actions,
@@ -170,6 +170,8 @@ export function PageHeader({
   const showAccess = Boolean(isCollaboration && accessInfo)
   const showCollaborationAccess = isCollaboration
   const showActionsColumn = Boolean(actions) || showCollaborationAccess
+  const showCollaboratorActionsSeparator =
+    showCollaborationAccess && Boolean(actions)
 
   return (
     <div
@@ -185,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>
@@ -208,6 +211,13 @@ export function PageHeader({
               addCollaboratorLabel={addCollaboratorLabel}
             />
           ) : null}
+          {showCollaboratorActionsSeparator ? (
+            <Separator
+              orientation="vertical"
+              decorative
+              className="h-8 shrink-0"
+            />
+          ) : null}
           {actions}
         </div>
       )}

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 {

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