@exxatdesignux/ui 0.2.18 → 0.3.0

package/src/components/data-views/board-card-primitives.tsx

@@ -0,0 +1,93 @@
+"use client"
+
+/**
+ * Reusable building blocks for kanban / board cards (icon rows, two-line blocks, placeholders).
+ */
+
+import * as React from "react"
+import { cn } from "../../lib/utils"
+import type { BoardLineCount } from "../../lib/data-list-display-options"
+
+export function BoardCardIconRow({
+  iconClass,
+  children,
+}: {
+  iconClass: string
+  children: React.ReactNode
+}) {
+  return (
+    <div className="flex items-start gap-2">
+      <i
+        className={cn(
+          `fa-light ${iconClass} text-xs text-muted-foreground mt-0.5 w-4 shrink-0 text-center`,
+        )}
+        aria-hidden
+      />
+      <div className="min-w-0 flex-1 text-xs leading-snug [&_.text-sm]:text-xs [&_span]:text-xs [&_div]:text-xs">
+        {children}
+      </div>
+    </div>
+  )
+}
+
+export function BoardCardTwoLineBlock({
+  iconClass,
+  line1,
+  line2,
+  line2ClassName,
+}: {
+  iconClass: string
+  line1: React.ReactNode
+  /** Omitted for a single-line row (same icon + primary alignment as Placements). */
+  line2?: React.ReactNode
+  /** Override default muted line-2 (e.g. badges / rich cells). */
+  line2ClassName?: string
+}) {
+  const showLine2 = line2 !== undefined && line2 !== null
+  return (
+    <div className="flex items-start gap-2">
+      <i
+        className={cn(
+          `fa-light ${iconClass} text-xs text-muted-foreground mt-0.5 w-4 shrink-0 text-center`,
+        )}
+        aria-hidden
+      />
+      <div className="min-w-0 flex-1">
+        <div className="truncate text-xs font-medium text-foreground leading-tight">{line1}</div>
+        {showLine2 ? (
+          <div
+            className={cn(
+              "mt-0.5 min-w-0 leading-tight",
+              line2ClassName ?? "truncate text-xs text-muted-foreground",
+            )}
+          >
+            {line2}
+          </div>
+        ) : null}
+      </div>
+    </div>
+  )
+}
+
+export function lineClampClass(n: BoardLineCount): string {
+  const base = "min-w-0 overflow-hidden break-words"
+  if (n === 1) return cn(base, "line-clamp-1")
+  if (n === 2) return cn(base, "line-clamp-2")
+  return cn(base, "line-clamp-3")
+}
+
+export function BoardNewCardPlaceholder({ position }: { position: "above" | "below" }) {
+  return (
+    <button
+      type="button"
+      className={cn(
+        "flex w-full items-center justify-center gap-1.5 rounded-lg border border-dashed border-border bg-background/50 py-2 text-xs font-medium text-muted-foreground transition-colors",
+        "hover:border-input hover:bg-muted/40 hover:text-foreground",
+        position === "above" ? "mb-2" : "mt-2",
+      )}
+    >
+      <i className="fa-light fa-plus text-xs" aria-hidden="true" />
+      New card
+    </button>
+  )
+}

package/src/components/data-views/data-row-list.tsx

