@roadlittledawn/docs-design-system-react 0.8.0 → 0.9.1

package/dist/components/Table.d.ts

@@ -0,0 +1,81 @@
+import React from 'react';
+type SortDirection = 'asc' | 'desc' | null;
+export interface TableProps {
+    /** Children — typically TableHead and TableBody */
+    children: React.ReactNode;
+    /**
+     * Visual variant of the table.
+     * `"default"` renders all borders; `"borderless"` shows only row top/bottom borders.
+     */
+    variant?: 'default' | 'borderless';
+    /**
+     * When true the thead sticks to the top of the scroll container while scrolling.
+     * Pair with the `style` prop (e.g. `style={{ maxHeight: '400px' }}`) to constrain
+     * the table height so that the header can stick.
+     */
+    stickyHeader?: boolean;
+    /**
+     * Background color applied to the header row.
+     * Accepts any valid CSS color value (e.g. `"#f0f4ff"`, `"var(--my-color)"`).
+     * Overrides the default token value.
+     */
+    headerBg?: string;
+    /**
+     * Callback fired when a sortable column header is clicked.
+     * Useful for server-side sorting. Receives the column key and new direction.
+     */
+    onSort?: (key: string, direction: SortDirection) => void;
+    /** Additional CSS classes applied to the outer wrapper */
+    className?: string;
+    /**
+     * Inline styles applied to the outer wrapper.
+     * Use `maxHeight` here to constrain the table height when `stickyHeader` is true.
+     */
+    style?: React.CSSProperties;
+}
+export declare function Table({ children, variant, stickyHeader, headerBg, onSort, className, style, }: TableProps): import("react/jsx-runtime").JSX.Element;
+export interface TableHeadProps {
+    /** Header rows — typically one TableRow containing TableHeaderCells */
+    children: React.ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function TableHead({ children, className }: TableHeadProps): import("react/jsx-runtime").JSX.Element;
+export interface TableBodyProps {
+    /** Table body rows */
+    children: React.ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function TableBody({ children, className }: TableBodyProps): import("react/jsx-runtime").JSX.Element;
+export interface TableRowProps {
+    /** Cells in this row */
+    children: React.ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function TableRow({ children, className }: TableRowProps): import("react/jsx-runtime").JSX.Element;
+export interface TableHeaderCellProps {
+    /** Cell content / column label */
+    children: React.ReactNode;
+    /**
+     * Unique key used to identify this column when sorting.
+     * When provided the column becomes sortable.
+     */
+    sortKey?: string;
+    /** Text alignment of the column */
+    align?: 'left' | 'center' | 'right';
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function TableHeaderCell({ children, sortKey, align, className, }: TableHeaderCellProps): import("react/jsx-runtime").JSX.Element;
+export interface TableCellProps {
+    /** Cell content */
+    children?: React.ReactNode;
+    /** Text alignment */
+    align?: 'left' | 'center' | 'right';
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function TableCell({ children, align, className }: TableCellProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Table.js

@@ -0,0 +1,93 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, createContext, useContext } from 'react';
+var TableContext = createContext(null);
+function useTableContext() {
+    var ctx = useContext(TableContext);
+    if (!ctx) {
+        throw new Error('Table sub-components must be used within a Table component');
+    }
+    return ctx;
+}
+export function Table(_a) {
+    var children = _a.children, _b = _a.variant, variant = _b === void 0 ? 'default' : _b, _c = _a.stickyHeader, stickyHeader = _c === void 0 ? false : _c, headerBg = _a.headerBg, onSort = _a.onSort, _d = _a.className, className = _d === void 0 ? '' : _d, style = _a.style;
+    var _e = useState(null), sortKey = _e[0], setSortKey = _e[1];
+    var _f = useState(null), sortDirection = _f[0], setSortDirection = _f[1];
+    var handleSort = function (key) {
+        var nextDirection;
+        if (sortKey === key) {
+            nextDirection = sortDirection === 'asc' ? 'desc' : sortDirection === 'desc' ? null : 'asc';
+        }
+        else {
+            nextDirection = 'asc';
+        }
+        setSortKey(nextDirection === null ? null : key);
+        setSortDirection(nextDirection);
+        onSort === null || onSort === void 0 ? void 0 : onSort(key, nextDirection);
+    };
+    var wrapperClasses = [
+        'dds-table-wrapper',
+        stickyHeader ? 'dds-table-scrollable' : '',
+        variant === 'borderless' ? 'dds-table-borderless' : '',
+        className,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return (_jsx(TableContext.Provider, { value: { sortKey: sortKey, sortDirection: sortDirection, onSort: handleSort, stickyHeader: stickyHeader, variant: variant, headerBg: headerBg }, children: _jsx("div", { className: wrapperClasses, style: style, children: _jsx("table", { className: "dds-table", children: children }) }) }));
+}
+export function TableHead(_a) {
+    var children = _a.children, _b = _a.className, className = _b === void 0 ? '' : _b;
+    var _c = useTableContext(), stickyHeader = _c.stickyHeader, headerBg = _c.headerBg;
+    var classes = ['dds-table-head', stickyHeader ? 'dds-table-head-sticky' : '', className]
+        .filter(Boolean)
+        .join(' ');
+    var style = headerBg ? { backgroundColor: headerBg } : {};
+    return (_jsx("thead", { className: classes, style: style, children: children }));
+}
+export function TableBody(_a) {
+    var children = _a.children, _b = _a.className, className = _b === void 0 ? '' : _b;
+    return _jsx("tbody", { className: ['dds-table-body', className].filter(Boolean).join(' '), children: children });
+}
+export function TableRow(_a) {
+    var children = _a.children, _b = _a.className, className = _b === void 0 ? '' : _b;
+    return _jsx("tr", { className: ['dds-table-row', className].filter(Boolean).join(' '), children: children });
+}
+export function TableHeaderCell(_a) {
+    var children = _a.children, sortKey = _a.sortKey, _b = _a.align, align = _b === void 0 ? 'left' : _b, _c = _a.className, className = _c === void 0 ? '' : _c;
+    var _d = useTableContext(), activeSortKey = _d.sortKey, sortDirection = _d.sortDirection, onSort = _d.onSort;
+    var isSortable = Boolean(sortKey);
+    var isActive = isSortable && activeSortKey === sortKey;
+    var classes = [
+        'dds-table-th',
+        isSortable ? 'dds-table-th-sortable' : '',
+        isActive ? 'dds-table-th-active' : '',
+        "dds-table-align-".concat(align),
+        className,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    var handleClick = function () {
+        if (sortKey) {
+            onSort(sortKey);
+        }
+    };
+    var handleKeyDown = function (e) {
+        if (isSortable && (e.key === 'Enter' || e.key === ' ')) {
+            e.preventDefault();
+            handleClick();
+        }
+    };
+    var ariaSort = isActive
+        ? sortDirection === 'asc'
+            ? 'ascending'
+            : sortDirection === 'desc'
+                ? 'descending'
+                : 'none'
+        : 'none';
+    return (_jsx("th", { className: classes, scope: "col", "aria-sort": isSortable ? ariaSort : undefined, onClick: isSortable ? handleClick : undefined, onKeyDown: isSortable ? handleKeyDown : undefined, tabIndex: isSortable ? 0 : undefined, children: _jsxs("span", { className: "dds-table-th-content", children: [children, isSortable && (_jsx("span", { className: "dds-table-sort-icon", "aria-hidden": "true", children: isActive && sortDirection === 'asc' ? '↑' : isActive && sortDirection === 'desc' ? '↓' : '↕' }))] }) }));
+}
+export function TableCell(_a) {
+    var children = _a.children, _b = _a.align, align = _b === void 0 ? 'left' : _b, _c = _a.className, className = _c === void 0 ? '' : _c;
+    var classes = ['dds-table-td', "dds-table-align-".concat(align), className].filter(Boolean).join(' ');
+    return _jsx("td", { className: classes, children: children });
+}

package/dist/components/Table.stories.d.ts

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Table } from "./Table";
+/**
+ * Table displays structured data in rows and columns. It supports sortable
+ * columns, a sticky header, a borderless variant, and responsive horizontal
+ * scrolling for mobile viewports.
+ */
+declare const meta: Meta<typeof Table>;
+export default meta;
+type Story = StoryObj<typeof Table>;
+/**
+ * A basic table with all borders (the default variant).
+ */
+export declare const Default: Story;
+/**
+ * Borderless variant — only row dividers are shown; no outer or column borders.
+ * Common in modern documentation sites.
+ */
+export declare const Borderless: Story;
+/**
+ * Sortable columns — clicking a column header sorts the table ascending then
+ * descending, and a third click resets sort order.
+ */
+export declare const Sortable: Story;
+/**
+ * Sticky header — the thead stays fixed at the top of the scroll container as
+ * the user scrolls through a long table. Use `style={{ maxHeight: '...' }}` to
+ * constrain the table height so the header can stick.
+ */
+export declare const StickyHeader: Story;
+/**
+ * A custom header background color applied via the `headerBg` prop.
+ */
+export declare const CustomHeaderBg: Story;
+/**
+ * Column cells can be aligned left (default), center, or right using the
+ * `align` prop on `TableHeaderCell` and `TableCell`.
+ */
+export declare const ColumnAlignment: Story;
+/**
+ * A typical API-reference table for documenting component props or
+ * configuration options.
+ */
+export declare const ApiReference: Story;

package/dist/components/Table.stories.js

@@ -0,0 +1,258 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { Table, TableHead, TableBody, TableRow, TableHeaderCell, TableCell, } from "./Table";
+/**
+ * Table displays structured data in rows and columns. It supports sortable
+ * columns, a sticky header, a borderless variant, and responsive horizontal
+ * scrolling for mobile viewports.
+ */
+var meta = {
+    title: "Components/Table",
+    component: Table,
+    tags: ["autodocs"],
+    argTypes: {
+        variant: {
+            control: "radio",
+            options: ["default", "borderless"],
+            description: '`"default"` renders all borders; `"borderless"` shows only row top/bottom borders.',
+            table: { defaultValue: { summary: '"default"' } },
+        },
+        stickyHeader: {
+            control: "boolean",
+            description: "When true the thead sticks to the top of the viewport while scrolling.",
+            table: { defaultValue: { summary: "false" } },
+        },
+        headerBg: {
+            control: "color",
+            description: "Background color applied to the header row. Accepts any valid CSS color value.",
+        },
+        onSort: {
+            control: false,
+            description: "Callback fired when a sortable column header is clicked. Useful for server-side sorting.",
+        },
+        children: {
+            control: false,
+            description: "Table content — typically `TableHead` and `TableBody`.",
+        },
+        className: {
+            control: "text",
+            description: "Additional CSS classes applied to the outer wrapper.",
+            table: { defaultValue: { summary: '""' } },
+        },
+    },
+    parameters: {
+        docs: {
+            description: {
+                component: "\nTable displays structured, relational data in rows and columns for technical documentation pages.\n\n## When to Use\n\n- Displaying configuration options, API parameters, or reference data\n- Comparing multiple items across the same set of attributes\n- Presenting tabular data that users may want to sort or scan quickly\n\n## When Not to Use\n\n- For layout purposes \u2014 use CSS Grid or Flexbox instead\n- When data has fewer than two columns (use a list instead)\n- When rows have vastly different data shapes\n\n## Accessibility\n\n- `<th>` elements have `scope=\"col\"` for screen readers\n- Sortable headers expose `aria-sort` (`ascending`, `descending`, or `none`)\n- Sortable headers are focusable via keyboard and respond to Enter/Space\n        ",
+            },
+        },
+    },
+};
+export default meta;
+var employees = [
+    { name: "Alice Johnson", role: "Engineer", department: "Platform", status: "Active" },
+    { name: "Bob Smith", role: "Designer", department: "UX", status: "Active" },
+    { name: "Carol White", role: "Manager", department: "Platform", status: "On Leave" },
+    { name: "Dan Brown", role: "Engineer", department: "Frontend", status: "Active" },
+    { name: "Eve Davis", role: "Analyst", department: "Data", status: "Inactive" },
+];
+// -----------------------------------------------------------------------
+// Default
+// -----------------------------------------------------------------------
+/**
+ * A basic table with all borders (the default variant).
+ */
+export var Default = {
+    args: {
+        variant: "default",
+        stickyHeader: false,
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Table>\n  <TableHead>\n    <TableRow>\n      <TableHeaderCell>Name</TableHeaderCell>\n      <TableHeaderCell>Role</TableHeaderCell>\n      <TableHeaderCell>Department</TableHeaderCell>\n      <TableHeaderCell>Status</TableHeaderCell>\n    </TableRow>\n  </TableHead>\n  <TableBody>\n    <TableRow>\n      <TableCell>Alice Johnson</TableCell>\n      <TableCell>Engineer</TableCell>\n      <TableCell>Platform</TableCell>\n      <TableCell>Active</TableCell>\n    </TableRow>\n  </TableBody>\n</Table>",
+            },
+        },
+    },
+    render: function (args) { return (_jsxs(Table, __assign({}, args, { children: [_jsx(TableHead, { children: _jsxs(TableRow, { children: [_jsx(TableHeaderCell, { children: "Name" }), _jsx(TableHeaderCell, { children: "Role" }), _jsx(TableHeaderCell, { children: "Department" }), _jsx(TableHeaderCell, { children: "Status" })] }) }), _jsx(TableBody, { children: employees.map(function (e) { return (_jsxs(TableRow, { children: [_jsx(TableCell, { children: e.name }), _jsx(TableCell, { children: e.role }), _jsx(TableCell, { children: e.department }), _jsx(TableCell, { children: e.status })] }, e.name)); }) })] }))); },
+};
+// -----------------------------------------------------------------------
+// Borderless
+// -----------------------------------------------------------------------
+/**
+ * Borderless variant — only row dividers are shown; no outer or column borders.
+ * Common in modern documentation sites.
+ */
+export var Borderless = {
+    args: {
+        variant: "borderless",
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Table variant=\"borderless\">\n  <TableHead>\n    <TableRow>\n      <TableHeaderCell>Name</TableHeaderCell>\n      <TableHeaderCell>Role</TableHeaderCell>\n      <TableHeaderCell>Department</TableHeaderCell>\n      <TableHeaderCell>Status</TableHeaderCell>\n    </TableRow>\n  </TableHead>\n  <TableBody>\n    {/* rows */}\n  </TableBody>\n</Table>",
+            },
+        },
+    },
+    render: function (args) { return (_jsxs(Table, __assign({}, args, { children: [_jsx(TableHead, { children: _jsxs(TableRow, { children: [_jsx(TableHeaderCell, { children: "Name" }), _jsx(TableHeaderCell, { children: "Role" }), _jsx(TableHeaderCell, { children: "Department" }), _jsx(TableHeaderCell, { children: "Status" })] }) }), _jsx(TableBody, { children: employees.map(function (e) { return (_jsxs(TableRow, { children: [_jsx(TableCell, { children: e.name }), _jsx(TableCell, { children: e.role }), _jsx(TableCell, { children: e.department }), _jsx(TableCell, { children: e.status })] }, e.name)); }) })] }))); },
+};
+// -----------------------------------------------------------------------
+// Sortable (client-side)
+// -----------------------------------------------------------------------
+/**
+ * Sortable columns — clicking a column header sorts the table ascending then
+ * descending, and a third click resets sort order.
+ */
+export var Sortable = {
+    parameters: {
+        docs: {
+            source: {
+                code: "function SortableExample() {\n  const [rows, setRows] = React.useState(data);\n\n  const handleSort = (key, direction) => {\n    if (!direction) {\n      setRows(data);\n      return;\n    }\n    const sorted = [...rows].sort((a, b) => {\n      const cmp = a[key].localeCompare(b[key]);\n      return direction === 'asc' ? cmp : -cmp;\n    });\n    setRows(sorted);\n  };\n\n  return (\n    <Table onSort={handleSort}>\n      <TableHead>\n        <TableRow>\n          <TableHeaderCell sortKey=\"name\">Name</TableHeaderCell>\n          <TableHeaderCell sortKey=\"role\">Role</TableHeaderCell>\n          <TableHeaderCell sortKey=\"department\">Department</TableHeaderCell>\n          <TableHeaderCell sortKey=\"status\">Status</TableHeaderCell>\n        </TableRow>\n      </TableHead>\n      <TableBody>\n        {rows.map((e) => (\n          <TableRow key={e.name}>\n            <TableCell>{e.name}</TableCell>\n            <TableCell>{e.role}</TableCell>\n            <TableCell>{e.department}</TableCell>\n            <TableCell>{e.status}</TableCell>\n          </TableRow>\n        ))}\n      </TableBody>\n    </Table>\n  );\n}",
+            },
+        },
+    },
+    render: function SortableExample() {
+        var _a = useState(employees), rows = _a[0], setRows = _a[1];
+        var handleSort = function (key, direction) {
+            if (!direction) {
+                setRows(employees);
+                return;
+            }
+            var sorted = __spreadArray([], rows, true).sort(function (a, b) {
+                var aVal = a[key];
+                var bVal = b[key];
+                var cmp = aVal.localeCompare(bVal);
+                return direction === "asc" ? cmp : -cmp;
+            });
+            setRows(sorted);
+        };
+        return (_jsxs(Table, { onSort: handleSort, children: [_jsx(TableHead, { children: _jsxs(TableRow, { children: [_jsx(TableHeaderCell, { sortKey: "name", children: "Name" }), _jsx(TableHeaderCell, { sortKey: "role", children: "Role" }), _jsx(TableHeaderCell, { sortKey: "department", children: "Department" }), _jsx(TableHeaderCell, { sortKey: "status", children: "Status" })] }) }), _jsx(TableBody, { children: rows.map(function (e) { return (_jsxs(TableRow, { children: [_jsx(TableCell, { children: e.name }), _jsx(TableCell, { children: e.role }), _jsx(TableCell, { children: e.department }), _jsx(TableCell, { children: e.status })] }, e.name)); }) })] }));
+    },
+};
+// -----------------------------------------------------------------------
+// Sticky Header
+// -----------------------------------------------------------------------
+/**
+ * Sticky header — the thead stays fixed at the top of the scroll container as
+ * the user scrolls through a long table. Use `style={{ maxHeight: '...' }}` to
+ * constrain the table height so the header can stick.
+ */
+export var StickyHeader = {
+    args: {
+        stickyHeader: true,
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Table stickyHeader style={{ maxHeight: '300px' }}>\n  <TableHead>\n    <TableRow>\n      <TableHeaderCell>#</TableHeaderCell>\n      <TableHeaderCell>Name</TableHeaderCell>\n      <TableHeaderCell>Role</TableHeaderCell>\n      <TableHeaderCell>Department</TableHeaderCell>\n    </TableRow>\n  </TableHead>\n  <TableBody>\n    {/* many rows */}\n  </TableBody>\n</Table>",
+            },
+        },
+    },
+    render: function (args) {
+        var manyRows = Array.from({ length: 20 }, function (_, i) { return (__assign(__assign({}, employees[i % employees.length]), { name: "".concat(employees[i % employees.length].name, " ").concat(i + 1) })); });
+        return (_jsxs(Table, __assign({}, args, { style: { maxHeight: "300px" }, children: [_jsx(TableHead, { children: _jsxs(TableRow, { children: [_jsx(TableHeaderCell, { children: "#" }), _jsx(TableHeaderCell, { children: "Name" }), _jsx(TableHeaderCell, { children: "Role" }), _jsx(TableHeaderCell, { children: "Department" })] }) }), _jsx(TableBody, { children: manyRows.map(function (e, i) { return (_jsxs(TableRow, { children: [_jsx(TableCell, { children: i + 1 }), _jsx(TableCell, { children: e.name }), _jsx(TableCell, { children: e.role }), _jsx(TableCell, { children: e.department })] }, i)); }) })] })));
+    },
+};
+// -----------------------------------------------------------------------
+// Custom Header Background
+// -----------------------------------------------------------------------
+/**
+ * A custom header background color applied via the `headerBg` prop.
+ */
+export var CustomHeaderBg = {
+    args: {
+        headerBg: "#dbeafe",
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Table headerBg=\"#dbeafe\">\n  <TableHead>\n    <TableRow>\n      <TableHeaderCell>Name</TableHeaderCell>\n      <TableHeaderCell>Role</TableHeaderCell>\n      <TableHeaderCell>Department</TableHeaderCell>\n    </TableRow>\n  </TableHead>\n  <TableBody>\n    {/* rows */}\n  </TableBody>\n</Table>",
+            },
+        },
+    },
+    render: function (args) { return (_jsxs(Table, __assign({}, args, { children: [_jsx(TableHead, { children: _jsxs(TableRow, { children: [_jsx(TableHeaderCell, { children: "Name" }), _jsx(TableHeaderCell, { children: "Role" }), _jsx(TableHeaderCell, { children: "Department" }), _jsx(TableHeaderCell, { children: "Status" })] }) }), _jsx(TableBody, { children: employees.map(function (e) { return (_jsxs(TableRow, { children: [_jsx(TableCell, { children: e.name }), _jsx(TableCell, { children: e.role }), _jsx(TableCell, { children: e.department }), _jsx(TableCell, { children: e.status })] }, e.name)); }) })] }))); },
+};
+// -----------------------------------------------------------------------
+// Column Alignment
+// -----------------------------------------------------------------------
+/**
+ * Column cells can be aligned left (default), center, or right using the
+ * `align` prop on `TableHeaderCell` and `TableCell`.
+ */
+export var ColumnAlignment = {
+    parameters: {
+        docs: {
+            source: {
+                code: "<Table>\n  <TableHead>\n    <TableRow>\n      <TableHeaderCell align=\"left\">Name</TableHeaderCell>\n      <TableHeaderCell align=\"center\">Version</TableHeaderCell>\n      <TableHeaderCell align=\"right\">Downloads</TableHeaderCell>\n    </TableRow>\n  </TableHead>\n  <TableBody>\n    <TableRow>\n      <TableCell align=\"left\">react</TableCell>\n      <TableCell align=\"center\">18.3.0</TableCell>\n      <TableCell align=\"right\">24,000,000</TableCell>\n    </TableRow>\n  </TableBody>\n</Table>",
+            },
+        },
+    },
+    render: function () { return (_jsxs(Table, { children: [_jsx(TableHead, { children: _jsxs(TableRow, { children: [_jsx(TableHeaderCell, { align: "left", children: "Package" }), _jsx(TableHeaderCell, { align: "center", children: "Version" }), _jsx(TableHeaderCell, { align: "right", children: "Weekly Downloads" })] }) }), _jsx(TableBody, { children: [
+                    { name: "react", version: "18.3.0", downloads: "24,000,000" },
+                    { name: "typescript", version: "5.4.5", downloads: "58,000,000" },
+                    { name: "vite", version: "5.2.11", downloads: "9,800,000" },
+                    { name: "tailwindcss", version: "3.4.4", downloads: "11,200,000" },
+                ].map(function (pkg) { return (_jsxs(TableRow, { children: [_jsx(TableCell, { align: "left", children: pkg.name }), _jsx(TableCell, { align: "center", children: pkg.version }), _jsx(TableCell, { align: "right", children: pkg.downloads })] }, pkg.name)); }) })] })); },
+};
+// -----------------------------------------------------------------------
+// API Reference (documentation use-case)
+// -----------------------------------------------------------------------
+/**
+ * A typical API-reference table for documenting component props or
+ * configuration options.
+ */
+export var ApiReference = {
+    parameters: {
+        docs: {
+            source: {
+                code: "<Table variant=\"borderless\">\n  <TableHead>\n    <TableRow>\n      <TableHeaderCell>Prop</TableHeaderCell>\n      <TableHeaderCell>Type</TableHeaderCell>\n      <TableHeaderCell>Default</TableHeaderCell>\n      <TableHeaderCell>Description</TableHeaderCell>\n    </TableRow>\n  </TableHead>\n  <TableBody>\n    {/* prop rows */}\n  </TableBody>\n</Table>",
+            },
+        },
+    },
+    render: function () { return (_jsxs(Table, { variant: "borderless", children: [_jsx(TableHead, { children: _jsxs(TableRow, { children: [_jsx(TableHeaderCell, { children: "Prop" }), _jsx(TableHeaderCell, { children: "Type" }), _jsx(TableHeaderCell, { children: "Default" }), _jsx(TableHeaderCell, { children: "Description" })] }) }), _jsx(TableBody, { children: [
+                    {
+                        prop: "variant",
+                        type: '"default" | "borderless"',
+                        defaultVal: '"default"',
+                        desc: "Visual style of the table.",
+                    },
+                    {
+                        prop: "stickyHeader",
+                        type: "boolean",
+                        defaultVal: "false",
+                        desc: "Pins the header row to the top of the viewport while scrolling.",
+                    },
+                    {
+                        prop: "headerBg",
+                        type: "string",
+                        defaultVal: "—",
+                        desc: "CSS color applied to the header background.",
+                    },
+                    {
+                        prop: "onSort",
+                        type: "(key, direction) => void",
+                        defaultVal: "—",
+                        desc: "Callback for server-side sorting.",
+                    },
+                ].map(function (row) { return (_jsxs(TableRow, { children: [_jsx(TableCell, { children: _jsx("code", { children: row.prop }) }), _jsx(TableCell, { children: _jsx("code", { children: row.type }) }), _jsx(TableCell, { children: _jsx("code", { children: row.defaultVal }) }), _jsx(TableCell, { children: row.desc })] }, row.prop)); }) })] })); },
+};

