ai-design-system 0.1.0

package/components/primitives/Dialog/Dialog.tsx

@@ -0,0 +1,140 @@
+import * as React from "react"
+import {
+  Dialog as ShadcnDialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+} from "../../ui/dialog"
+
+/**
+ * Dialog Primitive
+ *
+ * A foundational modal dialog component that wraps shadcn/ui Dialog with extensibility for
+ * design system-specific enhancements. This primitive provides accessible modal interactions
+ * with full keyboard navigation and focus management.
+ *
+ * Built on Radix UI Dialog primitive with WCAG 2.1 Level AA compliance:
+ * - Proper focus trapping and restoration
+ * - Keyboard navigation (Escape to close)
+ * - Screen reader announcements
+ * - Portal rendering for proper layering
+ *
+ * @example
+ * ```tsx
+ * <Dialog>
+ *   <DialogTrigger asChild>
+ *     <Button>Open Dialog</Button>
+ *   </DialogTrigger>
+ *   <DialogContent>
+ *     <DialogHeader>
+ *       <DialogTitle>Dialog Title</DialogTitle>
+ *       <DialogDescription>Dialog description text</DialogDescription>
+ *     </DialogHeader>
+ *     <div>Dialog body content</div>
+ *     <DialogFooter>
+ *       <Button>Action</Button>
+ *     </DialogFooter>
+ *   </DialogContent>
+ * </Dialog>
+ * ```
+ *
+ * @see https://ui.shadcn.com/docs/components/dialog - shadcn/ui Dialog documentation
+ * @see https://www.radix-ui.com/primitives/docs/components/dialog - Radix UI Dialog primitive
+ */
+
+/**
+ * Dialog Root component props
+ * Controls the open state and modal behavior
+ */
+export type DialogProps = React.ComponentProps<typeof ShadcnDialog>
+
+/**
+ * DialogContent component props
+ * Main content container with optional close button
+ */
+export type DialogContentProps = React.ComponentProps<typeof DialogContent>
+
+/**
+ * DialogTrigger component props
+ * Element that opens the dialog
+ */
+export type DialogTriggerProps = React.ComponentProps<typeof DialogTrigger>
+
+/**
+ * DialogHeader component props
+ * Header section for title and description
+ */
+export type DialogHeaderProps = React.ComponentProps<typeof DialogHeader>
+
+/**
+ * DialogFooter component props
+ * Footer section for action buttons
+ */
+export type DialogFooterProps = React.ComponentProps<typeof DialogFooter>
+
+/**
+ * DialogTitle component props
+ * Accessible title for the dialog
+ */
+export type DialogTitleProps = React.ComponentProps<typeof DialogTitle>
+
+/**
+ * DialogDescription component props
+ * Accessible description for the dialog
+ */
+export type DialogDescriptionProps = React.ComponentProps<typeof DialogDescription>
+
+/**
+ * Dialog component
+ *
+ * A modal dialog component built on Radix UI Dialog primitive.
+ * Provides accessible modal interactions with full keyboard navigation.
+ *
+ * Features:
+ * - Focus trapping and restoration
+ * - Keyboard navigation (Escape to close)
+ * - Screen reader announcements
+ * - Portal rendering for proper layering
+ * - Overlay dismiss support
+ * - Dark mode support
+ */
+export const Dialog = React.forwardRef<
+  React.ElementRef<typeof ShadcnDialog>,
+  DialogProps
+>((props, ref) => {
+  return <ShadcnDialog {...props} />
+})
+
+Dialog.displayName = "Dialog"
+
+/**
+ * Re-export all Dialog sub-components for composition
+ *
+ * These components should be used together to build complete dialog experiences:
+ * - DialogTrigger: Opens the dialog
+ * - DialogContent: Main content container
+ * - DialogHeader: Header section with title and description
+ * - DialogFooter: Footer section with actions
+ * - DialogTitle: Accessible title (required for a11y)
+ * - DialogDescription: Accessible description (recommended for a11y)
+ * - DialogClose: Explicitly close the dialog (optional, auto close button in DialogContent)
+ * - DialogPortal: Advanced portal customization (rarely needed)
+ * - DialogOverlay: Advanced overlay customization (rarely needed)
+ */
+export {
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+}

