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

package/dist/components/Collapser.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode } from "react";
-interface CollapserProps {
+export interface CollapserProps {
     /** Title text or element displayed in the collapsible header */
     title: string | ReactNode;
     /** Optional ID for the title element */
@@ -21,6 +21,23 @@ interface CollapserProps {
     children: ReactNode;
     /** Additional CSS classes */
     className?: string;
+    /**
+     * Alignment of the title within the header.
+     * Use 'right' for right-aligned titles, typically paired with an icon on the left.
+     * @default 'left'
+     */
+    align?: 'left' | 'right';
+    /**
+     * Optional icon or React element rendered on the left side of the header,
+     * before the title text. Useful for visual identification of each section.
+     */
+    icon?: ReactNode;
+    /**
+     * Numeric step label shown on the far left of the header.
+     * Automatically injected by `CollapserGroup` when `numbered` is true;
+     * can also be set manually on individual collapsers.
+     * Use `--dds-collapser-step-number-color` to customise its colour.
+     */
+    stepNumber?: number;
 }
-export declare function Collapser({ title, id, defaultOpen, open: controlledOpen, onToggle, children, className, }: CollapserProps): import("react/jsx-runtime").JSX.Element;
-export {};
+export declare function Collapser({ title, id, defaultOpen, open: controlledOpen, onToggle, children, className, align, icon, stepNumber, }: CollapserProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Collapser.js

@@ -1,13 +1,13 @@
 'use client';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { useState, useRef, useEffect } from "react";
 import { useKeyPress } from "../hooks/useKeyPress";
 export function Collapser(_a) {
-    var title = _a.title, id = _a.id, _b = _a.defaultOpen, defaultOpen = _b === void 0 ? false : _b, controlledOpen = _a.open, onToggle = _a.onToggle, children = _a.children, _c = _a.className, className = _c === void 0 ? "" : _c;
-    var _d = useState(defaultOpen), uncontrolledOpen = _d[0], setUncontrolledOpen = _d[1];
+    var title = _a.title, id = _a.id, _b = _a.defaultOpen, defaultOpen = _b === void 0 ? false : _b, controlledOpen = _a.open, onToggle = _a.onToggle, children = _a.children, _c = _a.className, className = _c === void 0 ? "" : _c, _d = _a.align, align = _d === void 0 ? 'left' : _d, icon = _a.icon, stepNumber = _a.stepNumber;
+    var _e = useState(defaultOpen), uncontrolledOpen = _e[0], setUncontrolledOpen = _e[1];
     var isControlled = controlledOpen !== undefined;
     var isOpen = isControlled ? controlledOpen : uncontrolledOpen;
-    var _e = useState(undefined), height = _e[0], setHeight = _e[1];
+    var _f = useState(undefined), height = _f[0], setHeight = _f[1];
     var contentRef = useRef(null);
     // Keyboard shortcuts: 's' or 'f' to show, 'h' to hide
     useKeyPress(['s', 'f', 'h'], function (e) {
@@ -28,10 +28,14 @@ export function Collapser(_a) {
             setUncontrolledOpen(!uncontrolledOpen);
         }
     };
-    var collapserClasses = ["dds-collapser", className]
+    var collapserClasses = [
+        "dds-collapser",
+        align === 'right' ? "dds-collapser--align-right" : "",
+        className,
+    ]
         .filter(Boolean)
         .join(" ");
-    return (_jsxs("div", { className: collapserClasses, children: [_jsxs("button", { onClick: toggleOpen, type: "button", className: "dds-collapser-button", "aria-expanded": isOpen, children: [_jsx("h5", { id: id, className: "dds-collapser-title", children: title }), _jsx("svg", { className: "dds-collapser-icon ".concat(isOpen ? "dds-collapser-icon-open" : ""), width: "16", height: "16", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("polyline", { points: "6 9 12 15 18 9" }) })] }), _jsx("div", { className: "dds-collapser-content-wrapper", style: {
+    return (_jsxs("div", { className: collapserClasses, children: [_jsxs("button", { onClick: toggleOpen, type: "button", className: "dds-collapser-button", "aria-expanded": isOpen, children: [stepNumber !== undefined && (_jsxs("span", { className: "dds-collapser-step-number", children: [stepNumber, "."] })), icon && (_jsx("span", { className: "dds-collapser-header-icon", "aria-hidden": "true", children: icon })), _jsx("h5", { id: id, className: "dds-collapser-title", children: title }), _jsx("svg", { className: "dds-collapser-icon ".concat(isOpen ? "dds-collapser-icon-open" : ""), width: "16", height: "16", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("polyline", { points: "6 9 12 15 18 9" }) })] }), _jsx("div", { className: "dds-collapser-content-wrapper", style: {
                     height: isOpen ? height : 0,
                 }, children: _jsx("div", { ref: contentRef, className: "dds-collapser-content", children: children }) })] }));
 }

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

@@ -18,11 +18,44 @@ export declare const DefaultOpen: Story;
  * Collapser with an ID for the title.
  */
 export declare const WithID: Story;
+/**
+ * Collapser with an icon rendered on the left side of the header.
+ * The icon prop accepts any React element — use your own icon component or SVG.
+ */
+export declare const WithIcon: Story;
+/**
+ * Collapser with the title right-aligned within the header.
+ * Use this for design layouts where the title should appear on the right
+ * and content (such as a step number or icon) anchors the left.
+ */
+export declare const RightAligned: Story;
+/**
+ * Collapser with both an icon and right-aligned title — matching the
+ * reference screenshot layout where an icon anchors the left and the
+ * title text flows to the right before the chevron.
+ */
+export declare const WithIconRightAligned: Story;
 /**
  * Collapser containing complex content.
  */
 export declare const ComplexContent: Story;
+/**
+ * Shows all four header layout variants side-by-side for visual comparison:
+ * default left-aligned, left-aligned with icon, right-aligned, and right-aligned with icon.
+ */
+export declare const AllVariants: Story;
 /**
  * Multiple collapsers in a FAQ-style layout using CollapserGroup.
  */
 export declare const FAQExample: Story;
+/**
+ * Example matching the reference screenshot: collapsers in a group where each
+ * has a distinct icon on the left and right-aligned title text.
+ */
+export declare const IconGroupExample: Story;
+/**
+ * CollapserGroup with `numbered` auto-numbers each entry.
+ * Matches the reference screenshot pattern: step number + icon on the left,
+ * title right-aligned, chevron on the far right.
+ */
+export declare const NumberedGroup: Story;

package/dist/components/Collapser.stories.js

@@ -1,6 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Collapser } from './Collapser';
 import { CollapserGroup } from './CollapserGroup';
+// Spoofed icon components for demonstration purposes
+// (replace with your own Icon component when available)
+var IconBook = function () { return (_jsxs("svg", { width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [_jsx("path", { d: "M4 19.5A2.5 2.5 0 0 1 6.5 17H20" }), _jsx("path", { d: "M6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z" })] })); };
+var IconBolt = function () { return (_jsx("svg", { width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: _jsx("polyline", { points: "13 2 3 14 12 14 11 22 21 10 12 10 13 2" }) })); };
+var IconStar = function () { return (_jsx("svg", { width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: _jsx("polygon", { points: "12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2" }) })); };
+var IconSettings = function () { return (_jsxs("svg", { width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [_jsx("circle", { cx: "12", cy: "12", r: "3" }), _jsx("path", { d: "M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83-2.83l.06-.06A1.65 1.65 0 0 0 4.68 15a1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 2.83-2.83l.06.06A1.65 1.65 0 0 0 9 4.68a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 2.83l-.06.06A1.65 1.65 0 0 0 19.4 9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z" })] })); };
 /**
  * The Collapser component creates expandable/collapsible content sections with smooth animations.
  */
@@ -22,6 +28,20 @@ var meta = {
             description: 'Whether the collapser should be open by default (uncontrolled mode).',
             table: { defaultValue: { summary: 'false' } },
         },
+        align: {
+            control: 'radio',
+            options: ['left', 'right'],
+            description: "Alignment of the title within the header. Use 'right' for right-aligned titles, typically paired with an icon on the left.",
+            table: { defaultValue: { summary: 'left' } },
+        },
+        icon: {
+            control: false,
+            description: 'Optional icon or React element rendered on the left side of the header, before the title text.',
+        },
+        stepNumber: {
+            control: 'number',
+            description: 'Numeric step label shown on the far left. Auto-injected by `CollapserGroup` when `numbered` is true. Colour controlled via `--dds-collapser-step-number-color`.',
+        },
         children: {
             control: false,
             description: 'Content to show/hide when toggling.',
@@ -35,7 +55,7 @@ var meta = {
     parameters: {
         docs: {
             description: {
-                component: "\nThe Collapser component allows users to show and hide content sections to reduce visual clutter.\n\n## When to Use\n\n- For FAQ sections where answers can be toggled\n- To hide advanced options or detailed information\n- For progressive disclosure of content\n- When you have lengthy content that doesn't need to be visible all the time\n\n## When Not to Use\n\n- For primary navigation (use proper navigation components)\n- For critical information that should always be visible\n- When most users will need to expand all sections (just show the content)\n\n## Accessibility\n\n- Uses proper ARIA attributes (aria-expanded)\n- Keyboard accessible with Enter and Space keys\n- Supports additional keyboard shortcuts: 's' or 'f' to show, 'h' to hide\n- Screen reader friendly\n\n## Keyboard Shortcuts\n\n- **s** or **f**: Show/expand the content\n- **h**: Hide/collapse the content\n- **Enter** or **Space**: Toggle expand/collapse\n        ",
+                component: "\nThe Collapser component allows users to show and hide content sections to reduce visual clutter.\n\n## When to Use\n\n- For FAQ sections where answers can be toggled\n- To hide advanced options or detailed information\n- For progressive disclosure of content\n- When you have lengthy content that doesn't need to be visible all the time\n\n## When Not to Use\n\n- For primary navigation (use proper navigation components)\n- For critical information that should always be visible\n- When most users will need to expand all sections (just show the content)\n\n## Accessibility\n\n- Uses proper ARIA attributes (aria-expanded)\n- Keyboard accessible with Enter and Space keys\n- Supports additional keyboard shortcuts: 's' or 'f' to show, 'h' to hide\n- Screen reader friendly\n- Icons passed via the `icon` prop should be wrapped in a container with `aria-hidden=\"true\"` since the title provides the accessible label\n\n## Keyboard Shortcuts\n\n- **s** or **f**: Show/expand the content\n- **h**: Hide/collapse the content\n- **Enter** or **Space**: Toggle expand/collapse\n\n## Customising Step Numbers\n\nOverride the CSS custom property to change the step number colour:\n\n```css\n.my-steps {\n  --dds-collapser-step-number-color: #7c3aed;\n}\n```\n        ",
             },
         },
     },
@@ -91,6 +111,63 @@ export var WithID = {
         },
     },
 };
+/**
+ * Collapser with an icon rendered on the left side of the header.
+ * The icon prop accepts any React element — use your own icon component or SVG.
+ */
+export var WithIcon = {
+    args: {
+        title: 'Documentation guides',
+        icon: _jsx(IconBook, {}),
+        children: (_jsxs("p", { style: { color: 'var(--dds-collapser-text)' }, children: ["Icons help users quickly identify sections at a glance. Pass any React element to the ", _jsx("code", { children: "icon" }), " prop to display it on the left side of the header."] })),
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Collapser title=\"Documentation guides\" icon={<IconBook />}>\n  <p>\n    Icons help users quickly identify sections at a glance. Pass any React\n    element to the icon prop to display it on the left side of the header.\n  </p>\n</Collapser>",
+            },
+        },
+    },
+};
+/**
+ * Collapser with the title right-aligned within the header.
+ * Use this for design layouts where the title should appear on the right
+ * and content (such as a step number or icon) anchors the left.
+ */
+export var RightAligned = {
+    args: {
+        title: 'Right-aligned title',
+        align: 'right',
+        children: (_jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "The title is right-aligned in the header, with the chevron remaining on the far right. Long titles will wrap to a new line on small screens rather than colliding with other elements." })),
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Collapser title=\"Right-aligned title\" align=\"right\">\n  <p>\n    The title is right-aligned in the header, with the chevron remaining on\n    the far right.\n  </p>\n</Collapser>",
+            },
+        },
+    },
+};
+/**
+ * Collapser with both an icon and right-aligned title — matching the
+ * reference screenshot layout where an icon anchors the left and the
+ * title text flows to the right before the chevron.
+ */
+export var WithIconRightAligned = {
+    args: {
+        title: 'Quick start guide',
+        align: 'right',
+        icon: _jsx(IconBolt, {}),
+        children: (_jsxs("p", { style: { color: 'var(--dds-collapser-text)' }, children: ["Combining ", _jsx("code", { children: "icon" }), " and ", _jsx("code", { children: "align=\"right\"" }), " produces a layout where the icon anchors the left edge, the title flows to the right, and the chevron stays at the far right."] })),
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Collapser title=\"Quick start guide\" align=\"right\" icon={<IconBolt />}>\n  <p>\n    Combining icon and align=\"right\" produces a layout where the icon anchors\n    the left edge, the title flows to the right, and the chevron stays at the far right.\n  </p>\n</Collapser>",
+            },
+        },
+    },
+};
 /**
  * Collapser containing complex content.
  */
@@ -107,6 +184,20 @@ export var ComplexContent = {
         },
     },
 };
