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

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/components/Tabs.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
-interface TabsProps {
+export interface TabsProps {
     /** ID of the initially active tab */
     defaultActiveTab?: string;
     /** Controlled active tab ID */
@@ -12,14 +12,14 @@ interface TabsProps {
     className?: string;
 }
 export declare function Tabs({ defaultActiveTab, activeTab: controlledActiveTab, onTabChange, children, className, }: TabsProps): import("react/jsx-runtime").JSX.Element;
-interface TabListProps {
+export interface TabListProps {
     /** Tab buttons */
     children: React.ReactNode;
     /** Additional CSS classes */
     className?: string;
 }
 export declare function TabList({ children, className }: TabListProps): import("react/jsx-runtime").JSX.Element;
-interface TabProps {
+export interface TabProps {
     /** Unique identifier for this tab */
     id: string;
     /** Tab label */
@@ -28,7 +28,7 @@ interface TabProps {
     className?: string;
 }
 export declare function Tab({ id, children, className }: TabProps): import("react/jsx-runtime").JSX.Element;
-interface TabPanelProps {
+export interface TabPanelProps {
     /** ID matching the corresponding Tab */
     id: string;
     /** Panel content */
@@ -37,4 +37,3 @@ interface TabPanelProps {
     className?: string;
 }
 export declare function TabPanel({ id, children, className }: TabPanelProps): import("react/jsx-runtime").JSX.Element | null;
-export {};

package/dist/components/Typography.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-interface TypographyProps {
+export interface TypographyProps {
     /**
      * Typography style variant
      * @default 'p'
@@ -11,4 +11,3 @@ interface TypographyProps {
     className?: string;
 }
 export declare const Typography: React.FC<TypographyProps>;
-export {};

package/dist/index.d.ts

@@ -11,5 +11,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 * from './components/Breadcrumb';
 export * from './hooks/useKeyPress';

package/dist/index.js

@@ -12,6 +12,8 @@ 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 './components/Breadcrumb';
 // Export hooks
 export * from './hooks/useKeyPress';