package/components/primitives/Dialog/index.ts

@@ -0,0 +1,22 @@
+export {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+} from "./Dialog"
+
+export type {
+  DialogProps,
+  DialogContentProps,
+  DialogTriggerProps,
+  DialogHeaderProps,
+  DialogFooterProps,
+  DialogTitleProps,
+  DialogDescriptionProps,
+} from "./Dialog"

package/components/primitives/Drawer/Drawer.stories.tsx

@@ -0,0 +1,327 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import {
+  Drawer,
+  DrawerTrigger,
+  DrawerContent,
+  DrawerHeader,
+  DrawerFooter,
+  DrawerTitle,
+  DrawerDescription,
+  DrawerClose,
+} from './Drawer'
+import { Button } from '../Button'
+
+/**
+ * Drawer Primitive Stories
+ *
+ * The Drawer component is a foundational primitive for displaying content in a slide-out panel.
+ * It extends shadcn/ui's Drawer with design system-specific enhancements and maintains
+ * full accessibility compliance (WCAG 2.1 Level AA).
+ *
+ * ## Features
+ * - Slide-out panel from bottom (mobile-first)
+ * - Backdrop overlay
+ * - Keyboard navigation support
+ * - Focus management
+ * - Dark mode support
+ *
+ * ## Accessibility
+ * - Proper ARIA attributes for dialog
+ * - Focus trap within drawer
+ * - Keyboard navigation (Escape to close)
+ * - Screen reader announcements
+ * - Focus restoration on close
+ *
+ * ## Usage Guidelines
+ *
+ * ### Do's
+ * - Use for mobile-first slide-up panels
+ * - Include DrawerTitle for accessibility
+ * - Provide clear close actions
+ * - Use for contextual actions and details
+ *
+ * ### Don'ts
+ * - Don't use for critical information
+ * - Don't nest drawers
+ * - Don't use for complex forms (use Dialog instead)
+ * - Don't omit title and description
+ */
+const meta = {
+  title: 'Primitives/Drawer',
+  component: Drawer,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'A drawer component for displaying content in a slide-out panel, built on shadcn/ui foundation.',
+      },
+    },
+  },
+} satisfies Meta<typeof Drawer>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Default drawer
+ *
+ * Basic drawer with trigger, content, header, and footer.
+ */
+export const Default: Story = {
+  render: () => (
+    <Drawer>
+      <DrawerTrigger asChild>
+        <Button variant="outline">Open Drawer</Button>
+      </DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Drawer Title</DrawerTitle>
+          <DrawerDescription>This is a drawer description that provides context.</DrawerDescription>
+        </DrawerHeader>
+        <div style={{ padding: '16px' }}>
+          <p>Drawer content goes here. This is a mobile-first slide-up panel.</p>
+        </div>
+        <DrawerFooter>
+          <Button>Submit</Button>
+          <DrawerClose asChild>
+            <Button variant="outline">Cancel</Button>
+          </DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>
+  ),
+}
+
+/**
+ * With Form
+ *
+ * Drawer containing a simple form.
+ */
+export const WithForm: Story = {
+  render: () => (
+    <Drawer>
+      <DrawerTrigger asChild>
+        <Button>Edit Profile</Button>
+      </DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Edit Profile</DrawerTitle>
+          <DrawerDescription>Make changes to your profile here.</DrawerDescription>
+        </DrawerHeader>
+        <div style={{ padding: '16px', display: 'flex', flexDirection: 'column', gap: '16px' }}>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+            <label htmlFor="name" style={{ fontSize: '14px', fontWeight: 500 }}>
+              Name
+            </label>
+            <input
+              id="name"
+              defaultValue="John Doe"
+              style={{
+                padding: '8px 12px',
+                border: '1px solid hsl(var(--border))',
+                borderRadius: '6px',
+                fontSize: '14px',
+              }}
+            />
+          </div>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+            <label htmlFor="email" style={{ fontSize: '14px', fontWeight: 500 }}>
+              Email
+            </label>
+            <input
+              id="email"
+              type="email"
+              defaultValue="john@example.com"
+              style={{
+                padding: '8px 12px',
+                border: '1px solid hsl(var(--border))',
+                borderRadius: '6px',
+                fontSize: '14px',
+              }}
+            />
+          </div>
+        </div>
+        <DrawerFooter>
+          <Button>Save Changes</Button>
+          <DrawerClose asChild>
+            <Button variant="outline">Cancel</Button>
+          </DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Drawers can contain forms for quick edits and data entry.',
+      },
+    },
+  },
+}
+
+/**
+ * With List
+ *
+ * Drawer containing a list of items.
+ */
+export const WithList: Story = {
+  render: () => (
+    <Drawer>
+      <DrawerTrigger asChild>
+        <Button variant="outline">View Options</Button>
+      </DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Select an Option</DrawerTitle>
+          <DrawerDescription>Choose from the available options below.</DrawerDescription>
+        </DrawerHeader>
+        <div style={{ padding: '16px' }}>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+            {['Option 1', 'Option 2', 'Option 3', 'Option 4'].map((option) => (
+              <button
+                key={option}
+                style={{
+                  padding: '12px',
+                  textAlign: 'left',
+                  border: '1px solid hsl(var(--border))',
+                  borderRadius: '6px',
+                  background: 'transparent',
+                  cursor: 'pointer',
+                  fontSize: '14px',
+                }}
+              >
+                {option}
+              </button>
+            ))}
+          </div>
+        </div>
+        <DrawerFooter>
+          <DrawerClose asChild>
+            <Button variant="outline">Close</Button>
+          </DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Drawers work well for displaying lists of options or actions.',
+      },
+    },
+  },
+}
+
+/**
+ * With Scrollable Content
+ *
+ * Drawer with content that scrolls.
+ */
+export const WithScrollableContent: Story = {
+  render: () => (
+    <Drawer>
+      <DrawerTrigger asChild>
+        <Button>View Details</Button>
+      </DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Long Content</DrawerTitle>
+          <DrawerDescription>This drawer contains scrollable content.</DrawerDescription>
+        </DrawerHeader>
+        <div style={{ padding: '16px', maxHeight: '300px', overflowY: 'auto' }}>
+          {Array.from({ length: 20 }, (_, i) => (
+            <p key={i} style={{ marginBottom: '12px', fontSize: '14px' }}>
+              This is paragraph {i + 1}. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+            </p>
+          ))}
+        </div>
+        <DrawerFooter>
+          <DrawerClose asChild>
+            <Button>Close</Button>
+          </DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Drawers can handle scrollable content for longer information.',
+      },
+    },
+  },
+}
+
+/**
+ * Without Footer
+ *
+ * Drawer without a footer section.
+ */
+export const WithoutFooter: Story = {
+  render: () => (
+    <Drawer>
+      <DrawerTrigger asChild>
+        <Button variant="outline">Open</Button>
+      </DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Information</DrawerTitle>
+          <DrawerDescription>This drawer has no footer actions.</DrawerDescription>
+        </DrawerHeader>
+        <div style={{ padding: '16px' }}>
+          <p>Content without footer actions. Users can swipe down or tap outside to close.</p>
+        </div>
+      </DrawerContent>
+    </Drawer>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Drawers can omit the footer if no actions are needed.',
+      },
+    },
+  },
+}
+
+/**
+ * Dark Mode Preview
+ *
+ * Drawer in dark mode to verify theming compatibility.
+ */
+export const DarkMode: Story = {
+  render: () => (
+    <div className="dark" style={{ padding: '24px', background: 'hsl(222.2 84% 4.9%)', borderRadius: '8px' }}>
+      <Drawer>
+        <DrawerTrigger asChild>
+          <Button>Open Drawer</Button>
+        </DrawerTrigger>
+        <DrawerContent>
+          <DrawerHeader>
+            <DrawerTitle>Dark Mode Drawer</DrawerTitle>
+            <DrawerDescription>This drawer adapts to dark mode automatically.</DrawerDescription>
+          </DrawerHeader>
+          <div style={{ padding: '16px' }}>
+            <p style={{ color: 'hsl(var(--foreground))' }}>
+              Drawer content in dark mode with proper contrast and visibility.
+            </p>
+          </div>
+          <DrawerFooter>
+            <Button>Action</Button>
+            <DrawerClose asChild>
+              <Button variant="outline">Cancel</Button>
+            </DrawerClose>
+          </DrawerFooter>
+        </DrawerContent>
+      </Drawer>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Drawers automatically adapt to dark mode with appropriate contrast.',
+      },
+    },
+    backgrounds: { disable: true },
+  },
+}