+/**
+ * Shows all four header layout variants side-by-side for visual comparison:
+ * default left-aligned, left-aligned with icon, right-aligned, and right-aligned with icon.
+ */
+export var AllVariants = {
+    parameters: {
+        docs: {
+            source: {
+                code: "{/* Left-aligned (default) */}\n<Collapser title=\"Left-aligned (default)\">\n  <p>The standard layout \u2014 title on the left, chevron on the right.</p>\n</Collapser>\n\n{/* Left-aligned with icon */}\n<Collapser title=\"Left-aligned with icon\" icon={<IconBook />}>\n  <p>An icon appears to the left of the title.</p>\n</Collapser>\n\n{/* Right-aligned */}\n<Collapser title=\"Right-aligned title\" align=\"right\">\n  <p>Title text flows to the right. Chevron stays at the far right.</p>\n</Collapser>\n\n{/* Right-aligned with icon */}\n<Collapser title=\"Right-aligned with icon\" align=\"right\" icon={<IconBolt />}>\n  <p>Icon anchors the left, title flows right, chevron at the far right.</p>\n</Collapser>",
+            },
+        },
+    },
+    render: function () { return (_jsxs("div", { children: [_jsx(Collapser, { title: "Left-aligned (default)", children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "The standard layout \u2014 title on the left, chevron on the right." }) }), _jsx(Collapser, { title: "Left-aligned with icon", icon: _jsx(IconBook, {}), children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "An icon appears to the left of the title." }) }), _jsx(Collapser, { title: "Right-aligned title", align: "right", children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "Title text flows to the right. Chevron stays at the far right." }) }), _jsx(Collapser, { title: "Right-aligned with icon", align: "right", icon: _jsx(IconBolt, {}), children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "Icon anchors the left, title flows right, chevron at the far right." }) })] })); },
+};
 /**
  * Multiple collapsers in a FAQ-style layout using CollapserGroup.
  */
@@ -118,5 +209,34 @@ export var FAQExample = {
             },
         },
     },
