@exxatdesignux/ui 0.2.16 → 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/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"
@@ -103,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/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/export-drawer.tsx

@@ -145,7 +145,7 @@ export function ExportDrawer({
         side="right"
         showCloseButton={false}
         showOverlay={false}
-        className="z-[60] w-80 sm:max-w-80 p-0 gap-0 flex flex-col border border-border shadow-xl rounded-xl overflow-hidden"
+        className="z-[80] w-80 sm:max-w-80 p-0 gap-0 flex flex-col border border-border shadow-xl rounded-xl overflow-hidden"
         style={{ top: "0.5rem", bottom: "0.5rem", right: "0.5rem", height: "calc(100vh - 1rem)" }}
       >
         {/* Header */}