@roadlittledawn/docs-design-system-react 0.1.0

package/dist/components/Collapser.stories.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Collapser } from './Collapser';
+/**
+ * The Collapser component creates expandable/collapsible content sections with smooth animations.
+ */
+var meta = {
+    title: 'Components/Collapser',
+    component: Collapser,
+    tags: ['autodocs'],
+    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        ",
+            },
+        },
+    },
+};
+export default meta;
+/**
+ * Basic collapser that starts collapsed.
+ */
+export var Basic = {
+    args: {
+        title: 'Click to expand',
+        children: (_jsx("p", { children: "This content is hidden by default and can be revealed by clicking the title. It includes smooth height animations for a better user experience." })),
+    },
+};
+/**
+ * Collapser that starts in the open state.
+ */
+export var DefaultOpen = {
+    args: {
+        title: 'This section starts open',
+        defaultOpen: true,
+        children: (_jsx("p", { children: "This collapser is open by default. Users can still click to collapse it." })),
+    },
+};
+/**
+ * Collapser with an ID for the title.
+ */
+export var WithID = {
+    args: {
+        title: 'Section with ID',
+        id: 'faq-question-1',
+        children: (_jsx("p", { children: "This collapser has an ID on its title, which is useful for anchor links and accessibility purposes." })),
+    },
+};
+/**
+ * Collapser containing complex content.
+ */
+export var ComplexContent = {
+    args: {
+        title: 'How do I install the components?',
+        children: (_jsxs("div", { children: [_jsx("p", { children: "You can install the components using npm:" }), _jsx("pre", { style: { background: '#f5f5f5', padding: '1rem', borderRadius: '4px' }, children: "npm install @docs-design-system/ui" }), _jsx("p", { children: "Then import them in your React application:" }), _jsx("pre", { style: { background: '#f5f5f5', padding: '1rem', borderRadius: '4px' }, children: "import { Button, Card } from '@docs-design-system/ui';" })] })),
+    },
+};
+/**
+ * Multiple collapsers in a FAQ-style layout.
+ */
+export var FAQExample = {
+    render: function () { return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: '0.5rem' }, 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." }) })] })); },
+};

package/dist/components/Heading.d.ts

