@proteos/ui 0.31.0

package/src/components/data-table/cells.tsx

@@ -0,0 +1,165 @@
+import type { AnchorHTMLAttributes, MouseEvent, ReactNode } from 'react'
+
+import { cn } from '../../lib/cn'
+
+/* =========================================================================
+   Cell helpers — attribute-driven only.
+   These exist because RecordTable auto-generates columns from
+   Entity.attributes and dispatches the renderer at runtime by AttributeType.
+   Bespoke per-domain cells (status pills, lane pairs, deltas, avatars+name)
+   are NOT here — the consumer composes those inline via `column.cell`,
+   matching the shadcn/TanStack idiom. The lib already exports Badge / Avatar
+   / etc. for those compositions.
+   ========================================================================= */
+
+/* ---------- DateCell ----------------------------------------------------- */
+
+export type DateCellProps = {
+  value: string | number | Date | null | undefined
+  locale?: string
+  options?: Intl.DateTimeFormatOptions
+  fallback?: ReactNode
+  className?: string
+}
+
+const DEFAULT_DATE_OPTIONS: Intl.DateTimeFormatOptions = {
+  year: 'numeric',
+  month: 'short',
+  day: '2-digit',
+}
+
+export function DateCell({
+  value,
+  locale,
+  options = DEFAULT_DATE_OPTIONS,
+  fallback = '—',
+  className,
+}: DateCellProps) {
+  if (value == null || value === '') return <span className={className}>{fallback}</span>
+  const date = value instanceof Date ? value : new Date(value)
+  if (Number.isNaN(date.getTime())) return <span className={className}>{fallback}</span>
+  return <span className={className}>{date.toLocaleDateString(locale, options)}</span>
+}
+
+/* ---------- DateTimeCell ------------------------------------------------- */
+
+export type DateTimeCellProps = DateCellProps
+
+const DEFAULT_DATETIME_OPTIONS: Intl.DateTimeFormatOptions = {
+  year: 'numeric',
+  month: 'short',
+  day: '2-digit',
+  hour: '2-digit',
+  minute: '2-digit',
+  hour12: false,
+}
+
+export function DateTimeCell({
+  value,
+  locale,
+  options = DEFAULT_DATETIME_OPTIONS,
+  fallback = '—',
+  className,
+}: DateTimeCellProps) {
+  if (value == null || value === '') return <span className={className}>{fallback}</span>
+  const date = value instanceof Date ? value : new Date(value)
+  if (Number.isNaN(date.getTime())) return <span className={className}>{fallback}</span>
+  return <span className={className}>{date.toLocaleString(locale, options)}</span>
+}
+
+/* ---------- BooleanCell -------------------------------------------------- */
+
+export type BooleanCellProps = {
+  value: boolean | null | undefined
+  className?: string
+}
+
+export function BooleanCell({ value, className }: BooleanCellProps) {
+  if (value === true) {
+    return (
+      <span aria-label="true" className={cn('text-success', className)}>
+        <CheckIcon />
+      </span>
+    )
+  }
+  if (value === false) {
+    return (
+      <span aria-label="false" className={cn('text-ink-4', className)}>
+        <MinusIcon />
+      </span>
+    )
+  }
+  return <span className={cn('text-ink-4', className)}>—</span>
+}
+
+function CheckIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+      <path
+        d="M2.5 7.5 L5.5 10.5 L11.5 4"
+        stroke="currentColor"
+        strokeWidth="1.6"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}
+
+function MinusIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+      <path d="M3 7 L11 7" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+/* ---------- TruncateCell ------------------------------------------------- */
+
+export type TruncateCellProps = {
+  value: ReactNode
+  title?: string
+  className?: string
+}
+
+/**
+ * The parent TableCell already clips with `overflow-hidden text-ellipsis`,
+ * so this just adds a `title` attribute for the native tooltip when the
+ * value is a string.
+ */
+export function TruncateCell({ value, title, className }: TruncateCellProps) {
+  const tooltip = title ?? (typeof value === 'string' ? value : undefined)
+  return (
+    <span className={cn('truncate min-w-0', className)} title={tooltip}>
+      {value ?? '—'}
+    </span>
+  )
+}
+
+/* ---------- LinkCell ----------------------------------------------------- */
+
+export type LinkCellProps = AnchorHTMLAttributes<HTMLAnchorElement> & {
+  children: ReactNode
+}
+
+/**
+ * An anchor that stops click propagation so a row-click handler on the
+ * parent <TableRow> doesn't fire alongside the link navigation.
+ */
+export function LinkCell({ children, onClick, className, ...props }: LinkCellProps) {
+  return (
+    <a
+      {...props}
+      onClick={(e: MouseEvent<HTMLAnchorElement>) => {
+        e.stopPropagation()
+        onClick?.(e)
+      }}
+      className={cn(
+        'text-ink underline decoration-rule underline-offset-2 hover:decoration-ink',
+        className,
+      )}
+    >
+      {children}
+    </a>
+  )
+}

