@roadlittledawn/docs-design-system-react 0.3.0 → 0.4.0

package/dist/components/Tabs.d.ts

@@ -0,0 +1,40 @@
+import React from "react";
+interface TabsProps {
+    /** ID of the initially active tab */
+    defaultActiveTab?: string;
+    /** Controlled active tab ID */
+    activeTab?: string;
+    /** Callback when tab changes */
+    onTabChange?: (id: string) => void;
+    /** Tab content */
+    children: React.ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function Tabs({ defaultActiveTab, activeTab: controlledActiveTab, onTabChange, children, className, }: TabsProps): import("react/jsx-runtime").JSX.Element;
+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 {
+    /** Unique identifier for this tab */
+    id: string;
+    /** Tab label */
+    children: React.ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function Tab({ id, children, className }: TabProps): import("react/jsx-runtime").JSX.Element;
+interface TabPanelProps {
+    /** ID matching the corresponding Tab */
+    id: string;
+    /** Panel content */
+    children: React.ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function TabPanel({ id, children, className }: TabPanelProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/Tabs.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useState, createContext, useContext } from "react";
+var TabsContext = createContext(null);
+export function Tabs(_a) {
+    var defaultActiveTab = _a.defaultActiveTab, controlledActiveTab = _a.activeTab, onTabChange = _a.onTabChange, children = _a.children, _b = _a.className, className = _b === void 0 ? "" : _b;
+    var _c = useState(defaultActiveTab || ""), internalActiveTab = _c[0], setInternalActiveTab = _c[1];
+    var isControlled = controlledActiveTab !== undefined;
+    var activeTab = isControlled ? controlledActiveTab : internalActiveTab;
+    var setActiveTab = function (id) {
+        if (!isControlled) {
+            setInternalActiveTab(id);
+        }
+        onTabChange === null || onTabChange === void 0 ? void 0 : onTabChange(id);
+    };
+    return (_jsx(TabsContext.Provider, { value: { activeTab: activeTab, setActiveTab: setActiveTab }, children: _jsx("div", { className: "dds-tabs ".concat(className).trim(), children: children }) }));
+}
+export function TabList(_a) {
+    var children = _a.children, _b = _a.className, className = _b === void 0 ? "" : _b;
+    return (_jsx("div", { className: "dds-tabs-list ".concat(className).trim(), role: "tablist", children: children }));
+}
+export function Tab(_a) {
+    var id = _a.id, children = _a.children, _b = _a.className, className = _b === void 0 ? "" : _b;
+    var context = useContext(TabsContext);
+    if (!context) {
+        throw new Error("Tab must be used within Tabs component");
+    }
+    var activeTab = context.activeTab, setActiveTab = context.setActiveTab;
+    var isActive = activeTab === id;
+    return (_jsx("button", { className: "dds-tab ".concat(isActive ? "dds-tab-active" : "", " ").concat(className).trim(), onClick: function () { return setActiveTab(id); }, role: "tab", "aria-selected": isActive, "aria-controls": "panel-".concat(id), id: "tab-".concat(id), type: "button", children: children }));
+}
+export function TabPanel(_a) {
+    var id = _a.id, children = _a.children, _b = _a.className, className = _b === void 0 ? "" : _b;
+    var context = useContext(TabsContext);
+    if (!context) {
+        throw new Error("TabPanel must be used within Tabs component");
+    }
+    var activeTab = context.activeTab;
+    var isActive = activeTab === id;
+    if (!isActive)
+        return null;
+    return (_jsx("div", { className: "dds-tab-panel ".concat(className).trim(), role: "tabpanel", "aria-labelledby": "tab-".concat(id), id: "panel-".concat(id), children: children }));
+}

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

@@ -0,0 +1,25 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Tabs } from "./Tabs";
+/**
+ * Tabs organize and segment related content, reducing cognitive load by allowing users
+ * to toggle between views without navigating to new pages.
+ */
+declare const meta: Meta<typeof Tabs>;
+export default meta;
+type Story = StoryObj<typeof Tabs>;
+/**
+ * Basic tabs with three sections of content.
+ */
+export declare const Basic: Story;
+/**
+ * Tabs showing code examples in different programming languages.
+ */
+export declare const CodeExamples: Story;
+/**
+ * Tabs with longer content demonstrating scrollable tab list.
+ */
+export declare const ManyTabs: Story;
+/**
+ * Controlled tabs where the active tab is managed by parent component state.
+ */
+export declare const Controlled: Story;

package/dist/components/Tabs.stories.js

@@ -0,0 +1,89 @@
+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);
+};
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from "react";
+import { Tabs, TabList, Tab, TabPanel } from "./Tabs";
+import { CodeBlock } from "./CodeBlock";
+/**
+ * Tabs organize and segment related content, reducing cognitive load by allowing users
+ * to toggle between views without navigating to new pages.
+ */
+var meta = {
+    title: "Components/Tabs",
+    component: Tabs,
+    tags: ["autodocs"],
+    parameters: {
+        docs: {
+            description: {
+                component: "\nTabs are best used to organize, segment, and reduce cognitive load when presenting large amounts of related but distinct content.\n\n## When to Use\n\n- **Segmenting Related Alternatives**: Show different solutions for the same task (e.g., code examples in Python, Java, JavaScript)\n- **Managing Complex/Long Documents**: Break down extensive documentation into smaller, more manageable sections\n- **Context-Switching**: Allow users to switch between different views (e.g., \"Overview,\" \"Usage,\" \"API Reference\") while staying in the same context\n- **Organizing Workflows**: Separate complex workflows, such as student work from instructions, or setup steps from troubleshooting\n- **Reducing Clutter**: Hide non-essential or less frequently used information, showing only relevant details at one time\n\n## When Not to Use\n\n- When content is short and can be easily scrolled\n- When users need to compare all content simultaneously\n- If the information in the tabs is not related\n- For navigation between pages (use Link component instead)\n\n## Best Practices\n\n- **Default View**: Always set a logical default tab (e.g., the most commonly used language or platform)\n- **Clear Labels**: Ensure tab labels are concise, descriptive, and clearly distinguish between options\n- **Limit Number**: Avoid using too many tabs (more than 5-6 can clutter the interface)\n- **Avoid Nested Tabs**: Too many levels of navigation can confuse users\n\n## Tabs vs Collapsers\n\nUse **tabs** for a small number of distinct, parallel content sections where users rarely need to compare them simultaneously. Use **collapsers** (accordions) for long, vertical content, mobile-first layouts, or FAQs to minimize scrolling and allow users to see all options at once.\n\n## Accessibility\n\n- Uses proper ARIA attributes (`role=\"tab\"`, `role=\"tabpanel\"`, `aria-selected`)\n- Tab buttons are keyboard accessible\n- Active tab is clearly indicated visually and to screen readers\n        ",
+            },
+        },
+    },
+};
+export default meta;
+/**
+ * Basic tabs with three sections of content.
+ */
+export var Basic = {
+    args: {
+        defaultActiveTab: "overview",
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Tabs defaultActiveTab=\"overview\">\n  <TabList>\n    <Tab id=\"overview\">Overview</Tab>\n    <Tab id=\"usage\">Usage</Tab>\n    <Tab id=\"api\">API Reference</Tab>\n  </TabList>\n  <TabPanel id=\"overview\">\n    <p>\n      This is the overview section. It provides a high-level introduction\n      to the topic.\n    </p>\n  </TabPanel>\n  <TabPanel id=\"usage\">\n    <p>\n      This is the usage section. It contains practical examples and\n      instructions.\n    </p>\n  </TabPanel>\n  <TabPanel id=\"api\">\n    <p>\n      This is the API reference section. It documents the technical\n      interface.\n    </p>\n  </TabPanel>\n</Tabs>",
+            },
+        },
+    },
+    render: function (args) { return (_jsxs(Tabs, __assign({}, args, { children: [_jsxs(TabList, { children: [_jsx(Tab, { id: "overview", children: "Overview" }), _jsx(Tab, { id: "usage", children: "Usage" }), _jsx(Tab, { id: "api", children: "API Reference" })] }), _jsx(TabPanel, { id: "overview", children: _jsx("p", { children: "This is the overview section. It provides a high-level introduction to the topic." }) }), _jsx(TabPanel, { id: "usage", children: _jsx("p", { children: "This is the usage section. It contains practical examples and instructions." }) }), _jsx(TabPanel, { id: "api", children: _jsx("p", { children: "This is the API reference section. It documents the technical interface." }) })] }))); },
+};
+/**
+ * Tabs showing code examples in different programming languages.
+ */
+export var CodeExamples = {
+    args: {
+        defaultActiveTab: "javascript",
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Tabs defaultActiveTab=\"javascript\">\n  <TabList>\n    <Tab id=\"javascript\">JavaScript</Tab>\n    <Tab id=\"python\">Python</Tab>\n    <Tab id=\"java\">Java</Tab>\n  </TabList>\n  <TabPanel id=\"javascript\">\n    <CodeBlock \n      language=\"javascript\" \n      code={`const greeting = \"Hello, world!\";\nconsole.log(greeting);`} \n    />\n  </TabPanel>\n  <TabPanel id=\"python\">\n    <CodeBlock \n      language=\"python\" \n      code={`greeting = \"Hello, world!\"\nprint(greeting)`} \n    />\n  </TabPanel>\n  <TabPanel id=\"java\">\n    <CodeBlock \n      language=\"java\" \n      code={`String greeting = \"Hello, world!\";\nSystem.out.println(greeting);`} \n    />\n  </TabPanel>\n</Tabs>",
+            },
+        },
+    },
+    render: function (args) { return (_jsxs(Tabs, __assign({}, args, { children: [_jsxs(TabList, { children: [_jsx(Tab, { id: "javascript", children: "JavaScript" }), _jsx(Tab, { id: "python", children: "Python" }), _jsx(Tab, { id: "java", children: "Java" })] }), _jsx(TabPanel, { id: "javascript", children: _jsx(CodeBlock, { language: "javascript", code: "const greeting = \"Hello, world!\";\nconsole.log(greeting);" }) }), _jsx(TabPanel, { id: "python", children: _jsx(CodeBlock, { language: "python", code: "greeting = \"Hello, world!\"\nprint(greeting)" }) }), _jsx(TabPanel, { id: "java", children: _jsx(CodeBlock, { language: "java", code: "String greeting = \"Hello, world!\";\nSystem.out.println(greeting);" }) })] }))); },
+};
+/**
+ * Tabs with longer content demonstrating scrollable tab list.
+ */
+export var ManyTabs = {
+    args: {
+        defaultActiveTab: "tab1",
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Tabs defaultActiveTab=\"tab1\">\n  <TabList>\n    <Tab id=\"tab1\">Introduction</Tab>\n    <Tab id=\"tab2\">Getting Started</Tab>\n    <Tab id=\"tab3\">Configuration</Tab>\n    <Tab id=\"tab4\">Advanced Usage</Tab>\n    <Tab id=\"tab5\">Troubleshooting</Tab>\n    <Tab id=\"tab6\">FAQ</Tab>\n  </TabList>\n  <TabPanel id=\"tab1\">\n    <p>Introduction content goes here.</p>\n  </TabPanel>\n  <TabPanel id=\"tab2\">\n    <p>Getting started content goes here.</p>\n  </TabPanel>\n  <TabPanel id=\"tab3\">\n    <p>Configuration content goes here.</p>\n  </TabPanel>\n  <TabPanel id=\"tab4\">\n    <p>Advanced usage content goes here.</p>\n  </TabPanel>\n  <TabPanel id=\"tab5\">\n    <p>Troubleshooting content goes here.</p>\n  </TabPanel>\n  <TabPanel id=\"tab6\">\n    <p>FAQ content goes here.</p>\n  </TabPanel>\n</Tabs>",
+            },
+        },
+    },
+    render: function (args) { return (_jsxs(Tabs, __assign({}, args, { children: [_jsxs(TabList, { children: [_jsx(Tab, { id: "tab1", children: "Introduction" }), _jsx(Tab, { id: "tab2", children: "Getting Started" }), _jsx(Tab, { id: "tab3", children: "Configuration" }), _jsx(Tab, { id: "tab4", children: "Advanced Usage" }), _jsx(Tab, { id: "tab5", children: "Troubleshooting" }), _jsx(Tab, { id: "tab6", children: "FAQ" })] }), _jsx(TabPanel, { id: "tab1", children: _jsx("p", { children: "Introduction content goes here." }) }), _jsx(TabPanel, { id: "tab2", children: _jsx("p", { children: "Getting started content goes here." }) }), _jsx(TabPanel, { id: "tab3", children: _jsx("p", { children: "Configuration content goes here." }) }), _jsx(TabPanel, { id: "tab4", children: _jsx("p", { children: "Advanced usage content goes here." }) }), _jsx(TabPanel, { id: "tab5", children: _jsx("p", { children: "Troubleshooting content goes here." }) }), _jsx(TabPanel, { id: "tab6", children: _jsx("p", { children: "FAQ content goes here." }) })] }))); },
+};
+/**
+ * Controlled tabs where the active tab is managed by parent component state.
+ */
+export var Controlled = {
+    render: function ControlledExample() {
+        var _a = React.useState("tab1"), activeTab = _a[0], setActiveTab = _a[1];
+        return (_jsxs("div", { children: [_jsxs("p", { style: { marginBottom: "1rem", color: "var(--dds-tabs-panel-text)" }, children: ["Active tab: ", _jsx("strong", { children: activeTab })] }), _jsxs(Tabs, { activeTab: activeTab, onTabChange: setActiveTab, children: [_jsxs(TabList, { children: [_jsx(Tab, { id: "tab1", children: "Tab 1" }), _jsx(Tab, { id: "tab2", children: "Tab 2" }), _jsx(Tab, { id: "tab3", children: "Tab 3" })] }), _jsx(TabPanel, { id: "tab1", children: _jsx("p", { children: "Content for tab 1" }) }), _jsx(TabPanel, { id: "tab2", children: _jsx("p", { children: "Content for tab 2" }) }), _jsx(TabPanel, { id: "tab3", children: _jsx("p", { children: "Content for tab 3" }) })] })] }));
+    },
+};

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from './components/CardGrid';
 export * from './components/Collapser';
 export * from './components/CollapserGroup';
 export * from './components/CodeBlock';