@@ -0,0 +1,11 @@
+import React from "react";
+interface HeadingProps {
+    /** Heading level (h1, h2, h3, or h4) */
+    level: 1 | 2 | 3 | 4;
+    /** Heading content */
+    children?: React.ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function Heading({ level, children, className }: HeadingProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Heading.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export function Heading(_a) {
+    var level = _a.level, children = _a.children, _b = _a.className, className = _b === void 0 ? "" : _b;
+    var Tag = "h".concat(level);
+    var classNames = "dds-heading dds-heading-".concat(level, " ").concat(className).trim();
+    return _jsx(Tag, { className: classNames, children: children });
+}

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

@@ -0,0 +1,32 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Heading } from './Heading';
+/**
+ * The Heading component renders semantic HTML headings with consistent styling.
+ */
+declare const meta: Meta<typeof Heading>;
+export default meta;
+type Story = StoryObj<typeof Heading>;
+/**
+ * Level 1 heading (h1) - typically used once per page for the main title.
+ */
+export declare const Level1: Story;
+/**
+ * Level 2 heading (h2) - used for major sections.
+ */
+export declare const Level2: Story;
+/**
+ * Level 3 heading (h3) - used for subsections.
+ */
+export declare const Level3: Story;
+/**
+ * Level 4 heading (h4) - used for sub-subsections.
+ */
+export declare const Level4: Story;
+/**
+ * All heading levels displayed together to show the hierarchy.
+ */
+export declare const AllLevels: Story;
+/**
+ * Example of a properly structured document hierarchy.
+ */
+export declare const DocumentStructure: Story;

package/dist/components/Heading.stories.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Heading } from './Heading';
+/**
+ * The Heading component renders semantic HTML headings with consistent styling.
+ */
+var meta = {
+    title: 'Components/Heading',
+    component: Heading,
+    tags: ['autodocs'],
+    parameters: {
+        docs: {
+            description: {
+                component: "\nThe Heading component provides semantic HTML headings (h1-h4) with consistent styling.\n\n## When to Use\n\n- For page and section titles\n- To create proper document structure\n- When semantic HTML heading levels are important for SEO and accessibility\n- For creating a clear content hierarchy\n\n## When Not to Use\n\n- For text that looks like a heading but isn't structurally a heading (use Typography)\n- For headings deeper than h4 (h5, h6 are not supported - reconsider your document structure)\n- For buttons or links that look like headings\n\n## Accessibility\n\n- Uses proper semantic HTML heading elements (h1-h4)\n- Creates a logical document outline for screen readers\n- Helps users navigate content with assistive technology\n- Important for SEO and document structure\n\n## Best Practices\n\n- Use only one h1 per page\n- Don't skip heading levels (don't jump from h2 to h4)\n- Keep headings concise and descriptive\n- Use headings to create a logical document structure\n        ",
+            },
+        },
+    },
+};
+export default meta;
+/**
+ * Level 1 heading (h1) - typically used once per page for the main title.
+ */
+export var Level1 = {
+    args: {
+        level: 1,
+        children: 'Page Title (H1)',
+    },
+};
+/**
+ * Level 2 heading (h2) - used for major sections.
+ */
+export var Level2 = {
+    args: {
+        level: 2,
+        children: 'Section Title (H2)',
+    },
+};
+/**
+ * Level 3 heading (h3) - used for subsections.
+ */
+export var Level3 = {
+    args: {
+        level: 3,
+        children: 'Subsection Title (H3)',
+    },
+};
+/**
+ * Level 4 heading (h4) - used for sub-subsections.
+ */
+export var Level4 = {
+    args: {
+        level: 4,
+        children: 'Sub-subsection Title (H4)',
+    },
+};
+/**
+ * All heading levels displayed together to show the hierarchy.
+ */
+export var AllLevels = {
+    render: function () { return (_jsxs("div", { children: [_jsx(Heading, { level: 1, children: "Level 1 - Main Page Title" }), _jsx("p", { style: { marginBottom: '1rem', color: '#666' }, children: "Use h1 for the main page title. There should only be one h1 per page." }), _jsx(Heading, { level: 2, children: "Level 2 - Major Section" }), _jsx("p", { style: { marginBottom: '1rem', color: '#666' }, children: "Use h2 for major sections of your page." }), _jsx(Heading, { level: 3, children: "Level 3 - Subsection" }), _jsx("p", { style: { marginBottom: '1rem', color: '#666' }, children: "Use h3 for subsections within major sections." }), _jsx(Heading, { level: 4, children: "Level 4 - Sub-subsection" }), _jsx("p", { style: { color: '#666' }, children: "Use h4 for sub-subsections. If you need deeper levels, reconsider your document structure." })] })); },
+};
+/**
+ * Example of a properly structured document hierarchy.
+ */
+export var DocumentStructure = {
+    render: function () { return (_jsxs("div", { children: [_jsx(Heading, { level: 1, children: "Getting Started Guide" }), _jsx("p", { children: "Introduction to the documentation system..." }), _jsx(Heading, { level: 2, children: "Installation" }), _jsx("p", { children: "How to install the components..." }), _jsx(Heading, { level: 3, children: "Prerequisites" }), _jsx("p", { children: "What you need before installing..." }), _jsx(Heading, { level: 3, children: "Installation Steps" }), _jsx("p", { children: "Step-by-step installation instructions..." }), _jsx(Heading, { level: 2, children: "Configuration" }), _jsx("p", { children: "How to configure the system..." }), _jsx(Heading, { level: 3, children: "Basic Configuration" }), _jsx("p", { children: "Essential configuration options..." }), _jsx(Heading, { level: 4, children: "Environment Variables" }), _jsx("p", { children: "Required environment variables..." })] })); },
+};

package/dist/components/Link.d.ts

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