package/components/primitives/Drawer/Drawer.tsx

@@ -0,0 +1,208 @@
+import * as React from "react"
+import {
+  Drawer as ShadcnDrawer,
+  DrawerPortal as ShadcnDrawerPortal,
+  DrawerOverlay as ShadcnDrawerOverlay,
+  DrawerTrigger as ShadcnDrawerTrigger,
+  DrawerClose as ShadcnDrawerClose,
+  DrawerContent as ShadcnDrawerContent,
+  DrawerHeader as ShadcnDrawerHeader,
+  DrawerFooter as ShadcnDrawerFooter,
+  DrawerTitle as ShadcnDrawerTitle,
+  DrawerDescription as ShadcnDrawerDescription,
+} from "../../ui/drawer"
+
+/**
+ * Drawer Primitive
+ *
+ * A foundational drawer component that wraps shadcn/ui Drawer with design system
+ * enhancements. This primitive serves as the single source of truth for all drawer
+ * interactions across the application.
+ *
+ * @example
+ * ```tsx
+ * <Drawer>
+ *   <DrawerTrigger>Open Drawer</DrawerTrigger>
+ *   <DrawerContent>
+ *     <DrawerHeader>
+ *       <DrawerTitle>Drawer Title</DrawerTitle>
+ *       <DrawerDescription>Drawer description</DrawerDescription>
+ *     </DrawerHeader>
+ *     <div>Drawer content</div>
+ *     <DrawerFooter>
+ *       <DrawerClose>Close</DrawerClose>
+ *     </DrawerFooter>
+ *   </DrawerContent>
+ * </Drawer>
+ * ```
+ *
+ * @see https://ui.shadcn.com/docs/components/drawer - shadcn/ui Drawer documentation
+ */
+
+/**
+ * Drawer component props
+ */
+export type DrawerProps = React.ComponentProps<typeof ShadcnDrawer>
+
+/**
+ * Drawer component
+ *
+ * A drawer component for displaying content in a slide-out panel, built on shadcn/ui foundation.
+ *
+ * Features:
+ * - Slide-out panel from bottom (mobile-first)
+ * - Backdrop overlay
+ * - Keyboard navigation support
+ * - Focus management
+ * - Dark mode support
+ */
+export const Drawer = ShadcnDrawer
+
+Drawer.displayName = "Drawer"
+
+/**
+ * DrawerPortal component
+ *
+ * Portal component for rendering drawer content in a portal.
+ */
+export const DrawerPortal = ShadcnDrawerPortal
+
+DrawerPortal.displayName = "DrawerPortal"
+
+/**
+ * DrawerOverlay component props
+ */
+export type DrawerOverlayProps = React.ComponentPropsWithoutRef<typeof ShadcnDrawerOverlay>
+
+/**
+ * DrawerOverlay component
+ *
+ * Backdrop overlay for the drawer.
+ */
+export const DrawerOverlay = React.memo(
+  React.forwardRef<
+    React.ElementRef<typeof ShadcnDrawerOverlay>,
+    DrawerOverlayProps
+  >((props, ref) => {
+    return <ShadcnDrawerOverlay ref={ref} {...props} />
+  })
+)
+
+DrawerOverlay.displayName = "DrawerOverlay"
+
+/**
+ * DrawerTrigger component
+ *
+ * Button that triggers the drawer to open.
+ */
+export const DrawerTrigger = ShadcnDrawerTrigger
+
+DrawerTrigger.displayName = "DrawerTrigger"
+
+/**
+ * DrawerClose component
+ *
+ * Button that closes the drawer.
+ */
+export const DrawerClose = ShadcnDrawerClose
+
+DrawerClose.displayName = "DrawerClose"
+
+/**
+ * DrawerContent component props
+ */
+export type DrawerContentProps = React.ComponentPropsWithoutRef<typeof ShadcnDrawerContent>
+
+/**
+ * DrawerContent component
+ *
+ * Container for drawer content with proper styling and animations.
+ */
+export const DrawerContent = React.memo(
+  React.forwardRef<
+    React.ElementRef<typeof ShadcnDrawerContent>,
+    DrawerContentProps
+  >((props, ref) => {
+    return <ShadcnDrawerContent ref={ref} {...props} />
+  })
+)
+
+DrawerContent.displayName = "DrawerContent"
+
+/**
+ * DrawerHeader component props
+ */
+export type DrawerHeaderProps = React.HTMLAttributes<HTMLDivElement>
+
+/**
+ * DrawerHeader component
+ *
+ * Header section of the drawer for title and description.
+ */
+export const DrawerHeader = React.memo(
+  React.forwardRef<HTMLDivElement, DrawerHeaderProps>((props, ref) => {
+    return <ShadcnDrawerHeader ref={ref} {...props} />
+  })
+)
+
+DrawerHeader.displayName = "DrawerHeader"
+
+/**
+ * DrawerFooter component props
+ */
+export type DrawerFooterProps = React.HTMLAttributes<HTMLDivElement>
+
+/**
+ * DrawerFooter component
+ *
+ * Footer section of the drawer for actions.
+ */
+export const DrawerFooter = React.memo(
+  React.forwardRef<HTMLDivElement, DrawerFooterProps>((props, ref) => {
+    return <ShadcnDrawerFooter ref={ref} {...props} />
+  })
+)
+
+DrawerFooter.displayName = "DrawerFooter"
+
+/**
+ * DrawerTitle component props
+ */
+export type DrawerTitleProps = React.ComponentPropsWithoutRef<typeof ShadcnDrawerTitle>
+
+/**
+ * DrawerTitle component
+ *
+ * Title of the drawer for accessibility.
+ */
+export const DrawerTitle = React.memo(
+  React.forwardRef<
+    React.ElementRef<typeof ShadcnDrawerTitle>,
+    DrawerTitleProps
+  >((props, ref) => {
+    return <ShadcnDrawerTitle ref={ref} {...props} />
+  })
+)
+
+DrawerTitle.displayName = "DrawerTitle"
+
+/**
+ * DrawerDescription component props
+ */
+export type DrawerDescriptionProps = React.ComponentPropsWithoutRef<typeof ShadcnDrawerDescription>
+
+/**
+ * DrawerDescription component
+ *
+ * Description of the drawer for accessibility.
+ */
+export const DrawerDescription = React.memo(
+  React.forwardRef<
+    React.ElementRef<typeof ShadcnDrawerDescription>,
+    DrawerDescriptionProps
+  >((props, ref) => {
+    return <ShadcnDrawerDescription ref={ref} {...props} />
+  })
+)
+
+DrawerDescription.displayName = "DrawerDescription"