-    render: function () { return (_jsxs(CollapserGroup, { children: [_jsx(Collapser, { title: "What is this documentation system?", children: _jsx("p", { children: "This is a comprehensive documentation design system that provides reusable components and guidelines for creating effective technical documentation." }) }), _jsx(Collapser, { title: "How do I get started?", children: _jsx("p", { children: "Start by installing the component package, then explore the components in Storybook to understand their usage and configuration options." }) }), _jsx(Collapser, { title: "Can I customize the components?", children: _jsx("p", { children: "Yes! All components accept a className prop for custom styling, and you can override the default styles using CSS." }) }), _jsx(Collapser, { title: "Is this accessible?", children: _jsx("p", { children: "Accessibility is a core principle. All components follow WAI-ARIA best practices and are keyboard navigable." }) })] })); },
+    render: function () { return (_jsxs(CollapserGroup, { children: [_jsx(Collapser, { title: "What is this documentation system?", children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "This is a comprehensive documentation design system that provides reusable components and guidelines for creating effective technical documentation." }) }), _jsx(Collapser, { title: "How do I get started?", children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "Start by installing the component package, then explore the components in Storybook to understand their usage and configuration options." }) }), _jsx(Collapser, { title: "Can I customize the components?", children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "Yes! All components accept a className prop for custom styling, and you can override the default styles using CSS." }) }), _jsx(Collapser, { title: "Is this accessible?", children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "Accessibility is a core principle. All components follow WAI-ARIA best practices and are keyboard navigable." }) })] })); },
+};
+/**
+ * Example matching the reference screenshot: collapsers in a group where each
+ * has a distinct icon on the left and right-aligned title text.
+ */
+export var IconGroupExample = {
+    parameters: {
+        docs: {
+            source: {
+                code: "<CollapserGroup>\n  <Collapser title=\"Getting started\" align=\"right\" icon={<IconBook />}>\n    <p>Learn the basics and set up your environment.</p>\n  </Collapser>\n  <Collapser title=\"Quick actions\" align=\"right\" icon={<IconBolt />}>\n    <p>Discover shortcuts and power-user features.</p>\n  </Collapser>\n  <Collapser title=\"Highlights\" align=\"right\" icon={<IconStar />}>\n    <p>See what makes this system stand out.</p>\n  </Collapser>\n  <Collapser title=\"Configuration\" align=\"right\" icon={<IconSettings />}>\n    <p>Customise the system to fit your workflow.</p>\n  </Collapser>\n</CollapserGroup>",
+            },
+        },
+    },
+    render: function () { return (_jsxs(CollapserGroup, { children: [_jsx(Collapser, { title: "Getting started", align: "right", icon: _jsx(IconBook, {}), children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "Learn the basics and set up your environment." }) }), _jsx(Collapser, { title: "Quick actions", align: "right", icon: _jsx(IconBolt, {}), children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "Discover shortcuts and power-user features." }) }), _jsx(Collapser, { title: "Highlights", align: "right", icon: _jsx(IconStar, {}), children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "See what makes this system stand out." }) }), _jsx(Collapser, { title: "Configuration", align: "right", icon: _jsx(IconSettings, {}), children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "Customise the system to fit your workflow." }) })] })); },
+};
+/**
+ * CollapserGroup with `numbered` auto-numbers each entry.
+ * Matches the reference screenshot pattern: step number + icon on the left,
+ * title right-aligned, chevron on the far right.
+ */
+export var NumberedGroup = {
+    parameters: {
+        docs: {
+            source: {
+                code: "{/* numbered=true on CollapserGroup auto-injects stepNumber into each child */}\n<CollapserGroup numbered>\n  <Collapser title=\"Decrease pain\" align=\"right\" icon={<IconBolt />}>\n    <p>Step numbers are injected automatically by CollapserGroup.</p>\n  </Collapser>\n  <Collapser title=\"Align your workflow\" align=\"right\" icon={<IconBook />}>\n    <p>Combine numbered with icons and right-aligned titles.</p>\n  </Collapser>\n  <Collapser title=\"Learn to move\" align=\"right\" icon={<IconStar />}>\n    <p>Each entry gets a sequential step number on the far left.</p>\n  </Collapser>\n  <Collapser title=\"Configuration\" align=\"right\" icon={<IconSettings />}>\n    <p>Customise the system to fit your workflow.</p>\n  </Collapser>\n</CollapserGroup>",
+            },
+        },
+    },
+    render: function () { return (_jsxs(CollapserGroup, { numbered: true, children: [_jsx(Collapser, { title: "Decrease pain", align: "right", icon: _jsx(IconBolt, {}), children: _jsxs("p", { style: { color: 'var(--dds-collapser-text)' }, children: ["Step numbers are injected automatically by CollapserGroup when", ' ', _jsx("code", { children: "numbered" }), " is true."] }) }), _jsx(Collapser, { title: "Align your workflow", align: "right", icon: _jsx(IconBook, {}), children: _jsxs("p", { style: { color: 'var(--dds-collapser-text)' }, children: ["Combine ", _jsx("code", { children: "numbered" }), " with icons and right-aligned titles for a clean annotated-list layout."] }) }), _jsx(Collapser, { title: "Learn to move", align: "right", icon: _jsx(IconStar, {}), children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "Each entry gets a sequential step number on the far left." }) }), _jsx(Collapser, { title: "Configuration", align: "right", icon: _jsx(IconSettings, {}), children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "Customise the system to fit your workflow." }) })] })); },
 };

package/dist/components/CollapserGroup.d.ts

@@ -11,5 +11,11 @@ export interface CollapserGroupProps {
     onChange?: (openIndexes: number[]) => void;
     /** Additional CSS classes */
     className?: string;
+    /**
+     * Automatically prefix each collapser header with a sequential step number (1, 2, 3…).
+     * The number is injected via the `stepNumber` prop on each `Collapser` child.
+     * @default false
+     */
+    numbered?: boolean;
 }
 export declare const CollapserGroup: React.FC<CollapserGroupProps>;

package/dist/components/CollapserGroup.js

@@ -23,12 +23,12 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useState, Children, cloneElement, isValidElement } from 'react';
 import { Collapser } from './Collapser';
 export var CollapserGroup = function (_a) {
-    var children = _a.children, _b = _a.spacing, spacing = _b === void 0 ? '0.5rem' : _b, _c = _a.allowMultiple, allowMultiple = _c === void 0 ? true : _c, defaultOpen = _a.defaultOpen, onChange = _a.onChange, _d = _a.className, className = _d === void 0 ? '' : _d;
-    var _e = useState(function () {
+    var children = _a.children, _b = _a.spacing, spacing = _b === void 0 ? '0.5rem' : _b, _c = _a.allowMultiple, allowMultiple = _c === void 0 ? true : _c, defaultOpen = _a.defaultOpen, onChange = _a.onChange, _d = _a.className, className = _d === void 0 ? '' : _d, _e = _a.numbered, numbered = _e === void 0 ? false : _e;
+    var _f = useState(function () {
         if (defaultOpen === undefined)
             return [];
         return Array.isArray(defaultOpen) ? defaultOpen : [defaultOpen];
-    }), openIndexes = _e[0], setOpenIndexes = _e[1];
+    }), openIndexes = _f[0], setOpenIndexes = _f[1];
     var handleToggle = function (index) {
         setOpenIndexes(function (prev) {
             var next;
@@ -49,7 +49,7 @@ export var CollapserGroup = function (_a) {
                 return child;
             // Only inject props if child is a Collapser component
             if (child.type === Collapser) {
-                return cloneElement(child, __assign(__assign({}, child.props), { open: openIndexes.includes(index), onToggle: function () { return handleToggle(index); } }));
+                return cloneElement(child, __assign(__assign(__assign({}, child.props), { open: openIndexes.includes(index), onToggle: function () { return handleToggle(index); } }), (numbered ? { stepNumber: index + 1 } : {})));
             }
             return child;
         }) }));

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

@@ -27,3 +27,10 @@ export declare const DefaultOpen: Story;
  * Multiple collapsers open by default.
  */
 export declare const MultipleDefaultOpen: Story;
+/**
+ * Setting `numbered` on CollapserGroup automatically prefixes each collapser header
+ * with a sequential step number (1., 2., …), closely matching the reference screenshot
+ * with number + icon on the left and right-aligned title text.
+ * Customise the number colour with `--dds-collapser-step-number-color`.
+ */
+export declare const NumberedGroup: Story;

package/dist/components/CollapserGroup.stories.js