package/dist/index.d.ts

@@ -11,5 +11,6 @@ export * from './components/Typography';
 export * from './components/Heading';
 export * from './components/Link';
 export * from './components/List';
+export * from './components/Table';
 export * from './components/Grid';
 export * from './hooks/useKeyPress';

package/dist/index.js

@@ -12,6 +12,7 @@ export * from './components/Typography';
 export * from './components/Heading';
 export * from './components/Link';
 export * from './components/List';
+export * from './components/Table';
 export * from './components/Grid';
 // Export hooks
 export * from './hooks/useKeyPress';

package/dist/styles.css

@@ -259,6 +259,27 @@
   --dds-list-connector-line: #eceef2; /* gray-200 */
   --dds-list-text: #374151; /* gray-700 */
 
+  /* Table */
+  --dds-table-margin: 1rem 0;
+  --dds-table-radius: 0.5rem; /* rounded-lg */
+  --dds-table-font-size: 0.875rem; /* text-sm */
+  --dds-table-bg: transparent;
+  --dds-table-text: #374151; /* gray-700 */
+  --dds-table-border: #e5e7eb; /* gray-200 */
+  --dds-table-row-border: #e5e7eb; /* gray-200 */
+  --dds-table-row-hover-bg: #f9fafb; /* gray-50 */
+  --dds-table-header-bg: #f3f4f6; /* gray-100 */
+  --dds-table-sticky-bg: var(--dds-table-header-bg); /* used as sticky header background; should be opaque */
+  --dds-table-sticky-hover-bg: var(--dds-table-header-hover-bg); /* used as sticky sortable header hover; should be opaque */
+  --dds-table-header-text: #111827; /* gray-900 */
+  --dds-table-header-font-size: 0.8125rem; /* ~13px */
+  --dds-table-header-border: #d1d5db; /* gray-300 */
+  --dds-table-header-hover-bg: #e5e7eb; /* gray-200 */
+  --dds-table-header-hover-text: #111827; /* gray-900 */
+  --dds-table-header-active-text: #1d4ed8; /* blue-700 */
+  --dds-table-cell-padding: 0.75rem 1rem;
+  --dds-table-focus-ring: #3b82f6; /* blue-500 */
+
   /* Grid */
   --dds-grid-gap-sm: 1rem; /* gap-4 */
   --dds-grid-gap-md: 1.5rem; /* gap-6 */