package/dist/components/Link.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function Link(_a) {
+    var href = _a.href, children = _a.children, _b = _a.className, className = _b === void 0 ? '' : _b;
+    var isExternal = href.startsWith('http://') || href.startsWith('https://');
+    var classNames = "dds-link ".concat(className).trim();
+    if (isExternal) {
+        return (_jsxs("a", { href: href, className: classNames, target: "_blank", rel: "noopener noreferrer", children: [children, _jsx("svg", { className: "dds-link-icon", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14" }) })] }));
+    }
+    return _jsx("a", { href: href, className: classNames, children: children });
+}

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

@@ -0,0 +1,32 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Link } from './Link';
+/**
+ * The Link component creates styled hyperlinks with automatic external link handling.
+ */
+declare const meta: Meta<typeof Link>;
+export default meta;
+type Story = StoryObj<typeof Link>;
+/**
+ * Internal link (relative URL).
+ */
+export declare const Internal: Story;
+/**
+ * External link (absolute URL) - opens in new tab with icon.
+ */
+export declare const External: Story;
+/**
+ * Anchor link to a section on the same page.
+ */
+export declare const AnchorLink: Story;
+/**
+ * Link within body text.
+ */
+export declare const InlineLink: Story;
+/**
+ * Multiple links in a list.
+ */
+export declare const LinkList: Story;
+/**
+ * Comparison of internal and external links.
+ */
+export declare const InternalVsExternal: Story;

package/dist/components/Link.stories.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Link } from './Link';
+/**
+ * The Link component creates styled hyperlinks with automatic external link handling.
+ */
+var meta = {
+    title: 'Components/Link',
+    component: Link,
+    tags: ['autodocs'],
+    parameters: {
+        docs: {
+            description: {
+                component: "\nThe Link component provides consistent link styling and automatically handles external links.\n\n## When to Use\n\n- For navigation between pages\n- For links to external resources\n- For anchor links within a page\n- When you need a text link instead of a button\n\n## When Not to Use\n\n- For primary actions (use Button component)\n- For navigation that looks like a button (use Button)\n- For clickable cards (use Card with href prop)\n\n## Accessibility\n\n- Uses proper HTML anchor elements\n- External links automatically open in new tabs with proper security attributes\n- External links include a visual indicator icon\n- Screen readers announce the link purpose\n\n## External Link Behavior\n\nLinks starting with `http://` or `https://` are automatically treated as external:\n- Open in a new tab (target=\"_blank\")\n- Include security attributes (rel=\"noopener noreferrer\")\n- Display an external link icon\n        ",
+            },
+        },
+    },
+};
+export default meta;
+/**
+ * Internal link (relative URL).
+ */
+export var Internal = {
+    args: {
+        href: '/docs/components',
+        children: 'View Components Documentation',
+    },
+};
+/**
+ * External link (absolute URL) - opens in new tab with icon.
+ */
+export var External = {
+    args: {
+        href: 'https://github.com/your-repo/docs-design-system',
+        children: 'View on GitHub',
+    },
+};
+/**
+ * Anchor link to a section on the same page.
+ */
+export var AnchorLink = {
+    args: {
+        href: '#installation',
+        children: 'Jump to Installation',
+    },
+};
+/**
+ * Link within body text.
+ */
+export var InlineLink = {
+    render: function () { return (_jsxs("p", { children: ["For more information, check out the", ' ', _jsx(Link, { href: "/docs/getting-started", children: "Getting Started guide" }), ' ', "or visit our", ' ', _jsx(Link, { href: "https://github.com", children: "GitHub repository" }), "."] })); },
+};
+/**
+ * Multiple links in a list.
+ */
+export var LinkList = {
+    render: function () { return (_jsxs("ul", { style: { listStyle: 'none', padding: 0, display: 'flex', flexDirection: 'column', gap: '0.5rem' }, children: [_jsx("li", { children: _jsx(Link, { href: "/docs/introduction", children: "Introduction" }) }), _jsx("li", { children: _jsx(Link, { href: "/docs/components", children: "Components" }) }), _jsx("li", { children: _jsx(Link, { href: "/docs/best-practices", children: "Best Practices" }) }), _jsx("li", { children: _jsx(Link, { href: "https://github.com", children: "GitHub" }) }), _jsx("li", { children: _jsx(Link, { href: "https://npmjs.com", children: "NPM" }) })] })); },
+};
+/**
+ * Comparison of internal and external links.
+ */
+export var InternalVsExternal = {
+    render: function () { return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: '1rem' }, children: [_jsxs("div", { children: [_jsx("strong", { children: "Internal Link:" }), _jsx("br", {}), _jsx(Link, { href: "/docs/components", children: "Components (internal)" }), _jsx("p", { style: { fontSize: '0.875rem', color: '#666', marginTop: '0.5rem' }, children: "Opens in the same tab, no icon" })] }), _jsxs("div", { children: [_jsx("strong", { children: "External Link:" }), _jsx("br", {}), _jsx(Link, { href: "https://example.com", children: "Example.com (external)" }), _jsx("p", { style: { fontSize: '0.875rem', color: '#666', marginTop: '0.5rem' }, children: "Opens in new tab, includes external link icon" })] })] })); },
+};

