@usefragments/ui 1.0.0

package/src/components/DataTable/DataTable.module.scss

@@ -0,0 +1,429 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+.wrapper {
+  --fui-data-table-bg: var(--fui-table-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
+  --fui-data-table-header-bg: var(--fui-table-header-bg, color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 5%, transparent));
+
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+// Caption for accessibility
+.caption {
+  padding: var(--fui-space-3, $fui-space-3) 0;
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  text-align: left;
+  caption-side: top;
+}
+
+// Visually hidden caption (screen readers only)
+.captionHidden {
+  @include visually-hidden;
+}
+
+// Size variants
+.sm {
+  .th,
+  .td {
+    padding: var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
+    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  }
+}
+
+.md {
+  .th,
+  .td {
+    padding: var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
+    font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  }
+}
+
+// Header
+.thead {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+}
+
+.headerRow {
+  border-bottom: 1px solid var(--fui-table-header-border, var(--fui-border, #{$fui-border}));
+}
+
+.th {
+  text-align: left;
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  white-space: nowrap;
+  vertical-align: middle;
+  user-select: none;
+  // Opaque so the sticky header doesn't let rows bleed through on scroll,
+  // while inheriting the table surface instead of forcing the page background.
+  background: var(--fui-data-table-header-bg);
+
+  &:first-child {
+    border-top-left-radius: var(--fui-radius-md, $fui-radius-md);
+  }
+
+  &:last-child {
+    border-top-right-radius: var(--fui-radius-md, $fui-radius-md);
+  }
+}
+
+.headerContent {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+}
+
+// Sortable header cell (for focus styles)
+.thSortable {
+  padding: 0;
+}
+
+.sortButton {
+  @include button-reset;
+  @include interactive-base;
+
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--fui-space-1, $fui-space-1);
+  width: 100%;
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
+  color: inherit;
+  text-align: left;
+  transition: color var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover {
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+}
+
+.sortIndicator {
+  display: inline-flex;
+  align-items: center;
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+  flex-shrink: 0;
+
+  svg {
+    width: var(--fui-icon-xs, $fui-icon-xs);
+    height: var(--fui-icon-xs, $fui-icon-xs);
+  }
+  // Quiet by default; the neutral glyph appears on hover/focus, and the
+  // active direction arrow stays visible (revealed via aria-sort below).
+  opacity: 0;
+  transition: opacity var(--fui-transition-fast, $fui-transition-fast);
+
+  .sortButton:hover & {
+    color: var(--fui-text-secondary, $fui-text-secondary);
+    opacity: 1;
+  }
+
+  .sortButton:focus-visible & {
+    opacity: 1;
+  }
+}
+
+.th[aria-sort="ascending"] .sortIndicator,
+.th[aria-sort="descending"] .sortIndicator {
+  opacity: 1;
+}
+
+// Body
+.tbody {
+}
+
+.row {
+  border-bottom: 1px solid var(--fui-table-border, var(--fui-border, #{$fui-border}));
+  transition: background-color var(--fui-transition-fast, $fui-transition-fast);
+
+  &:last-child {
+    border-bottom: none;
+  }
+
+  &:hover {
+    background-color: var(--fui-table-row-hover-bg, var(--fui-bg-hover, #{$fui-bg-hover}));
+  }
+}
+
+.clickable {
+  cursor: pointer;
+
+  &:hover {
+    background-color: var(--fui-table-row-hover-bg, var(--fui-bg-hover, #{$fui-bg-hover}));
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+
+  &:active {
+    background-color: var(--fui-table-row-active-bg, var(--fui-bg-active, #{$fui-bg-active}));
+  }
+}
+
+.selected {
+  background-color: var(--fui-table-row-selected-bg, color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 8%, transparent));
+  box-shadow: inset 1px 0 0 var(--fui-table-row-selected-border, var(--fui-border-strong, #{$fui-border-strong}));
+
+  &:hover {
+    background-color: var(--fui-table-row-selected-bg, color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 10%, transparent));
+  }
+}
+
+.td {
+  color: var(--fui-text-primary, $fui-text-primary);
+  vertical-align: middle;
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+// Striped rows
+.striped {
+  .row:nth-child(even) {
+    background-color: var(--fui-table-subrow-bg, var(--fui-bg-subtle, #{$fui-bg-subtle}));
+  }
+
+  // Hover and selected override stripe
+  .clickable:hover {
+    background-color: var(--fui-table-row-hover-bg, var(--fui-bg-hover, #{$fui-bg-hover}));
+  }
+
+  .clickable:active {
+    background-color: var(--fui-table-row-active-bg, var(--fui-bg-active, #{$fui-bg-active}));
+  }
+
+  .selected {
+    background-color: var(--fui-table-row-selected-bg, color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 8%, transparent));
+
+    &:hover {
+      background-color: var(--fui-table-row-selected-bg, color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 10%, transparent));
+    }
+  }
+}
+
+// Bordered
+.bordered {
+  border: 1px solid var(--fui-table-border, var(--fui-border, #{$fui-border}));
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  background: var(--fui-data-table-bg);
+  overflow: hidden;
+}
+
+// Fixed layout for explicit column sizes
+.fixedLayout {
+  table-layout: fixed;
+}
+
+// ============================================
+// Density presets — condensed / regular / relaxed
+// ============================================
+
+// Fixed density rails. Off the 7px spacing grid by design (no row-height
+// token set exists yet); kept as literals so the three steps stay an even
+// 40/48/56 ladder. Snap to row-height tokens once they land.
+.densityCondensed .row {
+  height: 40px;
+}
+
+.densityRegular .row {
+  height: 48px;
+}
+
+.densityRelaxed .row {
+  height: 56px;
+}
+
+// ============================================
+// Per-column alignment (numbers align right)
+// ============================================
+
+.th[data-align="right"],
+.td[data-align="right"] {
+  text-align: right;
+}
+
+.th[data-align="right"] .headerContent,
+.th[data-align="right"] .sortButton {
+  justify-content: flex-end;
+}
+
+.th[data-align="center"],
+.td[data-align="center"] {
+  text-align: center;
+}
+
+.th[data-align="center"] .headerContent,
+.th[data-align="center"] .sortButton {
+  justify-content: center;
+}
+
+// ============================================
+// Truncation (single line + ellipsis; pairs with a column width)
+// ============================================
+
+.truncate {
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+// ============================================
+// Loading skeleton
+// ============================================
+
+.skeletonBar {
+  display: block;
+  height: 10px;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  background: linear-gradient(
+    90deg,
+    color-mix(in srgb, currentColor 8%, transparent) 25%,
+    color-mix(in srgb, currentColor 14%, transparent) 50%,
+    color-mix(in srgb, currentColor 8%, transparent) 75%
+  );
+  background-size: 200% 100%;
+  animation: dataTableShimmer 1.4s ease-in-out infinite;
+}
+
+@keyframes dataTableShimmer {
+  from {
+    background-position: 200% 0;
+  }
+  to {
+    background-position: -200% 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .skeletonBar {
+    animation: none;
+  }
+
+  .sortIndicator {
+    transition: none;
+  }
+}
+
+// Checkbox column
+.checkboxCell {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+// Expandable rows
+.expandCell {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+}
+
+.expandButton {
+  @include button-reset;
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--fui-icon-lg, $fui-icon-lg);
+  height: var(--fui-icon-lg, $fui-icon-lg);
+  flex-shrink: 0;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+  transition:
+    color var(--fui-transition-fast, $fui-transition-fast),
+    background-color var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover {
+    color: var(--fui-text-primary, $fui-text-primary);
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+.expandIcon {
+  width: var(--fui-icon-xs, $fui-icon-xs);
+  height: var(--fui-icon-xs, $fui-icon-xs);
+  transition: transform var(--fui-transition-fast, $fui-transition-fast);
+}
+
+.expandIconOpen {
+  transform: rotate(90deg);
+}
+
+.subRow {
+  background-color: var(--fui-table-subrow-bg, var(--fui-bg-subtle, #{$fui-bg-subtle}));
+
+  &:hover {
+    background-color: var(--fui-table-row-hover-bg, var(--fui-bg-hover, #{$fui-bg-hover}));
+  }
+}
+
+// Empty state
+.emptyState {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--fui-space-12, $fui-space-12) var(--fui-space-6, $fui-space-6);
+}
+
+.emptyMessage {
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+}
+
+// Responsive: allow horizontal scroll on small screens
+@include below-sm {
+  .wrapper {
+    margin-left: calc(-1 * var(--fui-space-4, $fui-space-4));
+    margin-right: calc(-1 * var(--fui-space-4, $fui-space-4));
+    padding-left: var(--fui-space-4, $fui-space-4);
+    padding-right: var(--fui-space-4, $fui-space-4);
+  }
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .headerRow {
+    border-bottom-width: 2px;
+  }
+
+  .row {
+    border-bottom-width: 2px;
+  }
+
+  .sortButton:focus-visible {
+    outline-width: 3px;
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .row {
+    transition: none;
+  }
+
+  .sortButton {
+    transition: none;
+  }
+}

package/src/components/DataTable/DataTable.stories.tsx

@@ -0,0 +1,129 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { DataTable } from '.';
+import type { ColumnDef, DataTableProps } from '.';
+
+/**
+ * Data table with sorting, selection, and column management, powered by
+ * TanStack Table. Requires `columns` and `data`; supports sortable headers,
+ * checkbox selection, clickable rows, striped/bordered styling, and sizes.
+ */
+
+type User = {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+  status: string;
+};
+
+const columns: ColumnDef<User>[] = [
+  { accessorKey: 'name', header: 'Name' },
+  { accessorKey: 'email', header: 'Email' },
+  { accessorKey: 'role', header: 'Role' },
+  { accessorKey: 'status', header: 'Status' },
+];
+
+const data: User[] = [
+  {
+    id: '1',
+    name: 'Alice Johnson',
+    email: 'alice@example.com',
+    role: 'Admin',
+    status: 'active',
+  },
+  {
+    id: '2',
+    name: 'Bob Chen',
+    email: 'bob@example.com',
+    role: 'Member',
+    status: 'pending',
+  },
+  {
+    id: '3',
+    name: 'Carol Smith',
+    email: 'carol@example.com',
+    role: 'Member',
+    status: 'active',
+  },
+];
+
+const meta = {
+  title: 'Display/DataTable',
+  component: DataTable,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Data table with sorting, selection, and column management.',
+      },
+    },
+  },
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['sm', 'md'],
+      description: 'Table density',
+    },
+    sortable: { control: 'boolean', description: 'Enable column sorting' },
+    selectable: { control: 'boolean', description: 'Enable row selection' },
+    showCheckbox: {
+      control: 'boolean',
+      description: 'Show checkbox column (requires selectable)',
+    },
+    striped: { control: 'boolean', description: 'Alternating row backgrounds' },
+    bordered: { control: 'boolean', description: 'Bordered container' },
+    captionHidden: { control: 'boolean' },
+  },
+  args: { columns, data, size: 'md' },
+} satisfies Meta<DataTableProps<User>>;
+
+export default meta;
+
+type Story = StoryObj<DataTableProps<User>>;
+
+export const Default: Story = {
+  args: { columns, data },
+};
+
+export const Sortable: Story = {
+  args: {
+    columns,
+    data,
+    sortable: true,
+    bordered: true,
+    caption: 'Team members',
+    captionHidden: true,
+  },
+};
+
+export const CheckboxSelection: Story = {
+  args: {
+    columns,
+    data,
+    selectable: true,
+    showCheckbox: true,
+    bordered: true,
+    getRowId: (row: User) => row.id,
+  },
+};
+
+export const Striped: Story = {
+  args: { columns, data, striped: true, size: 'sm' },
+};
+
+export const ClickableRows: Story = {
+  args: {
+    columns,
+    data,
+    onRowClick: (row: User) => alert(row.name),
+    size: 'sm',
+  },
+};
+
+export const Empty: Story = {
+  args: {
+    columns,
+    data: [],
+    emptyMessage: 'No users match your search criteria',
+  },
+};

package/src/components/DataTable/DataTable.support.tsx

@@ -0,0 +1,75 @@
+import * as React from "react";
+
+// Skeleton placeholder rows shown while `loading`. Keeps the table's
+// column rhythm so the populated state doesn't jump on arrival.
+export function DataTableSkeletonRows({
+  rowCount,
+  columnCount,
+  rowClassName,
+  cellClassName,
+  barClassName,
+}: {
+  rowCount: number;
+  columnCount: number;
+  rowClassName: string;
+  cellClassName: string;
+  barClassName: string;
+}) {
+  return (
+    <>
+      {Array.from({ length: rowCount }).map((_, r) => (
+        <tr key={r} className={rowClassName} aria-hidden="true">
+          {Array.from({ length: columnCount }).map((_, c) => (
+            <td key={c} className={cellClassName}>
+              <span className={barClassName} style={{ width: `${45 + ((r + c) % 4) * 14}%` }} />
+            </td>
+          ))}
+        </tr>
+      ))}
+    </>
+  );
+}
+
+const NAV_KEYS = new Set(["ArrowDown", "ArrowUp", "Home", "End"]);
+
+// Roving arrow-key navigation across focusable (clickable) rows. Enter /
+// Space activation is handled per-row by the table itself. This only moves
+// focus; it never hijacks keys when focus is outside the table body.
+export function useArrowKeyRowNav(
+  tableRef: React.RefObject<HTMLTableElement | null>,
+  enabled: boolean
+) {
+  React.useEffect(() => {
+    const table = tableRef.current;
+    if (!enabled || !table) return;
+
+    function onKeyDown(event: KeyboardEvent) {
+      if (!NAV_KEYS.has(event.key)) return;
+      const host = tableRef.current;
+      if (!host) return;
+      const rows = Array.from(host.querySelectorAll<HTMLElement>("tbody tr[tabindex]"));
+      if (rows.length === 0) return;
+
+      const active = document.activeElement;
+      const current = rows.findIndex((row) => row === active || row.contains(active));
+      // Only take over the arrow keys when focus is already on a row.
+      if (current === -1) return;
+
+      event.preventDefault();
+      let next = current;
+      if (event.key === "ArrowDown") {
+        next = Math.min(rows.length - 1, current + 1);
+      } else if (event.key === "ArrowUp") {
+        next = Math.max(0, current - 1);
+      } else if (event.key === "Home") {
+        next = 0;
+      } else if (event.key === "End") {
+        next = rows.length - 1;
+      }
+      rows[next]?.focus();
+    }
+
+    table.addEventListener("keydown", onKeyDown);
+    return () => table.removeEventListener("keydown", onKeyDown);
+  }, [tableRef, enabled]);
+}