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

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,4 +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,5 +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';