@roadlittledawn/docs-design-system-react 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# @roadlittledawn/docs-design-system-react
+
+React components for building documentation interfaces.
+
+## Installation
+
+```bash
+npm install @roadlittledawn/docs-design-system-react
+```
+
+## Usage
+
+```tsx
+import { Callout, CodeBlock, Card } from '@roadlittledawn/docs-design-system-react';
+```
+
+### Importing Styles
+
+Import the component styles in your app:
+
+```tsx
+import '@roadlittledawn/docs-design-system-react/styles.css';
+```
+
+## Components
+
+### Callout
+
+Highlight important information, warnings, tips, or notes.
+
+```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>
+```
+
+### 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>
+```
+
+## Hooks
+
+### useKeyPress
+
+Listen for keyboard events.
+
+```tsx
+const isPressed = useKeyPress('Escape');
+```
+
+## Documentation
+
+Full component documentation with live examples is available in our Storybook.
+
+**Storybook URL:** _Coming soon_
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Watch mode for development
+npm run dev
+```

package/dist/components/Button.d.ts

@@ -0,0 +1,17 @@
+import React from "react";
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * Visual style variant of the button
+     * @default 'primary'
+     */
+    variant?: "primary" | "secondary" | "outline";
+    /**
+     * Size of the button
+     * @default 'md'
+     */
+    size?: "sm" | "md" | "lg";
+    /** Button content */
+    children: React.ReactNode;
+}
+export declare const Button: React.FC<ButtonProps>;
+export {};

package/dist/components/Button.js

@@ -0,0 +1,28 @@
+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);
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { jsx as _jsx } from "react/jsx-runtime";
+export var Button = function (_a) {
+    var _b = _a.variant, variant = _b === void 0 ? "primary" : _b, _c = _a.size, size = _c === void 0 ? "md" : _c, children = _a.children, _d = _a.className, className = _d === void 0 ? "" : _d, props = __rest(_a, ["variant", "size", "children", "className"]);
+    var classNames = "dds-button dds-button-".concat(variant, " dds-button-").concat(size, " ").concat(className).trim();
+    return (_jsx("button", __assign({ className: classNames }, props, { children: children })));
+};

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

@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button } from './Button';
+/**
+ * The Button component is used for user actions and navigation.
+ * It supports multiple variants and sizes to accommodate different use cases.
+ */
+declare const meta: Meta<typeof Button>;
+export default meta;
+type Story = StoryObj<typeof Button>;
+/**
+ * The primary button style is used for the main action on a page.
+ */
+export declare const Primary: Story;
+/**
+ * The secondary button style is used for alternative or less important actions.
+ */
+export declare const Secondary: Story;
+/**
+ * The outline button style is used for tertiary actions or when you need a more subtle button.
+ */
+export declare const Outline: Story;
+/**
+ * Small button size for compact interfaces or less prominent actions.
+ */
+export declare const Small: Story;
+/**
+ * Medium is the default button size, suitable for most use cases.
+ */
+export declare const Medium: Story;
+/**
+ * Large button size for prominent calls-to-action.
+ */
+export declare const Large: Story;
+/**
+ * Disabled state for buttons that are temporarily unavailable.
+ */
+export declare const Disabled: Story;
+/**
+ * Example showing all button variants side by side for comparison.
+ */
+export declare const AllVariants: Story;
+/**
+ * Example showing all button sizes side by side for comparison.
+ */
+export declare const AllSizes: Story;

package/dist/components/Button.stories.js