@@ -12,6 +12,11 @@ var __assign = (this && this.__assign) || function () {
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { CollapserGroup } from './CollapserGroup';
 import { Collapser } from './Collapser';
+// Spoofed icons for the NumberedGroup story (replace with your Icon component when available)
+var IconBolt = function () { return (_jsx("svg", { width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: _jsx("polyline", { points: "13 2 3 14 12 14 11 22 21 10 12 10 13 2" }) })); };
+var IconBook = function () { return (_jsxs("svg", { width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [_jsx("path", { d: "M4 19.5A2.5 2.5 0 0 1 6.5 17H20" }), _jsx("path", { d: "M6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z" })] })); };
+var IconStar = function () { return (_jsx("svg", { width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: _jsx("polygon", { points: "12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2" }) })); };
+var IconSettings = function () { return (_jsxs("svg", { width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [_jsx("circle", { cx: "12", cy: "12", r: "3" }), _jsx("path", { d: "M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83-2.83l.06-.06A1.65 1.65 0 0 0 4.68 15a1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 2.83-2.83l.06.06A1.65 1.65 0 0 0 9 4.68a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 2.83l-.06.06A1.65 1.65 0 0 0 19.4 9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z" })] })); };
 /**
  * CollapserGroup manages multiple Collapser components with consistent spacing
  * and optional accordion behavior.
@@ -48,6 +53,11 @@ var meta = {
             description: 'Additional CSS classes.',
             table: { defaultValue: { summary: '""' } },
         },
+        numbered: {
+            control: 'boolean',
+            description: 'Automatically prefix each collapser header with a sequential step number (1, 2, 3…). Pairs well with `icon` and `align="right"` on child collapsers.',
+            table: { defaultValue: { summary: 'false' } },
+        },
     },
     parameters: {
         docs: {
@@ -139,3 +149,22 @@ export var MultipleDefaultOpen = {
     },
     render: function (args) { return (_jsxs(CollapserGroup, __assign({}, args, { children: [_jsx(Collapser, { title: "Introduction", children: _jsx("p", { children: "This section is open by default." }) }), _jsx(Collapser, { title: "Installation", children: _jsx("p", { children: "This section starts closed." }) }), _jsx(Collapser, { title: "Quick Start", children: _jsx("p", { children: "This section is also open by default." }) })] }))); },
 };
+/**
+ * Setting `numbered` on CollapserGroup automatically prefixes each collapser header
+ * with a sequential step number (1., 2., …), closely matching the reference screenshot
+ * with number + icon on the left and right-aligned title text.
+ * Customise the number colour with `--dds-collapser-step-number-color`.
+ */
+export var NumberedGroup = {
+    args: {
+        numbered: true,
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<CollapserGroup numbered>\n  <Collapser title=\"Decrease pain\" align=\"right\" icon={<IconBolt />}>\n    <p>Step numbers are injected automatically \u2014 no extra props needed on each item.</p>\n  </Collapser>\n  <Collapser title=\"Align your workflow\" align=\"right\" icon={<IconBook />}>\n    <p>Combine numbered with icons and right-aligned titles.</p>\n  </Collapser>\n  <Collapser title=\"Learn to move\" align=\"right\" icon={<IconStar />}>\n    <p>Each entry gets a sequential step number on the far left.</p>\n  </Collapser>\n  <Collapser title=\"Build strength\" align=\"right\" icon={<IconSettings />}>\n    <p>Customise the number colour with --dds-collapser-step-number-color.</p>\n  </Collapser>\n</CollapserGroup>",
+            },
+        },
+    },
+    render: function (args) { return (_jsxs(CollapserGroup, __assign({}, args, { children: [_jsx(Collapser, { title: "Decrease pain", align: "right", icon: _jsx(IconBolt, {}), children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "Step numbers are injected automatically \u2014 no extra props needed on each item." }) }), _jsx(Collapser, { title: "Align your workflow", align: "right", icon: _jsx(IconBook, {}), children: _jsxs("p", { style: { color: 'var(--dds-collapser-text)' }, children: ["Combine ", _jsx("code", { children: "numbered" }), " with icons and right-aligned titles for a clean annotated-list layout."] }) }), _jsx(Collapser, { title: "Learn to move", align: "right", icon: _jsx(IconStar, {}), children: _jsx("p", { style: { color: 'var(--dds-collapser-text)' }, children: "Each entry gets a sequential step number on the far left." }) }), _jsx(Collapser, { title: "Build strength", align: "right", icon: _jsx(IconSettings, {}), children: _jsxs("p", { style: { color: 'var(--dds-collapser-text)' }, children: ["Customise the number colour with ", _jsx("code", { children: "--dds-collapser-step-number-color" }), "."] }) })] }))); },
+};

package/dist/components/Grid.d.ts