@@ -0,0 +1,183 @@
+"use client"
+
+/**
+ * DataRowList — generic vertical-stack list view used by every hub's "list"
+ * tab (placements, team, compliance, sites, question-bank, …). Replaces the
+ * hand-rolled `<ul …flex-col gap-2 px-4 pb-8 pt-2 lg:px-6> {rows.map(<li>…)}`
+ * shell that was duplicated across `*-list-view.tsx` files.
+ *
+ * Composition over inheritance: callers provide a `renderRow(row)` that
+ * returns whatever ListPageBoardCard / link / chip-stack they need — this
+ * component owns the chrome (spacing, empty state, virtualization), not the
+ * row body.
+ *
+ * Auto-virtualises with `@tanstack/react-virtual` when the row count meets
+ * `virtualizeThreshold` (default 100). Disable by passing `0`.
+ */
+
+import * as React from "react"
+import { useWindowVirtualizer } from "@tanstack/react-virtual"
+import { cn } from "../../lib/utils"
+
+const DEFAULT_VIRTUALIZE_THRESHOLD = 100
+const DEFAULT_ESTIMATED_ROW_HEIGHT = 96
+const DEFAULT_OVERSCAN = 8
+
+export interface DataRowListProps<TRow> {
+  /** The filtered/sorted rows from `tableState.rows` (or wherever). */
+  rows: readonly TRow[]
+  /** Stable id used as the React `key` and (for virtualizer) the v-key. */
+  getRowId: (row: TRow, index: number) => string | number
+  /** Render the body of one row. Wrap with `<ListPageBoardCard layout="row">` etc. */
+  renderRow: (row: TRow, index: number) => React.ReactNode
+  /**
+   * Shown when `rows.length === 0`. Strings render as muted body copy; pass
+   * a `ReactNode` for richer empty states (illustration, CTA, etc.).
+   */
+  emptyState?: React.ReactNode
+  /**
+   * Auto-virtualise when `rows.length >= virtualizeThreshold`. Default 100.
+   * Pass `0` to never virtualise (preserves predictable layout for short
+   * lists like dashboards / pinned tabs).
+   */
+  virtualizeThreshold?: number
+  /** Hint for the virtualizer; clamps to measured size after first paint. */
+  estimatedRowHeight?: number
+  /** Override the default container padding / gap if needed. */
+  className?: string
+  /** Override the per-row `<li>` className (e.g. tighter spacing). */
+  rowClassName?: string
+  /** `aria-label` for the `<ul>` (screen-reader name for the list). */
+  ariaLabel?: string
+}
+
+const DEFAULT_OUTER_CLASS = "flex list-none flex-col gap-2 px-4 pb-8 pt-2 lg:px-6"
+
+export function DataRowList<TRow>(props: DataRowListProps<TRow>) {
+  const {
+    rows,
+    getRowId,
+    renderRow,
+    emptyState,
+    virtualizeThreshold = DEFAULT_VIRTUALIZE_THRESHOLD,
+    estimatedRowHeight = DEFAULT_ESTIMATED_ROW_HEIGHT,
+    className,
+    rowClassName,
+    ariaLabel,
+  } = props
+
+  if (rows.length === 0) {
+    if (emptyState == null) return null
+    if (typeof emptyState === "string") {
+      return (
+        <div className="px-4 py-16 text-center lg:px-6">
+          <p className="text-sm text-muted-foreground">{emptyState}</p>
+        </div>
+      )
+    }
+    return <div className="px-4 py-16 text-center lg:px-6">{emptyState}</div>
+  }
+
+  if (virtualizeThreshold > 0 && rows.length >= virtualizeThreshold) {
+    return (
+      <DataRowListVirtualized
+        rows={rows}
+        getRowId={getRowId}
+        renderRow={renderRow}
+        estimatedRowHeight={estimatedRowHeight}
+        className={className}
+        rowClassName={rowClassName}
+        ariaLabel={ariaLabel}
+      />
+    )
+  }
+
+  return (
+    <ul aria-label={ariaLabel} className={cn(DEFAULT_OUTER_CLASS, className)}>
+      {rows.map((row, i) => (
+        <li key={getRowId(row, i)} className={rowClassName}>
+          {renderRow(row, i)}
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Virtualised variant — keeps the DOM short on long lists (e.g. 1000+ rows).
+// Uses `useWindowVirtualizer` so the page scroll drives row recycling; this
+// is the right tool for hub-level lists (not nested-scroll containers).
+// ─────────────────────────────────────────────────────────────────────────────
+
+function DataRowListVirtualized<TRow>({
+  rows,
+  getRowId,
+  renderRow,
+  estimatedRowHeight,
+  className,
+  rowClassName,
+  ariaLabel,
+}: {
+  rows: readonly TRow[]
+  getRowId: (row: TRow, index: number) => string | number
+  renderRow: (row: TRow, index: number) => React.ReactNode
+  estimatedRowHeight: number
+  className?: string
+  rowClassName?: string
+  ariaLabel?: string
+}) {
+  const anchorRef = React.useRef<HTMLDivElement | null>(null)
+  // `scrollMargin` is read by the virtualizer during render, so it has to
+  // be state (not a ref). We measure with `useLayoutEffect` after the first
+  // paint and on resize so window-scroll math stays accurate when the page
+  // layout shifts (sidebar collapse, banner, etc.).
+  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])
+
+  const virtualizer = useWindowVirtualizer({
+    count: rows.length,
+    estimateSize: () => estimatedRowHeight,
+    overscan: DEFAULT_OVERSCAN,
+    scrollMargin,
+    getItemKey: i => String(getRowId(rows[i], i)),
+  })
+
+  const totalSize = virtualizer.getTotalSize()
+
+  return (
+    <div ref={anchorRef} className={cn("px-4 pb-8 pt-2 lg:px-6", className)}>
+      <ul
+        aria-label={ariaLabel}
+        className="relative m-0 w-full list-none p-0"
+        style={{ height: `${totalSize}px` }}
+      >
+        {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={cn("absolute left-0 top-0 w-full pb-2", rowClassName)}
+              style={{ transform: `translateY(${vr.start}px)` }}
+            >
+              {renderRow(row, vr.index)}
+            </li>
+          )
+        })}
+      </ul>
+    </div>
+  )
+}