@@ -0,0 +1,98 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from './Button';
+/**
+ * The Button component is used for user actions and navigation.
+ * It supports multiple variants and sizes to accommodate different use cases.
+ */
+var meta = {
+    title: 'Components/Button',
+    component: Button,
+    tags: ['autodocs'],
+    parameters: {
+        docs: {
+            description: {
+                component: "\nThe Button component provides a consistent way to trigger actions across your documentation.\n\n## When to Use\n\n- Primary actions like \"Submit\", \"Save\", or \"Continue\"\n- Secondary actions like \"Cancel\" or \"Go Back\"\n- Important calls-to-action within documentation pages\n\n## When Not to Use\n\n- For navigation between pages (use the Link component instead)\n- For less important actions (consider using a text link)\n- When you need a clickable card (use Card with href prop)\n\n## Accessibility\n\n- All buttons include proper HTML button semantics\n- Buttons are keyboard accessible\n- Use descriptive button text for screen readers\n        ",
+            },
+        },
+    },
+};
+export default meta;
+/**
+ * The primary button style is used for the main action on a page.
+ */
+export var Primary = {
+    args: {
+        variant: 'primary',
+        children: 'Primary Button',
+    },
+};
+/**
+ * The secondary button style is used for alternative or less important actions.
+ */
+export var Secondary = {
+    args: {
+        variant: 'secondary',
+        children: 'Secondary Button',
+    },
+};
+/**
+ * The outline button style is used for tertiary actions or when you need a more subtle button.
+ */
+export var Outline = {
+    args: {
+        variant: 'outline',
+        children: 'Outline Button',
+    },
+};
+/**
+ * Small button size for compact interfaces or less prominent actions.
+ */
+export var Small = {
+    args: {
+        variant: 'primary',
+        size: 'sm',
+        children: 'Small Button',
+    },
+};
+/**
+ * Medium is the default button size, suitable for most use cases.
+ */
+export var Medium = {
+    args: {
+        variant: 'primary',
+        size: 'md',
+        children: 'Medium Button',
+    },
+};
+/**
+ * Large button size for prominent calls-to-action.
+ */
+export var Large = {
+    args: {
+        variant: 'primary',
+        size: 'lg',
+        children: 'Large Button',
+    },
+};
+/**
+ * Disabled state for buttons that are temporarily unavailable.
+ */
+export var Disabled = {
+    args: {
+        variant: 'primary',
+        children: 'Disabled Button',
+        disabled: true,
+    },
+};
+/**
+ * Example showing all button variants side by side for comparison.
+ */
+export var AllVariants = {
+    render: function () { return (_jsxs("div", { style: { display: 'flex', gap: '1rem', flexWrap: 'wrap', alignItems: 'center' }, children: [_jsx(Button, { variant: "primary", children: "Primary" }), _jsx(Button, { variant: "secondary", children: "Secondary" }), _jsx(Button, { variant: "outline", children: "Outline" })] })); },
+};
+/**
+ * Example showing all button sizes side by side for comparison.
+ */
+export var AllSizes = {
+    render: function () { return (_jsxs("div", { style: { display: 'flex', gap: '1rem', flexWrap: 'wrap', alignItems: 'center' }, children: [_jsx(Button, { size: "sm", children: "Small" }), _jsx(Button, { size: "md", children: "Medium" }), _jsx(Button, { size: "lg", children: "Large" })] })); },
+};

