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

package/dist/components/Icon.stories.js

@@ -0,0 +1,141 @@
+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 { Icon } from './Icon';
+// ─── Sample SVG components used in stories ────────────────────────────────────
+// Note: these sample SVG components intentionally omit accessibility attributes
+// (aria-hidden, role, aria-label). The Icon component applies them based on
+// whether an aria-label prop is provided.
+var StarIcon = function (props) { return (_jsx("svg", __assign({ viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round" }, props, { 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 ChevronIcon = function (props) { return (_jsx("svg", __assign({ viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round" }, props, { children: _jsx("polyline", { points: "6 9 12 15 18 9" }) }))); };
+var ExternalLinkIcon = function (props) { return (_jsxs("svg", __assign({ viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round" }, props, { children: [_jsx("path", { d: "M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" }), _jsx("polyline", { points: "15 3 21 3 21 9" }), _jsx("line", { x1: "10", y1: "14", x2: "21", y2: "3" })] }))); };
+// Raw SVG string example
+var closeIconSvg = "<svg viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><line x1=\"18\" y1=\"6\" x2=\"6\" y2=\"18\"/><line x1=\"6\" y1=\"6\" x2=\"18\" y2=\"18\"/></svg>";
+// ─── Meta ─────────────────────────────────────────────────────────────────────
+var meta = {
+    title: 'Components/Icon',
+    component: Icon,
+    tags: ['autodocs'],
+    decorators: [
+        function (Story) { return (_jsx("div", { style: { color: 'var(--dds-tabs-panel-text)' }, children: _jsx(Story, {}) })); },
+    ],
+    argTypes: {
+        svg: {
+            description: 'SVG to render — accepts a React SVG component or a raw SVG string.',
+            control: false,
+        },
+        size: {
+            control: { type: 'number', min: 8, max: 64, step: 2 },
+            description: 'Width and height in pixels.',
+            table: { defaultValue: { summary: '16' } },
+        },
+        className: {
+            control: 'text',
+            description: 'Additional CSS class names.',
+            table: { defaultValue: { summary: '""' } },
+        },
+        'aria-label': {
+            control: 'text',
+            description: 'Accessible label. When provided the icon is announced by screen readers. When omitted the icon is treated as decorative and hidden from assistive technology.',
+        },
+    },
+    parameters: {
+        docs: {
+            description: {
+                component: "\nThe `Icon` component renders an SVG icon without bundling any specific icon library.\nYou bring your own SVGs \u2014 as a React component or a raw SVG string \u2014 so you are never\nforced to adopt a particular icon set.\n\n## When to Use\n\n- Rendering icons imported with SVGR (e.g. `import { ReactComponent as Star } from './star.svg'`)\n- Rendering inline SVG components defined directly in your code\n- Rendering a trusted raw SVG string from your project's assets\n\n## When Not to Use\n\n- Do not pass untrusted or user-supplied SVG strings; the raw string path uses\n  `dangerouslySetInnerHTML` without sanitization.\n- When you only need a decorative shape that can be achieved with CSS alone.\n\n## Accessibility\n\n- Decorative icons (no `aria-label`) automatically receive `aria-hidden=\"true\"` so\n  they are ignored by screen readers.\n- Meaningful icons (e.g. a standalone icon button) should receive a descriptive\n  `aria-label` so they are announced correctly.\n        ",
+            },
+        },
+    },
+};
+export default meta;
+// ─── Stories ──────────────────────────────────────────────────────────────────
+/**
+ * Pass any React SVG component to the `svg` prop. The component is rendered
+ * directly with the provided `size` applied as `width` and `height`.
+ */
+export var WithReactComponent = {
+    args: {
+        svg: StarIcon,
+        size: 24,
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "const StarIcon = (props: React.SVGProps<SVGSVGElement>) => (\n  <svg viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\" strokeLinecap=\"round\" strokeLinejoin=\"round\" {...props}>\n    <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\" />\n  </svg>\n);\n\n<Icon svg={StarIcon} size={24} />",
+            },
+        },
+    },
+};
+/**
+ * Pass a raw SVG string to the `svg` prop. The string is injected using
+ * `dangerouslySetInnerHTML` — ensure the content is from a trusted source.
+ */
+export var WithSvgString = {
+    args: {
+        svg: closeIconSvg,
+        size: 24,
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "const closeIconSvg = `<svg viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><line x1=\"18\" y1=\"6\" x2=\"6\" y2=\"18\"/><line x1=\"6\" y1=\"6\" x2=\"18\" y2=\"18\"/></svg>`;\n\n<Icon svg={closeIconSvg} size={24} />",
+            },
+        },
+    },
+};
+/**
+ * When an `aria-label` is provided the icon receives `role="img"` and is
+ * announced by screen readers with the given label. Use this when the icon
+ * conveys meaning without surrounding text.
+ */
+export var WithAriaLabel = {
+    args: {
+        svg: ExternalLinkIcon,
+        size: 20,
+        'aria-label': 'Opens in a new tab',
+    },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Icon svg={ExternalLinkIcon} size={20} aria-label=\"Opens in a new tab\" />",
+            },
+        },
+    },
+};
+/**
+ * Sizes from small (12 px) to large (48 px). The `size` prop sets both
+ * `width` and `height` so the icon is always square.
+ */
+export var Sizes = {
+    parameters: {
+        docs: {
+            source: {
+                code: "<Icon svg={ChevronIcon} size={12} />\n<Icon svg={ChevronIcon} size={16} />\n<Icon svg={ChevronIcon} size={20} />\n<Icon svg={ChevronIcon} size={24} />\n<Icon svg={ChevronIcon} size={32} />\n<Icon svg={ChevronIcon} size={48} />",
+            },
+        },
+    },
+    render: function () { return (_jsx("div", { style: { display: 'flex', gap: '1rem', alignItems: 'center' }, children: [12, 16, 20, 24, 32, 48].map(function (size) { return (_jsx(Icon, { svg: ChevronIcon, size: size }, size)); }) })); },
+};
+/**
+ * Icons inherit `currentColor` for their stroke/fill, so they automatically
+ * adapt to the surrounding text color.
+ */
+export var InheritedColor = {
+    parameters: {
+        docs: {
+            source: {
+                code: "<p style={{ color: '#3b82f6' }}>\n  <Icon svg={StarIcon} size={16} /> Blue text with a blue icon\n</p>\n<p style={{ color: '#ef4444' }}>\n  <Icon svg={StarIcon} size={16} /> Red text with a red icon\n</p>",
+            },
+        },
+    },
+    render: function () { return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: '0.5rem' }, children: [_jsxs("p", { style: { color: '#3b82f6', margin: 0, display: 'flex', alignItems: 'center', gap: '0.375rem', fontFamily: 'sans-serif' }, children: [_jsx(Icon, { svg: StarIcon, size: 16 }), " Blue text with a blue icon"] }), _jsxs("p", { style: { color: '#ef4444', margin: 0, display: 'flex', alignItems: 'center', gap: '0.375rem', fontFamily: 'sans-serif' }, children: [_jsx(Icon, { svg: StarIcon, size: 16 }), " Red text with a red icon"] })] })); },
+};