@@ -0,0 +1,90 @@
+import { ReactNode } from 'react';
+/** Breakpoint at which columns stack vertically */
+type StackAt = 'sm' | 'md' | 'lg' | 'never';
+/** Vertical alignment of column content */
+type AlignItems = 'start' | 'center' | 'end' | 'stretch';
+/** Configuration for a border or divider line */
+export interface BorderConfig {
+    /**
+     * Line thickness in pixels
+     * @default 1
+     */
+    thickness?: number;
+    /** Line color (defaults to the `--dds-grid-divider-color` token) */
+    color?: string;
+}
+export interface GridProps {
+    /**
+     * Number of equal columns, or an array of fractional widths
+     * (e.g. `[1, 2]` for a 1/3 + 2/3 split).
+     * @default 2
+     */
+    columns?: number | number[];
+    /**
+     * Space between columns. Use `'sm'`, `'md'`, or `'lg'` for design-token sizes,
+     * or any valid CSS length string (e.g. `'16px'`, `'1.5rem'`, `'2em'`).
+     * @default 'md'
+     */
+    gap?: string;
+    /**
+     * Viewport breakpoint at which columns collapse to a single vertical stack.
+     * @default 'md'
+     */
+    stackAt?: StackAt;
+    /**
+     * Vertical dividing line drawn between columns.
+     * Converts to a horizontal rule when the layout stacks.
+     */
+    columnDivider?: BorderConfig;
+    /** Horizontal rule rendered above the grid. */
+    topBorder?: BorderConfig;
+    /** Horizontal rule rendered below the grid. */
+    bottomBorder?: BorderConfig;
+    /**
+     * Vertical alignment of content within each column.
+     * @default 'stretch'
+     */
+    align?: AlignItems;
+    /** Background color applied to the grid container. */
+    backgroundColor?: string;
+    /** Additional CSS classes applied to the grid wrapper. */
+    className?: string;
+    children: ReactNode;
+}
+export interface ColumnProps {
+    /**
+     * How many grid columns this item should span.
+     * @default 1
+     */
+    span?: number;
+    /**
+     * Makes the column content sticky (`position: sticky; top: …`) while adjacent columns scroll.
+     * Useful for tutorial-style layouts with a persistent code panel.
+     * Automatically disabled when the grid stacks on mobile.
+     * @default false
+     */
+    sticky?: boolean;
+    /** Background color applied to the column. */
+    backgroundColor?: string;
+    /** Additional CSS classes applied to the column wrapper. */
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * Multi-column layout container for documentation pages.
+ * Supports equal and fractional column splits, configurable responsive stacking,
+ * optional column dividers, top/bottom borders, and background colours.
+ *
+ * Pair with `<Column>` children to control individual column behaviour.
+ */
+export declare function Grid({ columns, gap, stackAt, columnDivider, topBorder, bottomBorder, align, backgroundColor, className, children, }: GridProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * An individual column within a `<Grid>`.
+ *
+ * Use the `span` prop to make a column occupy more than one grid track, and
+ * `sticky` to keep the column content pinned while adjacent content scrolls.
+ * The column element itself always stretches to the full row height so that
+ * column dividers cover the entire row regardless of which column is taller.
+ */
+export declare function Column({ span, sticky, backgroundColor, className, children, }: ColumnProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Grid.js

@@ -0,0 +1,95 @@
+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 } from "react/jsx-runtime";
+var GAP_TOKEN_MAP = {
+    sm: 'var(--dds-grid-gap-sm)',
+    md: 'var(--dds-grid-gap-md)',
+    lg: 'var(--dds-grid-gap-lg)',
+};
+var ALIGN_MAP = {
+    start: 'start',
+    center: 'center',
+    end: 'end',
+    stretch: 'stretch',
+};
+function resolveGap(gap) {
+    if (gap in GAP_TOKEN_MAP)
+        return GAP_TOKEN_MAP[gap];
+    return gap; // custom CSS length string, e.g. '16px', '1.5rem', '2em'
+}
+/**
+ * Multi-column layout container for documentation pages.
+ * Supports equal and fractional column splits, configurable responsive stacking,
+ * optional column dividers, top/bottom borders, and background colours.
+ *
+ * Pair with `<Column>` children to control individual column behaviour.
+ */
+export function Grid(_a) {
+    var _b, _c, _d, _e, _f, _g;
+    var _h = _a.columns, columns = _h === void 0 ? 2 : _h, _j = _a.gap, gap = _j === void 0 ? 'md' : _j, _k = _a.stackAt, stackAt = _k === void 0 ? 'md' : _k, columnDivider = _a.columnDivider, topBorder = _a.topBorder, bottomBorder = _a.bottomBorder, _l = _a.align, align = _l === void 0 ? 'stretch' : _l, backgroundColor = _a.backgroundColor, _m = _a.className, className = _m === void 0 ? '' : _m, children = _a.children;
+    var columnTemplate = Array.isArray(columns)
+        ? columns.map(function (n) { return "".concat(n, "fr"); }).join(' ')
+        : "repeat(".concat(columns, ", 1fr)");
+    var style = __assign(__assign(__assign(__assign({ '--dds-grid-template-columns': columnTemplate, '--dds-grid-gap': resolveGap(gap), '--dds-grid-align': ALIGN_MAP[align] }, (backgroundColor ? { backgroundColor: backgroundColor } : {})), (topBorder
+        ? {
+            '--dds-grid-top-border-thickness': "".concat((_b = topBorder.thickness) !== null && _b !== void 0 ? _b : 1, "px"),
+            '--dds-grid-top-border-color': (_c = topBorder.color) !== null && _c !== void 0 ? _c : 'var(--dds-grid-divider-color)',
+        }
+        : {})), (bottomBorder
+        ? {
+            '--dds-grid-bottom-border-thickness': "".concat((_d = bottomBorder.thickness) !== null && _d !== void 0 ? _d : 1, "px"),
+            '--dds-grid-bottom-border-color': (_e = bottomBorder.color) !== null && _e !== void 0 ? _e : 'var(--dds-grid-divider-color)',
+        }
+        : {})), (columnDivider
+        ? {
+            '--dds-grid-column-divider-thickness': "".concat((_f = columnDivider.thickness) !== null && _f !== void 0 ? _f : 1, "px"),
+            '--dds-grid-column-divider-color': (_g = columnDivider.color) !== null && _g !== void 0 ? _g : 'var(--dds-grid-divider-color)',
+        }
+        : {}));
+    var classNames = [
+        'dds-grid',
+        "dds-grid-stack-".concat(stackAt),
+        topBorder ? 'dds-grid-has-top-border' : '',
+        bottomBorder ? 'dds-grid-has-bottom-border' : '',
+        columnDivider ? 'dds-grid-has-column-divider' : '',
+        className,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return (_jsx("div", { className: classNames, style: style, children: children }));
+}
+/**
+ * An individual column within a `<Grid>`.
+ *
+ * Use the `span` prop to make a column occupy more than one grid track, and
+ * `sticky` to keep the column content pinned while adjacent content scrolls.
+ * The column element itself always stretches to the full row height so that
+ * column dividers cover the entire row regardless of which column is taller.
+ */
+export function Column(_a) {
+    var span = _a.span, _b = _a.sticky, sticky = _b === void 0 ? false : _b, backgroundColor = _a.backgroundColor, _c = _a.className, className = _c === void 0 ? '' : _c, children = _a.children;
+    var style = {};
+    if (span && span > 1) {
+        style.gridColumn = "span ".concat(span);
+    }
+    if (backgroundColor) {
+        style.backgroundColor = backgroundColor;
+    }
+    var classNames = [
+        'dds-grid-column',
+        sticky ? 'dds-grid-column-sticky' : '',
+        className,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return (_jsx("div", { className: classNames, style: style, children: sticky ? (_jsx("div", { className: "dds-grid-column-sticky-inner", children: children })) : (children) }));
+}

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

@@ -0,0 +1,69 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Grid } from './Grid';
+/**
+ * `Grid` and `Column` provide a flexible multi-column layout for documentation pages.
+ * Common patterns include side-by-side comparisons, image + annotation, and
+ * tutorial-style instruction / code pairings.
+ */
+declare const meta: Meta<typeof Grid>;
+export default meta;
+type Story = StoryObj<typeof Grid>;
+/**
+ * Fully interactive default story — all controls in the prop table affect this
+ * live preview. Adjust `columns`, `gap`, `stackAt`, `align`, `columnDivider`,
+ * `topBorder`, `bottomBorder`, and `backgroundColor` via the Controls panel.
+ */
+export declare const Default: Story;
+/**
+ * Two equal columns — the default layout. Columns stack vertically at the `md`
+ * breakpoint (768 px) by default.
+ */
+export declare const TwoEqualColumns: Story;
+/**
+ * Three equal columns, with a top and bottom border to create a contained
+ * "feature grid" panel. Useful for listing icons with short descriptions.
+ */
+export declare const ThreeColumnFeatureGrid: Story;
+/**
+ * Asymmetric 1/3 + 2/3 split — pass an array of fractional weights.
+ * A common pattern for a narrow label / sidebar alongside wide content.
+ */
+export declare const AsymmetricSplit: Story;
+/**
+ * Image + annotation layout. `align="center"` vertically centres the shorter
+ * column when image and text have different heights.
+ */
+export declare const ImageAndText: Story;
+/**
+ * Tutorial layout — prose instructions on the left, sticky code panel on the
+ * right. The code panel stays in view while the user scrolls through the steps.
+ * The column divider runs the full height of the row regardless of which column
+ * is taller. The `sticky` prop is automatically disabled when the grid stacks.
+ */
+export declare const TutorialWithStickyCode: Story;
+/**
+ * Column dividers — a vertical line between columns that converts to a
+ * horizontal rule at the stacking breakpoint.
+ */
+export declare const WithColumnDivider: Story;
+/**
+ * Background colors — apply a background to the entire grid and / or to
+ * individual columns using the `backgroundColor` prop.
+ */
+export declare const BackgroundColors: Story;
+/**
+ * Large gap between columns — useful when columns contain rich content
+ * that needs extra breathing room.
+ */
+export declare const LargeGap: Story;
+/**
+ * Custom gap — pass any CSS length string such as `'1.5rem'` or `'40px'`
+ * for fine-grained control beyond the named size tokens.
+ */
+export declare const CustomGap: Story;
+/**
+ * Span — a column set to `span={2}` occupies two grid tracks.
+ * Useful for full-width content (e.g. a summary row) inside an otherwise
+ * multi-column grid.
+ */
+export declare const ColumnSpan: Story;

package/dist/components/Grid.stories.js

@@ -0,0 +1,259 @@
+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 { Grid } from './Grid';
+import { Column } from './Grid';
+import { CodeBlock } from './CodeBlock';
+/**
+ * `Grid` and `Column` provide a flexible multi-column layout for documentation pages.
+ * Common patterns include side-by-side comparisons, image + annotation, and
+ * tutorial-style instruction / code pairings.
+ */
+var meta = {
+    title: 'Components/Grid',
+    component: Grid,
+    tags: ['autodocs'],
+    argTypes: {
+        columns: {
+            control: { type: 'object' },
+            description: 'Number of equal columns, or an array of fractional weights for asymmetric splits (e.g. `[1, 2]` → 1/3 + 2/3). Enter a number or a JSON array in the control.',
+            table: { defaultValue: { summary: '2' } },
+        },
+        gap: {
+            control: { type: 'select' },
+            options: ['sm', 'md', 'lg', '0.5rem', '1rem', '1.5rem', '2rem', '3rem', '8px', '16px', '24px', '32px'],
+            description: "Space between columns. Use `'sm'`, `'md'`, or `'lg'` for design-token sizes, or any CSS length string (e.g. `'16px'`, `'1.5rem'`).",
+            table: { defaultValue: { summary: "'md'" } },
+        },
+        stackAt: {
+            control: { type: 'select' },
+            options: ['sm', 'md', 'lg', 'never'],
+            description: 'Breakpoint at which columns collapse to a single vertical stack.',
+            table: { defaultValue: { summary: "'md'" } },
+        },
+        align: {
+            control: { type: 'select' },
+            options: ['start', 'center', 'end', 'stretch'],
+            description: 'Vertical alignment of content within each column.',
+            table: { defaultValue: { summary: "'stretch'" } },
+        },
+        columnDivider: {
+            control: { type: 'object' },
+            description: 'Vertical line between columns (`{ thickness?: number; color?: string }`). Converts to a horizontal rule when stacked.',
+        },
+        topBorder: {
+            control: { type: 'object' },
+            description: 'Horizontal rule above the grid (`{ thickness?: number; color?: string }`).',
+        },
+        bottomBorder: {
+            control: { type: 'object' },
+            description: 'Horizontal rule below the grid (`{ thickness?: number; color?: string }`).',
+        },
+        backgroundColor: {
+            control: 'color',
+            description: 'Background color for the entire grid container.',
+        },
+        className: {
+            control: 'text',
+            description: 'Additional CSS classes applied to the grid wrapper.',
+            table: { defaultValue: { summary: '""' } },
+        },
+        children: {
+            control: false,
+            description: 'Grid content — typically `Column` components.',
+        },
+    },
+    parameters: {
+        docs: {
+            description: {
+                component: "\nLayout primitive for multi-column documentation content.\n\n## When to Use\n\n- **Image + annotation** \u2014 screenshot or diagram on one side, feature callouts on the other\n- **Tutorial / live demo** \u2014 prose instructions on one side, sticky code panel on the other\n- **Side-by-side comparison** \u2014 before/after, two approaches, or option A vs option B\n- **Feature grid** \u2014 icon + short description repeated across columns\n\n## When Not to Use\n\n- For card-style repeating items of the same type \u2014 use `CardGrid` instead\n- For a single column of content \u2014 use standard block-level markup\n\n## Accessibility\n\n- Rendered as a semantic `<div>`; no implicit ARIA role (not a data table)\n- Source order should match reading order; avoid visual reordering via CSS `order`\n- Column dividers are decorative and carry no meaning for assistive technology\n        ",
+            },
+        },
+    },
+};
+export default meta;
+/* -------------------------------------------------------------------------- */
+/* Helpers                                                                     */
+/* -------------------------------------------------------------------------- */
+var textColor = { color: 'var(--dds-tabs-panel-text)' };
+var subtle = { color: 'var(--dds-tabs-panel-text)', fontFamily: 'sans-serif', margin: 0 };
+function Placeholder(_a) {
+    var label = _a.label, _b = _a.height, height = _b === void 0 ? 120 : _b, _c = _a.bg, bg = _c === void 0 ? 'rgba(99,102,241,0.1)' : _c;
+    return (_jsx("div", { style: __assign(__assign({ display: 'flex', alignItems: 'center', justifyContent: 'center', height: height, background: bg, borderRadius: 6 }, textColor), { fontFamily: 'sans-serif', fontWeight: 600, fontSize: '0.875rem' }), children: label }));
+}
+/* -------------------------------------------------------------------------- */
+/* Stories                                                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * Fully interactive default story — all controls in the prop table affect this
+ * live preview. Adjust `columns`, `gap`, `stackAt`, `align`, `columnDivider`,
+ * `topBorder`, `bottomBorder`, and `backgroundColor` via the Controls panel.
+ */
+export var Default = {
+    args: {
+        columns: 2,
+        gap: 'md',
+        stackAt: 'md',
+        align: 'stretch',
+    },
+    render: function (args) { return (_jsxs(Grid, __assign({}, args, { children: [_jsx(Column, { children: _jsx(Placeholder, { label: "Column 1" }) }), _jsx(Column, { children: _jsx(Placeholder, { label: "Column 2" }) })] }))); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={2} gap=\"md\">\n  <Column>Column 1 content</Column>\n  <Column>Column 2 content</Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Two equal columns — the default layout. Columns stack vertically at the `md`
+ * breakpoint (768 px) by default.
+ */
+export var TwoEqualColumns = {
+    render: function () { return (_jsxs(Grid, { columns: 2, children: [_jsx(Column, { children: _jsx(Placeholder, { label: "Column 1" }) }), _jsx(Column, { children: _jsx(Placeholder, { label: "Column 2" }) })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={2}>\n  <Column>Column 1 content</Column>\n  <Column>Column 2 content</Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Three equal columns, with a top and bottom border to create a contained
+ * "feature grid" panel. Useful for listing icons with short descriptions.
+ */
+export var ThreeColumnFeatureGrid = {
+    render: function () { return (_jsxs(Grid, { columns: 3, gap: "md", topBorder: { color: 'var(--dds-grid-divider-color)' }, bottomBorder: { color: 'var(--dds-grid-divider-color)' }, children: [_jsx(Column, { children: _jsxs("p", { style: subtle, children: [_jsx("strong", { children: "Feature A" }), _jsx("br", {}), "Short description of the feature."] }) }), _jsx(Column, { children: _jsxs("p", { style: subtle, children: [_jsx("strong", { children: "Feature B" }), _jsx("br", {}), "Short description of the feature."] }) }), _jsx(Column, { children: _jsxs("p", { style: subtle, children: [_jsx("strong", { children: "Feature C" }), _jsx("br", {}), "Short description of the feature."] }) })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid\n  columns={3}\n  gap=\"md\"\n  topBorder={{ color: '#ccc' }}\n  bottomBorder={{ color: '#ccc' }}\n>\n  <Column><strong>Feature A</strong> \u2014 Short description.</Column>\n  <Column><strong>Feature B</strong> \u2014 Short description.</Column>\n  <Column><strong>Feature C</strong> \u2014 Short description.</Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Asymmetric 1/3 + 2/3 split — pass an array of fractional weights.
+ * A common pattern for a narrow label / sidebar alongside wide content.
+ */
+export var AsymmetricSplit = {
+    render: function () { return (_jsxs(Grid, { columns: [1, 2], children: [_jsx(Column, { children: _jsx(Placeholder, { label: "1 / 3", height: 160, bg: "rgba(16,185,129,0.1)" }) }), _jsx(Column, { children: _jsx(Placeholder, { label: "2 / 3", height: 160, bg: "rgba(99,102,241,0.1)" }) })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={[1, 2]}>\n  <Column>Narrow (1/3)</Column>\n  <Column>Wide (2/3)</Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Image + annotation layout. `align="center"` vertically centres the shorter
+ * column when image and text have different heights.
+ */
+export var ImageAndText = {
+    render: function () { return (_jsxs(Grid, { columns: [1, 2], align: "center", columnDivider: { color: 'var(--dds-grid-divider-color)' }, children: [_jsx(Column, { children: _jsx(Placeholder, { label: "Diagram / Screenshot", height: 200, bg: "rgba(234,179,8,0.1)" }) }), _jsxs(Column, { children: [_jsx("p", { style: __assign(__assign({}, subtle), { marginBottom: '0.5rem' }), children: _jsx("strong", { children: "What you're looking at" }) }), _jsxs("p", { style: subtle, children: ["This panel describes the key elements of the diagram on the left. Use ", _jsx("code", { children: "align=\"center\"" }), " so short text stays vertically centred next to a taller image."] })] })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={[1, 2]} align=\"center\" columnDivider={{ color: '#ddd' }}>\n  <Column>\n    <img src=\"/diagram.png\" alt=\"Architecture diagram\" />\n  </Column>\n  <Column>\n    <h3>What you're looking at</h3>\n    <p>Description of the diagram elements...</p>\n  </Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Tutorial layout — prose instructions on the left, sticky code panel on the
+ * right. The code panel stays in view while the user scrolls through the steps.
+ * The column divider runs the full height of the row regardless of which column
+ * is taller. The `sticky` prop is automatically disabled when the grid stacks.
+ */
+export var TutorialWithStickyCode = {
+    render: function () { return (_jsxs(Grid, { columns: 2, stackAt: "lg", gap: "lg", columnDivider: { thickness: 2, color: 'var(--dds-grid-divider-color)' }, children: [_jsxs(Column, { children: [_jsx("p", { style: __assign(__assign({}, subtle), { marginBottom: '1rem' }), children: _jsx("strong", { children: "Step 1 \u2014 Install dependencies" }) }), _jsx("p", { style: __assign(__assign({}, subtle), { marginBottom: '1rem' }), children: "Run the installer and follow the prompts. This sets up the project scaffold and pulls in all required packages." }), _jsx("p", { style: __assign(__assign({}, subtle), { marginBottom: '1rem' }), children: _jsx("strong", { children: "Step 2 \u2014 Configure your project" }) }), _jsxs("p", { style: __assign(__assign({}, subtle), { marginBottom: '1rem' }), children: ["Open ", _jsx("code", { children: "config.ts" }), " and update the values for your environment. Refer to the code panel on the right for a complete example."] }), _jsx("p", { style: __assign(__assign({}, subtle), { marginBottom: '1rem' }), children: _jsx("strong", { children: "Step 3 \u2014 Start the dev server" }) }), _jsx("p", { style: subtle, children: "Run the dev command. The server watches for file changes and hot-reloads automatically." })] }), _jsx(Column, { sticky: true, children: _jsx(CodeBlock, { language: "bash", code: "npm install\n\nnpm run dev" }) })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={2} stackAt=\"lg\" gap=\"lg\" columnDivider={{ thickness: 2 }}>\n  <Column>\n    {/* Step-by-step instructions */}\n    <p><strong>Step 1 \u2014 Install dependencies</strong></p>\n    <p>Run the installer and follow the prompts.</p>\n    {/* \u2026 more steps \u2026 */}\n  </Column>\n  <Column sticky>\n    <CodeBlock language=\"bash\" code=\"npm install\\n\\nnpm run dev\" />\n  </Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Column dividers — a vertical line between columns that converts to a
+ * horizontal rule at the stacking breakpoint.
+ */
+export var WithColumnDivider = {
+    render: function () { return (_jsxs(Grid, { columns: 3, columnDivider: { thickness: 1, color: 'var(--dds-grid-divider-color)' }, children: [_jsxs(Column, { children: [_jsx("p", { style: subtle, children: _jsx("strong", { children: "Option A" }) }), _jsx("p", { style: subtle, children: "Description of the first approach." })] }), _jsxs(Column, { children: [_jsx("p", { style: subtle, children: _jsx("strong", { children: "Option B" }) }), _jsx("p", { style: subtle, children: "Description of the second approach." })] }), _jsxs(Column, { children: [_jsx("p", { style: subtle, children: _jsx("strong", { children: "Option C" }) }), _jsx("p", { style: subtle, children: "Description of the third approach." })] })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={3} columnDivider={{ thickness: 1, color: '#e0e0e0' }}>\n  <Column>\n    <strong>Option A</strong>\n    <p>Description of the first approach.</p>\n  </Column>\n  <Column>\n    <strong>Option B</strong>\n    <p>Description of the second approach.</p>\n  </Column>\n  <Column>\n    <strong>Option C</strong>\n    <p>Description of the third approach.</p>\n  </Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Background colors — apply a background to the entire grid and / or to
+ * individual columns using the `backgroundColor` prop.
+ */
+export var BackgroundColors = {
+    render: function () { return (_jsxs(Grid, { columns: 2, gap: "lg", backgroundColor: "rgba(99,102,241,0.04)", children: [_jsxs(Column, { backgroundColor: "rgba(16,185,129,0.08)", children: [_jsx("p", { style: subtle, children: _jsx("strong", { children: "Column with background" }) }), _jsx("p", { style: subtle, children: "Each column can have its own background color." })] }), _jsxs(Column, { backgroundColor: "rgba(234,179,8,0.08)", children: [_jsx("p", { style: subtle, children: _jsx("strong", { children: "Another column background" }) }), _jsxs("p", { style: subtle, children: ["The grid container also has a light background applied via", ' ', _jsx("code", { children: "backgroundColor" }), " on the ", _jsx("code", { children: "Grid" }), "."] })] })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={2} gap=\"lg\" backgroundColor=\"rgba(99,102,241,0.04)\">\n  <Column backgroundColor=\"rgba(16,185,129,0.08)\">\n    <strong>Column with background</strong>\n    <p>Each column can have its own background color.</p>\n  </Column>\n  <Column backgroundColor=\"rgba(234,179,8,0.08)\">\n    <strong>Another column background</strong>\n    <p>Set on both the Grid container and individual Columns.</p>\n  </Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Large gap between columns — useful when columns contain rich content
+ * that needs extra breathing room.
+ */
+export var LargeGap = {
+    render: function () { return (_jsxs(Grid, { columns: 2, gap: "lg", children: [_jsx(Column, { children: _jsx(Placeholder, { label: "Column 1", height: 140 }) }), _jsx(Column, { children: _jsx(Placeholder, { label: "Column 2", height: 140 }) })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={2} gap=\"lg\">\n  <Column>Column 1 content</Column>\n  <Column>Column 2 content</Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Custom gap — pass any CSS length string such as `'1.5rem'` or `'40px'`
+ * for fine-grained control beyond the named size tokens.
+ */
+export var CustomGap = {
+    render: function () { return (_jsxs(Grid, { columns: 2, gap: "3rem", children: [_jsx(Column, { children: _jsx(Placeholder, { label: "Column 1", height: 140 }) }), _jsx(Column, { children: _jsx(Placeholder, { label: "Column 2", height: 140 }) })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={2} gap=\"3rem\">\n  <Column>Column 1 content</Column>\n  <Column>Column 2 content</Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Span — a column set to `span={2}` occupies two grid tracks.
+ * Useful for full-width content (e.g. a summary row) inside an otherwise
+ * multi-column grid.
+ */
+export var ColumnSpan = {
+    render: function () { return (_jsxs(Grid, { columns: 3, gap: "md", children: [_jsx(Column, { children: _jsx(Placeholder, { label: "Col 1" }) }), _jsx(Column, { children: _jsx(Placeholder, { label: "Col 2" }) }), _jsx(Column, { children: _jsx(Placeholder, { label: "Col 3" }) }), _jsx(Column, { span: 3, children: _jsx(Placeholder, { label: "Spans all 3 columns", height: 60, bg: "rgba(239,68,68,0.1)" }) })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={3} gap=\"md\">\n  <Column>Col 1</Column>\n  <Column>Col 2</Column>\n  <Column>Col 3</Column>\n  <Column span={3}>Spans all 3 columns</Column>\n</Grid>",
+            },
+        },
+    },
+};

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/styles.css

@@ -207,8 +207,10 @@
   --dds-collapser-button-padding: 0.75rem; /* p-3 */
   --dds-collapser-button-hover-bg: #f9fafb; /* gray-50 */
   --dds-collapser-icon-color: #6b7280; /* gray-500 */
+  --dds-collapser-step-number-color: #6b7280; /* gray-500 — override to customise step numbers */
   --dds-collapser-text: #374151; /* gray-700 */
   --dds-collapser-content-padding: 1rem; /* p-4 */
+  --dds-collapser-header-gap: 0.5rem;
 
   /* Tabs */
   --dds-tabs-margin: 1rem 0;
@@ -256,6 +258,13 @@
   --dds-list-badge-shadow: inset 0 0 0 1px #bfc2c7;
   --dds-list-connector-line: #eceef2; /* gray-200 */
   --dds-list-text: #374151; /* gray-700 */
+
+  /* Grid */
+  --dds-grid-gap-sm: 1rem; /* gap-4 */
+  --dds-grid-gap-md: 1.5rem; /* gap-6 */
+  --dds-grid-gap-lg: 2.5rem; /* gap-10 */
+  --dds-grid-divider-color: #e5e7eb; /* gray-200 */
+  --dds-grid-sticky-top: 1rem;
 }
 /* ==========================================================================
    Dark Mode Tokens
@@ -342,6 +351,7 @@
   --dds-collapser-border: #4b5563; /* gray-600 */
   --dds-collapser-button-hover-bg: rgba(255, 255, 255, 0.05);
   --dds-collapser-icon-color: #9ca3af; /* gray-400 */
+  --dds-collapser-step-number-color: #9ca3af;
   --dds-collapser-text: #e5e7eb; /* gray-200 */
 
   /* Tabs */
@@ -416,6 +426,9 @@
   --dds-list-badge-shadow: inset 0 0 0 1px #353a42;
   --dds-list-connector-line: #353a42; /* gray-600 */
   --dds-list-text: #e5e7eb; /* gray-200 */
+
+  /* Grid */
+  --dds-grid-divider-color: #4b5563; /* gray-600 */
 }
 /* Auto dark mode — follows OS preference, opt-out with .dds-light */
 @media (prefers-color-scheme: dark) {
@@ -497,6 +510,7 @@
     --dds-collapser-border: #4b5563;
     --dds-collapser-button-hover-bg: rgba(255, 255, 255, 0.05);
     --dds-collapser-icon-color: #9ca3af;
+    --dds-collapser-step-number-color: #9ca3af;
     --dds-collapser-text: #e5e7eb;
 
     /* Tabs */
@@ -571,6 +585,9 @@
     --dds-list-badge-shadow: inset 0 0 0 1px #353a42;
     --dds-list-connector-line: #353a42; /* gray-600 */
     --dds-list-text: #e5e7eb; /* gray-200 */
+
+    /* Grid */
+    --dds-grid-divider-color: #4b5563; /* gray-600 */
   }
 }
 /* Explicit dark mode via data attribute (overrides OS preference) */
@@ -652,6 +669,7 @@
   --dds-collapser-border: #4b5563;
   --dds-collapser-button-hover-bg: rgba(255, 255, 255, 0.05);
   --dds-collapser-icon-color: #9ca3af;
+  --dds-collapser-step-number-color: #9ca3af;
   --dds-collapser-text: #e5e7eb;
 
   /* CodeBlock */
@@ -1101,6 +1119,7 @@ a.no-text-decoration {
   padding: var(--dds-collapser-button-padding);
   display: flex;
   align-items: center;
+  gap: var(--dds-collapser-header-gap);
   transition: var(--dds-transition-colors);
   border: none;
   background: transparent;
@@ -1112,6 +1131,18 @@ a.no-text-decoration {
   background-color: var(--dds-collapser-button-hover-bg);
   outline: none;
 }
+.dds-collapser-step-number {
+  flex-shrink: 0;
+  min-width: 1.5em;
+  font-variant-numeric: tabular-nums;
+  color: var(--dds-collapser-step-number-color);
+}
+.dds-collapser-header-icon {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+  color: var(--dds-collapser-icon-color);
+}
 .dds-collapser-title {
   display: flex;
   align-items: center;
@@ -1120,12 +1151,18 @@ a.no-text-decoration {
   margin: 0;
   font-weight: bold;
   color: var(--dds-heading-color);
+  word-break: break-word;
+  min-width: 0;
+}
+.dds-collapser--align-right .dds-collapser-title {
+  justify-content: flex-end;
+  text-align: right;
 }
 .dds-collapser-icon {
   margin-left: auto;
+  flex-shrink: 0;
   transition: transform 0.3s ease;
   color: var(--dds-collapser-icon-color);
-  flex-shrink: 0;
 }
 .dds-collapser-icon-open {
   transform: rotate(180deg);
@@ -1808,4 +1845,107 @@ a.no-text-decoration {
     }
   }
 }
+/* =============================================================================
+   Grid — multi-column layout component
+   ============================================================================= */
+/* Base grid container */
+.dds-grid {
+  display: grid;
+  grid-template-columns: var(--dds-grid-template-columns, repeat(2, 1fr));
+  gap: var(--dds-grid-gap, var(--dds-grid-gap-md));
+  align-items: var(--dds-grid-align, stretch);
+}
+/* Optional top border */
+.dds-grid-has-top-border {
+  border-top: var(--dds-grid-top-border-thickness, 1px) solid
+    var(--dds-grid-top-border-color, var(--dds-grid-divider-color));
+  padding-top: var(--dds-grid-gap, var(--dds-grid-gap-md));
+}
+/* Optional bottom border */
+.dds-grid-has-bottom-border {
+  border-bottom: var(--dds-grid-bottom-border-thickness, 1px) solid
+    var(--dds-grid-bottom-border-color, var(--dds-grid-divider-color));
+  padding-bottom: var(--dds-grid-gap, var(--dds-grid-gap-md));
+}
+/* Column divider — vertical line between columns */
+.dds-grid-has-column-divider .dds-grid-column + .dds-grid-column {
+  border-left: var(--dds-grid-column-divider-thickness, 1px) solid
+    var(--dds-grid-column-divider-color, var(--dds-grid-divider-color));
+  padding-left: var(--dds-grid-gap, var(--dds-grid-gap-md));
+}
+/* Individual column */
+.dds-grid-column {
+  /* Prevent grid cells from overflowing (e.g. wide code blocks) */
+  min-width: 0;
+}
+/* Sticky column — column div stretches to full row height so that border-left
+   covers the entire row. The CONTENT inside is what scrolls sticky, via the
+   inner wrapper. */
+.dds-grid-column-sticky {
+  /* No align-self override — stretches naturally to row height */
+}
+/* Inner wrapper that provides the actual sticky scroll behaviour */
+.dds-grid-column-sticky-inner {
+  position: sticky;
+  top: var(--dds-grid-sticky-top, 1rem);
+}
+/* =============================================================================
+   Responsive stacking — columns collapse to a single vertical track
+   ============================================================================= */
+/* Stack at sm breakpoint (≤ 640 px) */
+@media (max-width: 640px) {
+  .dds-grid-stack-sm {
+    grid-template-columns: 1fr;
+  }
+
+  /* Column divider becomes a horizontal rule when stacked */
+  .dds-grid-stack-sm.dds-grid-has-column-divider .dds-grid-column + .dds-grid-column {
+    border-left: none;
+    padding-left: 0;
+    border-top: var(--dds-grid-column-divider-thickness, 1px) solid
+      var(--dds-grid-column-divider-color, var(--dds-grid-divider-color));
+    padding-top: var(--dds-grid-gap, var(--dds-grid-gap-md));
+  }
+
+  /* Sticky inner wrapper no-ops when stacked */
+  .dds-grid-stack-sm .dds-grid-column-sticky-inner {
+    position: static;
+  }
+}
+/* Stack at md breakpoint (≤ 768 px) */
+@media (max-width: 768px) {
+  .dds-grid-stack-md {
+    grid-template-columns: 1fr;
+  }
+
+  .dds-grid-stack-md.dds-grid-has-column-divider .dds-grid-column + .dds-grid-column {
+    border-left: none;
+    padding-left: 0;
+    border-top: var(--dds-grid-column-divider-thickness, 1px) solid
+      var(--dds-grid-column-divider-color, var(--dds-grid-divider-color));
+    padding-top: var(--dds-grid-gap, var(--dds-grid-gap-md));
+  }
+
+  .dds-grid-stack-md .dds-grid-column-sticky-inner {
+    position: static;
+  }
+}
+/* Stack at lg breakpoint (≤ 1024 px) */
+@media (max-width: 1024px) {
+  .dds-grid-stack-lg {
+    grid-template-columns: 1fr;
+  }
+
+  .dds-grid-stack-lg.dds-grid-has-column-divider .dds-grid-column + .dds-grid-column {
+    border-left: none;
+    padding-left: 0;
+    border-top: var(--dds-grid-column-divider-thickness, 1px) solid
+      var(--dds-grid-column-divider-color, var(--dds-grid-divider-color));
+    padding-top: var(--dds-grid-gap, var(--dds-grid-gap-md));
+  }
+
+  .dds-grid-stack-lg .dds-grid-column-sticky-inner {
+    position: static;
+  }
+}
 

package/package.json

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