@exxatdesignux/ui 0.2.19 → 0.3.0

package/src/components/data-views/list-page-board-card.tsx

@@ -0,0 +1,192 @@
+"use client"
+
+/**
+ * ListPageBoardCard — single board-card shell for all list hubs (Placements, Team, Compliance, …).
+ *
+ * Information hierarchy (top → bottom):
+ * 1. **Title row** — `ListPageBoardCardTitleRow` — primary label (`text-sm font-semibold`), optional `trailing` (`ListPageBoardCardAvatar` initials chip, same as Placements).
+ * 2. **Badge row** — `ListPageBoardCardBadgeRow` — optional status / tags (`flex-wrap`).
+ * 3. **Body** — `ListPageBoardCardBody` — primary facts: icon rows, two-line blocks (`BoardCardIconRow` / `BoardCardTwoLineBlock` from board-card-primitives).
+ * 4. **Secondary** — `ListPageBoardCardSecondary` — optional muted supporting line (`text-xs text-muted-foreground`).
+ *
+ * Styling matches **`BoardPlacementCard`**: `Card` `size="sm"`, ring, hover shadow, optional **new** ring accent.
+ *
+ * **Interaction:** Pass **`onClick`** (e.g. `BoardPlacementCard`) or **`interactive`** when the card is
+ * wrapped in `<Link>` / router navigation so hover/cursor match placement board tiles.
+ *
+ * **Layouts:**
+ * - **`stack`** (default) — kanban / grid tile: compose with `ListPageBoardCardHeader`, title row, body.
+ * - **`row`** — full-width list row: optional **`leading`**, **`children`** as main column, optional **`rowEnd`**.
+ *   Use **`rowContainerClassName`** for responsive shells (e.g. `flex-col sm:flex-row`).
+ */
+
+import * as React from "react"
+import { AvatarInitials } from "../ui/avatar"
+import { cn } from "../../lib/utils"
+import { Card, CardHeader, CardTitle } from "../ui/card"
+
+export type ListPageBoardCardLayout = "stack" | "row"
+
+export type ListPageBoardCardProps = {
+  layout?: ListPageBoardCardLayout
+  /** `row` only — avatar / icon column. */
+  leading?: React.ReactNode
+  /** `row` only — status + chevron, etc. */
+  rowEnd?: React.ReactNode
+  /**
+   * `row` only — flex shell for the card (default `flex flex-row items-start gap-3`).
+   * Use e.g. `flex flex-col gap-1 sm:flex-row sm:items-center sm:gap-4` for compliance-style rows.
+   */
+  rowContainerClassName?: string
+  /** Entire card is clickable (e.g. open detail) — enables pointer + hover shadow. */
+  onClick?: () => void
+  /**
+   * Same hover/cursor as `onClick` when the parent uses `<Link>` or `button` instead of Card click
+   * (avoids nested interactive targets and keeps keyboard focus on the link).
+   */
+  interactive?: boolean
+  className?: string
+  style?: React.CSSProperties
+  /** Subtle brand ring — e.g. newly created row. */
+  isNew?: boolean
+  children: React.ReactNode
+}
+
+export function ListPageBoardCard({
+  layout = "stack",
+  leading,
+  rowEnd,
+  rowContainerClassName,
+  onClick,
+  interactive = false,
+  className,
+  style,
+  isNew,
+  children,
+}: ListPageBoardCardProps) {
+  const isRow = layout === "row"
+  const isInteractive = Boolean(onClick) || interactive
+  const rowShell = rowContainerClassName ?? "flex flex-row items-start gap-3"
+
+  return (
+    <Card
+      size="sm"
+      className={cn(
+        "w-full min-w-0 transition-shadow",
+        !isRow && "gap-1",
+        isRow && cn("!gap-0", rowShell, "px-4 py-3"),
+        isInteractive && "cursor-pointer hover:shadow-md",
+        isNew && "ring-brand/30",
+        className,
+      )}
+      style={style}
+      onClick={onClick}
+    >
+      {isRow ? (
+        <>
+          {leading}
+          <div className="min-w-0 flex-1">{children}</div>
+          {rowEnd}
+        </>
+      ) : (
+        children
+      )}
+    </Card>
+  )
+}
+
+/** Preferred public name — same component as `ListPageBoardCard`. */
+export const HubRecordCard = ListPageBoardCard
+
+export function ListPageBoardCardHeader({
+  className,
+  children,
+}: {
+  className?: string
+  children: React.ReactNode
+}) {
+  return <CardHeader className={cn("gap-2 pb-2", className)}>{children}</CardHeader>
+}
+
+/**
+ * Level 1 — Primary title (dominant text on the card).
+ */
+export function ListPageBoardCardTitleRow({
+  title,
+  titleClassName,
+  trailing,
+}: {
+  title: React.ReactNode
+  /** Extra classes on the title (e.g. line-clamp from `lineClampClass`). */
+  titleClassName?: string
+  /** End-aligned: avatar, icon, etc. */
+  trailing?: React.ReactNode
+}) {
+  return (
+    <div className="flex min-w-0 items-start justify-between gap-2">
+      <div className="min-w-0 flex-1">
+        <CardTitle
+          className={cn(
+            "break-words text-sm font-semibold leading-snug text-foreground",
+            titleClassName,
+          )}
+        >
+          {title}
+        </CardTitle>
+      </div>
+      {trailing}
+    </div>
+  )
+}
+
+/** Initials avatar — Radix `Avatar` + `--avatar-initials-*` tokens (same as tables / placement board). */
+export function ListPageBoardCardAvatar({
+  initials,
+  className,
+}: {
+  initials: string
+  className?: string
+}) {
+  return (
+    <AvatarInitials
+      initials={initials}
+      className={cn("size-7 shrink-0 text-xs", className)}
+      fallbackClassName="text-xs"
+    />
+  )
+}
+
+/**
+ * Level 2 — Status / metadata chips (below title, above primary body).
+ */
+export function ListPageBoardCardBadgeRow({ children }: { children: React.ReactNode }) {
+  return <div className="flex min-w-0 flex-wrap items-center gap-1.5">{children}</div>
+}
+
+/**
+ * Level 3 — Main facts: compose with `BoardCardIconRow`, `BoardCardTwoLineBlock`, etc.
+ */
+export function ListPageBoardCardBody({
+  className,
+  children,
+}: {
+  className?: string
+  children: React.ReactNode
+}) {
+  return <div className={cn("flex flex-col gap-2", className)}>{children}</div>
+}
+
+/**
+ * Level 4 — Optional muted supporting line (caption, hint, extra context).
+ */
+export function ListPageBoardCardSecondary({
+  className,
+  children,
+}: {
+  className?: string
+  children: React.ReactNode
+}) {
+  return (
+    <p className={cn("text-xs text-muted-foreground leading-snug", className)}>{children}</p>
+  )
+}