package/dist/components/Link.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-interface LinkProps {
+export interface LinkProps {
     /** URL to link to. External links (starting with http:// or https://) open in new tab */
     href: string;
     /** Link content */
@@ -8,4 +8,3 @@ interface LinkProps {
     className?: string;
 }
 export declare function Link({ href, children, className }: LinkProps): import("react/jsx-runtime").JSX.Element;
-export {};

package/dist/components/List.d.ts

@@ -11,7 +11,7 @@ export interface ListProps {
     /** Custom bullet icon (React node, e.g., SVG) for unordered lists. Takes precedence over bullet prop */
     bulletIcon?: ReactNode;
 }
-interface ListItemProps {
+export interface ListItemProps {
     /** List item content */
     children: ReactNode;
     /** Additional CSS classes */
@@ -23,4 +23,3 @@ export declare function ListItem({ children, className, bulletIcon }: ListItemPr
 export declare const List: FC<ListProps> & {
     Item: typeof ListItem;
 };
-export {};

package/dist/components/Tabs.d.ts

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

package/dist/components/Typography.d.ts

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

package/dist/index.d.ts

@@ -13,4 +13,6 @@ export * from './components/Link';
 export * from './components/List';
 export * from './components/Table';
 export * from './components/Grid';
+export * from './components/Breadcrumb';
+export * from './components/Icon';
 export * from './hooks/useKeyPress';

package/dist/index.js

@@ -14,5 +14,7 @@ export * from './components/Link';
 export * from './components/List';
 export * from './components/Table';
 export * from './components/Grid';
+export * from './components/Breadcrumb';
+export * from './components/Icon';
 // Export hooks
 export * from './hooks/useKeyPress';

package/dist/styles.css

@@ -286,6 +286,18 @@
   --dds-grid-gap-lg: 2.5rem; /* gap-10 */
   --dds-grid-divider-color: #e5e7eb; /* gray-200 */
   --dds-grid-sticky-top: 1rem;
+
+  /* Breadcrumb */
+  --dds-breadcrumb-font-size-sm: 0.75rem; /* text-xs */
+  --dds-breadcrumb-font-size-md: 0.875rem; /* text-sm */
+  --dds-breadcrumb-gap: 0.375rem;
+  --dds-breadcrumb-link-color: #6b7280; /* gray-500 */
+  --dds-breadcrumb-link-color-hover: #111827; /* gray-900 */
+  --dds-breadcrumb-current-color: #111827; /* gray-900 */
+  --dds-breadcrumb-current-weight: 500;
+  --dds-breadcrumb-delimiter-color: #9ca3af; /* gray-400 */
+  --dds-breadcrumb-ellipsis-radius: 0.25rem; /* rounded */
+  --dds-breadcrumb-ellipsis-hover-bg: #f3f4f6; /* gray-100 */
 }
 /* ==========================================================================
    Dark Mode Tokens
@@ -466,6 +478,13 @@
 
   /* Grid */
   --dds-grid-divider-color: #4b5563; /* gray-600 */
+
+  /* Breadcrumb */
+  --dds-breadcrumb-link-color: #9ca3af; /* gray-400 */
+  --dds-breadcrumb-link-color-hover: #f9fafb; /* gray-50 */
+  --dds-breadcrumb-current-color: #e5e7eb; /* gray-200 */
+  --dds-breadcrumb-delimiter-color: #6b7280; /* gray-500 */
+  --dds-breadcrumb-ellipsis-hover-bg: rgba(255, 255, 255, 0.08);
 }
 /* Auto dark mode — follows OS preference, opt-out with .dds-light */
 @media (prefers-color-scheme: dark) {
@@ -641,6 +660,13 @@
 
     /* Grid */
     --dds-grid-divider-color: #4b5563; /* gray-600 */
+
+    /* Breadcrumb */
+    --dds-breadcrumb-link-color: #9ca3af; /* gray-400 */
+    --dds-breadcrumb-link-color-hover: #f9fafb; /* gray-50 */
+    --dds-breadcrumb-current-color: #e5e7eb; /* gray-200 */
+    --dds-breadcrumb-delimiter-color: #6b7280; /* gray-500 */
+    --dds-breadcrumb-ellipsis-hover-bg: rgba(255, 255, 255, 0.08);
   }
 }
 /* Explicit dark mode via data attribute (overrides OS preference) */
@@ -795,6 +821,13 @@
   --dds-table-header-hover-text: #f9fafb;
   --dds-table-header-active-text: #93c5fd;
   --dds-table-focus-ring: #60a5fa;
+
+  /* Breadcrumb */
+  --dds-breadcrumb-link-color: #9ca3af; /* gray-400 */
+  --dds-breadcrumb-link-color-hover: #f9fafb; /* gray-50 */
+  --dds-breadcrumb-current-color: #e5e7eb; /* gray-200 */
+  --dds-breadcrumb-delimiter-color: #6b7280; /* gray-500 */
+  --dds-breadcrumb-ellipsis-hover-bg: rgba(255, 255, 255, 0.08);
 }
 /* Import PrismJS theme */
 /**
@@ -2136,4 +2169,118 @@ a.no-text-decoration {
     position: static;
   }
 }
+/* ============================================================
+   Breadcrumb component
+   ============================================================ */
+.dds-breadcrumb {
+  font-size: var(--dds-breadcrumb-font-size-md);
+  line-height: var(--dds-line-height-tight);
+}
+/* Size variants */
+.dds-breadcrumb--sm {
+  font-size: var(--dds-breadcrumb-font-size-sm);
+}
+/* The ordered list */
+.dds-breadcrumb-list {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  gap: var(--dds-breadcrumb-gap);
+}
+/* Scroll mode: single row with horizontal scroll (mobile only) */
+@media (max-width: 640px) {
+  .dds-breadcrumb--scroll .dds-breadcrumb-list {
+    flex-wrap: nowrap;
+    overflow-x: auto;
+    -webkit-overflow-scrolling: touch;
+    scrollbar-width: none; /* Firefox */
+  }
+
+  .dds-breadcrumb--scroll .dds-breadcrumb-list::-webkit-scrollbar {
+    display: none;
+  }
+}
+/* Individual segment items */
+.dds-breadcrumb-item {
+  display: flex;
+  align-items: center;
+  gap: var(--dds-breadcrumb-gap);
+  white-space: nowrap;
+}
+/* Linked segments */
+.dds-breadcrumb-link {
+  color: var(--dds-breadcrumb-link-color);
+  text-decoration: none;
+  transition: color 150ms ease;
+}
+a.dds-breadcrumb-link:hover {
+  color: var(--dds-breadcrumb-link-color-hover);
+  text-decoration: underline;
+}
+/* Current page segment */
+.dds-breadcrumb-current {
+  color: var(--dds-breadcrumb-current-color);
+  font-weight: var(--dds-breadcrumb-current-weight);
+}
+/* Delimiter characters — aria-hidden in markup */
+.dds-breadcrumb-delimiter {
+  color: var(--dds-breadcrumb-delimiter-color);
+  user-select: none;
+  flex-shrink: 0;
+}
+/* Ellipsis expand button */
+.dds-breadcrumb-ellipsis {
+  display: inline-flex;
+  align-items: center;
+  background: none;
+  border: none;
+  cursor: pointer;
+  color: var(--dds-breadcrumb-link-color);
+  font-size: inherit;
+  padding: 0.1em 0.3em;
+  line-height: 1;
+  border-radius: var(--dds-breadcrumb-ellipsis-radius);
+  transition: color 150ms ease, background-color 150ms ease;
+}
+.dds-breadcrumb-ellipsis:hover {
+  color: var(--dds-breadcrumb-link-color-hover);
+  background-color: var(--dds-breadcrumb-ellipsis-hover-bg);
+}
+.dds-breadcrumb-ellipsis:focus-visible {
+  outline: 2px solid var(--dds-breadcrumb-link-color-hover);
+  outline-offset: 2px;
+}
+/* ============================================================
+   Collapsible behaviour
+   ============================================================ */
+/* On desktop the ellipsis is always hidden — show all items */
+.dds-breadcrumb--collapsible .dds-breadcrumb-item--ellipsis {
+  display: none;
+}
+/* On narrow viewports: hide middle items and show ellipsis when not expanded */
+@media (max-width: 640px) {
+  .dds-breadcrumb--collapsible:not([data-expanded="true"])
+    .dds-breadcrumb-item--middle {
+    display: none;
+  }
+
+  .dds-breadcrumb--collapsible:not([data-expanded="true"])
+    .dds-breadcrumb-item--ellipsis {
+    display: flex;
+  }
+}
+.dds-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+/* Ensure an SVG injected via a raw string fills the container */
+.dds-icon svg {
+  width: 100%;
+  height: 100%;
+}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roadlittledawn/docs-design-system-react",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "license": "MIT",
   "description": "React components for documentation design system",
   "repository": {
@@ -11,7 +11,8 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "USAGE.md"
   ],
   "scripts": {
     "build": "tsc && npm run build:css",