package/dist/components/Typography.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+interface TypographyProps {
+    /**
+     * Typography style variant
+     * @default 'p'
+     */
+    variant?: 'h1' | 'h2' | 'h3' | 'h4' | 'p' | 'caption';
+    /** Text content */
+    children: React.ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const Typography: React.FC<TypographyProps>;
+export {};

package/dist/components/Typography.js

@@ -0,0 +1,9 @@
+import React from 'react';
+export var Typography = function (_a) {
+    var _b = _a.variant, variant = _b === void 0 ? 'p' : _b, children = _a.children, _c = _a.className, className = _c === void 0 ? '' : _c;
+    var Component = variant === 'p' || variant === 'caption' ? 'p' : variant;
+    var classNames = "dds-typography dds-typography-".concat(variant, " ").concat(className).trim();
+    return React.createElement(Component, {
+        className: classNames
+    }, children);
+};

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

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Typography } from './Typography';
+/**
+ * The Typography component provides consistent text styling across your documentation.
+ */
+declare const meta: Meta<typeof Typography>;
+export default meta;
+type Story = StoryObj<typeof Typography>;
+/**
+ * H1 heading style.
+ */
+export declare const H1: Story;
+/**
+ * H2 heading style.
+ */
+export declare const H2: Story;
+/**
+ * H3 heading style.
+ */
+export declare const H3: Story;
+/**
+ * H4 heading style.
+ */
+export declare const H4: Story;
+/**
+ * Paragraph style (default).
+ */
+export declare const Paragraph: Story;
+/**
+ * Caption style for small text.
+ */
+export declare const Caption: Story;
+/**
+ * All typography variants displayed together.
+ */
+export declare const AllVariants: Story;

package/dist/components/Typography.stories.js

@@ -0,0 +1,78 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Typography } from './Typography';
+/**
+ * The Typography component provides consistent text styling across your documentation.
+ */
+var meta = {
+    title: 'Components/Typography',
+    component: Typography,
+    tags: ['autodocs'],
+    parameters: {
+        docs: {
+            description: {
+                component: "\nThe Typography component renders text with predefined styles for consistency.\n\n## When to Use\n\n- For body text and paragraphs\n- For captions and small text\n- When you need consistent text styling\n- For headings when you don't need semantic HTML heading levels\n\n## When Not to Use\n\n- For semantic headings (use Heading component)\n- For buttons (use Button component)\n- For links (use Link component)\n\n## Accessibility\n\n- Uses proper HTML elements based on variant\n- Maintains readable contrast ratios\n- Supports custom classes for additional styling\n        ",
+            },
+        },
+    },
+};
+export default meta;
+/**
+ * H1 heading style.
+ */
+export var H1 = {
+    args: {
+        variant: 'h1',
+        children: 'Heading 1 Style',
+    },
+};
+/**
+ * H2 heading style.
+ */
+export var H2 = {
+    args: {
+        variant: 'h2',
+        children: 'Heading 2 Style',
+    },
+};
+/**
+ * H3 heading style.
+ */
+export var H3 = {
+    args: {
+        variant: 'h3',
+        children: 'Heading 3 Style',
+    },
+};
+/**
+ * H4 heading style.
+ */
+export var H4 = {
+    args: {
+        variant: 'h4',
+        children: 'Heading 4 Style',
+    },
+};
+/**
+ * Paragraph style (default).
+ */
+export var Paragraph = {
+    args: {
+        variant: 'p',
+        children: 'This is a paragraph with the default typography style. It provides readable text for body content.',
+    },
+};
+/**
+ * Caption style for small text.
+ */
+export var Caption = {
+    args: {
+        variant: 'caption',
+        children: 'This is caption text, typically used for figure captions or footnotes.',
+    },
+};
+/**
+ * All typography variants displayed together.
+ */
+export var AllVariants = {
+    render: function () { return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: '1rem' }, children: [_jsx(Typography, { variant: "h1", children: "Heading 1 Style" }), _jsx(Typography, { variant: "h2", children: "Heading 2 Style" }), _jsx(Typography, { variant: "h3", children: "Heading 3 Style" }), _jsx(Typography, { variant: "h4", children: "Heading 4 Style" }), _jsx(Typography, { variant: "p", children: "This is paragraph text. It's the default variant and is suitable for body content and general text throughout your documentation." }), _jsx(Typography, { variant: "caption", children: "This is caption text, used for smaller annotations or supplementary information." })] })); },
+};

