ai-design-system 0.1.0 → 0.1.1

package/README.md

@@ -36,272 +36,3 @@ pnpm storybook
 ```
 
 Open [http://localhost:6006](http://localhost:6006) to view the component library.
-
-## Design System Governance
-
-### Pre-Commit Hooks
-
-The design system enforces strict quality standards through automated pre-commit hooks:
-
-**Master Validation Script**
-- Runs all design system validations in a single command
-- Run manually: `bash scripts/run-all-validations.sh` or `pnpm run prebuild`
-
-**Layer Import Architecture**
-- Validates that components follow the layered architecture pattern
-- Ensures primitives don't import from patterns or features
-- Ensures patterns don't import from features
-- Run manually: `python3 scripts/validate-layer-imports.py`
-
-**Storybook Coverage**
-- Ensures every component has a corresponding `.stories.tsx` file
-- Validates story file naming conventions
-- Run manually: `node scripts/validate-storybook-coverage.js`
-
-**Adding New Validations**
-To add a new validation to the master script, edit `scripts/run-all-validations.sh`:
-1. Add a new section with clear header and description
-2. Run your validation script and capture exit code
-3. Add the exit code to the final results check
-4. The script provides clear guidance with comments for adding new validations
-
-**Bypassing Hooks (Not Recommended)**
-```bash
-git commit --no-verify
-```
-
-Only bypass hooks if you have a valid reason and plan to fix violations immediately.
-
-## Project Structure
-
-```
-packages/ui-lib/
-├── components/
-│   ├── primitives/      # Base components (buttons, inputs, etc.)
-│   ├── patterns/        # Composite components (cards, forms, etc.)
-│   └── features/        # Feature-specific components
-├── scripts/
-│   ├── hooks/          # Git hooks (tracked in version control)
-│   │   └── pre-commit  # Pre-commit validation hook
-│   ├── setup-hooks.sh  # Hook installation script
-│   ├── run-all-validations.sh  # Master validation script
-│   ├── validate-layer-imports.py
-│   └── validate-storybook-coverage.js
-├── styles/             # Global styles and themes
-└── tokens/             # Design tokens
-```
-
-## Layer Architecture
-
-The design system follows a strict three-layer architecture:
-
-1. **Primitives** - Base components with no dependencies on other layers
-   - Examples: Button, Input, Textarea, Badge
-   - Can only import from external libraries and utilities
-
-2. **Patterns** - Composite components built from primitives
-   - Examples: Card, Form, Dialog
-   - Can import from primitives and external libraries
-
-3. **Features** - Feature-specific components
-   - Examples: AIConversation, RefinementPanel
-   - Can import from primitives, patterns, and external libraries
-
-**Import Rules:**
-- Primitives → No internal imports
-- Patterns → Can import Primitives
-- Features → Can import Primitives + Patterns
-
-## Available Scripts
-
-```bash
-pnpm dev                  # Start development server
-pnpm build                # Build for production
-pnpm start                # Start production server
-pnpm lint                 # Run ESLint
-pnpm tokens:build         # Build design tokens
-pnpm tokens:watch         # Watch design tokens
-pnpm storybook            # Start Storybook dev server
-pnpm build-storybook      # Build Storybook for production
-```
-
-## Creating New Components
-
-### 1. Choose the Correct Layer
-
-Determine which layer your component belongs to:
-- **Primitive**: Standalone, reusable UI element
-- **Pattern**: Combination of primitives
-- **Feature**: Domain-specific component
-
-### 2. Create Component File
-
-Create your component following the established structure:
-
-```tsx
-// components/primitives/YourComponent/YourComponent.tsx
-import { cva, type VariantProps } from "class-variance-authority";
-import { cn } from "@/lib/utils";
-
-const yourComponentVariants = cva(
-  "base-classes",
-  {
-    variants: {
-      variant: {
-        default: "variant-classes",
-        secondary: "variant-classes",
-      },
-      size: {
-        default: "size-classes",
-        sm: "size-classes",
-        lg: "size-classes",
-      },
-    },
-    defaultVariants: {
-      variant: "default",
-      size: "default",
-    },
-  }
-);
-
-export interface YourComponentProps
-  extends React.HTMLAttributes<HTMLElement>,
-    VariantProps<typeof yourComponentVariants> {
-  // Additional props
-}
-
-export function YourComponent({
-  className,
-  variant,
-  size,
-  ...props
-}: YourComponentProps) {
-  return (
-    <div
-      className={cn(yourComponentVariants({ variant, size, className }))}
-      {...props}
-    />
-  );
-}
-```
-
-### 3. Create Index File
-
-```tsx
-// components/primitives/YourComponent/index.ts
-export { YourComponent } from "./YourComponent";
-export type { YourComponentProps } from "./YourComponent";
-```
-
-### 4. Create Storybook Story (REQUIRED)
-
-Every component must have a `.stories.tsx` file:
-
-```tsx
-// components/primitives/YourComponent/YourComponent.stories.tsx
-import type { Meta, StoryObj } from "@storybook/react";
-import { YourComponent } from "./YourComponent";
-
-const meta = {
-  title: "Primitives/YourComponent",
-  component: YourComponent,
-  tags: ["autodocs"],
-  parameters: {
-    layout: "centered",
-  },
-} satisfies Meta<typeof YourComponent>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = {
-  args: {
-    // default props
-  },
-};
-
-export const Variant: Story = {
-  args: {
-    variant: "secondary",
-  },
-};
-```
-
-### 5. Validate
-
-Run validation scripts to ensure compliance:
-
-```bash
-# Run all validations (recommended)
-bash scripts/run-all-validations.sh
-# or
-pnpm run prebuild
-
-# Run individual validations
-python3 scripts/validate-layer-imports.py          # Layer architecture
-node scripts/validate-storybook-coverage.js        # Storybook coverage
-```
-
-## Design Tokens
-
-The design system uses Style Dictionary for design tokens management:
-
-```bash
-# Build tokens once
-pnpm tokens:build
-
-# Watch for changes
-pnpm tokens:watch
-```
-
-Tokens are defined in the `tokens/` directory and compiled to CSS custom properties.
-
-## Technology Stack
-
-- **Framework**: Next.js 16 with App Router
-- **UI**: React 19
-- **Styling**: Tailwind CSS 4
-- **Component Variants**: Class Variance Authority (CVA)
-- **Component Foundation**: Radix UI primitives
-- **Documentation**: Storybook 10
-- **Type Safety**: TypeScript 5 (strict mode)
-- **Icons**: Lucide React
-- **Animation**: Motion (Framer Motion)
-
-## Accessibility
-
-All components must meet WCAG 2.1 Level AA standards:
-- Keyboard navigation support
-- Screen reader compatibility
-- Proper ARIA attributes
-- Focus management
-- Color contrast requirements
-
-## Theming
-
-The design system supports:
-- Light and dark modes
-- Design token-based theming
-- CSS custom properties
-- Responsive design across all breakpoints
-
-## Contributing
-
-1. Set up git hooks: `./scripts/setup-hooks.sh`
-2. Create components following the layer architecture
-3. Include Storybook stories for all components
-4. Ensure all validations pass before committing
-5. Document accessibility features and keyboard shortcuts
-
-## Learn More
-
-- [Next.js Documentation](https://nextjs.org/docs)
-- [Tailwind CSS](https://tailwindcss.com)
-- [Radix UI](https://www.radix-ui.com)
-- [shadcn/ui](https://ui.shadcn.com)
-- [Storybook](https://storybook.js.org)
-- [CVA](https://cva.style)
-
-## Support
-
-For questions or issues with the design system, contact the Design System Guardian or open an issue in the repository.

package/components/ai-elements/canvas.tsx

@@ -9,13 +9,14 @@ type CanvasProps = ReactFlowProps & {
 
 export const Canvas = ({ children, ...props }: CanvasProps) => (
   <ReactFlow
+    {...props}
     deleteKeyCode={["Backspace", "Delete"]}
     fitView
     panOnDrag={false}
     panOnScroll
+    proOptions={{ hideAttribution: true }}
     selectionOnDrag={true}
     zoomOnDoubleClick={false}
-    {...props}
   >
     <Background bgColor="var(--sidebar)" />
     <Controls />

package/components/ai-elements/edge.tsx

@@ -41,11 +41,9 @@ const Temporary = ({
 
 const getHandleCoordsByPosition = (
   node: InternalNode<Node>,
-  handlePosition: Position
+  handlePosition: Position,
+  handleType: "source" | "target"
 ) => {
-  // Choose the handle type based on position - Left is for target, Right is for source
-  const handleType = handlePosition === Position.Left ? "target" : "source";
-
   const handle = node.internals.handleBounds?.[handleType]?.find(
     (h) => h.position === handlePosition
   );
@@ -57,9 +55,6 @@ const getHandleCoordsByPosition = (
   let offsetX = handle.width / 2;
   let offsetY = handle.height / 2;
 
-  // this is a tiny detail to make the markerEnd of an edge visible.
-  // The handle position that gets calculated has the origin top-left, so depending which side we are using, we add a little offset
-  // when the handlePosition is Position.Right for example, we need to add an offset as big as the handle itself in order to get the correct position
   switch (handlePosition) {
     case Position.Left:
       offsetX = 0;
@@ -87,19 +82,32 @@ const getEdgeParams = (
   source: InternalNode<Node>,
   target: InternalNode<Node>
 ) => {
-  const sourcePos = Position.Right;
-  const [sx, sy] = getHandleCoordsByPosition(source, sourcePos);
-  const targetPos = Position.Left;
-  const [tx, ty] = getHandleCoordsByPosition(target, targetPos);
-
-  return {
-    sx,
-    sy,
-    tx,
-    ty,
-    sourcePos,
-    targetPos,
-  };
+  const sx = source.internals.positionAbsolute.x + (source.measured?.width ?? 0) / 2;
+  const sy = source.internals.positionAbsolute.y + (source.measured?.height ?? 0) / 2;
+  const tx = target.internals.positionAbsolute.x + (target.measured?.width ?? 0) / 2;
+  const ty = target.internals.positionAbsolute.y + (target.measured?.height ?? 0) / 2;
+
+  const dx = tx - sx;
+  const dy = ty - sy;
+
+  // Pick source/target positions based on dominant direction
+  let sourcePos: Position;
+  let targetPos: Position;
+
+  if (Math.abs(dx) > Math.abs(dy)) {
+    // Horizontal dominant
+    sourcePos = dx > 0 ? Position.Right : Position.Left;
+    targetPos = dx > 0 ? Position.Left : Position.Right;
+  } else {
+    // Vertical dominant
+    sourcePos = dy > 0 ? Position.Bottom : Position.Top;
+    targetPos = dy > 0 ? Position.Top : Position.Bottom;
+  }
+
+  const [srcX, srcY] = getHandleCoordsByPosition(source, sourcePos, "source");
+  const [tgtX, tgtY] = getHandleCoordsByPosition(target, targetPos, "target");
+
+  return { sx: srcX, sy: srcY, tx: tgtX, ty: tgtY, sourcePos, targetPos };
 };
 
 const Animated = ({ id, source, target, markerEnd, style }: EdgeProps) => {

package/components/ai-elements/node.tsx

@@ -7,6 +7,7 @@ import {
   CardHeader,
   CardTitle,
 } from "@/components/ui/card";
+import { AnimatedBorder } from "@/components/ui/animated-border";
 import { cn } from "@/lib/utils";
 import { Handle, Position } from "@xyflow/react";
 import type { ComponentProps } from "react";
@@ -16,18 +17,36 @@ export type NodeProps = ComponentProps<typeof Card> & {
     target: boolean;
     source: boolean;
   };
+  status?: "idle" | "running" | "success" | "error";
 };
 
-export const Node = ({ handles, className, ...props }: NodeProps) => (
+export const Node = ({ handles, className, status, ...props }: NodeProps) => (
   <Card
     className={cn(
-      "node-container relative size-full h-auto w-sm gap-0 rounded-md p-0",
+      "node-container relative size-full h-auto w-sm gap-0 rounded-md bg-card p-0 transition-all duration-200",
+      status === "success" && "border-green-500 border-2",
+      status === "error" && "border-red-500 border-2",
       className
     )}
     {...props}
   >
-    {handles.target && <Handle position={Position.Left} type="target" />}
-    {handles.source && <Handle position={Position.Right} type="source" />}
+    {status === "running" && <AnimatedBorder />}
+    {handles.target && (
+      <>
+        <Handle id="target-top"    position={Position.Top}    type="target" />
+        <Handle id="target-right"  position={Position.Right}  type="target" />
+        <Handle id="target-bottom" position={Position.Bottom} type="target" />
+        <Handle id="target-left"   position={Position.Left}   type="target" />
+      </>
+    )}
+    {handles.source && (
+      <>
+        <Handle id="source-top"    position={Position.Top}    type="source" />
+        <Handle id="source-right"  position={Position.Right}  type="source" />
+        <Handle id="source-bottom" position={Position.Bottom} type="source" />
+        <Handle id="source-left"   position={Position.Left}   type="source" />
+      </>
+    )}
     {props.children}
   </Card>
 );

package/components/blocks/WorkflowCanvas/WorkflowCanvas.stories.tsx

@@ -0,0 +1,279 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import type { NodeChange, EdgeChange, Connection } from "@xyflow/react";
+import { applyNodeChanges, applyEdgeChanges } from "@xyflow/react";
+import { WorkflowCanvas, type WorkflowNode, type WorkflowEdge } from "./WorkflowCanvas";
+import "@xyflow/react/dist/style.css";
+
+/**
+ * WorkflowCanvas Stories
+ *
+ * WorkflowCanvas is a complete workflow canvas composite with ReactFlow integration.
+ * It provides a visual canvas for building workflow diagrams with state and transition nodes.
+ *
+ * ## Features
+ * - ReactFlow canvas with grid background
+ * - State nodes and Transition nodes
+ * - Bezier curve edges with animation
+ * - Pan and zoom controls
+ * - Minimap toggle
+ * - Node drag and drop
+ * - Edge creation by dragging from handles
+ * - Duplicate connection prevention
+ * - Delete nodes/edges with Backspace/Delete
+ * - Keyboard shortcuts (Cmd+/ for fit view)
+ *
+ * ## Usage Guidelines
+ *
+ * ### Do's
+ * - Provide nodes and edges data
+ * - Handle onNodesChange and onEdgesChange for state updates
+ * - Use onConnect to handle new connections
+ * - Set showMinimap for large workflows
+ *
+ * ### Don'ts
+ * - Don't use without proper height container
+ * - Don't mix node types incorrectly
+ */
+const meta = {
+  title: "Blocks/WorkflowCanvas",
+  component: WorkflowCanvas,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "Complete workflow canvas composite with ReactFlow integration for building visual workflow diagrams.",
+      },
+    },
+  },
+} satisfies Meta<typeof WorkflowCanvas>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const initialNodes: WorkflowNode[] = [
+  {
+    id: "1",
+    type: "transition",
+    position: { x: 300, y: 50 },
+    data: { label: "Start", type: "transition", status: "idle" },
+  },
+  {
+    id: "2",
+    type: "state",
+    position: { x: 300, y: 130 },
+    data: { label: "Approve Order", description: "Approve the order", type: "state", status: "idle" },
+  },
+  {
+    id: "3",
+    type: "transition",
+    position: { x: 300, y: 210 },
+    data: { label: "Order Approved", type: "transition", status: "idle" },
+  },
+  {
+    id: "4",
+    type: "state",
+    position: { x: 300, y: 290 },
+    data: { label: "Process Payment", description: "Process payment", type: "state", status: "idle" },
+  },
+];
+
+const initialEdges: WorkflowEdge[] = [
+  { id: "e1-2", source: "1", target: "2", type: "animated" },
+  { id: "e2-3", source: "2", target: "3", type: "animated" },
+  { id: "e3-4", source: "3", target: "4", type: "animated" },
+];
+
+/**
+ * Default workflow canvas with basic nodes and edges
+ */
+export const Default: Story = {
+  render: () => {
+    const [nodes, setNodes] = useState<WorkflowNode[]>(initialNodes);
+    const [edges, setEdges] = useState<WorkflowEdge[]>(initialEdges);
+
+    const onNodesChange = (changes: NodeChange[]) => {
+      setNodes((nds) => applyNodeChanges(changes, nds) as WorkflowNode[]);
+    };
+
+    const onEdgesChange = (changes: EdgeChange[]) => {
+      setEdges((eds) => applyEdgeChanges(changes, eds) as WorkflowEdge[]);
+    };
+
+    const onConnect = (connection: Connection) => {
+      setEdges((eds) => [
+        ...eds,
+        {
+          id: `e${connection.source}-${connection.target}`,
+          source: connection.source!,
+          target: connection.target!,
+          type: "animated",
+        },
+      ]);
+    };
+
+    return (
+      <div style={{ width: "100vw", height: "100vh" }}>
+        <WorkflowCanvas
+          nodes={nodes}
+          edges={edges}
+          onNodesChange={onNodesChange}
+          onEdgesChange={onEdgesChange}
+          onConnect={onConnect}
+        />
+      </div>
+    );
+  },
+};
+
+/**
+ * Workflow canvas with minimap enabled
+ */
+export const WithMinimap: Story = {
+  render: () => {
+    const [nodes, setNodes] = useState<WorkflowNode[]>(initialNodes);
+    const [edges, setEdges] = useState<WorkflowEdge[]>(initialEdges);
+
+    const onNodesChange = (changes: NodeChange[]) => {
+      setNodes((nds) => applyNodeChanges(changes, nds) as WorkflowNode[]);
+    };
+
+    const onEdgesChange = (changes: EdgeChange[]) => {
+      setEdges((eds) => applyEdgeChanges(changes, eds) as WorkflowEdge[]);
+    };
+
+    const onConnect = (connection: Connection) => {
+      setEdges((eds) => [
+        ...eds,
+        {
+          id: `e${connection.source}-${connection.target}`,
+          source: connection.source!,
+          target: connection.target!,
+          type: "animated",
+        },
+      ]);
+    };
+
+    return (
+      <div style={{ width: "100vw", height: "100vh" }}>
+        <WorkflowCanvas
+          nodes={nodes}
+          edges={edges}
+          onNodesChange={onNodesChange}
+          onEdgesChange={onEdgesChange}
+          onConnect={onConnect}
+          showMinimap={true}
+        />
+      </div>
+    );
+  },
+};
+
+/**
+ * Complex workflow with multiple branches
+ */
+export const ComplexWorkflow: Story = {
+  render: () => {
+    const complexNodes: WorkflowNode[] = [
+      { id: "start",      type: "transition", position: { x: 300, y: 0   }, data: { label: "Start",                   type: "transition", status: "idle" } },
+      { id: "req",        type: "transition", position: { x: 300, y: 100 }, data: { label: "Order Requested",         type: "transition", status: "idle" } },
+      { id: "approve",    type: "state",      position: { x: 100, y: 200 }, data: { label: "Approve Order",           type: "state",      status: "idle" } },
+      { id: "reject",     type: "state",      position: { x: 500, y: 200 }, data: { label: "Reject Order",            type: "state",      status: "idle" } },
+      { id: "cancel",     type: "state",      position: { x: 0,   y: 320 }, data: { label: "Cancel Order",            type: "state",      status: "idle" } },
+      { id: "approved",   type: "transition", position: { x: 200, y: 320 }, data: { label: "Order Approved",          type: "transition", status: "idle" } },
+      { id: "rejected",   type: "transition", position: { x: 500, y: 320 }, data: { label: "Order Rejected",          type: "transition", status: "idle" } },
+      { id: "start_proc", type: "state",      position: { x: 300, y: 420 }, data: { label: "Start Order Processing",  type: "state",      status: "idle" } },
+      { id: "cancelled",  type: "transition", position: { x: 0,   y: 440 }, data: { label: "Order Cancelled",         type: "transition", status: "idle" } },
+      { id: "complete",   type: "state",      position: { x: 150, y: 540 }, data: { label: "Complete Order Processing",type: "state",     status: "idle" } },
+      { id: "processing", type: "transition", position: { x: 400, y: 540 }, data: { label: "Order Processing",        type: "transition", status: "idle" } },
+      { id: "hold",       type: "state",      position: { x: 600, y: 540 }, data: { label: "Place Order On Hold",     type: "state",      status: "idle" } },
+      { id: "resume",     type: "state",      position: { x: 750, y: 420 }, data: { label: "Resume Order Processing", type: "state",      status: "idle" } },
+      { id: "ready",      type: "transition", position: { x: 150, y: 660 }, data: { label: "Order Ready for Delivery",type: "transition", status: "idle" } },
+      { id: "on_hold",    type: "transition", position: { x: 600, y: 660 }, data: { label: "Order On Hold",           type: "transition", status: "idle" } },
+    ];
+
+    const complexEdges: WorkflowEdge[] = [
+      { id: "e1",  source: "start",     target: "req",        type: "animated" },
+      { id: "e2",  source: "req",       target: "approve",    type: "animated" },
+      { id: "e3",  source: "req",       target: "reject",     type: "animated" },
+      { id: "e4",  source: "approve",   target: "cancel",     type: "animated" },
+      { id: "e5",  source: "approve",   target: "approved",   type: "animated" },
+      { id: "e6",  source: "reject",    target: "rejected",   type: "animated" },
+      { id: "e7",  source: "approved",  target: "start_proc", type: "animated" },
+      { id: "e8",  source: "cancel",    target: "cancelled",  type: "animated" },
+      { id: "e9",  source: "start_proc",target: "complete",   type: "animated" },
+      { id: "e10", source: "start_proc",target: "processing", type: "animated" },
+      { id: "e11", source: "processing",target: "hold",       type: "animated" },
+      { id: "e12", source: "hold",      target: "resume",     type: "animated" },
+      { id: "e13", source: "complete",  target: "ready",      type: "animated" },
+      { id: "e14", source: "hold",      target: "on_hold",    type: "animated" },
+    ];
+
+    const [nodes, setNodes] = useState<WorkflowNode[]>(complexNodes);
+    const [edges, setEdges] = useState<WorkflowEdge[]>(complexEdges);
+
+    const onNodesChange = (changes: NodeChange[]) => {
+      setNodes((nds) => applyNodeChanges(changes, nds) as WorkflowNode[]);
+    };
+
+    const onEdgesChange = (changes: EdgeChange[]) => {
+      setEdges((eds) => applyEdgeChanges(changes, eds) as WorkflowEdge[]);
+    };
+
+    const onConnect = (connection: Connection) => {
+      setEdges((eds) => [
+        ...eds,
+        {
+          id: `e${connection.source}-${connection.target}`,
+          source: connection.source!,
+          target: connection.target!,
+          type: "animated",
+        },
+      ]);
+    };
+
+    return (
+      <div style={{ width: "100vw", height: "100vh" }}>
+        <WorkflowCanvas
+          nodes={nodes}
+          edges={edges}
+          onNodesChange={onNodesChange}
+          onEdgesChange={onEdgesChange}
+          onConnect={onConnect}
+          showMinimap={true}
+        />
+      </div>
+    );
+  },
+};
+
+/**
+ * Empty workflow canvas
+ */
+export const Empty: Story = {
+  render: () => {
+    const [nodes, setNodes] = useState<WorkflowNode[]>([]);
+    const [edges, setEdges] = useState<WorkflowEdge[]>([]);
+
+    const onNodesChange = (changes: NodeChange[]) => {
+      setNodes((nds) => applyNodeChanges(changes, nds) as WorkflowNode[]);
+    };
+
+    const onEdgesChange = (changes: EdgeChange[]) => {
+      setEdges((eds) => applyEdgeChanges(changes, eds) as WorkflowEdge[]);
+    };
+
+    return (
+      <div style={{ width: "100vw", height: "100vh" }}>
+        <WorkflowCanvas
+          nodes={nodes}
+          edges={edges}
+          onNodesChange={onNodesChange}
+          onEdgesChange={onEdgesChange}
+        />
+      </div>
+    );
+  },
+};