@@ -427,6 +448,22 @@
   --dds-list-connector-line: #353a42; /* gray-600 */
   --dds-list-text: #e5e7eb; /* gray-200 */
 
+  /* Table */
+  --dds-table-bg: transparent;
+  --dds-table-text: #d1d5db; /* gray-300 */
+  --dds-table-border: #4b5563; /* gray-600 */
+  --dds-table-row-border: #374151; /* gray-700 */
+  --dds-table-row-hover-bg: rgba(255, 255, 255, 0.04);
+  --dds-table-header-bg: rgba(255, 255, 255, 0.06);
+  --dds-table-sticky-bg: #1f2937; /* gray-800 — opaque fallback for sticky header */
+  --dds-table-sticky-hover-bg: #263347; /* slightly lighter opaque hover for sticky header */
+  --dds-table-header-text: #f9fafb; /* gray-50 */
+  --dds-table-header-border: #4b5563; /* gray-600 */
+  --dds-table-header-hover-bg: rgba(255, 255, 255, 0.1);
+  --dds-table-header-hover-text: #f9fafb; /* gray-50 */
+  --dds-table-header-active-text: #93c5fd; /* blue-300 */
+  --dds-table-focus-ring: #60a5fa; /* blue-400 */
+
   /* Grid */
   --dds-grid-divider-color: #4b5563; /* gray-600 */
 }