package/dist/hooks/useKeyPress.d.ts

@@ -0,0 +1,5 @@
+interface UseKeyPressOptions {
+    ignoreTextInput?: boolean;
+}
+export declare const useKeyPress: (keys: string | string[], handler: (event: KeyboardEvent) => void, { ignoreTextInput }?: UseKeyPressOptions) => void;
+export {};

package/dist/hooks/useKeyPress.js

@@ -0,0 +1,60 @@
+import { useEffect, useRef, useMemo } from 'react';
+var normalizeKeyCombination = function (keys) {
+    var parts = keys.split(/\s*\+\s*/);
+    if (parts.length === 1) {
+        return [null, parts[0]];
+    }
+    return [parts[0], parts[1]];
+};
+var matchesModifierKey = function (modifier, event) {
+    switch (modifier) {
+        case null:
+            return true;
+        case 'cmd':
+            return event.metaKey || event.ctrlKey;
+        case 'ctrl':
+            return event.ctrlKey;
+        case 'shift':
+            return event.shiftKey;
+        case 'alt':
+            return event.altKey;
+        default:
+            return false;
+    }
+};
+var matchesAnyCombination = function (combinations, event) {
+    return combinations.some(function (_a) {
+        var modifier = _a[0], key = _a[1];
+        return event.key === key && matchesModifierKey(modifier, event);
+    });
+};
+var isTypingInInput = function (event) {
+    var target = event.target;
+    return target.matches('input') || target.matches('textarea');
+};
+export var useKeyPress = function (keys, handler, _a) {
+    var _b = _a === void 0 ? {} : _a, _c = _b.ignoreTextInput, ignoreTextInput = _c === void 0 ? true : _c;
+    var savedHandler = useRef(handler);
+    var combinations = useMemo(function () {
+        return Array.isArray(keys)
+            ? keys.map(normalizeKeyCombination)
+            : [normalizeKeyCombination(keys)];
+    }, [keys]);
+    useEffect(function () {
+        savedHandler.current = handler;
+    }, [handler]);
+    useEffect(function () {
+        var handleKeyDown = function (event) {
+            if (ignoreTextInput && isTypingInInput(event)) {
+                return;
+            }
+            if (matchesAnyCombination(combinations, event)) {
+                savedHandler.current(event);
+            }
+        };
+        document.addEventListener('keydown', handleKeyDown);
+        return function () {
+            document.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [combinations, ignoreTextInput]);
+};

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './components/Button';
+export * from './components/Callout';
+export * from './components/Card';
+export * from './components/CardGrid';
+export * from './components/Collapser';
+export * from './components/CodeBlock';
+export * from './components/Typography';
+export * from './components/Heading';
+export * from './components/Link';
+export * from './hooks/useKeyPress';

package/dist/index.js

@@ -0,0 +1,12 @@
+// Export all components
+export * from './components/Button';
+export * from './components/Callout';
+export * from './components/Card';
+export * from './components/CardGrid';
+export * from './components/Collapser';
+export * from './components/CodeBlock';
+export * from './components/Typography';
+export * from './components/Heading';
+export * from './components/Link';
+// Export hooks
+export * from './hooks/useKeyPress';