package/dist/components/Callout.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from "react";
+export type CalloutVariant = "caution" | "important" | "tip" | "course";
+interface CalloutProps {
+    /** Visual style variant of the callout (caution, important, tip, or course) */
+    variant: CalloutVariant;
+    /**
+     * Optional title for the callout. Pass null to hide the title completely
+     * @default Default title based on variant ("Caution", "Important", "Tip", or "Course")
+     */
+    title?: string | null;
+    /** Callout content */
+    children: ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function Callout({ variant, title, children, className, }: CalloutProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Callout.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+var defaultTitles = {
+    caution: "Caution",
+    important: "Important",
+    tip: "Tip",
+    course: "Course",
+};
+export function Callout(_a) {
+    var variant = _a.variant, title = _a.title, children = _a.children, _b = _a.className, className = _b === void 0 ? "" : _b;
+    var calloutClasses = [
+        "dds-callout",
+        "dds-callout-".concat(variant),
+        className,
+    ]
+        .filter(Boolean)
+        .join(" ");
+    var titleClasses = ["dds-callout-title", "dds-callout-title-".concat(variant)].join(" ");
+    return (_jsxs("div", { className: calloutClasses, children: [title !== null && (_jsx("h4", { className: titleClasses, children: title || defaultTitles[variant] })), children] }));
+}

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

@@ -0,0 +1,36 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Callout } from './Callout';
+/**
+ * The Callout component highlights important information, warnings, tips, and course-specific content.
+ */
+declare const meta: Meta<typeof Callout>;
+export default meta;
+type Story = StoryObj<typeof Callout>;
+/**
+ * Caution callout for warnings and things to avoid.
+ */
+export declare const Caution: Story;
+/**
+ * Important callout for critical information.
+ */
+export declare const Important: Story;
+/**
+ * Tip callout for helpful suggestions.
+ */
+export declare const Tip: Story;
+/**
+ * Course callout for learning-oriented content.
+ */
+export declare const Course: Story;
+/**
+ * Callout with a custom title.
+ */
+export declare const CustomTitle: Story;
+/**
+ * Callout without a title.
+ */
+export declare const NoTitle: Story;
+/**
+ * All callout variants displayed together for comparison.
+ */
+export declare const AllVariants: Story;

package/dist/components/Callout.stories.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Callout } from './Callout';
+/**
+ * The Callout component highlights important information, warnings, tips, and course-specific content.
+ */
+var meta = {
+    title: 'Components/Callout',
+    component: Callout,
+    tags: ['autodocs'],
+    parameters: {
+        docs: {
+            description: {
+                component: "\nThe Callout component draws attention to important information within documentation pages.\n\n## When to Use\n\n- **Caution**: For warnings about potential issues or things to avoid\n- **Important**: For critical information users must know\n- **Tip**: For helpful suggestions and best practices\n- **Course**: For course-specific or learning-oriented content\n\n## When Not to Use\n\n- For general content (use regular paragraphs)\n- For code examples (use code blocks)\n- For navigation (use Link or Button components)\n\n## Accessibility\n\n- Uses semantic heading tags for titles\n- Color alone is not used to convey meaning (icons and labels provide context)\n        ",
+            },
+        },
+    },
+};
+export default meta;
+/**
+ * Caution callout for warnings and things to avoid.
+ */
+export var Caution = {
+    args: {
+        variant: 'caution',
+        children: 'This operation cannot be undone. Make sure you have a backup before proceeding.',
+    },
+};
+/**
+ * Important callout for critical information.
+ */
+export var Important = {
+    args: {
+        variant: 'important',
+        children: 'All users must update their passwords by the end of the month to comply with the new security policy.',
+    },
+};
+/**
+ * Tip callout for helpful suggestions.
+ */
+export var Tip = {
+    args: {
+        variant: 'tip',
+        children: 'You can use keyboard shortcuts (Cmd+K or Ctrl+K) to quickly search the documentation.',
+    },
+};
+/**
+ * Course callout for learning-oriented content.
+ */
+export var Course = {
+    args: {
+        variant: 'course',
+        children: 'In this section, you will learn how to configure your development environment and install the necessary dependencies.',
+    },
+};
+/**
+ * Callout with a custom title.
+ */
+export var CustomTitle = {
+    args: {
+        variant: 'important',
+        title: 'Security Notice',
+        children: 'Two-factor authentication is now required for all administrator accounts.',
+    },
+};
+/**
+ * Callout without a title.
+ */
+export var NoTitle = {
+    args: {
+        variant: 'tip',
+        title: null,
+        children: 'This callout has no title and displays only the content.',
+    },
+};
+/**
+ * All callout variants displayed together for comparison.
+ */
+export var AllVariants = {
+    render: function () { return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: '1rem' }, children: [_jsx(Callout, { variant: "caution", children: "Caution: Be careful when modifying system files." }), _jsx(Callout, { variant: "important", children: "Important: This feature requires administrator privileges." }), _jsx(Callout, { variant: "tip", children: "Tip: Use the search function to find topics quickly." }), _jsx(Callout, { variant: "course", children: "Course: This module covers the basics of component design." })] })); },
+};

