@usefragments/ui 1.0.0

package/src/components/Dialog/index.tsx

@@ -0,0 +1,264 @@
+'use client';
+
+import * as React from 'react';
+import { Dialog as BaseDialog } from '@base-ui/react/dialog';
+import styles from './Dialog.module.scss';
+
+// ============================================
+// Types
+// ============================================
+
+/**
+ * Modal dialog overlay for confirmations, forms, and focused tasks.
+ * @see https://usefragments.com/components/dialog
+ */
+export interface DialogProps {
+  children: React.ReactNode;
+  /** Controlled open state */
+  open?: boolean;
+  /** Default open state */
+  defaultOpen?: boolean;
+  /** Called when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Whether the dialog blocks interaction with the rest of the page.
+   * @default true */
+  modal?: boolean;
+}
+
+export interface DialogContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Dialog width.
+   * @default "md"
+   * @see https://usefragments.com/components/dialog#sizes */
+  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
+  /** Whether the dialog should autofocus content on open.
+   * @default true */
+  initialFocus?: boolean;
+}
+
+export interface DialogTitleProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+  children: React.ReactNode;
+}
+
+export interface DialogDescriptionProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+  children: React.ReactNode;
+}
+
+export interface DialogHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+export interface DialogBodyProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+export interface DialogFooterProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+type DialogTriggerAsButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
+  children: React.ReactNode;
+  asChild?: false;
+};
+
+type DialogTriggerAsChildProps = Omit<React.HTMLAttributes<HTMLElement>, 'children'> & {
+  children: React.ReactElement;
+  asChild: true;
+};
+
+export type DialogTriggerProps = DialogTriggerAsButtonProps | DialogTriggerAsChildProps;
+
+type DialogCloseAsButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
+  children?: React.ReactNode;
+  asChild?: false;
+};
+
+type DialogCloseAsChildProps = Omit<React.HTMLAttributes<HTMLElement>, 'children'> & {
+  children: React.ReactElement;
+  asChild: true;
+};
+
+export type DialogCloseProps = DialogCloseAsButtonProps | DialogCloseAsChildProps;
+
+// ============================================
+// Close Icon
+// ============================================
+
+function CloseIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <line x1="18" y1="6" x2="6" y2="18" />
+      <line x1="6" y1="6" x2="18" y2="18" />
+    </svg>
+  );
+}
+
+// ============================================
+// Components
+// ============================================
+
+function DialogRoot({
+  children,
+  open,
+  defaultOpen,
+  onOpenChange,
+  modal = true,
+}: DialogProps) {
+  return (
+    <BaseDialog.Root
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange}
+      modal={modal}
+    >
+      {children}
+    </BaseDialog.Root>
+  );
+}
+
+function DialogTrigger({
+  children,
+  asChild,
+  className,
+  ...htmlProps
+}: DialogTriggerProps) {
+  if (asChild) {
+    return (
+      <BaseDialog.Trigger {...htmlProps} className={className} render={children as React.ReactElement}>
+        {null}
+      </BaseDialog.Trigger>
+    );
+  }
+
+  return (
+    <BaseDialog.Trigger {...htmlProps} className={className}>
+      {children}
+    </BaseDialog.Trigger>
+  );
+}
+
+function DialogContent({
+  children,
+  size = 'md',
+  initialFocus = true,
+  className,
+  ...htmlProps
+}: DialogContentProps) {
+  const popupClasses = [styles.popup, styles[size], className]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <BaseDialog.Portal>
+      <BaseDialog.Backdrop className={styles.backdrop} />
+      <BaseDialog.Viewport className={styles.positioner}>
+        <BaseDialog.Popup initialFocus={initialFocus} {...htmlProps} className={popupClasses}>
+          {children}
+        </BaseDialog.Popup>
+      </BaseDialog.Viewport>
+    </BaseDialog.Portal>
+  );
+}
+
+function DialogHeader({ children, className, ...htmlProps }: DialogHeaderProps) {
+  const classes = [styles.header, className].filter(Boolean).join(' ');
+  return <div {...htmlProps} className={classes}>{children}</div>;
+}
+
+function DialogTitle({ children, className, ...htmlProps }: DialogTitleProps) {
+  const classes = [styles.title, className].filter(Boolean).join(' ');
+  return <BaseDialog.Title {...htmlProps} className={classes}>{children}</BaseDialog.Title>;
+}
+
+function DialogDescription({ children, className, ...htmlProps }: DialogDescriptionProps) {
+  const classes = [styles.description, className].filter(Boolean).join(' ');
+  return (
+    <BaseDialog.Description {...htmlProps} className={classes}>
+      {children}
+    </BaseDialog.Description>
+  );
+}
+
+function DialogBody({ children, className, ...htmlProps }: DialogBodyProps) {
+  const classes = [styles.body, className].filter(Boolean).join(' ');
+  return <div {...htmlProps} className={classes}>{children}</div>;
+}
+
+function DialogFooter({ children, className, ...htmlProps }: DialogFooterProps) {
+  const classes = [styles.footer, className].filter(Boolean).join(' ');
+  return <div {...htmlProps} className={classes}>{children}</div>;
+}
+
+function DialogClose({ children, asChild, className, ...htmlProps }: DialogCloseProps) {
+  // If no children, render the default X close button
+  if (!children) {
+    return (
+      <BaseDialog.Close
+        {...htmlProps}
+        data-dialog-close
+        aria-label="Close dialog"
+        className={[styles.close, className].filter(Boolean).join(' ')}
+      >
+        <CloseIcon />
+      </BaseDialog.Close>
+    );
+  }
+
+  if (asChild) {
+    return (
+      <BaseDialog.Close
+        {...htmlProps}
+        data-dialog-close
+        className={className}
+        render={children as React.ReactElement}
+      >
+        {null}
+      </BaseDialog.Close>
+    );
+  }
+
+  return (
+    <BaseDialog.Close {...htmlProps} data-dialog-close className={className}>
+      {children}
+    </BaseDialog.Close>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Dialog = Object.assign(DialogRoot, {
+  Trigger: DialogTrigger,
+  Content: DialogContent,
+  Header: DialogHeader,
+  Title: DialogTitle,
+  Description: DialogDescription,
+  Body: DialogBody,
+  Footer: DialogFooter,
+  Close: DialogClose,
+});
+
+// Re-export individual components for tree-shaking
+export {
+  DialogRoot,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogBody,
+  DialogFooter,
+  DialogClose,
+};

package/src/components/Drawer/Drawer.contract.json

@@ -0,0 +1,161 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Drawer",
+  "description": "A panel that slides in from screen edges. Extends the Dialog pattern with slide animations and edge positioning.",
+  "category": "feedback",
+  "tags": [
+    "drawer",
+    "sheet",
+    "panel",
+    "sidebar",
+    "slide-over"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Drawer/index.tsx",
+  "exportName": "Drawer",
+  "propsSummary": [
+    "children: node (required)",
+    "open: boolean",
+    "defaultOpen: boolean",
+    "onOpenChange: function",
+    "modal: boolean (default: true)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Drawer content (use Drawer.Content, Drawer.Header, etc.)",
+      "required": true
+    },
+    "open": {
+      "type": "boolean",
+      "description": "Controlled open state",
+      "required": false
+    },
+    "defaultOpen": {
+      "type": "boolean",
+      "description": "Default open state (uncontrolled)",
+      "default": "false",
+      "required": false
+    },
+    "onOpenChange": {
+      "type": "function",
+      "description": "Called when open state changes",
+      "required": false
+    },
+    "modal": {
+      "type": "boolean",
+      "description": "Whether to render as modal (blocks interaction with rest of page)",
+      "default": "true",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Side panels for editing or creating content",
+      "Mobile-style bottom sheets for actions",
+      "Navigation panels that slide in from the left",
+      "Detail views that overlay the main content"
+    ],
+    "whenNot": [
+      "Centered modal dialogs (use Dialog)",
+      "Non-blocking notifications (use Toast)",
+      "Permanent side navigation (use Sidebar)",
+      "Small contextual menus (use Menu or Popover)"
+    ],
+    "guidelines": [
+      "Default to right side for content editing and forms",
+      "Use left side for navigation drawers",
+      "Use bottom for mobile-style action sheets",
+      "Provide clear close affordance (X button or cancel)",
+      "Keep drawer content focused on a single task",
+      "Drawer.Trigger and Drawer.Close with asChild require a single valid React element child",
+      "Set Drawer.Content initialFocus={false} when custom focus management is needed"
+    ],
+    "accessibility": [
+      "Automatically traps focus within the drawer",
+      "Closes on Escape key press",
+      "Returns focus to trigger element on close",
+      "Uses role=\"dialog\" with proper aria attributes"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Right-side drawer with header, body, and footer",
+      "code": "<Drawer>\n  <Drawer.Trigger asChild>\n    <Button>Open Drawer</Button>\n  </Drawer.Trigger>\n  <Drawer.Content>\n    <Drawer.Close />\n    <Drawer.Header>\n      <Drawer.Title>Drawer Title</Drawer.Title>\n      <Drawer.Description>\n        A panel sliding in from the right.\n      </Drawer.Description>\n    </Drawer.Header>\n    <Drawer.Body>\n      <p>Drawer content goes here.</p>\n    </Drawer.Body>\n    <Drawer.Footer>\n      <Drawer.Close asChild>\n        <Button variant=\"secondary\">Cancel</Button>\n      </Drawer.Close>\n      <Button variant=\"primary\">Save</Button>\n    </Drawer.Footer>\n  </Drawer.Content>\n</Drawer>"
+    },
+    {
+      "name": "Left Side",
+      "description": "Left-side drawer for navigation",
+      "code": "<Drawer>\n  <Drawer.Trigger asChild>\n    <Button variant=\"secondary\">Open Left</Button>\n  </Drawer.Trigger>\n  <Drawer.Content side=\"left\">\n    <Drawer.Close />\n    <Drawer.Header>\n      <Drawer.Title>Navigation</Drawer.Title>\n    </Drawer.Header>\n    <Drawer.Body>\n      <p>Left-side drawer for navigation or filters.</p>\n    </Drawer.Body>\n  </Drawer.Content>\n</Drawer>"
+    },
+    {
+      "name": "Bottom Sheet",
+      "description": "Bottom drawer for mobile-style actions",
+      "code": "<Drawer>\n  <Drawer.Trigger asChild>\n    <Button variant=\"secondary\">Open Bottom Sheet</Button>\n  </Drawer.Trigger>\n  <Drawer.Content side=\"bottom\" size=\"sm\">\n    <Drawer.Header>\n      <Drawer.Title>Actions</Drawer.Title>\n    </Drawer.Header>\n    <Drawer.Body>\n      <p>Bottom sheet for mobile-style actions.</p>\n    </Drawer.Body>\n  </Drawer.Content>\n</Drawer>"
+    },
+    {
+      "name": "With Form",
+      "description": "Drawer with a form layout",
+      "code": "<Drawer>\n  <Drawer.Trigger asChild>\n    <Button>Edit Settings</Button>\n  </Drawer.Trigger>\n  <Drawer.Content size=\"md\">\n    <Drawer.Close />\n    <Drawer.Header>\n      <Drawer.Title>Settings</Drawer.Title>\n      <Drawer.Description>Update your preferences.</Drawer.Description>\n    </Drawer.Header>\n    <Drawer.Body>\n      <Stack gap=\"md\">\n        <Input label=\"Display Name\" placeholder=\"Enter name\" />\n        <Input label=\"Email\" type=\"email\" placeholder=\"you@example.com\" />\n      </Stack>\n    </Drawer.Body>\n    <Drawer.Footer>\n      <Drawer.Close asChild>\n        <Button variant=\"secondary\">Cancel</Button>\n      </Drawer.Close>\n      <Button variant=\"primary\">Save Changes</Button>\n    </Drawer.Footer>\n  </Drawer.Content>\n</Drawer>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Dialog",
+      "relationship": "sibling",
+      "note": "Use Dialog for centered modal overlays"
+    },
+    {
+      "component": "Sidebar",
+      "relationship": "alternative",
+      "note": "Use Sidebar for permanent side navigation"
+    },
+    {
+      "component": "Popover",
+      "relationship": "alternative",
+      "note": "Use Popover for small contextual content"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "open: boolean - controlled open state",
+      "onOpenChange: (open) => void - open state handler",
+      "modal: boolean - blocks page interaction (default: true)",
+      "Drawer.Content side: left|right|top|bottom - slide direction (default: right)",
+      "Drawer.Content size: sm|md|lg|xl|full - panel size",
+      "Drawer.Content initialFocus: boolean - auto-focus popup on open (default: true)"
+    ],
+    "a11yRules": [
+      "A11Y_DIALOG_FOCUS",
+      "A11Y_DIALOG_ESCAPE",
+      "A11Y_DIALOG_LABEL"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Trigger",
+      "Content",
+      "Close",
+      "SwipeArea",
+      "Header",
+      "Title",
+      "Description",
+      "Body",
+      "Footer"
+    ],
+    "requiredChildren": [
+      "Content"
+    ],
+    "commonPatterns": [
+      "<Drawer><Drawer.Trigger><Button>Open</Button></Drawer.Trigger><Drawer.Content><Drawer.Close /><Drawer.Header><Drawer.Title>{title}</Drawer.Title></Drawer.Header><Drawer.Body>{content}</Drawer.Body><Drawer.Footer><Drawer.Close asChild><Button variant=\"secondary\">Cancel</Button></Drawer.Close><Button>Save</Button></Drawer.Footer></Drawer.Content></Drawer>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:55.637Z"
+  }
+}

package/src/components/Drawer/Drawer.module.scss

@@ -0,0 +1,255 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// Backdrop overlay
+.backdrop {
+  position: fixed;
+  inset: 0;
+  background-color: var(--fui-backdrop, $fui-backdrop);
+  z-index: 50;
+
+  // Animation
+  opacity: 0;
+  transition: opacity var(--fui-transition-normal, $fui-transition-normal);
+
+  &[data-open] {
+    opacity: 1;
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+  }
+}
+
+// Viewport positioning container
+.viewport {
+  position: fixed;
+  inset: 0;
+  z-index: 51;
+  pointer-events: none;
+
+  &[data-open] {
+    pointer-events: auto;
+  }
+}
+
+// The popup panel
+.popup {
+  @include surface-elevated;
+  @include text-base;
+
+  position: fixed;
+  z-index: 51;
+  display: flex;
+  flex-direction: column;
+  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+  overflow-y: auto;
+  pointer-events: auto;
+
+  // Animation
+  transition:
+    opacity var(--fui-transition-normal, $fui-transition-normal),
+    transform var(--fui-transition-normal, $fui-transition-normal);
+  opacity: 0;
+
+  &[data-open] {
+    opacity: 1;
+    transform: translate(0, 0);
+  }
+}
+
+// ============================================
+// Side positioning — swipe-aware transforms
+// ============================================
+
+.side-right {
+  top: 0;
+  right: 0;
+  bottom: 0;
+  transform: translateX(calc(100% + var(--drawer-swipe-movement-x, 0px)));
+
+  &[data-open] {
+    transform: translateX(var(--drawer-swipe-movement-x, 0px));
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    transform: translateX(100%);
+  }
+}
+
+.side-left {
+  top: 0;
+  left: 0;
+  bottom: 0;
+  transform: translateX(calc(-100% + var(--drawer-swipe-movement-x, 0px)));
+
+  &[data-open] {
+    transform: translateX(var(--drawer-swipe-movement-x, 0px));
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    transform: translateX(-100%);
+  }
+}
+
+.side-top {
+  top: 0;
+  left: 0;
+  right: 0;
+  transform: translateY(calc(-100% + var(--drawer-swipe-movement-y, 0px)));
+
+  &[data-open] {
+    transform: translateY(var(--drawer-swipe-movement-y, 0px));
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    transform: translateY(-100%);
+  }
+}
+
+.side-bottom {
+  bottom: 0;
+  left: 0;
+  right: 0;
+  transform: translateY(calc(100% + var(--drawer-swipe-movement-y, 0px)));
+
+  &[data-open] {
+    transform: translateY(var(--drawer-swipe-movement-y, 0px));
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    transform: translateY(100%);
+  }
+}
+
+// Disable transition during active swipe for instant feedback
+.popup[data-swiping] {
+  transition-duration: 0s;
+}
+
+// ============================================
+// Size variants — width for left/right, height for top/bottom
+// ============================================
+
+// Left/Right: size maps to width
+.side-left,
+.side-right {
+  &.size-sm { width: 20rem; }
+  &.size-md { width: 24rem; }
+  &.size-lg { width: 32rem; }
+  &.size-xl { width: 48rem; }
+  &.size-full { width: 100vw; }
+}
+
+// Top/Bottom: size maps to height
+.side-top,
+.side-bottom {
+  &.size-sm { height: 25vh; }
+  &.size-md { height: 40vh; }
+  &.size-lg { height: 60vh; }
+  &.size-xl { height: 80vh; }
+  &.size-full { height: 100vh; }
+}
+
+// ============================================
+// Content sections (mirror Dialog)
+// ============================================
+
+// Header area
+.header {
+  padding: var(--fui-space-3, $fui-space-3) var(--fui-space-4, $fui-space-4);
+}
+
+// Title
+.title {
+  margin: 0;
+  font-size: var(--fui-font-size-lg, $fui-font-size-lg);
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+  color: var(--fui-text-primary, $fui-text-primary);
+  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+}
+
+// Description
+.description {
+  margin: var(--fui-space-1, $fui-space-1) 0 0;
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+// Body content
+.body {
+  flex: 1;
+  padding: 0 var(--fui-space-4, $fui-space-4) var(--fui-space-3, $fui-space-3);
+  overflow-y: auto;
+}
+
+// Footer for actions
+.footer {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--fui-space-1, $fui-space-1);
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-4, $fui-space-4);
+  border-top: 1px solid var(--fui-border, $fui-border);
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+}
+
+// Close button (X in corner)
+.close {
+  @include button-reset;
+  @include interactive-base;
+
+  position: absolute;
+  top: var(--fui-space-3, $fui-space-3);
+  right: var(--fui-space-3, $fui-space-3);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  z-index: 1;
+
+  &:hover {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  svg {
+    width: 1rem;
+    height: 1rem;
+  }
+}
+
+// SwipeArea — invisible gesture zone at screen edge
+.swipeArea {
+  position: fixed;
+  z-index: 49;
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .backdrop {
+    transition: none;
+  }
+
+  .popup {
+    transition: none;
+    transform: none;
+
+    &[data-starting-style],
+    &[data-ending-style] {
+      transform: none;
+    }
+  }
+}