+export * from './components/Tabs';
 export * from './components/Typography';
 export * from './components/Heading';
 export * from './components/Link';

package/dist/index.js

@@ -6,6 +6,7 @@ export * from './components/CardGrid';
 export * from './components/Collapser';
 export * from './components/CollapserGroup';
 export * from './components/CodeBlock';
+export * from './components/Tabs';
 export * from './components/Typography';
 export * from './components/Heading';
 export * from './components/Link';

package/dist/styles.css

@@ -209,6 +209,21 @@
   --dds-collapser-icon-color: #6b7280; /* gray-500 */
   --dds-collapser-text: #374151; /* gray-700 */
   --dds-collapser-content-padding: 1rem; /* p-4 */
+
+  /* Tabs */
+  --dds-tabs-margin: 1rem 0;
+  --dds-tabs-border: #e5e7eb; /* gray-200 */
+  --dds-tabs-tab-padding: 0.75rem 1rem;
+  --dds-tabs-tab-bg: transparent;
+  --dds-tabs-tab-text: #6b7280; /* gray-500 */
+  --dds-tabs-tab-size: 0.875rem;
+  --dds-tabs-tab-text-hover: #374151; /* gray-700 */
+  --dds-tabs-tab-bg-hover: transparent;
+  --dds-tabs-tab-text-active: #111827; /* gray-900 */
+  --dds-tabs-tab-bg-active: transparent;
+  --dds-tabs-tab-border-active: #3b82f6; /* blue-500 */
+  --dds-tabs-panel-padding: 1.25rem 0;
+  --dds-tabs-panel-text: #111827; /* gray-900 */
 }
 /* ==========================================================================
    Dark Mode Tokens
@@ -297,6 +312,17 @@
   --dds-collapser-icon-color: #9ca3af; /* gray-400 */
   --dds-collapser-text: #e5e7eb; /* gray-200 */
 
