doom-design-system 0.4.17 → 0.5.1

package/.agent/skills/doom/components/chart.md

@@ -8,31 +8,38 @@ import { Chart } from "doom-design-system";
 
 ## Props
 
-| Prop            | Type                        | Default  | Description                |
-| --------------- | --------------------------- | -------- | -------------------------- |
-| `data`          | `T[]`                       | required | Data array                 |
-| `config`        | `ChartConfig`               | required | Series configuration       |
-| `type`          | `"line" \| "area" \| "bar"` | —        | Chart type (shorthand API) |
-| `xKey`          | `string`                    | required | X-axis data key            |
-| `height`        | `number`                    | `300`    | Chart height               |
-| `title`         | `string`                    | —        | Chart title                |
-| `subtitle`      | `string`                    | —        | Chart subtitle             |
-| `withLegend`    | `boolean`                   | —        | Show legend                |
-| `render`        | `(ctx) => ReactNode`        | —        | Custom render function     |
-| `renderTooltip` | `(ctx) => ReactNode`        | —        | Custom tooltip             |
-
-## Config
+| Prop            | Type                         | Default     | Description                         |
+| --------------- | ---------------------------- | ----------- | ----------------------------------- |
+| `data`          | `T[]`                        | required    | Data array                          |
+| `x`             | `(d: T) => string \| number` | required    | Accessor function for X-axis values |
+| `y`             | `(d: T) => number`           | required    | Accessor function for Y-axis values |
+| `type`          | `"line" \| "area" \| "bar"`  | —           | Chart type (shorthand API)          |
+| `title`         | `string \| ReactNode`        | —           | Chart title                         |
+| `subtitle`      | `string`                     | —           | Chart subtitle                      |
+| `withLegend`    | `boolean`                    | —           | Show legend                         |
+| `withFrame`     | `boolean`                    | `true`      | Render card frame around chart      |
+| `variant`       | `"default" \| "solid"`       | `"default"` | Visual variant                      |
+| `flat`          | `boolean`                    | `false`     | Remove shadow                       |
+| `d3Config`      | `ChartConfig`                | —           | D3 configuration options            |
+| `render`        | `(ctx: DrawContext) => void` | —           | Custom D3 render function           |
+| `renderTooltip` | `(data: T) => ReactNode`     | —           | Custom tooltip renderer             |
+| `onValueChange` | `(data: T \| null) => void`  | —           | Callback when hovered value changes |
+| `style`         | `CSSProperties`              | —           | Inline styles                       |
+| `className`     | `string`                     | —           | CSS class name                      |
+
+## D3 Config
 
 ```tsx
-const config = {
-  revenue: {
-    label: "Revenue",
-    color: "var(--primary)",
-  },
-  profit: {
-    label: "Profit",
-    color: "var(--success)",
-  },
+const d3Config = {
+  margin: { top: 20, right: 20, bottom: 40, left: 50 },
+  grid: true,
+  withGradient: true,
+  showDots: true,
+  hideYAxisDomain: true,
+  xAxisLabel: "Month",
+  yAxisLabel: "Revenue (USD)",
+  curve: d3Shape.curveMonotoneX, // requires import from d3-shape
+  animate: true,
 };
 ```
 
