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

package/USAGE.md

@@ -927,3 +927,144 @@ import {
   </TableBody>
 </Table>
 ```
+
+---
+
+## Breadcrumb
+
+Breadcrumb navigation component. Renders a `<nav aria-label="Breadcrumb">` with an ordered list of segments. The last item receives `aria-current="page"`. Delimiters are marked `aria-hidden` so screen readers skip them.
+
+### Import
+
+```tsx
+import { Breadcrumb } from '@roadlittledawn/docs-design-system-react';
+```
+
+### Types
+
+```ts
+interface BreadcrumbItem {
+  label: string;   // Display text for the segment
+  href?: string;   // Optional URL; omit for the current (last) page
+}
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `BreadcrumbItem[]` | — | Ordered list of path segments, root first |
+| `delimiter` | `ReactNode` | `"/"` | Separator between segments. Accepts a string or any ReactNode |
+| `size` | `"sm" \| "md"` | `"md"` | Size variant controlling font size |
+| `collapseOnMobile` | `boolean` | `false` | Collapse middle segments behind an expandable ellipsis on narrow viewports |
+| `scrollOnMobile` | `boolean` | `false` | Let the full trail scroll horizontally instead of wrapping on narrow viewports |
+| `className` | `string` | `""` | Additional CSS classes |
+
+### Examples
+
+#### Basic
+
+```tsx
+<Breadcrumb
+  items={[
+    { label: 'Home', href: '/' },
+    { label: 'Docs', href: '/docs' },
+    { label: 'Getting Started' },
+  ]}
+/>
+```
+
+#### Small size with custom delimiter
+
+```tsx
+<Breadcrumb
+  size="sm"
+  delimiter="›"
+  items={[
+    { label: 'Home', href: '/' },
+    { label: 'Reference', href: '/reference' },
+    { label: 'API' },
+  ]}
+/>
+```
+
+#### Collapse middle items on mobile
+
+```tsx
+<Breadcrumb
+  collapseOnMobile
+  items={[
+    { label: 'Home', href: '/' },
+    { label: 'Products', href: '/products' },
+    { label: 'Widgets', href: '/products/widgets' },
+    { label: 'Details' },
+  ]}
+/>
+```
+
+---
+
+## Icon
+
+Renders an SVG icon without bundling any specific icon library. Accepts a React SVG component (e.g. imported with SVGR or defined inline) or a raw SVG string, making it easy to use your own icon library.
+
+### Import
+
+```tsx
+import { Icon } from '@roadlittledawn/docs-design-system-react';
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `svg` | `React.ComponentType<React.SVGProps<SVGSVGElement>> \| string` | — | SVG to render — accepts a React SVG component or a raw SVG string |
+| `size` | `number` | `16` | Width and height in pixels |
+| `className` | `string` | `""` | Additional CSS class names |
+| `aria-label` | `string` | — | Accessible label. When provided the icon gets `role="img"` and is announced by screen readers. When omitted the icon is decorative (`aria-hidden="true"`) |
+
+### Examples
+
+#### React SVG component (SVGR)
+
+```tsx
+import { ReactComponent as ChevronIcon } from './chevron.svg';
+
+<Icon svg={ChevronIcon} size={20} aria-label="Expand" />
+```
+
+#### Inline SVG function (define props to forward size/className/aria-*)
+
+```tsx
+const StarIcon = (props: React.SVGProps<SVGSVGElement>) => (
+  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" {...props}>
+    <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" />
+  </svg>
+);
+
+<Icon svg={StarIcon} size={24} />
+```
+
+#### Raw SVG string
+
+```tsx
+const closeIconSvg = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>`;
+
+<Icon svg={closeIconSvg} size={24} aria-label="Close" />
+```
+
+#### Decorative vs meaningful icons
+
+```tsx
+{/* Decorative — hidden from screen readers */}
+<Icon svg={StarIcon} size={16} />
+
+{/* Meaningful — announced as "Favorite" */}
+<Icon svg={StarIcon} size={16} aria-label="Favorite" />
+```
+
+### Accessibility notes
+
+- Do **not** include `aria-hidden`, `role`, or `aria-label` attributes inside your SVG component. The `Icon` component manages all accessibility attributes.
+- When passing a raw SVG string, do **not** include accessibility attributes in the string itself.
+- Do **not** pass untrusted or user-supplied SVG strings — the raw string path uses `dangerouslySetInnerHTML` without sanitization.

package/dist/components/Icon.d.ts

@@ -0,0 +1,52 @@
+import React from 'react';
+export interface IconProps {
+    /**
+     * SVG to render. Accepts a React SVG component (e.g. imported with SVGR or
+     * defined inline) or a raw SVG string.
+     *
+     * **Accessibility note:** when passing a React SVG component, do not include
+     * `aria-hidden`, `role`, or `aria-label` attributes in the component itself.
+     * The `Icon` component applies the correct accessibility attributes based on
+     * whether an `aria-label` prop is provided.
+     *
+     * **Security note:** when passing a raw SVG string, ensure the content is
+     * from a trusted source. The string is injected via `dangerouslySetInnerHTML`
+     * without sanitization.
+     */
+    svg: React.ComponentType<React.SVGProps<SVGSVGElement>> | string;
+    /**
+     * Width and height in pixels.
+     * @default 16
+     */
+    size?: number;
+    /** Additional CSS class names to apply to the icon element. */
+    className?: string;
+    /**
+     * Accessible label for the icon. When provided the icon is announced by
+     * screen readers with `role="img"`. When omitted the icon is treated as
+     * decorative and hidden from assistive technology (`aria-hidden="true"`).
+     */
+    'aria-label'?: string;
+}
+/**
+ * Renders an SVG icon. Accepts either a React SVG component (e.g. imported
+ * with SVGR) or a raw SVG string, making it easy to use your own icon library
+ * without being tied to a specific icon set.
+ *
+ * @example
+ * // React SVG component
+ * import { ReactComponent as ChevronIcon } from './chevron.svg';
+ * <Icon svg={ChevronIcon} size={20} aria-label="Expand" />
+ *
+ * @example
+ * // Inline SVG function
+ * const StarIcon = (props: React.SVGProps<SVGSVGElement>) => (
+ *   <svg viewBox="0 0 24 24" {...props}>...</svg>
+ * );
+ * <Icon svg={StarIcon} size={16} />
+ *
+ * @example
+ * // Raw SVG string
+ * <Icon svg='<svg viewBox="0 0 24 24">...</svg>' size={24} />
+ */
+export declare function Icon({ svg, size, className, 'aria-label': ariaLabel, }: IconProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/Icon.js

@@ -0,0 +1,49 @@
+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";
+/**
+ * Renders an SVG icon. Accepts either a React SVG component (e.g. imported
+ * with SVGR) or a raw SVG string, making it easy to use your own icon library
+ * without being tied to a specific icon set.
+ *
+ * @example
+ * // React SVG component
+ * import { ReactComponent as ChevronIcon } from './chevron.svg';
+ * <Icon svg={ChevronIcon} size={20} aria-label="Expand" />
+ *
+ * @example
+ * // Inline SVG function
+ * const StarIcon = (props: React.SVGProps<SVGSVGElement>) => (
+ *   <svg viewBox="0 0 24 24" {...props}>...</svg>
+ * );
+ * <Icon svg={StarIcon} size={16} />
+ *
+ * @example
+ * // Raw SVG string
+ * <Icon svg='<svg viewBox="0 0 24 24">...</svg>' size={24} />
+ */
+export function Icon(_a) {
+    var svg = _a.svg, _b = _a.size, size = _b === void 0 ? 16 : _b, _c = _a.className, className = _c === void 0 ? '' : _c, ariaLabel = _a["aria-label"];
+    var isDecorative = !ariaLabel;
+    var classNames = ['dds-icon', className].filter(Boolean).join(' ');
+    if (typeof svg === 'string') {
+        return (_jsx("span", __assign({ className: classNames, style: { width: size, height: size }, 
+            // eslint-disable-next-line react/no-danger
+            dangerouslySetInnerHTML: { __html: svg } }, (isDecorative
+            ? { 'aria-hidden': true }
+            : { role: 'img', 'aria-label': ariaLabel }))));
+    }
+    var SvgComponent = svg;
+    return (_jsx(SvgComponent, __assign({ className: classNames, width: size, height: size }, (isDecorative
+        ? { 'aria-hidden': true }
+        : { role: 'img', 'aria-label': ariaLabel }))));
+}

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

@@ -0,0 +1,31 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Icon } from './Icon';
+declare const meta: Meta<typeof Icon>;
+export default meta;
+type Story = StoryObj<typeof Icon>;
+/**
+ * Pass any React SVG component to the `svg` prop. The component is rendered
+ * directly with the provided `size` applied as `width` and `height`.
+ */
+export declare const WithReactComponent: Story;
+/**
+ * Pass a raw SVG string to the `svg` prop. The string is injected using
+ * `dangerouslySetInnerHTML` — ensure the content is from a trusted source.
+ */
+export declare const WithSvgString: Story;
+/**
+ * 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 declare const WithAriaLabel: Story;
+/**
+ * Sizes from small (12 px) to large (48 px). The `size` prop sets both
+ * `width` and `height` so the icon is always square.
+ */
+export declare const Sizes: Story;
+/**
+ * Icons inherit `currentColor` for their stroke/fill, so they automatically
+ * adapt to the surrounding text color.
+ */
+export declare const InheritedColor: Story;

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

@@ -14,4 +14,5 @@ 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

@@ -15,5 +15,6 @@ 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

@@ -2272,4 +2272,15 @@ a.dds-breadcrumb-link:hover {
     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.10.0",
+  "version": "0.11.0",
   "license": "MIT",
   "description": "React components for documentation design system",
   "repository": {