@roadlittledawn/docs-design-system-react 0.5.0 → 0.6.1

package/README.md

@@ -1,8 +1,9 @@
 # @roadlittledawn/docs-design-system-react
 
-React components for building documentation interfaces.
+[![npm version](https://img.shields.io/npm/v/@roadlittledawn/docs-design-system-react.svg)](https://www.npmjs.com/package/@roadlittledawn/docs-design-system-react)
+[![GitHub](https://img.shields.io/badge/github-repo-blue.svg)](https://github.com/roadlittledawn/docs-design-system)
 
-See [package on NPM](https://www.npmjs.com/package/@roadlittledawn/docs-design-system-react).
+React components for documentation content and MDX-driven sites.
 
 ## Installation
 
@@ -30,91 +31,13 @@ import "@roadlittledawn/docs-design-system-react/styles.css";
 
 ## Components
 
-### Callout
+Full component documentation with live examples, usage guidelines, and API documentation is available in Storybook:
 
-Highlight important information, warnings, tips, or notes.
+**[View Component Documentation →](https://docs-design-system-storybook.netlify.app/?path=/docs/components-button--docs)**
 
-```tsx
-<Callout variant="tip">This is a helpful tip!</Callout>
-```
-
-### CodeBlock
-
-Syntax-highlighted code with copy functionality.
-
-```tsx
-<CodeBlock language="javascript">
-  {`const greeting = "Hello, world!";`}
-</CodeBlock>
-```
-
-### Collapser
-
-Expandable/collapsible sections for optional or detailed content.
-
-```tsx
-<Collapser title="More details">Hidden content revealed on expand.</Collapser>
-```
-
-### Card
-
-Clickable card for navigation or content grouping.
-
-```tsx
-<Card title="Getting Started" href="/docs/intro">
-  Learn the basics.
-</Card>
-```
-
-### CardGrid
-
-Grid layout for organizing multiple cards.
-
-```tsx
-<CardGrid columns={3}>
-  <Card title="Guide 1" href="/guide-1">
-    Description
-  </Card>
-  <Card title="Guide 2" href="/guide-2">
-    Description
-  </Card>
-</CardGrid>
-```
+## Next.js / React Server Components
 
-### Typography
-
-Text component with semantic variants.
-
-```tsx
-<Typography variant="body">Paragraph text</Typography>
-```
-
-### Heading
-
-Semantic heading levels.
-
-```tsx
-<Heading level={2}>Section Title</Heading>
-```
-
-### Link
-
-Styled anchor with external link detection.
-
-```tsx
-<Link href="/docs">Internal link</Link>
-<Link href="https://example.com">External link</Link>
-```
-
-### Button
-
-Action button with variants.
-
-```tsx
-<Button variant="primary" onClick={handleClick}>
-  Click me
-</Button>
-```
+Interactive components (`Collapser`, `CollapserGroup`, `CodeBlock`, `Tabs`, `Popover`) are pre-marked with `'use client'`, so they work in Next.js App Router without any extra setup. Stateless components (`Button`, `Callout`, `Card`, `CardGrid`, `Heading`, `Link`, `List`, `Typography`) have no directive and are fully usable as Server Components.
 
 ## Dark Mode
 
@@ -175,11 +98,7 @@ Listen for keyboard events.
 const isPressed = useKeyPress("Escape");
 ```
 
-## Documentation
-
-Full component documentation with live examples is available in our Storybook.
-
-**Storybook URL:** _Coming soon_
+Full hook documentation is available in [Storybook](https://docs-design-system-storybook.netlify.app).
 
 ## Development
 

package/dist/components/CodeBlock.js

@@ -1,3 +1,4 @@
+'use client';
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {

package/dist/components/Collapser.js

@@ -1,3 +1,4 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState, useRef, useEffect } from "react";
 import { useKeyPress } from "../hooks/useKeyPress";

package/dist/components/CollapserGroup.js

@@ -1,3 +1,4 @@
+'use client';
 var __assign = (this && this.__assign) || function () {
     __assign = Object.assign || function(t) {
         for (var s, i = 1, n = arguments.length; i < n; i++) {

package/dist/components/List.d.ts

@@ -0,0 +1,26 @@
+import { ReactNode, FC } from "react";
+export interface ListProps {
+    /** List items */
+    children: ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+    /** Whether the list is ordered (numbered) or unordered (bullets). Default: true */
+    ordered?: boolean;
+    /** Custom bullet character for unordered lists (emoji or text). Only applies when ordered=false */
+    bullet?: string;
+    /** Custom bullet icon (React node, e.g., SVG) for unordered lists. Takes precedence over bullet prop */
+    bulletIcon?: ReactNode;
+}
+interface ListItemProps {
+    /** List item content */
+    children: ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+    /** Internal: bullet icon injected by List parent for unordered lists */
+    bulletIcon?: ReactNode;
+}
+export declare function ListItem({ children, className, bulletIcon }: ListItemProps): import("react/jsx-runtime").JSX.Element;
+export declare const List: FC<ListProps> & {
+    Item: typeof ListItem;
+};
+export {};

package/dist/components/List.js

@@ -0,0 +1,36 @@
+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";
+function ListImpl(_a) {
+    var children = _a.children, _b = _a.className, className = _b === void 0 ? "" : _b, _c = _a.ordered, ordered = _c === void 0 ? true : _c, bullet = _a.bullet, bulletIcon = _a.bulletIcon;
+    var listClasses = ["dds-list", className].filter(Boolean).join(" ");
+    var Element = ordered ? "ol" : "ul";
+    return (_jsx(Element, { className: listClasses, "data-ordered": ordered, "data-has-icon": !!bulletIcon && !ordered, style: bullet && !bulletIcon
+            ? { "--dds-list-bullet": JSON.stringify(bullet) }
+            : undefined, children: bulletIcon && !ordered
+            ? React.Children.map(children, function (child) {
+                if (React.isValidElement(child) && child.type === ListItem) {
+                    return React.cloneElement(child, __assign(__assign({}, child.props), { bulletIcon: bulletIcon }));
+                }
+                return child;
+            })
+            : children }));
+}
+export function ListItem(_a) {
+    var children = _a.children, _b = _a.className, className = _b === void 0 ? "" : _b, bulletIcon = _a.bulletIcon;
+    var itemClasses = ["dds-list-item", className].filter(Boolean).join(" ");
+    return (_jsxs("li", { className: itemClasses, children: [bulletIcon && (_jsx("span", { className: "dds-list-item-icon", "aria-hidden": "true", children: bulletIcon })), children] }));
+}
+export var List = Object.assign(ListImpl, {
+    Item: ListItem,
+});

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

@@ -0,0 +1,28 @@
+import type { StoryObj } from "@storybook/react";
+declare const meta: {
+    title: string;
+    component: import("react").FC<import("./List").ListProps> & {
+        Item: typeof import("./List").ListItem;
+    };
+    parameters: {
+        layout: string;
+        docs: {
+            description: {
+                component: string;
+            };
+        };
+    };
+    tags: string[];
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+/** Default list with multi-line content and code examples */
+export declare const OrderedList: Story;
+/** List with nested components like CodeBlock and Callout */
+export declare const OrderedListWithNestedComponents: Story;
+/** Unordered list with default bullet */
+export declare const Unordered: Story;
+/** Unordered list with custom emoji bullet */
+export declare const UnorderedWithEmoji: Story;
+/** Unordered list with custom icon bullet */
+export declare const UnorderedWithIcon: Story;

package/dist/components/List.stories.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { List } from "./List";
+import { CodeBlock } from "./CodeBlock";
+import { Callout } from "./Callout";
+var meta = {
+    title: "Components/List",
+    component: List,
+    parameters: {
+        layout: "padded",
+        docs: {
+            description: {
+                component: "A visually enhanced list component with numbered badges (ordered) or custom bullets (unordered) and connector lines, designed for complex content that deserves more visual prominence.\n\n## When to Use\n- Tutorial or getting started guides with substantial steps\n- Multi-step workflows where each step contains rich content (paragraphs, code blocks, callouts)\n- Marketing or landing pages that need more visual polish\n- Complex instructions where each step is its own section of content\n- Feature lists or benefits that need custom emoji/icon bullets\n- When you want to nest other components (CodeBlock, Callout, etc.) within list items\n\n## When Not to Use\n- Simple, short lists with brief text items (use standard `<ol>` or `<ul>` instead)\n- Very long lists with many items (consider breaking into sections with Tabs or Collapsers)\n- When visual simplicity is preferred over aesthetic enhancement\n\n## Accessibility\n- Uses semantic `<ol>` or `<ul>` elements for proper screen reader support\n- CSS counters and custom bullets provide visual styling without affecting content\n- Maintains proper reading order and list semantics\n        ",
+            },
+        },
+    },
+    tags: ["autodocs"],
+};
+export default meta;
+/** Default list with multi-line content and code examples */
+export var OrderedList = {
+    args: {
+        children: null,
+    },
+    render: function () { return (_jsxs(List, { children: [_jsxs(List.Item, { children: ["Run the following command in your terminal to start the install wizard:", _jsx("code", { style: { display: "block", marginTop: "0.5rem" }, children: "npm create astro@latest" })] }), _jsxs(List.Item, { children: ["Now that your project has been created, you can ", _jsx("code", { children: "cd" }), " into your new project directory to begin using Astro."] }), _jsx(List.Item, { children: "If you skipped the \"Install dependencies?\" step during the CLI wizard, then be sure to install your dependencies before continuing." }), _jsx(List.Item, { children: "You can now start the Astro dev server and see a live preview of your project while you build!" })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<List>\n  <List.Item>\n    Run the following command in your terminal to start the install wizard:\n    <code style={{ display: \"block\", marginTop: \"0.5rem\" }}>\n      npm create astro@latest\n    </code>\n  </List.Item>\n  <List.Item>\n    Now that your project has been created, you can <code>cd</code> into\n    your new project directory to begin using Astro.\n  </List.Item>\n  <List.Item>\n    If you skipped the \"Install dependencies?\" step during the CLI wizard,\n    then be sure to install your dependencies before continuing.\n  </List.Item>\n  <List.Item>\n    You can now start the Astro dev server and see a live preview of your\n    project while you build!\n  </List.Item>\n</List>",
+            },
+        },
+    },
+};
+/** List with nested components like CodeBlock and Callout */
+export var OrderedListWithNestedComponents = {
+    args: {
+        children: null,
+    },
+    render: function () { return (_jsxs(List, { children: [_jsxs(List.Item, { children: [_jsx("p", { children: _jsx("b", { children: "Install dependencies" }) }), _jsx("p", { style: { color: "var(--dds-list-text)" }, children: "Run the following command to install all required packages:" }), _jsx(CodeBlock, { language: "bash", code: "npm install" })] }), _jsxs(List.Item, { children: [_jsx("strong", { children: "Configure your project" }), _jsx(Callout, { variant: "tip", title: "Pro Tip", children: "Make sure to review the configuration file before proceeding." })] }), _jsxs(List.Item, { children: [_jsx("p", { children: _jsx("b", { children: "Start development" }) }), _jsx("p", { style: { color: "var(--dds-list-text)" }, children: "Launch the dev server and begin building:" }), _jsx(CodeBlock, { language: "bash", code: "npm run dev" })] })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<List>\n  <List.Item>\n    <strong>Install dependencies</strong>\n    <p>Run the following command to install all required packages:</p>\n    <CodeBlock language=\"bash\" code=\"npm install\" />\n  </List.Item>\n  <List.Item>\n    <strong>Configure your project</strong>\n    <Callout variant=\"tip\" title=\"Pro Tip\">\n      Make sure to review the configuration file before proceeding.\n    </Callout>\n  </List.Item>\n  <List.Item>\n    <strong>Start development</strong>\n    <p>Launch the dev server and begin building:</p>\n    <CodeBlock language=\"bash\" code=\"npm run dev\" />\n  </List.Item>\n</List>",
+            },
+        },
+    },
+};
+/** Unordered list with default bullet */
+export var Unordered = {
+    args: {
+        children: null,
+    },
+    render: function () { return (_jsxs(List, { ordered: false, children: [_jsx(List.Item, { children: "Key feature of the product" }), _jsx(List.Item, { children: "Another important capability" }), _jsx(List.Item, { children: "Additional benefit to highlight" })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<List ordered={false}>\n  <List.Item>Key feature of the product</List.Item>\n  <List.Item>Another important capability</List.Item>\n  <List.Item>Additional benefit to highlight</List.Item>\n</List>",
+            },
+        },
+    },
+};
+/** Unordered list with custom emoji bullet */
+export var UnorderedWithEmoji = {
+    args: {
+        children: null,
+    },
+    render: function () { return (_jsxs(List, { ordered: false, bullet: "\u2705", children: [_jsx(List.Item, { children: "Beautifully designed components" }), _jsx(List.Item, { children: "Accessible by default" }), _jsx(List.Item, { children: "Fully customizable styling" })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<List ordered={false} bullet=\"\u2705\">\n  <List.Item>Beautifully designed components</List.Item>\n  <List.Item>Accessible by default</List.Item>\n  <List.Item>Fully customizable styling</List.Item>\n</List>",
+            },
+        },
+    },
+};
+/** Unordered list with custom icon bullet */
+export var UnorderedWithIcon = {
+    args: {
+        children: null,
+    },
+    render: function () { return (_jsxs(List, { ordered: false, bulletIcon: _jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", children: _jsx("path", { d: "M5 12h14M12 5l7 7-7 7" }) }), children: [_jsx(List.Item, { children: "Navigate to the settings page" }), _jsx(List.Item, { children: "Select your preferences" }), _jsx(List.Item, { children: "Save your changes" })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<List\n  ordered={false}\n  bulletIcon={\n    <svg viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\">\n      <path d=\"M5 12h14M12 5l7 7-7 7\" />\n    </svg>\n  }\n>\n  <List.Item>Navigate to the settings page</List.Item>\n  <List.Item>Select your preferences</List.Item>\n  <List.Item>Save your changes</List.Item>\n</List>",
+            },
+        },
+    },
+};

package/dist/components/Popover.js

@@ -1,3 +1,4 @@
+'use client';
 var __assign = (this && this.__assign) || function () {
     __assign = Object.assign || function(t) {
         for (var s, i = 1, n = arguments.length; i < n; i++) {

package/dist/components/Tabs.js

@@ -1,3 +1,4 @@
+'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useState, createContext, useContext } from "react";
 var TabsContext = createContext(null);

package/dist/hooks/useKeyPress.js

@@ -1,3 +1,4 @@
+'use client';
 import { useEffect, useRef, useMemo } from 'react';
 var normalizeKeyCombination = function (keys) {
     var parts = keys.split(/\s*\+\s*/);

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/styles.css

@@ -245,6 +245,17 @@
   --dds-popover-title-size: 0.9375rem; /* ~15px */
   --dds-popover-text-size: 0.875rem; /* text-sm */
   --dds-popover-eyebrow-size: 0.6875rem; /* ~11px */
+
+  /* List */
+  --dds-list-margin: 1.5rem 0;
+  --dds-list-item-margin-bottom: 1.5rem;
+  --dds-list-badge-size: calc(var(--dds-line-height-relaxed) * 1rem);
+  --dds-list-badge-font-size: 0.8125rem;
+  --dds-list-badge-text: #171a1c; /* gray-900 */
+  --dds-list-badge-bg: #eceef2;
+  --dds-list-badge-shadow: inset 0 0 0 1px #bfc2c7;
+  --dds-list-connector-line: #eceef2; /* gray-200 */
+  --dds-list-text: #374151; /* gray-700 */
 }
 /* ==========================================================================
    Dark Mode Tokens
@@ -398,6 +409,13 @@
   --dds-popover-eyebrow-color: #9ca3af; /* gray-400 */
   --dds-popover-link-color: #60a5fa; /* blue-400 */
   --dds-popover-link-color-hover: #93c5fd; /* blue-300 */
+
+  /* List */
+  --dds-list-badge-text: #ffffff;
+  --dds-list-badge-bg: #232831;
+  --dds-list-badge-shadow: inset 0 0 0 1px #353a42;
+  --dds-list-connector-line: #353a42; /* gray-600 */
+  --dds-list-text: #e5e7eb; /* gray-200 */
 }
 /* Auto dark mode — follows OS preference, opt-out with .dds-light */
 @media (prefers-color-scheme: dark) {
@@ -546,6 +564,13 @@
     --dds-popover-eyebrow-color: #9ca3af;
     --dds-popover-link-color: #60a5fa;
     --dds-popover-link-color-hover: #93c5fd;
+
+    /* List */
+    --dds-list-badge-text: #ffffff;
+    --dds-list-badge-bg: #232831;
+    --dds-list-badge-shadow: inset 0 0 0 1px #353a42;
+    --dds-list-connector-line: #353a42; /* gray-600 */
+    --dds-list-text: #e5e7eb; /* gray-200 */
   }
 }
 /* Explicit dark mode via data attribute (overrides OS preference) */
@@ -1466,6 +1491,93 @@ a.no-text-decoration {
   margin-bottom: 0.25rem; /* mb-1 */
   vertical-align: middle;
 }
+.dds-list {
+  list-style: none;
+  counter-reset: list-counter;
+  padding-left: 0;
+  margin: var(--dds-list-margin, 1.5rem 0);
+  color: var(--dds-list-text);
+}
+.dds-list[data-ordered="false"] {
+  counter-reset: none;
+}
+.dds-list-item {
+  counter-increment: list-counter;
+  position: relative;
+  padding-inline-start: calc(var(--dds-list-badge-size) + 1rem);
+  margin-bottom: var(--dds-list-item-margin-bottom, 1.5rem);
+  min-height: var(--dds-list-badge-size);
+}
+.dds-list[data-ordered="false"] .dds-list-item {
+  counter-increment: none;
+}
+.dds-list-item::after {
+  content: "";
+  position: absolute;
+  top: calc(var(--dds-list-badge-size, 2.5rem) + 0.5rem);
+  bottom: calc(-1 * var(--dds-list-item-margin-bottom, 1.5rem) + 0.5rem);
+  left: calc((var(--dds-list-badge-size, 2.5rem) - 1px) / 2);
+  width: 1px;
+  background-color: var(--dds-list-connector-line);
+}
+.dds-list-item:last-child::after {
+  display: none;
+}
+/* Ordered list badges */
+.dds-list[data-ordered="true"] .dds-list-item::before {
+  content: counter(list-counter);
+  position: absolute;
+  left: 0;
+  top: 0;
+  width: var(--dds-list-badge-size, 2.5rem);
+  height: var(--dds-list-badge-size, 2.5rem);
+  line-height: var(--dds-line-height-relaxed);
+  inset-inline-start: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: var(--dds-font-bold, 700);
+  font-size: var(--dds-list-badge-font-size, 1.125rem);
+  color: var(--dds-list-badge-text);
+  background: var(--dds-list-badge-bg);
+  box-shadow: var(--dds-list-badge-shadow);
+  border-radius: 50%;
+}
+/* Unordered list bullets */
+.dds-list[data-ordered="false"] .dds-list-item::before {
+  content: var(--dds-list-bullet, "•");
+  position: absolute;
+  left: 0;
+  top: 0;
+  width: var(--dds-list-badge-size, 2.5rem);
+  height: var(--dds-list-badge-size, 2.5rem);
+  inset-inline-start: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: var(--dds-list-bullet-size, 1.5rem);
+  color: var(--dds-list-badge-text);
+}
+/* Hide ::before when using custom icon */
+.dds-list[data-has-icon="true"] .dds-list-item::before {
+  display: none;
+}
+/* Custom icon bullet */
+.dds-list-item-icon {
+  position: absolute;
+  left: 0;
+  top: 0;
+  width: var(--dds-list-badge-size, 2.5rem);
+  height: var(--dds-list-badge-size, 2.5rem);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--dds-list-badge-text);
+}
+.dds-list-item-icon svg {
+  width: 1.25rem;
+  height: 1.25rem;
+}
 /* ==========================================================================
    Popover Component
    Uses the native Popover API for top-layer rendering.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roadlittledawn/docs-design-system-react",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "license": "MIT",
   "description": "React components for documentation design system",
   "repository": {
@@ -37,9 +37,10 @@
     "postcss-import": "^16.0.0",
     "typescript": "^5.0.0"
   },
+  "sideEffects": false,
   "peerDependencies": {
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
   },
   "exports": {
     ".": {