@@ -586,6 +623,22 @@
     --dds-list-connector-line: #353a42; /* gray-600 */
     --dds-list-text: #e5e7eb; /* gray-200 */
 
+    /* Table */
+    --dds-table-bg: transparent;
+    --dds-table-text: #d1d5db;
+    --dds-table-border: #4b5563;
+    --dds-table-row-border: #374151;
+    --dds-table-row-hover-bg: rgba(255, 255, 255, 0.04);
+    --dds-table-header-bg: rgba(255, 255, 255, 0.06);
+    --dds-table-sticky-bg: #1f2937;
+    --dds-table-sticky-hover-bg: #263347;
+    --dds-table-header-text: #f9fafb;
+    --dds-table-header-border: #4b5563;
+    --dds-table-header-hover-bg: rgba(255, 255, 255, 0.1);
+    --dds-table-header-hover-text: #f9fafb;
+    --dds-table-header-active-text: #93c5fd;
+    --dds-table-focus-ring: #60a5fa;
+
     /* Grid */
     --dds-grid-divider-color: #4b5563; /* gray-600 */
   }
@@ -726,6 +779,22 @@
   --dds-popover-eyebrow-color: #9ca3af;
   --dds-popover-link-color: #60a5fa;
   --dds-popover-link-color-hover: #93c5fd;