@@ -41,31 +48,59 @@ const config = {
 ### Shorthand API
 
 ```tsx
+const data = [
+  { month: "Jan", revenue: 4500 },
+  { month: "Feb", revenue: 5200 },
+  { month: "Mar", revenue: 4900 },
+];
+
 <Chart
-  type="line"
+  type="area"
   data={data}
-  config={config}
-  xKey="month"
+  x={(d) => d.month}
+  y={(d) => d.revenue}
   title="Monthly Revenue"
   withLegend
-/>
+  d3Config={{ grid: true, withGradient: true }}
+/>;
 ```
 
 ### Composition API
 
 ```tsx
-<Chart.Root data={data} config={config} xKey="month">
+<Chart.Root
+  data={data}
+  x={(d) => d.label}
+  y={(d) => d.value}
+  d3Config={{ grid: true, showDots: true }}
+>
   <Chart.Header title="Sales" subtitle="Last 12 months">
     <Chart.Legend />
   </Chart.Header>
-  <Chart.Plot type="area" />
-  <Chart.Footer>Custom footer</Chart.Footer>
+  <Chart.Plot type="area" color="var(--primary)" />
+  <Chart.Footer>Custom footer content</Chart.Footer>
 </Chart.Root>
 ```
 
+### Custom D3 Render
+
+```tsx
+<Chart
+  data={pieData}
+  x={(d) => d.label}
+  y={(d) => d.value}
+  d3Config={{ showAxes: false, grid: false }}
+  render={(ctx) => {
+    // Full D3 access via ctx.g (SVG group)
+    // ctx.data, ctx.xScale, ctx.yScale available
+  }}
+/>
+```
+
 ## Guidelines
 
-- Use shorthand API for simple charts.
-- Use composition API for custom layouts.
-- Built on D3.js; supports line, area, and bar charts.
-- Supports gradients with `withGradient` prop on Plot.
+- Use shorthand API for simple line/area/bar charts.
+- Use composition API for custom layouts with headers/footers.
+- Use `render` prop for fully custom D3 visualizations (pie, treemap, etc.).
+- Built on D3.js with full access to scales and selections.
+- Supports touch interactions and responsive sizing.

package/.agent/skills/doom/components/copybutton.md

@@ -0,0 +1,41 @@
+# CopyButton Component
+
+## Import
+
+```tsx
+import { CopyButton } from "doom-design-system";
+```
+
+## Props
+
+| Prop         | Type           | Default       | Description              |
+| ------------ | -------------- | ------------- | ------------------------ |
+| `value`      | `string`       | **required**  | Text to copy             |
+| `variant`    | Button variant | `"secondary"` | Visual style             |
+| `size`       | Button size    | `"md"`        | Button size              |
+| `copiedText` | `string`       | `"Copied!"`   | Text shown after copy    |
+| `resetDelay` | `number`       | `2000`        | Ms before reset to orig. |
+
+Plus all standard `<button>` HTML attributes.
+
+## Usage
+
+```tsx
+<CopyButton value={textToCopy}>Copy</CopyButton>
+
+<CopyButton value={code} variant="ghost" size="sm">
+  Copy Code
+</CopyButton>
+
+<CopyButton copiedText="Done!" value={referenceDoc}>
+  Copy Reference
+</CopyButton>
+```
+
+## Behavior
+
+- **Tactile Pop Animation**: Press effect on click, springy scale-in for success state
+- Text changes to `copiedText` (default: "Copied!")
+- Button width preserved (doesn't jump)
+- Auto-resets after `resetDelay` ms (default 2s)
+- Variant stays the same (no jarring color change)

package/.agent/skills/doom/components/sidebar.md

@@ -0,0 +1,92 @@
+# Sidebar Component
+
+The Sidebar is a complex navigation component supporting dual-mode (Standard and Rail), collapsible sections, groups, and hover-peek functionality.
+
+## Import
+
+```tsx
+import { Sidebar } from "doom-design-system";
+```
+
+## Props
+
+### Sidebar
+
+| Prop              | Type                                           | Default | Description                                                      |
+| ----------------- | ---------------------------------------------- | ------- | ---------------------------------------------------------------- |
+| `withRail`        | `boolean`                                      | `false` | Enables the two-column rail navigation.                          |
+| `collapsed`       | `boolean`                                      | `false` | Collapses the main panel (standard) or whole sidebar (rail).     |
+| `activeSection`   | `string`                                       | —       | The ID of the currently active Section.                          |
+| `activeItem`      | `string`                                       | —       | The `href` of the currently active Item.                         |
+| `onNavigate`      | `(href: string, e?: React.MouseEvent) => void` | —       | Navigation callback.                                             |
+| `onSectionChange` | `(id: string) => void`                         | —       | Callback when the active section changes (useful for Rail mode). |
+| `brandIcon`       | `React.ReactNode`                              | —       | Icon displayed at the top of the Sidebar/Rail.                   |
+
+### Sidebar.Section
+
+| Prop       | Type              | Default | Description                                    |
+| ---------- | ----------------- | ------- | ---------------------------------------------- |
+| `id`       | `string`          | —       | Unique identifier for section switching.       |
+| `label`    | `string`          | —       | Descriptive label for the section.             |
+| `icon`     | `React.ReactNode` | —       | Icon for the section (required for Rail mode). |
+| `expanded` | `boolean`         | —       | Controlled expansion state.                    |
+
+### Sidebar.Group
+
+| Prop       | Type              | Default | Description                      |
+| ---------- | ----------------- | ------- | -------------------------------- |
+| `id`       | `string`          | —       | Unique identifier for the group. |
+| `label`    | `string`          | —       | Descriptive label for the group. |
+| `icon`     | `React.ReactNode` | —       | Optional icon for the group.     |
+| `expanded` | `boolean`         | —       | Controlled expansion state.      |
+
+### Sidebar.Item
+
+| Prop            | Type              | Default | Description                                     |
+| --------------- | ----------------- | ------- | ----------------------------------------------- |
+| `href`          | `string`          | —       | Link destination.                               |
+| `icon`          | `React.ReactNode` | —       | Optional icon.                                  |
+| `appendContent` | `React.ReactNode` | —       | Content (badges, chips) at the end of the item. |
+
+## Usage
+
+### Standard Sidebar
+
+```tsx
+<Sidebar activeItem="/home">
+  <Sidebar.Header>App Logo</Sidebar.Header>
+  <Sidebar.Nav>
+    <Sidebar.Section id="main" label="Main" icon={<Home />}>
+      <Sidebar.Item href="/home" icon={<Home />}>
+        Dashboard
+      </Sidebar.Item>
+      <Sidebar.Item href="/inbox">Inbox</Sidebar.Item>
+    </Sidebar.Section>
+  </Sidebar.Nav>
+</Sidebar>
+```
+
+### Rail Mode with Groups
+
+```tsx
+<Sidebar withRail activeSection="admin">
+  <Sidebar.Nav>
+    <Sidebar.Section id="main" label="Main" icon={<Home />}>
+      <Sidebar.Item href="/home">Home</Sidebar.Item>
+    </Sidebar.Section>
+    <Sidebar.Section id="admin" label="Admin" icon={<Settings />}>
+      <Sidebar.Group id="users" label="User Management">
+        <Sidebar.Item href="/users/list">User List</Sidebar.Item>
+        <Sidebar.Item href="/users/permissions">Permissions</Sidebar.Item>
+      </Sidebar.Group>
+    </Sidebar.Section>
+  </Sidebar.Nav>
+</Sidebar>
+```
+
+## Guidelines
+
+- **Rail Icons**: Ensure every `Sidebar.Section` has an `icon` if `withRail` is enabled.
+- **Snappy UI**: The component uses instant transitions for a high-performance feel.
+- **Auto-collapse**: In rail mode, clicking an item auto-collapses to save space.
+- **Accessibility**: Collapsed content is hidden via `display: none` to remove it from keyboard tab order.

package/.agent/skills/doom/index.md

@@ -112,6 +112,7 @@ function ThemeSwitcher() {
 - [breadcrumbs.md](components/breadcrumbs.md) — Navigation hierarchy
 - [link.md](components/link.md) — Anchor links
 - [pagination.md](components/pagination.md) — Page navigation
+- [sidebar.md](components/sidebar.md) — Multi-mode side navigation
 - [tabs.md](components/tabs.md) — Tab navigation
 
 ### Forms

package/README.md

@@ -1,6 +1,6 @@
 # Doom Design System
 
-[![Doom CI](https://github.com/ornelasEduardo/doom/actions/workflows/ci.yml/badge.svg)](https://github.com/ornelasEduardo/doom/actions/workflows/ci.yml)
+[![Doom CI](https://github.com/ornelasEduardo/doom/actions/workflows/main.yml/badge.svg)](https://github.com/ornelasEduardo/doom/actions/workflows/main.yml)
 [![npm version](https://img.shields.io/npm/v/doom-design-system.svg)](https://www.npmjs.com/package/doom-design-system)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 

package/dist/components/A2UI/Renderer.d.ts

@@ -0,0 +1,51 @@
+import React from "react";
+import type { A2UIComponentEntry, SurfaceUpdateMessage } from "./types";
+/**
+ * Props for the A2UI Renderer component.
+ */
+export interface RendererProps {
+    /**
+     * A2UI surface update payload or array of component entries.
+     *
+     * Can be either:
+     * - A full `surfaceUpdate` payload with surfaceId and components
+     * - Just the components array for simpler usage
+     */
+    surface: SurfaceUpdateMessage["surfaceUpdate"] | A2UIComponentEntry[];
+    /**
+     * ID of the root component to render.
+     *
+     * Required when `surface` is a components array.
+     * Optional when `surface` is a full payload (uses the first component if omitted).
+     */
+    rootId?: string;
+    /**
+     * Data model for resolving path bindings.
+     *
+     * When components use `{ path: "/user/name" }` values,
+     * they are resolved against this object.
+     */
+    dataModel?: Record<string, unknown>;
+}
+/**
+ * A2UI Renderer Component
+ *
+ * Renders A2UI component trees following the official message schema.
+ * Handles adjacency list resolution, data binding, and component mapping.
+ *
+ * @see https://a2ui.org/reference/messages/
+ *
+ * @example
+ * ```tsx
+ * const surface = {
+ *   surfaceId: "main",
+ *   components: [
+ *     { id: "root", component: { Text: { text: { literalString: "Hello!" } } } }
+ *   ]
+ * };
+ *
+ * <Renderer surface={surface} rootId="root" />
+ * ```
+ */
+export declare function Renderer({ surface, rootId, dataModel, }: RendererProps): React.ReactElement | null;
+export type { RendererProps as A2UIProps };

package/dist/components/A2UI/Renderer.js

@@ -0,0 +1,116 @@
+"use client";
+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 { createElement as _createElement } from "react";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { componentMap } from "./mapping.js";
+import { isA2UITextValue } from "./types/index.js";
+import { resolveTextValue, resolveTree } from "./utils/index.js";
+/**
+ * A2UI Renderer Component
+ *
+ * Renders A2UI component trees following the official message schema.
+ * Handles adjacency list resolution, data binding, and component mapping.
+ *
+ * @see https://a2ui.org/reference/messages/
+ *
+ * @example
+ * ```tsx
+ * const surface = {
+ *   surfaceId: "main",
+ *   components: [
+ *     { id: "root", component: { Text: { text: { literalString: "Hello!" } } } }
+ *   ]
+ * };
+ *
+ * <Renderer surface={surface} rootId="root" />
+ * ```
+ */
+export function Renderer({ surface, rootId, dataModel = {}, }) {
+    var _a;
+    // Normalize input to components array
+    const components = Array.isArray(surface) ? surface : surface.components;
+    if (!components || components.length === 0) {
+        return null;
+    }
+    // Determine root ID
+    const effectiveRootId = rootId !== null && rootId !== void 0 ? rootId : (_a = components[0]) === null || _a === void 0 ? void 0 : _a.id;
+    if (!effectiveRootId) {
+        console.warn("A2UI: No root ID provided and no components available");
+        return null;
+    }
+    // Resolve adjacency list to tree
+    const tree = resolveTree(components, effectiveRootId);
+    if (!tree) {
+        return null;
+    }
+    // Render the resolved tree
+    return _jsx(NodeRenderer, { dataModel: dataModel, node: tree });
+}
+/**
+ * Internal component that renders a single resolved node.
+ */
+function NodeRenderer({ node, dataModel, }) {
+    var _a, _b;
+    const { id, type, props, children } = node;
+    // Look up component (case-insensitive)
+    const Component = (_b = (_a = componentMap[type]) !== null && _a !== void 0 ? _a : componentMap[type.toLowerCase()]) !== null && _b !== void 0 ? _b : null;
+    if (!Component) {
+        console.warn(`A2UI: Unknown component type "${type}"`);
+        return null;
+    }
+    // Resolve any data-bound props (including text -> children mapping)
+    const resolvedProps = resolveProps(props, dataModel);
+    // Render tree children (from adjacency list resolution)
+    const renderedChildren = children.map((child, index) => {
+        var _a;
+        if (typeof child === "string") {
+            return child;
+        }
+        return (_jsx(NodeRenderer, { dataModel: dataModel, node: child }, (_a = child.id) !== null && _a !== void 0 ? _a : index));
+    });
+    // Determine final children:
+    // 1. If there are tree children (from adjacency list), use those
+    // 2. Otherwise, use resolved children from props (e.g., from text prop)
+    const finalChildren = renderedChildren.length > 0 ? renderedChildren : resolvedProps.children;
+    // Remove children from props since we're passing it explicitly
+    const { children: _ } = resolvedProps, propsWithoutChildren = __rest(resolvedProps, ["children"]);
+    return (_createElement(Component, Object.assign({}, propsWithoutChildren, { key: id }), finalChildren));
+}
+/**
+ * Resolves data-bound values in props.
+ *
+ * Walks through props and resolves any A2UI text values
+ * (literalString or path references) to their actual values.
+ *
+ * Also handles A2UI-to-React prop mapping:
+ * - `text` prop is mapped to `children` for React components
+ */
+function resolveProps(props, dataModel) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(props)) {
+        if (isA2UITextValue(value)) {
+            const resolvedValue = resolveTextValue(value, dataModel);
+            // Map A2UI 'text' prop to React 'children'
+            if (key === "text") {
+                resolved.children = resolvedValue;
+            }
+            else {
+                resolved[key] = resolvedValue;
+            }
+        }
+        else {
+            resolved[key] = value;
+        }
+    }
+    return resolved;
+}

package/dist/components/A2UI/catalog.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A2UI Component Catalog
+ *
+ * Machine-readable catalog of available components for AI/LLM consumption.
+ * This is the single source of truth for component metadata.
+ *
+ * @see https://a2ui.org/reference/messages/ for catalogId specification
+ */
+/**
+ * Describes a single component prop
+ */
+export interface PropDescriptor {
+    /** Prop name */
+    name: string;
+    /** TypeScript-style type description */
+    type: string;
+    /** Whether the prop is required */
+    required?: boolean;
+    /** Human-readable description */
+    description: string;
+    /** Default value if any */
+    default?: string;
+}
+/**
+ * Describes a component in the catalog
+ */
+export interface ComponentDescriptor {
+    /** Component type key (matches mapping.tsx) */
+    type: string;
+    /** Human-readable name */
+    name: string;
+    /** Category for grouping */
+    category: "primitives" | "layout" | "navigation" | "feedback" | "data-display" | "actions";
+    /** Brief description */
+    description: string;
+    /** Whether this component receives text via the `text` prop (mapped to children) */
+    usesTextProp?: boolean;
+    /** List of key props */
+    props: PropDescriptor[];
+}
+/**
+ * The full component catalog
+ */
+export declare const componentCatalog: ComponentDescriptor[];
+/**
+ * Get component types grouped by category
+ */
+export declare function getComponentsByCategory(): Record<string, ComponentDescriptor[]>;
+/**
+ * Get a flat list of all component type keys
+ */
+export declare function getComponentTypes(): string[];
+/**
+ * Look up a component by type
+ */
+export declare function getComponent(type: string): ComponentDescriptor | undefined;
+/**
+ * Generate JSON catalog for A2UI catalogId endpoint
+ */
+export declare function getCatalogJSON(): string;