package/src/components/data-views/list-page-board-template.tsx

@@ -0,0 +1,122 @@
+"use client"
+
+/**
+ * ListPageBoardTemplate — reusable kanban shell for list pages (Team, custom hubs).
+ *
+ * - Columns are defined with predicates; each row is placed in the **first** matching column.
+ * - Cards are rendered by the caller (`renderCard`) — compose **`ListPageBoardCard`** + primitives (`BoardCardTwoLineBlock`, etc.).
+ * - Placements keeps richer column headers (search, menus); this template is for simpler hubs.
+ *
+ * @see `docs/data-views-pattern.md` — board primitives
+ */
+
+import * as React from "react"
+import { cn } from "../../lib/utils"
+import { Badge } from "../ui/badge"
+import { BoardNewCardPlaceholder } from "./board-card-primitives"
+
+export type ListPageBoardColumnDef<T> = {
+  id: string
+  label: string
+  /** Shown beside the title on larger breakpoints */
+  description?: string
+  /** First matching column wins; columns should be mutually exclusive for most domains. */
+  filter: (row: T) => boolean
+}
+
+export type ListPageBoardTemplateProps<T> = {
+  columns: ListPageBoardColumnDef<T>[]
+  rows: T[]
+  getRowKey: (row: T) => string | number
+  renderCard: (row: T) => React.ReactNode
+  /** Tailwind classes for the count pill, keyed by column `id` */
+  columnCountBadgeClassName?: Record<string, string>
+  /** Copy when a column has no rows */
+  emptyColumnLabel?: string
+}
+
+function ListPageBoardColumnHeader({
+  label,
+  description,
+  count,
+  badgeClassName,
+}: {
+  label: string
+  description?: string
+  count: number
+  badgeClassName?: string
+}) {
+  return (
+    <div className="flex items-center justify-between border-b border-border px-3 py-2.5">
+      <div className="flex min-w-0 items-center gap-2">
+        <span className="truncate text-sm font-semibold text-foreground">{label}</span>
+        {description ? (
+          <span className="hidden text-xs text-muted-foreground sm:inline">{description}</span>
+        ) : null}
+      </div>
+      <Badge
+        variant="outline"
+        className={cn(
+          "inline-flex h-6 min-w-6 shrink-0 items-center justify-center border-0 bg-muted/70 px-2 text-xs font-semibold tabular-nums text-foreground",
+          badgeClassName,
+        )}
+        aria-label={`${count} ${count === 1 ? "item" : "items"}`}
+      >
+        {count}
+      </Badge>
+    </div>
+  )
+}
+
+export function ListPageBoardTemplate<T>({
+  columns,
+  rows,
+  getRowKey,
+  renderCard,
+  columnCountBadgeClassName = {},
+  emptyColumnLabel = "No items",
+}: ListPageBoardTemplateProps<T>) {
+  const grouped = React.useMemo(() => {
+    const map: Record<string, T[]> = {}
+    for (const col of columns) map[col.id] = []
+    for (const row of rows) {
+      for (const col of columns) {
+        if (col.filter(row)) {
+          map[col.id].push(row)
+          break
+        }
+      }
+    }
+    return map
+  }, [columns, rows])
+
+  return (
+    <div className="flex min-h-0 flex-1 gap-3 overflow-x-auto px-4 pb-6 pt-2 lg:px-6">
+      {columns.map(col => (
+        <div
+          key={col.id}
+          className="flex w-72 shrink-0 flex-col overflow-hidden rounded-xl border border-border bg-muted/30"
+        >
+          <ListPageBoardColumnHeader
+            label={col.label}
+            description={col.description}
+            count={grouped[col.id]?.length ?? 0}
+            badgeClassName={columnCountBadgeClassName[col.id]}
+          />
+
+          <div className="flex flex-1 flex-col gap-2 overflow-y-auto p-2">
+            <BoardNewCardPlaceholder position="above" />
+
+            {(grouped[col.id]?.length ?? 0) === 0 ? (
+              <p className="py-6 text-center text-xs text-muted-foreground">{emptyColumnLabel}</p>
+            ) : (
+              grouped[col.id]!.map(row => <React.Fragment key={String(getRowKey(row))}>{renderCard(row)}</React.Fragment>)
+            )}
+
+            <BoardNewCardPlaceholder position="below" />
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/components/data-views/list-page-connected-view-body.tsx

@@ -0,0 +1,66 @@
+"use client"
+
+/**
+ * Switches list-hub view bodies by `DataListViewRenderKind`.
+ * Hubs pass one renderer per kind they support; missing kinds show a clear empty state
+ * (never silently fall through to dashboard).
+ */
+
+import * as React from "react"
+import type { DataListViewType } from "../../lib/data-list-view"
+import {
+  dataListViewDefinition,
+  dataListViewLabel,
+  getDataListViewRenderKind,
+  type DataListViewRenderKind,
+} from "../../lib/data-list-view-registry"
+
+export type ListPageConnectedViewRenderers = Partial<
+  Record<DataListViewRenderKind, React.ReactNode | (() => React.ReactNode)>
+>
+
+export interface ListPageConnectedViewBodyProps {
+  view: DataListViewType
+  /** Human-readable hub name for the not-configured state. */
+  hubLabel?: string
+  renderers: ListPageConnectedViewRenderers
+}
+
+function resolveRenderer(node: React.ReactNode | (() => React.ReactNode) | undefined) {
+  if (node == null) return null
+  return typeof node === "function" ? node() : node
+}
+
+export function ListPageViewNotConfigured({
+  view,
+  hubLabel = "This hub",
+}: {
+  view: DataListViewType
+  hubLabel?: string
+}) {
+  const label = dataListViewLabel(view)
+  return (
+    <div
+      className="flex flex-1 items-center justify-center px-4 py-12 text-center text-sm text-muted-foreground"
+      role="status"
+    >
+      {hubLabel} does not implement {label}. Add a renderer for{" "}
+      <span className="font-medium text-foreground">{dataListViewDefinition(view).renderKind}</span>{" "}
+      in this hub&apos;s table component, or remove the view from{" "}
+      <code className="rounded bg-muted px-1 py-0.5 text-xs">supportedViewTypes</code>.
+    </div>
+  )
+}
+
+export function ListPageConnectedViewBody({
+  view,
+  hubLabel,
+  renderers,
+}: ListPageConnectedViewBodyProps) {
+  const kind = getDataListViewRenderKind(view)
+  const body = resolveRenderer(renderers[kind])
+  if (body == null) {
+    return <ListPageViewNotConfigured view={view} hubLabel={hubLabel} />
+  }
+  return <>{body}</>
+}

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

@@ -0,0 +1,39 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../lib/utils"
+
+export interface ListPageSplitDetailsPlaceholderProps {
+  title?: string
+  description?: React.ReactNode
+  className?: string
+}
+
+/**
+ * Empty right pane for split hubs — flat `bg-card` to match Miller / tree columns.
+ */
+export function ListPageSplitDetailsPlaceholder({
+  title = "Nothing selected",
+  description,
+  className,
+}: ListPageSplitDetailsPlaceholderProps) {
+  return (
+    <div
+      className={cn(
+        "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-card">
+        <i
+          className="fa-light fa-sidebar text-[1.65rem] leading-none text-muted-foreground/70"
+          aria-hidden="true"
+        />
+      </div>
+      <p className="text-sm font-medium text-foreground">{title}</p>
+      {description ? (
+        <div className="mt-1.5 max-w-[16rem] text-xs leading-relaxed text-muted-foreground">{description}</div>
+      ) : null}
+    </div>
+  )
+}

package/src/components/data-views/list-page-split-hub-chrome.tsx

@@ -0,0 +1,60 @@
+"use client"
+
+/**
+ * Shared **centered** chrome for list-hub split surfaces (finder / tree / multi-column explorers).
+ *
+ * Composes `ListPageViewFrame` (gutter + max width) with a single bordered card + fixed viewport
+ * height so panel and tree views match across routes (`AGENTS.md` §4.5).
+ */
+
+import * as React from "react"
+import { cn } from "../../lib/utils"
+import {
+  ListPageViewFrame,
+  LIST_PAGE_VIEW_FRAME_GUTTER,
+  LIST_PAGE_VIEW_FRAME_MAX_WIDE,
+} from "../ui/list-page-view-frame"
+
+/** Default height band for split views under `ListPageTemplate` + toolbar. */
+export const LIST_PAGE_SPLIT_HUB_HEIGHT_STYLE: React.CSSProperties = {
+  height: "calc(100vh - 280px)",
+  minHeight: 420,
+}
+
+const SURFACE_CLASS =
+  "flex min-h-0 flex-1 flex-col overflow-hidden rounded-xl border border-border bg-card"
+
+export interface ListPageSplitHubChromeProps {
+  children: React.ReactNode
+  "aria-label"?: string
+  gutterClassName?: string
+  maxWidthClassName?: string
+  /** Override default split viewport height / min-height */
+  surfaceStyle?: React.CSSProperties
+  surfaceClassName?: string
+}
+
+export function ListPageSplitHubChrome({
+  children,
+  "aria-label": ariaLabel,
+  gutterClassName = LIST_PAGE_VIEW_FRAME_GUTTER,
+  maxWidthClassName = LIST_PAGE_VIEW_FRAME_MAX_WIDE,
+  surfaceStyle,
+  surfaceClassName,
+}: ListPageSplitHubChromeProps) {
+  return (
+    <ListPageViewFrame
+      gutterClassName={gutterClassName}
+      maxWidthClassName={maxWidthClassName}
+      className="flex min-h-0 flex-1 flex-col"
+    >
+      <div
+        className={cn(SURFACE_CLASS, surfaceClassName)}
+        style={{ ...LIST_PAGE_SPLIT_HUB_HEIGHT_STYLE, ...surfaceStyle }}
+        aria-label={ariaLabel}
+      >
+        {children}
+      </div>
+    </ListPageViewFrame>
+  )
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Shared layout tokens for list-hub split surfaces (Miller columns, tree + details).
+ * Keeps Question bank panel / tree and generic `FinderPanelView` visually aligned.
+ */
+
+/** `ResizableHandle` between miller / tree columns — matches Question bank panel. */
+export const LIST_PAGE_SPLIT_RESIZABLE_HANDLE_CLASS =
+  "w-1 bg-border/40 hover:bg-brand/20 transition-colors"
+
+/** 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-card"
+
+/** Right-hand inspector / detail column shell. */
+export const LIST_PAGE_SPLIT_MILLER_DETAIL_PANEL_CLASS =
+  "flex min-h-0 min-w-0 flex-col bg-card"

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

@@ -0,0 +1,31 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../lib/utils"
+
+export interface ListPageTreeColumnHeaderProps {
+  title: string
+  /** Right side (e.g. icon buttons) — keep touch targets ≥ 24px */
+  trailing?: React.ReactNode
+  className?: string
+}
+
+/**
+ * Shared left-column header for tree / outline surfaces — matches Question bank “Questions” bar.
+ */
+export function ListPageTreeColumnHeader({
+  title,
+  trailing,
+  className,
+}: ListPageTreeColumnHeaderProps) {
+  return (
+    <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 ? (
+          <div className="flex shrink-0 items-center gap-0.5">{trailing}</div>
+        ) : null}
+      </div>
+    </div>
+  )
+}

package/src/components/data-views/list-page-tree-panel-shell.tsx

@@ -0,0 +1,91 @@
+"use client"
+
+/**
+ * Generic two-pane layout: scrollable **tree / outline** column + **details** column,
+ * with persisted split sizes (`ResizablePanelGroup` `id`) and shared **split hub chrome**
+ * (`ListPageSplitHubChrome`) so tree views match finder / folder panels across the app.
+ *
+ * Domain hubs pass `tree` and `details` nodes; this module stays entity-agnostic.
+ */
+
+import * as React from "react"
+import {
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+} from "../ui/resizable"
+import { ListPageSplitHubChrome } from "./list-page-split-hub-chrome"
+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"
+import {
+  LIST_PAGE_VIEW_FRAME_GUTTER,
+  LIST_PAGE_VIEW_FRAME_MAX_WIDE,
+} from "../ui/list-page-view-frame"
+
+export interface ListPageTreePanelShellProps {
+  /** Stable id for `react-resizable-panels` layout persistence (per hub / route). */
+  resizableGroupId: string
+  /** Left column (tree chrome + body). */
+  tree: React.ReactNode
+  /** Right column (detail / inspector). */
+  details: React.ReactNode
+  /** Accessible name for the split surface, e.g. “Curriculum tree and details”. */
+  ariaLabel: string
+  treePanelId?: string
+  detailsPanelId?: string
+  treeDefaultSize?: string
+  treeMinSize?: string
+  treeMaxSize?: string
+  detailsDefaultSize?: string
+  detailsMinSize?: string
+  gutterClassName?: string
+  maxWidthClassName?: string
+}
+
+export function ListPageTreePanelShell({
+  resizableGroupId,
+  tree,
+  details,
+  ariaLabel,
+  treePanelId = "tree",
+  detailsPanelId = "details",
+  treeDefaultSize = "40%",
+  treeMinSize = "20%",
+  treeMaxSize = "60%",
+  detailsDefaultSize = "60%",
+  detailsMinSize = "30%",
+  gutterClassName = LIST_PAGE_VIEW_FRAME_GUTTER,
+  maxWidthClassName = LIST_PAGE_VIEW_FRAME_MAX_WIDE,
+}: ListPageTreePanelShellProps) {
+  return (
+    <ListPageSplitHubChrome
+      aria-label={ariaLabel}
+      gutterClassName={gutterClassName}
+      maxWidthClassName={maxWidthClassName}
+    >
+      <ResizablePanelGroup id={resizableGroupId} direction="horizontal" className="h-full min-h-0 w-full flex-1">
+        <ResizablePanel
+          id={treePanelId}
+          defaultSize={treeDefaultSize}
+          minSize={treeMinSize}
+          maxSize={treeMaxSize}
+          className={LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS}
+        >
+          {tree}
+        </ResizablePanel>
+        <ResizableHandle withHandle className={LIST_PAGE_SPLIT_RESIZABLE_HANDLE_CLASS} />
+        <ResizablePanel
+          id={detailsPanelId}
+          defaultSize={detailsDefaultSize}
+          minSize={detailsMinSize}
+          className={LIST_PAGE_SPLIT_MILLER_DETAIL_PANEL_CLASS}
+        >
+          {details}
+        </ResizablePanel>
+      </ResizablePanelGroup>
+    </ListPageSplitHubChrome>
+  )
+}