+  /* Tabs */
+  --dds-tabs-border: #4b5563; /* gray-600 */
+  --dds-tabs-tab-bg: transparent;
+  --dds-tabs-tab-text: #9ca3af; /* gray-400 */
+  --dds-tabs-tab-text-hover: #e5e7eb; /* gray-200 */
+  --dds-tabs-tab-bg-hover: transparent;
+  --dds-tabs-tab-text-active: #f9fafb; /* gray-50 */
+  --dds-tabs-tab-bg-active: transparent;
+  --dds-tabs-tab-border-active: #60a5fa; /* blue-400 */
+  --dds-tabs-panel-text: #e5e7eb; /* gray-200 */
+
   /* CodeBlock */
   --dds-code-block-bg: #0a0a0a;
   --dds-code-block-border: #2e2e2e; /* hsla(0,0%,18%,1) */
@@ -422,6 +448,17 @@
     --dds-collapser-icon-color: #9ca3af;
     --dds-collapser-text: #e5e7eb;
 
+    /* Tabs */
+    --dds-tabs-border: #4b5563;
+    --dds-tabs-tab-bg: transparent;
+    --dds-tabs-tab-text: #9ca3af;
+    --dds-tabs-tab-text-hover: #e5e7eb;
+    --dds-tabs-tab-bg-hover: transparent;
+    --dds-tabs-tab-text-active: #f9fafb;
+    --dds-tabs-tab-bg-active: transparent;
+    --dds-tabs-tab-border-active: #60a5fa;
+    --dds-tabs-panel-text: #e5e7eb;
+
     /* CodeBlock */
     --dds-code-block-bg: #0a0a0a;
     --dds-code-block-border: #262626;