package/src/components/data-views/finder-panel-view.tsx

@@ -0,0 +1,405 @@
+"use client"
+
+/**
+ * FinderPanelView — Miller-style 3-column split for list-page hubs.
+ *
+ * Visual shell matches Question bank panel (`ListPageTreeColumnHeader`, `LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS`,
+ * shared resizable handles) — see `list-page-split-hub-tokens.ts`.
+ */
+
+import * as React from "react"
+import { cn } from "../../lib/utils"
+import {
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+} from "../ui/resizable"
+import { ListPageTreeColumnHeader } from "./list-page-tree-column-header"
+import { ListPageSplitDetailsPlaceholder } from "./list-page-split-details-placeholder"
+import {
+  LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS,
+  LIST_PAGE_SPLIT_MILLER_DETAIL_PANEL_CLASS,
+  LIST_PAGE_SPLIT_RESIZABLE_HANDLE_CLASS,
+} from "./list-page-split-hub-tokens"
+
+export interface FinderGroup {
+  id: string
+  label: string
+  icon?: string
+  accent?: string
+  count: number
+}
+
+export interface FinderPanelViewProps<T> {
+  groups: FinderGroup[]
+  rows: T[]
+  getRowId: (row: T) => string | number
+  getRowGroupId: (row: T) => string
+  renderListRow: (row: T, isSelected: boolean) => React.ReactNode
+  renderDetail: (row: T) => React.ReactNode
+  emptyDetail?: React.ReactNode
+  emptyList?: React.ReactNode
+  defaultGroupId?: string
+  ariaLabel?: string
+  autoSaveId?: string
+  className?: string
+  style?: React.CSSProperties
+  onAddItem?: () => void
+  /**
+   * When true, omit outer margin, border, and card fill so the grid fits inside
+   * `ListPageSplitHubChrome` (shared split surface across hubs).
+   */
+  embedded?: boolean
+  /** Left column title (Question bank: “Categories”). */
+  groupsColumnTitle?: string
+  /** Middle column title; defaults from the active group label. */
+  getListColumnTitle?: (activeGroup: FinderGroup | undefined) => string
+}
+
+export function GroupsColumn({
+  groups,
+  selectedGroupId,
+  onSelect,
+  columnTitle,
+}: {
+  groups: FinderGroup[]
+  selectedGroupId: string
+  onSelect: (id: string) => void
+  columnTitle: string
+}) {
+  return (
+    <div className="flex h-full min-h-0 flex-col overflow-hidden">
+      <ListPageTreeColumnHeader title={columnTitle} />
+      <div
+        className="min-h-0 flex-1 overflow-y-auto py-1"
+        role="listbox"
+        aria-label="Group navigation"
+        aria-multiselectable="false"
+      >
+        {groups.map(group => {
+          const isSelected = group.id === selectedGroupId
+          return (
+            <div key={group.id} className="group flex items-center hover:bg-muted/50">
+              <button
+                type="button"
+                role="option"
+                aria-selected={isSelected}
+                onClick={() => onSelect(group.id)}
+                className={cn(
+                  "flex w-full flex-1 items-center gap-2 px-3 py-2 text-start text-sm transition-colors duration-75",
+                  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
+                  isSelected
+                    ? "bg-accent font-medium text-accent-foreground"
+                    : "text-foreground",
+                )}
+              >
+                {group.accent ? (
+                  <span className={cn("size-2 shrink-0 rounded-full", group.accent)} aria-hidden="true" />
+                ) : group.icon ? (
+                  <i
+                    className={cn(
+                      "fa-light shrink-0 text-xs",
+                      group.icon,
+                      isSelected ? "text-accent-foreground" : "text-muted-foreground",
+                    )}
+                    aria-hidden="true"
+                  />
+                ) : null}
+                <span className="min-w-0 flex-1 truncate leading-tight">{group.label}</span>
+                <span
+                  className={cn(
+                    "shrink-0 tabular-nums text-xs",
+                    isSelected ? "text-accent-foreground/80" : "text-muted-foreground",
+                  )}
+                >
+                  {group.count}
+                </span>
+              </button>
+            </div>
+          )
+        })}
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Horizontal scope strip (toolbar toggles). Optional: place above a hub body when you need
+ * status scope without consuming a Finder column.
+ */
+export function FinderGroupStrip({
+  groups,
+  selectedGroupId,
+  onSelect,
+  ariaLabel = "Scope",
+}: {
+  groups: FinderGroup[]
+  selectedGroupId: string
+  onSelect: (id: string) => void
+  ariaLabel?: string
+}) {
+  return (
+    <div
+      role="toolbar"
+      aria-label={ariaLabel}
+      className="flex min-h-10 flex-wrap items-center gap-1.5 border-b border-border bg-card px-2 py-2"
+    >
+      {groups.map(group => {
+        const isSelected = group.id === selectedGroupId
+        return (
+          <button
+            key={group.id}
+            type="button"
+            aria-pressed={isSelected}
+            onClick={() => onSelect(group.id)}
+            className={cn(
+              "inline-flex h-8 max-w-full min-w-0 shrink-0 items-center gap-1.5 rounded-lg border px-2.5 text-xs font-medium transition-colors",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+              isSelected
+                ? "border-brand/40 bg-accent text-accent-foreground"
+                : "border-transparent bg-background/80 text-foreground hover:bg-muted",
+            )}
+          >
+            {group.accent ? (
+              <span className={cn("size-2 shrink-0 rounded-full", group.accent)} aria-hidden="true" />
+            ) : group.icon ? (
+              <i
+                className={cn(
+                  "fa-light shrink-0 text-[11px]",
+                  group.icon,
+                  isSelected ? "text-accent-foreground" : "text-muted-foreground",
+                )}
+                aria-hidden="true"
+              />
+            ) : null}
+            <span className="min-w-0 truncate">{group.label}</span>
+            <span
+              className={cn(
+                "shrink-0 tabular-nums text-[11px]",
+                isSelected ? "text-accent-foreground/85" : "text-muted-foreground",
+              )}
+            >
+              {group.count}
+            </span>
+          </button>
+        )
+      })}
+    </div>
+  )
+}
+
+function ListColumn<T>({
+  rows,
+  getRowId,
+  selectedId,
+  renderListRow,
+  onSelect,
+  emptyList,
+  groupLabel,
+  columnTitle,
+  onAddItem,
+}: {
+  rows: T[]
+  getRowId: (row: T) => string | number
+  selectedId: string | number | null
+  renderListRow: (row: T, isSelected: boolean) => React.ReactNode
+  onSelect: (id: string | number) => void
+  emptyList?: React.ReactNode
+  groupLabel: string
+  columnTitle: string
+  onAddItem?: () => void
+}) {
+  return (
+    <div className="flex h-full min-h-0 flex-col overflow-hidden">
+      <ListPageTreeColumnHeader title={columnTitle} />
+      <div className="flex min-h-0 flex-1 flex-col">
+        <div
+          className="min-h-0 flex-1 overflow-y-auto py-1"
+          role="listbox"
+          aria-label={`${groupLabel} items`}
+          aria-multiselectable="false"
+        >
+          {rows.length === 0 ? (
+            <div className="flex flex-col items-center justify-center px-4 py-12 text-center text-sm text-muted-foreground">
+              {emptyList ?? <p>No items in this group.</p>}
+            </div>
+          ) : (
+            rows.map(row => {
+              const id = getRowId(row)
+              const isSelected = id === selectedId
+              return (
+                <div key={id} className="group flex items-center hover:bg-muted/50">
+                  <button
+                    type="button"
+                    role="option"
+                    aria-selected={isSelected}
+                    onClick={() => onSelect(id)}
+                    className={cn(
+                      "flex w-full flex-1 items-center gap-3 px-3 py-2 text-start text-sm transition-colors duration-75",
+                      "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
+                      isSelected
+                        ? "bg-accent font-medium text-accent-foreground"
+                        : "text-foreground",
+                    )}
+                  >
+                    {renderListRow(row, isSelected)}
+                  </button>
+                </div>
+              )
+            })
+          )}
+        </div>
+        {onAddItem ? (
+          <div className="flex shrink-0 items-center justify-center border-t border-border/50 px-2 py-1.5">
+            <button
+              type="button"
+              onClick={onAddItem}
+              className="flex h-8 w-8 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              aria-label={`Add item to ${groupLabel}`}
+            >
+              <i className="fa-light fa-plus text-xs" aria-hidden="true" />
+            </button>
+          </div>
+        ) : null}
+      </div>
+    </div>
+  )
+}
+
+function DetailColumn({ children }: { children: React.ReactNode }) {
+  return (
+    <div className={cn(LIST_PAGE_SPLIT_MILLER_DETAIL_PANEL_CLASS, "overflow-hidden")}>
+      <ListPageTreeColumnHeader title="Details" />
+      <div className="flex min-h-0 flex-1 flex-col overflow-hidden">{children}</div>
+    </div>
+  )
+}
+
+function DefaultEmptyDetail() {
+  return (
+    <ListPageSplitDetailsPlaceholder title="Nothing selected" />
+  )
+}
+
+export function FinderPanelView<T>({
+  groups,
+  rows,
+  getRowId,
+  getRowGroupId,
+  renderListRow,
+  renderDetail,
+  emptyDetail,
+  emptyList,
+  defaultGroupId,
+  ariaLabel = "List and details",
+  autoSaveId = "finder-panel-view",
+  className,
+  style,
+  onAddItem,
+  embedded = false,
+  groupsColumnTitle = "Categories",
+  getListColumnTitle = g => g?.label ?? "Items",
+}: FinderPanelViewProps<T>) {
+  const mergedStyle = React.useMemo<React.CSSProperties>(() => {
+    if (embedded) {
+      return { height: "100%", minHeight: 0, ...style }
+    }
+    return {
+      height: "calc(100vh - 280px)",
+      minHeight: 420,
+      ...style,
+    }
+  }, [embedded, style])
+  const firstGroupId = defaultGroupId ?? groups[0]?.id ?? "all"
+  const [selectedGroupId, setSelectedGroupId] = React.useState(firstGroupId)
+  const [selectedRowId, setSelectedRowId] = React.useState<string | number | null>(null)
+
+  const visibleRows = React.useMemo(() => {
+    if (selectedGroupId === "all") return rows
+    return rows.filter(r => getRowGroupId(r) === selectedGroupId)
+  }, [rows, selectedGroupId, getRowGroupId])
+
+  React.useEffect(() => {
+    setSelectedRowId(visibleRows[0] ? getRowId(visibleRows[0]) : null)
+  }, [selectedGroupId, visibleRows, getRowId])
+
+  React.useEffect(() => {
+    if (selectedRowId !== null && !visibleRows.find(r => getRowId(r) === selectedRowId)) {
+      setSelectedRowId(visibleRows[0] ? getRowId(visibleRows[0]) : null)
+    }
+  }, [visibleRows, selectedRowId, getRowId])
+
+  const selectedRow =
+    selectedRowId !== null
+      ? (visibleRows.find(r => getRowId(r) === selectedRowId) ?? null)
+      : null
+
+  const selectedGroup = groups.find(g => g.id === selectedGroupId)
+  const listColumnTitle = getListColumnTitle(selectedGroup)
+
+  return (
+    <div
+      className={cn(
+        embedded
+          ? "flex h-full min-h-0 flex-col overflow-hidden"
+          : "mx-4 mb-6 overflow-hidden rounded-xl border border-border bg-card lg:mx-6",
+        className,
+      )}
+      style={mergedStyle}
+      aria-label={ariaLabel}
+    >
+      <ResizablePanelGroup
+        id={String(autoSaveId)}
+        direction="horizontal"
+        className="h-full min-h-0 w-full flex-1"
+      >
+        <ResizablePanel
+          id="groups"
+          defaultSize="22%"
+          minSize="16%"
+          maxSize="32%"
+          className={LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS}
+        >
+          <GroupsColumn
+            columnTitle={groupsColumnTitle}
+            groups={groups}
+            selectedGroupId={selectedGroupId}
+            onSelect={id => setSelectedGroupId(id)}
+          />
+        </ResizablePanel>
+
+        <ResizableHandle withHandle className={LIST_PAGE_SPLIT_RESIZABLE_HANDLE_CLASS} />
+
+        <ResizablePanel
+          id="list"
+          defaultSize="34%"
+          minSize="22%"
+          maxSize="48%"
+          className={LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS}
+        >
+          <ListColumn
+            columnTitle={listColumnTitle}
+            rows={visibleRows}
+            getRowId={getRowId}
+            selectedId={selectedRowId}
+            renderListRow={renderListRow}
+            onSelect={id => setSelectedRowId(id)}
+            emptyList={emptyList}
+            groupLabel={selectedGroup?.label ?? "All"}
+            onAddItem={onAddItem}
+          />
+        </ResizablePanel>
+
+        <ResizableHandle withHandle className={LIST_PAGE_SPLIT_RESIZABLE_HANDLE_CLASS} />
+
+        <ResizablePanel id="detail" defaultSize="44%" minSize="30%" className={LIST_PAGE_SPLIT_MILLER_DETAIL_PANEL_CLASS}>
+          <DetailColumn>
+            {selectedRow
+              ? renderDetail(selectedRow)
+              : (emptyDetail ?? <DefaultEmptyDetail />)}
+          </DetailColumn>
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </div>
+  )
+}