package/dist/components/Card.d.ts

@@ -0,0 +1,23 @@
+import { ReactNode } from "react";
+interface CardProps {
+    /** Optional title displayed at the top of the card */
+    title?: string;
+    /**
+     * Color of the title text
+     * @default 'gray'
+     */
+    titleColor?: "blue" | "green" | "purple" | "red" | "yellow" | "gray";
+    /**
+     * Background color of the card
+     * @default 'white'
+     */
+    backgroundColor?: "blue" | "green" | "purple" | "red" | "yellow" | "gray" | "white";
+    /** Optional link URL. When provided, the entire card becomes clickable */
+    href?: string;
+    /** Card content */
+    children: ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function Card({ title, titleColor, backgroundColor, href, children, className, }: CardProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Card.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function Card(_a) {
+    var title = _a.title, _b = _a.titleColor, titleColor = _b === void 0 ? "gray" : _b, _c = _a.backgroundColor, backgroundColor = _c === void 0 ? "white" : _c, href = _a.href, children = _a.children, _d = _a.className, className = _d === void 0 ? "" : _d;
+    var cardClasses = [
+        "dds-card",
+        "dds-card-bg-".concat(backgroundColor),
+        href ? "dds-card-clickable" : "",
+        className,
+    ]
+        .filter(Boolean)
+        .join(" ");
+    var titleClasses = ["dds-card-title", "dds-card-title-".concat(titleColor)].join(" ");
+    var textClasses = backgroundColor !== "white"
+        ? "dds-card-text-".concat(backgroundColor)
+        : "dds-card-text-gray";
+    var content = (_jsxs("div", { className: cardClasses, children: [title && _jsx("h3", { className: titleClasses, children: title }), _jsx("div", { className: textClasses, children: children })] }));
+    if (href) {
+        return (_jsx("a", { href: href, className: "no-text-decoration", children: content }));
+    }
+    return content;
+}

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

@@ -0,0 +1,32 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Card } from './Card';
+/**
+ * The Card component displays content in a contained, elevated box with optional title and background color.
+ */
+declare const meta: Meta<typeof Card>;
+export default meta;
+type Story = StoryObj<typeof Card>;
+/**
+ * Basic card with title and content.
+ */
+export declare const Basic: Story;
+/**
+ * Clickable card that links to another page.
+ */
+export declare const Clickable: Story;
+/**
+ * Card with colored background.
+ */
+export declare const ColoredBackground: Story;
+/**
+ * Card without a title.
+ */
+export declare const NoTitle: Story;
+/**
+ * All title color variants.
+ */
+export declare const TitleColors: Story;
+/**
+ * All background color variants.
+ */
+export declare const BackgroundColors: Story;

package/dist/components/Card.stories.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Card } from './Card';
+/**
+ * The Card component displays content in a contained, elevated box with optional title and background color.
+ */
+var meta = {
+    title: 'Components/Card',
+    component: Card,
+    tags: ['autodocs'],
+    parameters: {
+        docs: {
+            description: {
+                component: "\nThe Card component provides a flexible container for displaying content with visual hierarchy.\n\n## When to Use\n\n- To group related content together\n- To create clickable navigation elements\n- To display feature highlights or key information\n- To organize content in grid layouts\n\n## When Not to Use\n\n- For plain text content (use typography components)\n- For alerts or notifications (use Callout)\n- For extensive content (consider using sections or pages)\n\n## Accessibility\n\n- Clickable cards use proper link semantics\n- Color is not the only means of conveying information\n        ",
+            },
+        },
+    },
+};
+export default meta;
+/**
+ * Basic card with title and content.
+ */
+export var Basic = {
+    args: {
+        title: 'Getting Started',
+        children: 'Learn the basics of using this documentation system.',
+    },
+};
+/**
+ * Clickable card that links to another page.
+ */
+export var Clickable = {
+    args: {
+        title: 'API Reference',
+        href: '/docs/api',
+        children: 'Complete reference for all available components and utilities.',
+    },
+};
+/**
+ * Card with colored background.
+ */
+export var ColoredBackground = {
+    args: {
+        title: 'New Feature',
+        titleColor: 'blue',
+        backgroundColor: 'blue',
+        children: 'Check out our latest component additions.',
+    },
+};
+/**
+ * Card without a title.
+ */
+export var NoTitle = {
+    args: {
+        children: 'This card displays content without a title.',
+    },
+};
+/**
+ * All title color variants.
+ */
+export var TitleColors = {
+    render: function () { return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: '1rem' }, children: [_jsx(Card, { title: "Blue Title", titleColor: "blue", children: "Content with blue title" }), _jsx(Card, { title: "Green Title", titleColor: "green", children: "Content with green title" }), _jsx(Card, { title: "Purple Title", titleColor: "purple", children: "Content with purple title" }), _jsx(Card, { title: "Red Title", titleColor: "red", children: "Content with red title" }), _jsx(Card, { title: "Yellow Title", titleColor: "yellow", children: "Content with yellow title" }), _jsx(Card, { title: "Gray Title", titleColor: "gray", children: "Content with gray title" })] })); },
+};
+/**
+ * All background color variants.
+ */
+export var BackgroundColors = {
+    render: function () { return (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: '1rem' }, children: [_jsx(Card, { title: "Blue", backgroundColor: "blue", children: "Card with blue background" }), _jsx(Card, { title: "Green", backgroundColor: "green", children: "Card with green background" }), _jsx(Card, { title: "Purple", backgroundColor: "purple", children: "Card with purple background" }), _jsx(Card, { title: "Red", backgroundColor: "red", children: "Card with red background" }), _jsx(Card, { title: "Yellow", backgroundColor: "yellow", children: "Card with yellow background" }), _jsx(Card, { title: "Gray", backgroundColor: "gray", children: "Card with gray background" }), _jsx(Card, { title: "White", backgroundColor: "white", children: "Card with white background" })] })); },
+};