+
+  /* Table */
+  --dds-table-bg: transparent;
+  --dds-table-text: #d1d5db;
+  --dds-table-border: #4b5563;
+  --dds-table-row-border: #374151;
+  --dds-table-row-hover-bg: rgba(255, 255, 255, 0.04);
+  --dds-table-header-bg: rgba(255, 255, 255, 0.06);
+  --dds-table-sticky-bg: #1f2937;
+  --dds-table-sticky-hover-bg: #263347;
+  --dds-table-header-text: #f9fafb;
+  --dds-table-header-border: #4b5563;
+  --dds-table-header-hover-bg: rgba(255, 255, 255, 0.1);
+  --dds-table-header-hover-text: #f9fafb;
+  --dds-table-header-active-text: #93c5fd;
+  --dds-table-focus-ring: #60a5fa;
 }
 /* Import PrismJS theme */
 /**
@@ -1845,6 +1914,125 @@ a.no-text-decoration {
     }
   }
 }
+/* Table wrapper — enables responsive horizontal scroll */
+.dds-table-wrapper {
+  width: 100%;
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+  border: 1px solid var(--dds-table-border);
+  border-radius: var(--dds-table-radius);
+  margin: var(--dds-table-margin);
+}
+/* When stickyHeader is true the wrapper also scrolls vertically so that
+   position:sticky on th elements activates within the same scroll container. */
+.dds-table-scrollable {
+  overflow-y: auto;
+}
+/* Remove outer border for borderless variant — only row borders remain */
+.dds-table-borderless {
+  border: none;
+  border-radius: 0;
+}
+.dds-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: var(--dds-table-font-size);
+  color: var(--dds-table-text);
+  background-color: var(--dds-table-bg);
+}
+/* -----------------------------------------------------------------------
+   Header
+   ----------------------------------------------------------------------- */
+.dds-table-head {
+  background-color: var(--dds-table-header-bg);
+}
+.dds-table-head-sticky th {
+  position: sticky;
+  top: 0;
+  z-index: 2;
+  background-color: var(--dds-table-sticky-bg, var(--dds-table-header-bg));
+}
+/* When headerBg is set via inline style, the sticky cells must inherit it */
+.dds-table-head-sticky[style] th {
+  background-color: inherit;
+}
+/* Sticky sortable header hover: keep background opaque to avoid bleed-through
+   when the global .dds-table-th-sortable:hover uses a semi-transparent color. */
+.dds-table-head-sticky th.dds-table-th-sortable:hover {
+  background-color: var(
+    --dds-table-sticky-hover-bg,
+    var(--dds-table-sticky-bg, var(--dds-table-header-bg))
+  );
+}
+/* -----------------------------------------------------------------------
+   Cells — shared
+   ----------------------------------------------------------------------- */
+.dds-table-th,
+.dds-table-td {
+  padding: var(--dds-table-cell-padding);
+  text-align: left;
+  vertical-align: top;
+}
+/* Alignment helpers */
+.dds-table-align-left  { text-align: left; }
+.dds-table-align-center { text-align: center; }
+.dds-table-align-right { text-align: right; }
+/* -----------------------------------------------------------------------
+   Header cell
+   ----------------------------------------------------------------------- */
+.dds-table-th {
+  font-weight: var(--dds-font-semibold);
+  font-size: var(--dds-table-header-font-size);
+  color: var(--dds-table-header-text);
+  border-bottom: 2px solid var(--dds-table-header-border);
+  white-space: nowrap;
+}
+/* Default variant: left/right column borders */
+.dds-table-wrapper:not(.dds-table-borderless) .dds-table-th + .dds-table-th,
+.dds-table-wrapper:not(.dds-table-borderless) .dds-table-td + .dds-table-td {
+  border-left: 1px solid var(--dds-table-border);
+}
+/* -----------------------------------------------------------------------
+   Sortable column header
+   ----------------------------------------------------------------------- */
+.dds-table-th-sortable {
+  cursor: pointer;
+  user-select: none;
+}
+.dds-table-th-sortable:hover {
+  background-color: var(--dds-table-header-hover-bg);
+  color: var(--dds-table-header-hover-text);
+}
+.dds-table-th-sortable:focus-visible {
+  outline: 2px solid var(--dds-table-focus-ring);
+  outline-offset: -2px;
+}
+.dds-table-th-active {
+  color: var(--dds-table-header-active-text);
+}
+.dds-table-th-content {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+}
+.dds-table-sort-icon {
+  font-size: 0.75em;
+  opacity: 0.7;
+  flex-shrink: 0;
+}
+.dds-table-th-active .dds-table-sort-icon {
+  opacity: 1;
+}
+/* -----------------------------------------------------------------------
+   Body rows
+   ----------------------------------------------------------------------- */
+.dds-table-body .dds-table-row {
+  border-top: 1px solid var(--dds-table-row-border);
+  transition: background-color 150ms ease-in-out;
+}
+.dds-table-body .dds-table-row:hover {
+  background-color: var(--dds-table-row-hover-bg);
+}
 /* =============================================================================
    Grid — multi-column layout component
    ============================================================================= */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roadlittledawn/docs-design-system-react",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "license": "MIT",
   "description": "React components for documentation design system",
   "repository": {