@@ -1279,6 +1316,50 @@ a.no-text-decoration {
 .dds-code-block-content .token.variable {
   color: var(--dds-prism-regex);
 }
+.dds-tabs {
+  margin: var(--dds-tabs-margin);
+}
+.dds-tabs-list {
+  display: flex;
+  gap: 0;
+  border-bottom: 1px solid var(--dds-tabs-border);
+  overflow-x: auto;
+  overflow-y: hidden;
+  -webkit-overflow-scrolling: touch;
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+}
+.dds-tabs-list::-webkit-scrollbar {
+  display: none;
+}
+.dds-tab {
+  padding: var(--dds-tabs-tab-padding);
+  background-color: var(--dds-tabs-tab-bg);
+  border: none;
+  border-bottom: 2px solid transparent;
+  color: var(--dds-tabs-tab-text);
+  font-size: var(--dds-tabs-tab-size);
+  font-weight: var(--dds-font-medium);
+  cursor: pointer;
+  white-space: nowrap;
+  transition: var(--dds-transition-colors);
+}
+.dds-tab:hover {
+  color: var(--dds-tabs-tab-text-hover);
+  background-color: var(--dds-tabs-tab-bg-hover);
+}
+.dds-tab-active {
+  color: var(--dds-tabs-tab-text-active);
+  background-color: var(--dds-tabs-tab-bg-active);
+  border-bottom-color: var(--dds-tabs-tab-border-active);
+}
+.dds-tab-active:hover {
+  background-color: var(--dds-tabs-tab-bg-active);
+}
+.dds-tab-panel {
+  padding: var(--dds-tabs-panel-padding);
+  color: var(--dds-tabs-panel-text);
+}
 .dds-typography {
   color: var(--dds-heading-color);
 }

package/package.json

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