@exxatdesignux/ui 0.0.5 → 0.0.7

package/template/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/template/components/data-views/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Central exports for list-page data surfaces and shared view chrome.
+ *
+ * **Pattern:** `ListPageTemplate` + `DataListTable` — 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 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"
+
+export {
+  ListPageTemplate,
+  type ViewTab,
+  type ViewType,
+} from "@/components/templates/list-page"
+
+export {
+  ViewSegmentedControl,
+  viewSegmentedToolbarClass,
+  viewSegmentedButtonClass,
+  type ViewSegmentOption,
+} from "@/components/ui/view-segmented-control"
+
+/** Unified hub tile + list row surface — see `list-page-board-card.tsx`. */
+export {
+  HubRecordCard,
+  ListPageBoardCard,
+  ListPageBoardCardAvatar,
+  ListPageBoardCardBadgeRow,
+  ListPageBoardCardBody,
+  ListPageBoardCardHeader,
+  ListPageBoardCardSecondary,
+  ListPageBoardCardTitleRow,
+  type ListPageBoardCardLayout,
+  type ListPageBoardCardProps,
+} from "@/components/data-views/list-page-board-card"

package/template/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 "@/components/ui/avatar"
+import { cn } from "@/lib/utils"
+import { Card, CardHeader, CardTitle } from "@/components/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/template/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 "@/components/ui/badge"
+import { BoardNewCardPlaceholder } from "@/components/data-views/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>
+  )
+}