package/src/components/data-table/data-table.stories.tsx

@@ -0,0 +1,371 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import type { ColumnDef, SortingState } from '@tanstack/react-table'
+import { useEffect, useMemo, useRef, useState } from 'react'
+
+import { Badge } from '../badge'
+import { DataTable, type InfiniteQueryLike } from './data-table'
+
+/* =========================================================================
+   DataTable stories — exercise the virtualized + infinite-scroll surface
+   in isolation. The fake infinite query is local to this file so stories
+   don't depend on the demo route.
+   ========================================================================= */
+
+const meta: Meta<typeof DataTable> = {
+  title: 'Components/DataTable',
+  component: DataTable,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div className="bg-surface p-6 h-[640px] flex">
+        <Story />
+      </div>
+    ),
+  ],
+}
+export default meta
+
+type Story = StoryObj<typeof DataTable>
+
+/* ---------- Synthetic dataset ------------------------------------------- */
+
+type Row = {
+  id: string
+  lane: string
+  carrier: string
+  status: 'in transit' | 'dispatching' | 'picked up' | 'delivered' | 'past due' | 'quoted'
+  statusVariant: 'active' | 'warning' | 'success' | 'danger' | 'neutral'
+  rate: number
+  weight: number
+}
+
+const ORIGINS = ['Long Beach', 'Newark', 'Houston', 'Savannah', 'Oakland', 'Seattle', 'Charleston']
+const DESTS = ['Columbus', 'Reno', 'Allentown', 'Indianapolis', 'Salt Lake City', 'Portland']
+const CARRIERS = [
+  'North Star',
+  'Pacific Drayage',
+  'Atlas Cartage',
+  'Cardinal Freight',
+  'Granite Hauling',
+]
+const STATUSES: ReadonlyArray<{ key: Row['status']; variant: Row['statusVariant'] }> = [
+  { key: 'in transit', variant: 'active' },
+  { key: 'dispatching', variant: 'warning' },
+  { key: 'picked up', variant: 'active' },
+  { key: 'delivered', variant: 'success' },
+  { key: 'past due', variant: 'danger' },
+  { key: 'quoted', variant: 'neutral' },
+]
+
+function mulberry32(seed: number): () => number {
+  let a = seed
+  return () => {
+    a |= 0
+    a = (a + 0x6d2b79f5) | 0
+    let t = Math.imul(a ^ (a >>> 15), 1 | a)
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+function buildDataset(count: number): Row[] {
+  const rng = mulberry32(7)
+  const out = new Array<Row>(count)
+  for (let i = 0; i < count; i++) {
+    const status = STATUSES[Math.floor(rng() * STATUSES.length)] as (typeof STATUSES)[number]
+    out[i] = {
+      id: `SH-${(10000 + i).toString().padStart(5, '0')}`,
+      lane: `${ORIGINS[Math.floor(rng() * ORIGINS.length)]} → ${DESTS[Math.floor(rng() * DESTS.length)]}`,
+      carrier: CARRIERS[Math.floor(rng() * CARRIERS.length)] as string,
+      status: status.key,
+      statusVariant: status.variant,
+      rate: 800 + Math.floor(rng() * 7200),
+      weight: 1200 + Math.floor(rng() * 42000),
+    }
+  }
+  return out
+}
+
+const fmtMoney = (n: number) => `$${n.toLocaleString('en-US')}`
+const fmtWeight = (n: number) => `${n.toLocaleString('en-US')} lb`
+
+const columns: ColumnDef<Row>[] = [
+  {
+    id: 'id',
+    accessorKey: 'id',
+    header: 'Shipment',
+    size: 110,
+    meta: { align: 'left', mono: true, ink: true },
+  },
+  {
+    id: 'lane',
+    accessorKey: 'lane',
+    header: 'Lane',
+    size: 280,
+    meta: { align: 'left' },
+  },
+  {
+    id: 'carrier',
+    accessorKey: 'carrier',
+    header: 'Carrier',
+    size: 180,
+    meta: { align: 'left' },
+  },
+  {
+    id: 'status',
+    accessorKey: 'status',
+    header: 'Status',
+    size: 130,
+    meta: { align: 'left' },
+    cell: ({ row }) => <Badge variant={row.original.statusVariant}>{row.original.status}</Badge>,
+  },
+  {
+    id: 'weight',
+    accessorKey: 'weight',
+    header: 'Weight',
+    size: 110,
+    meta: { align: 'right', mono: true },
+    cell: ({ row }) => fmtWeight(row.original.weight),
+  },
+  {
+    id: 'rate',
+    accessorKey: 'rate',
+    header: 'Rate',
+    size: 110,
+    meta: { align: 'right', mono: true },
+    cell: ({ row }) => fmtMoney(row.original.rate),
+  },
+]
+
+/* ---------- Fake infinite query ----------------------------------------- */
+
+const PAGE_SIZE = 60
+
+type FakeOptions = {
+  total: number
+  initialDelayMs?: number
+  pageDelayMs?: number
+  sorting?: SortingState
+  errorAfterPages?: number
+}
+
+function useFakeInfiniteQuery({
+  total,
+  initialDelayMs = 220,
+  pageDelayMs = 320,
+  sorting = [],
+  errorAfterPages,
+}: FakeOptions): InfiniteQueryLike<Row> {
+  const dataset = useMemo(() => buildDataset(total), [total])
+
+  const sorted = useMemo<Row[]>(() => {
+    if (sorting.length === 0) return dataset
+    const [first] = sorting
+    if (!first) return dataset
+    const { id: key, desc } = first
+    const mult = desc ? -1 : 1
+    return dataset.slice().sort((a, b) => {
+      const av = a[key as keyof Row]
+      const bv = b[key as keyof Row]
+      if (typeof av === 'number' && typeof bv === 'number') return (av - bv) * mult
+      return String(av).localeCompare(String(bv)) * mult
+    })
+  }, [dataset, sorting])
+
+  const [pagesLoaded, setPagesLoaded] = useState(1)
+  const [isFetchingNextPage, setIsFetchingNextPage] = useState(false)
+  const [isInitialLoading, setIsInitialLoading] = useState(true)
+  const [error, setError] = useState<Error | null>(null)
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    setPagesLoaded(1)
+    setIsInitialLoading(true)
+    setError(null)
+    const t = setTimeout(() => setIsInitialLoading(false), initialDelayMs)
+    return () => clearTimeout(t)
+  }, [sorting, initialDelayMs])
+
+  const totalPages = Math.max(1, Math.ceil(sorted.length / PAGE_SIZE))
+  const hasNextPage = pagesLoaded < totalPages
+
+  const pages = useMemo(
+    () =>
+      Array.from({ length: pagesLoaded }, (_, i) => ({
+        data: sorted.slice(i * PAGE_SIZE, (i + 1) * PAGE_SIZE),
+        meta: { items_total: sorted.length },
+      })),
+    [sorted, pagesLoaded],
+  )
+
+  return {
+    data: { pages },
+    isLoading: isInitialLoading,
+    isFetchingNextPage,
+    hasNextPage,
+    error,
+    fetchNextPage: () => {
+      if (!hasNextPage || isFetchingNextPage) return
+      setIsFetchingNextPage(true)
+      if (timer.current) clearTimeout(timer.current)
+      timer.current = setTimeout(() => {
+        if (errorAfterPages !== undefined && pagesLoaded + 1 > errorAfterPages) {
+          setError(new Error('Network unreachable. Could not fetch the next page.'))
+          setIsFetchingNextPage(false)
+          return
+        }
+        setPagesLoaded((n) => n + 1)
+        setIsFetchingNextPage(false)
+      }, pageDelayMs)
+    },
+  }
+}
+
+/* ---------- Stories ------------------------------------------------------ */
+
+export const Default: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => {
+    const [sorting, setSorting] = useState<SortingState>([{ id: 'id', desc: false }])
+    const query = useFakeInfiniteQuery({ total: 50_000, sorting })
+    return (
+      <DataTable<Row>
+        ariaLabel="Shipments"
+        query={query}
+        columns={columns}
+        sorting={sorting}
+        onSortingChange={setSorting}
+      />
+    )
+  },
+}
+
+export const InitialLoading: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => {
+    // Long initialDelay keeps the skeleton on screen.
+    const query = useFakeInfiniteQuery({ total: 200, initialDelayMs: 100_000 })
+    return <DataTable<Row> ariaLabel="Loading shipments" query={query} columns={columns} />
+  },
+}
+
+export const LoadingMore: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => {
+    // Stretchy page delay so the loader bar stays on screen mid-scroll.
+    const [sorting, setSorting] = useState<SortingState>([])
+    const query = useFakeInfiniteQuery({ total: 5_000, sorting, pageDelayMs: 100_000 })
+    return (
+      <DataTable<Row>
+        ariaLabel="Shipments — loading next page"
+        query={query}
+        columns={columns}
+        sorting={sorting}
+        onSortingChange={setSorting}
+      />
+    )
+  },
+}
+
+export const EndOfList: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => {
+    // Small dataset whose first page already covers everything — end marker
+    // appears as soon as the initial load resolves.
+    const query = useFakeInfiniteQuery({ total: 12 })
+    return <DataTable<Row> ariaLabel="Shipments — end" query={query} columns={columns} />
+  },
+}
+
+export const Empty: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => {
+    const query = useFakeInfiniteQuery({ total: 0 })
+    return <DataTable<Row> ariaLabel="Shipments — empty" query={query} columns={columns} />
+  },
+}
+
+export const ErrorState: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => {
+    // Returns no rows + an error so the error state replaces the body.
+    const query: InfiniteQueryLike<Row> = {
+      data: undefined,
+      isLoading: false,
+      isFetchingNextPage: false,
+      hasNextPage: false,
+      error: new Error('Network unreachable. Could not fetch shipments.'),
+      fetchNextPage: () => {
+        /* noop */
+      },
+    }
+    return <DataTable<Row> ariaLabel="Shipments — error" query={query} columns={columns} />
+  },
+}
+
+export const ReorderableColumns: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => {
+    const [orderedColumns, setOrderedColumns] = useState<ColumnDef<Row>[]>(columns)
+    const [sorting, setSorting] = useState<SortingState>([])
+    const [lastEvent, setLastEvent] = useState<string | null>(null)
+    const query = useFakeInfiniteQuery({ total: 800, sorting })
+    return (
+      <div className="flex flex-col gap-3 flex-1">
+        <div className="font-mono text-[11px] text-ink-3">
+          {lastEvent ?? 'drag a column header to reorder · click × to remove'}
+        </div>
+        <DataTable<Row>
+          ariaLabel="Shipments — reorderable + removable columns"
+          query={query}
+          columns={orderedColumns}
+          sorting={sorting}
+          onSortingChange={setSorting}
+          enableColumnReordering
+          enableColumnRemoval
+          onReorderColumn={({ id, toIndex }) => {
+            setLastEvent(`reorder: ${id} → index ${toIndex}`)
+            setOrderedColumns((prev) => {
+              const idx = prev.findIndex((c) => c.id === id)
+              if (idx === -1) return prev
+              const next = prev.slice()
+              const [moved] = next.splice(idx, 1)
+              if (!moved) return prev
+              next.splice(toIndex, 0, moved)
+              return next
+            })
+          }}
+          onRemoveColumn={(id) => {
+            setLastEvent(`remove: ${id}`)
+            setOrderedColumns((prev) => prev.filter((c) => c.id !== id))
+          }}
+        />
+      </div>
+    )
+  },
+}
+
+export const RowClickable: Story = {
+  parameters: { controls: { hideNoControlsWarning: true } },
+  render: () => {
+    const [sorting, setSorting] = useState<SortingState>([])
+    const [lastClicked, setLastClicked] = useState<string | null>(null)
+    const query = useFakeInfiniteQuery({ total: 800, sorting })
+    return (
+      <div className="flex flex-col gap-3 flex-1">
+        <div className="font-mono text-[11px] text-ink-3">
+          {lastClicked ? `last clicked: ${lastClicked}` : 'click a row'}
+        </div>
+        <DataTable<Row>
+          ariaLabel="Shipments — clickable rows"
+          query={query}
+          columns={columns}
+          sorting={sorting}
+          onSortingChange={setSorting}
+          onRowClick={(row) => setLastClicked(row.id)}
+        />
+      </div>
+    )
+  },
+}