package/dist/components/CardGrid.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from 'react';
+interface CardGridProps {
+    /**
+     * Number of columns in the grid
+     * @default 3
+     */
+    columns?: 2 | 3 | 4;
+    /** Grid content (typically Card components) */
+    children: ReactNode;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function CardGrid({ columns, children, className }: CardGridProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/CardGrid.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export function CardGrid(_a) {
+    var _b = _a.columns, columns = _b === void 0 ? 3 : _b, children = _a.children, _c = _a.className, className = _c === void 0 ? '' : _c;
+    var classNames = "dds-card-grid dds-card-grid-".concat(columns, " ").concat(className).trim();
+    return (_jsx("div", { className: classNames, children: children }));
+}

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

@@ -0,0 +1,24 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { CardGrid } from './CardGrid';
+/**
+ * The CardGrid component arranges Card components in a responsive grid layout.
+ */
+declare const meta: Meta<typeof CardGrid>;
+export default meta;
+type Story = StoryObj<typeof CardGrid>;
+/**
+ * Grid with 2 columns (responsive).
+ */
+export declare const TwoColumns: Story;
+/**
+ * Grid with 3 columns (default, responsive).
+ */
+export declare const ThreeColumns: Story;
+/**
+ * Grid with 4 columns (responsive).
+ */
+export declare const FourColumns: Story;
+/**
+ * Grid with clickable cards.
+ */
+export declare const ClickableCards: Story;