@exxatdesignux/ui 0.2.15 → 0.2.17

package/template/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/template/components/data-views/finder-panel-view.tsx

@@ -3,7 +3,7 @@
 /**
  * FinderPanelView — Miller-style 3-column split for list-page hubs.
  *
- * Visual shell matches Question bank panel (`ListPageTreeColumnHeader`, `bg-muted/15` columns,
+ * Visual shell matches Question bank panel (`ListPageTreeColumnHeader`, `LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS`,
  * shared resizable handles) — see `list-page-split-hub-tokens.ts`.
  */
 
@@ -142,7 +142,7 @@ export function FinderGroupStrip({
     <div
       role="toolbar"
       aria-label={ariaLabel}
-      className="flex min-h-10 flex-wrap items-center gap-1.5 border-b border-border bg-muted/15 px-2 py-2"
+      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

package/template/components/data-views/index.ts

@@ -1,14 +1,14 @@
 /**
  * Central exports for list-page data surfaces and shared view chrome.
  *
- * **Pattern:** `ListPageTemplate` + `DataListTable` — one `useTableState`, one toolbar,
+ * **Pattern:** `ListPageTemplate` + `PlacementsTable` (or any hub-specific `*-table.tsx`) — one `useTableState`, one toolbar,
  * table | list | board | dashboard from the same component (`AGENTS.md` §4, `docs/data-views-pattern.md`).
  *
  * **View UI:** `ViewSegmentedControl` matches the template’s views toolbar (`bg-muted/60` pills).
  */
 
-export { DataListTable } from "@/components/data-list-table"
-export type { DataListTableProps, DataListTableHandle } from "@/components/data-list-table"
+export { PlacementsTable } from "@/components/placements-table"
+export type { PlacementsTableProps, PlacementsTableHandle } from "@/components/placements-table"
 export type { PlacementLifecycleTabId } from "@/lib/placement-lifecycle"
 export type { DataListViewType } from "@/lib/data-list-view"
 export { DATA_LIST_VIEW_TILES, dataListViewIcon, dataListViewLabel } from "@/lib/data-list-view"
@@ -47,6 +47,25 @@ export {
   type ListPageTreeColumnHeaderProps,
 } from "@/components/data-views/list-page-tree-column-header"
 
+/** VS Code–style outline tree chrome — mirrors shadcn `SidebarMenuSub` (see module doc). */
+export {
+  OutlineTreeCollapsibleContentRail,
+  OutlineTreeLeafButton,
+  OutlineTreeMenu,
+  OutlineTreeMenuItem,
+  OutlineTreeSub,
+  OutlineTreeSubItem,
+  OUTLINE_TREE_COLLAPSIBLE_CONTENT_RAIL_CLASS,
+  OUTLINE_TREE_CHEVRON_GUIDE_SPACER_CLASS,
+  OUTLINE_TREE_SUB_ROW_SHIFT_CLASS,
+  type OutlineTreeGuideLayout,
+  type OutlineTreeLeafButtonProps,
+  type OutlineTreeSurface,
+} from "@/components/data-views/outline-tree-menu"
+
+export { QuestionBankFolderTreeBranch } from "@/components/data-views/question-bank-folder-tree-branch"
+export type { QuestionBankFolderTreeBranchProps } from "@/components/data-views/question-bank-folder-tree-branch"
+
 export {
   LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS,
   LIST_PAGE_SPLIT_MILLER_DETAIL_PANEL_CLASS,
@@ -84,6 +103,10 @@ export {
 /** Generic folder icon-grid — reusable across all list hubs. */
 export { FolderGridView, type FolderGridViewProps } from "@/components/data-views/folder-grid-view"
 
+/** Generic vertical row list — used by every hub's "list" tab. Composes
+ *  `ListPageBoardCard layout="row"` via a `renderRow` prop. */
+export { DataRowList, type DataRowListProps } from "@/components/data-views/data-row-list"
+
 
 /** Unified hub tile + list row surface — see `list-page-board-card.tsx`. */
 export {

package/template/components/data-views/list-page-split-details-placeholder.tsx

@@ -10,7 +10,7 @@ export interface ListPageSplitDetailsPlaceholderProps {
 }
 
 /**
- * Empty right pane for split hubs — matches Question bank tree “Nothing selected”.
+ * Empty right pane for split hubs — flat `bg-card` to match Miller / tree columns.
  */
 export function ListPageSplitDetailsPlaceholder({
   title = "Nothing selected",
@@ -20,11 +20,11 @@ export function ListPageSplitDetailsPlaceholder({
   return (
     <div
       className={cn(
-        "flex h-full min-h-0 flex-col items-center justify-center bg-gradient-to-b from-muted/25 via-card to-card px-6 py-10 text-center",
+        "flex h-full min-h-0 flex-col items-center justify-center bg-card px-6 py-10 text-center",
         className,
       )}
     >
-      <div className="mb-4 flex size-14 items-center justify-center rounded-2xl border border-dashed border-border/70 bg-muted/25">
+      <div className="mb-4 flex size-14 items-center justify-center rounded-2xl border border-dashed border-border/70 bg-card">
         <i
           className="fa-light fa-sidebar text-[1.65rem] leading-none text-muted-foreground/70"
           aria-hidden="true"

package/template/components/data-views/list-page-split-hub-tokens.ts

@@ -9,7 +9,7 @@ export const LIST_PAGE_SPLIT_RESIZABLE_HANDLE_CLASS =
 
 /** Primary column stack (scope list, folder list, record list, …). */
 export const LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS =
-  "flex min-h-0 min-w-0 flex-col bg-muted/15"
+  "flex min-h-0 min-w-0 flex-col bg-card"
 
 /** Right-hand inspector / detail column shell. */
 export const LIST_PAGE_SPLIT_MILLER_DETAIL_PANEL_CLASS =

package/template/components/data-views/list-page-tree-column-header.tsx

@@ -19,7 +19,7 @@ export function ListPageTreeColumnHeader({
   className,
 }: ListPageTreeColumnHeaderProps) {
   return (
-    <div className={cn("shrink-0 border-b border-border/50 bg-muted/10 px-3 py-2", className)}>
+    <div className={cn("shrink-0 border-b border-border/50 bg-card px-3 py-2", className)}>
       <div className="flex h-9 items-center justify-between gap-2">
         <h3 className="min-w-0 flex-1 truncate text-sm font-medium text-foreground">{title}</h3>
         {trailing ? (

package/template/components/data-views/os-folder-glyph.tsx

@@ -91,12 +91,20 @@ export function OsFolderGlyph({
       aria-label={!decorative ? label : undefined}
       aria-hidden={decorative ? true : undefined}
     >
+      {/* Static SVG — `next/image` can't optimize SVGs without
+          `dangerouslyAllowSVG`, so we stay on plain <img> but add the same
+          loading/decoding hints `next/image` would. Folder grids render many
+          of these at once; lazy-loading lets the browser skip off-screen
+          glyphs until they scroll near the viewport. */}
+      {/* eslint-disable-next-line @next/next/no-img-element -- SVG; next/image can't optimize without dangerouslyAllowSVG */}
       <img
         src={OS_FOLDER_GLYPH_SRC}
         alt=""
         width={240}
         height={240}
         draggable={false}
+        loading="lazy"
+        decoding="async"
         className={cn(
           "h-full w-full object-contain",
           "transition-[filter] duration-200",

package/template/components/data-views/outline-tree-menu.tsx

@@ -0,0 +1,157 @@
+"use client"
+
+/**
+ * Central outline-tree chrome — mirrors shadcn/ui **Sidebar** file-tree structure
+ * (`SidebarMenu` → `SidebarMenuItem` + `Collapsible` → `SidebarMenuSub` → rows) without
+ * coupling to `useSidebar`.
+ *
+ * - **`guideLayout="inset"`** — same rhythm as `SidebarMenuSub` (`mx-3.5` + `translate-x-px`).
+ * - **`guideLayout="chevronRail"`** — use with **`OutlineTreeCollapsibleContentRail`**: a **`w-6`**
+ *   spacer lines up the vertical guide with the **horizontal center** of a **`size-8`** chevron
+ *   when the folder row uses **`px-2`** (8px padding + 16px half of 32px chevron hit target).
+ *
+ * @see packages/ui/src/components/ui/sidebar.tsx — `SidebarMenuSub`, `SidebarMenuSubItem`
+ */
+
+import * as React from "react"
+import { CollapsibleContent } from "@/components/ui/collapsible"
+import { cn } from "@/lib/utils"
+
+export type OutlineTreeSurface = "sidebar" | "panel"
+
+export type OutlineTreeGuideLayout = "inset" | "chevronRail"
+
+const outlineTreeSubInsetClass: Record<OutlineTreeSurface, string> = {
+  sidebar:
+    "mx-3.5 flex min-w-0 list-none translate-x-px flex-col gap-1 border-s border-sidebar-border px-2.5 py-0.5 rtl:-translate-x-px",
+  panel:
+    "mx-3.5 flex min-w-0 list-none translate-x-px flex-col gap-1 border-s border-border/60 px-2.5 py-0.5 rtl:-translate-x-px",
+}
+
+const outlineTreeSubChevronRailClass: Record<OutlineTreeSurface, string> = {
+  sidebar:
+    "flex min-w-0 flex-1 list-none flex-col gap-1 border-s border-sidebar-border py-0.5 ps-2.5",
+  panel: "flex min-w-0 flex-1 list-none flex-col gap-1 border-s border-border/60 py-0.5 ps-2.5",
+}
+
+/** Pull row content onto the guide line — matches `SidebarMenuSubButton` horizontal nudge (inset layout only). */
+export const OUTLINE_TREE_SUB_ROW_SHIFT_CLASS = "-translate-x-px rtl:translate-x-px"
+
+/** `CollapsibleContent` row: spacer width = `px-2` (8px) + half of `size-8` chevron (16px) → guide under chevron center. */
+export const OUTLINE_TREE_COLLAPSIBLE_CONTENT_RAIL_CLASS = "flex min-w-0 w-full"
+
+/** Spacer column — keep in sync with folder row `px-2` + `size-8` chevron. */
+export const OUTLINE_TREE_CHEVRON_GUIDE_SPACER_CLASS = "w-6 shrink-0"
+
+/** Wrap `OutlineTreeSub` with `guideLayout="chevronRail"` so the vertical border meets the chevron center. */
+export function OutlineTreeCollapsibleContentRail({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof CollapsibleContent>) {
+  return (
+    <CollapsibleContent
+      className={cn(OUTLINE_TREE_COLLAPSIBLE_CONTENT_RAIL_CLASS, className)}
+      {...props}
+    >
+      <div className={OUTLINE_TREE_CHEVRON_GUIDE_SPACER_CLASS} aria-hidden />
+      {children}
+    </CollapsibleContent>
+  )
+}
+
+/** Nested list under a folder — vertical guide + indent. */
+export function OutlineTreeSub({
+  surface = "panel",
+  guideLayout = "inset",
+  className,
+  ...props
+}: React.ComponentProps<"ul"> & {
+  surface?: OutlineTreeSurface
+  guideLayout?: OutlineTreeGuideLayout
+}) {
+  return (
+    <ul
+      data-slot="outline-tree-sub"
+      data-guide-layout={guideLayout}
+      className={cn(
+        guideLayout === "inset" && outlineTreeSubInsetClass[surface],
+        guideLayout === "chevronRail" && outlineTreeSubChevronRailClass[surface],
+        className,
+      )}
+      {...props}
+    />
+  )
+}
+
+/** Root or nested branch list — matches `SidebarMenu` spacing. */
+export function OutlineTreeMenu({ className, ...props }: React.ComponentProps<"ul">) {
+  return (
+    <ul
+      data-slot="outline-tree-menu"
+      className={cn("flex w-full min-w-0 list-none flex-col gap-0", className)}
+      {...props}
+    />
+  )
+}
+
+/** Expandable folder row wrapper — matches `SidebarMenuItem`. */
+export function OutlineTreeMenuItem({ className, ...props }: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="outline-tree-menu-item"
+      className={cn("group/menu-item relative min-w-0 w-full list-none", className)}
+      {...props}
+    />
+  )
+}
+
+/** Leaf / nested row inside `OutlineTreeSub` — matches `SidebarMenuSubItem`. */
+export function OutlineTreeSubItem({ className, ...props }: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="outline-tree-sub-item"
+      className={cn("group/menu-sub-item relative min-w-0 w-full list-none", className)}
+      {...props}
+    />
+  )
+}
+
+export interface OutlineTreeLeafButtonProps extends React.ComponentProps<"button"> {
+  surface?: OutlineTreeSurface
+  isActive?: boolean
+  /** Inset `OutlineTreeSub` only — nudge like `SidebarMenuSubButton`. Ignored when parent uses `chevronRail`. */
+  subGuideAlign?: boolean
+}
+
+/** Selectable leaf row (file / terminal row) — `SidebarMenuSubButton`–aligned rhythm. */
+export function OutlineTreeLeafButton({
+  surface = "panel",
+  isActive = false,
+  subGuideAlign = false,
+  className,
+  ...props
+}: OutlineTreeLeafButtonProps) {
+  return (
+    <button
+      type="button"
+      data-active={isActive || undefined}
+      className={cn(
+        "flex min-h-8 w-full min-w-0 cursor-pointer select-none items-center gap-2 overflow-hidden rounded-md px-2 text-start text-sm outline-none ring-ring focus-visible:ring-2 focus-visible:ring-inset [&>svg]:size-4 [&>svg]:shrink-0",
+        subGuideAlign && OUTLINE_TREE_SUB_ROW_SHIFT_CLASS,
+        surface === "panel" &&
+          cn(
+            "text-foreground hover:bg-muted/50",
+            isActive && "bg-accent font-medium text-accent-foreground",
+          ),
+        surface === "sidebar" &&
+          cn(
+            "text-sidebar-foreground hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
+            isActive && "bg-sidebar-accent font-medium text-sidebar-accent-foreground",
+          ),
+        className,
+      )}
+      {...props}
+    />
+  )
+}