@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Dialog/index.tsx

@@ -1,8 +1,8 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import { Dialog as BaseDialog } from '@base-ui/react/dialog';
-import styles from './Dialog.module.scss';
+import * as React from "react";
+import { Dialog as BaseDialog } from "@base-ui/react/dialog";
+import styles from "./Dialog.module.scss";
 
 // ============================================
 // Types
@@ -30,17 +30,20 @@ export interface DialogContentProps extends React.HTMLAttributes<HTMLDivElement>
   /** Dialog width.
    * @default "md"
    * @see https://usefragments.com/components/dialog#sizes */
-  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
+  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'> {
+export interface DialogTitleProps extends Omit<React.HTMLAttributes<HTMLElement>, "children"> {
   children: React.ReactNode;
 }
 
-export interface DialogDescriptionProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+export interface DialogDescriptionProps extends Omit<
+  React.HTMLAttributes<HTMLElement>,
+  "children"
+> {
   children: React.ReactNode;
 }
 
@@ -61,7 +64,7 @@ type DialogTriggerAsButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement>
   asChild?: false;
 };
 
-type DialogTriggerAsChildProps = Omit<React.HTMLAttributes<HTMLElement>, 'children'> & {
+type DialogTriggerAsChildProps = Omit<React.HTMLAttributes<HTMLElement>, "children"> & {
   children: React.ReactElement;
   asChild: true;
 };
@@ -73,7 +76,7 @@ type DialogCloseAsButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
   asChild?: false;
 };
 
-type DialogCloseAsChildProps = Omit<React.HTMLAttributes<HTMLElement>, 'children'> & {
+type DialogCloseAsChildProps = Omit<React.HTMLAttributes<HTMLElement>, "children"> & {
   children: React.ReactElement;
   asChild: true;
 };
@@ -108,13 +111,7 @@ function CloseIcon() {
 // Components
 // ============================================
 
-function DialogRoot({
-  children,
-  open,
-  defaultOpen,
-  onOpenChange,
-  modal = true,
-}: DialogProps) {
+function DialogRoot({ children, open, defaultOpen, onOpenChange, modal = true }: DialogProps) {
   return (
     <BaseDialog.Root
       open={open}
@@ -127,15 +124,14 @@ function DialogRoot({
   );
 }
 
-function DialogTrigger({
-  children,
-  asChild,
-  className,
-  ...htmlProps
-}: DialogTriggerProps) {
+function DialogTrigger({ children, asChild, className, ...htmlProps }: DialogTriggerProps) {
   if (asChild) {
     return (
-      <BaseDialog.Trigger {...htmlProps} className={className} render={children as React.ReactElement}>
+      <BaseDialog.Trigger
+        {...htmlProps}
+        className={className}
+        render={children as React.ReactElement}
+      >
         {null}
       </BaseDialog.Trigger>
     );
@@ -150,14 +146,12 @@ function DialogTrigger({
 
 function DialogContent({
   children,
-  size = 'md',
+  size = "md",
   initialFocus = true,
   className,
   ...htmlProps
 }: DialogContentProps) {
-  const popupClasses = [styles.popup, styles[size], className]
-    .filter(Boolean)
-    .join(' ');
+  const popupClasses = [styles.popup, styles[size], className].filter(Boolean).join(" ");
 
   return (
     <BaseDialog.Portal>
@@ -172,17 +166,25 @@ function DialogContent({
 }
 
 function DialogHeader({ children, className, ...htmlProps }: DialogHeaderProps) {
-  const classes = [styles.header, className].filter(Boolean).join(' ');
-  return <div {...htmlProps} className={classes}>{children}</div>;
+  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>;
+  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(' ');
+  const classes = [styles.description, className].filter(Boolean).join(" ");
   return (
     <BaseDialog.Description {...htmlProps} className={classes}>
       {children}
@@ -191,13 +193,21 @@ function DialogDescription({ children, className, ...htmlProps }: DialogDescript
 }
 
 function DialogBody({ children, className, ...htmlProps }: DialogBodyProps) {
-  const classes = [styles.body, className].filter(Boolean).join(' ');
-  return <div {...htmlProps} className={classes}>{children}</div>;
+  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>;
+  const classes = [styles.footer, className].filter(Boolean).join(" ");
+  return (
+    <div {...htmlProps} className={classes}>
+      {children}
+    </div>
+  );
 }
 
 function DialogClose({ children, asChild, className, ...htmlProps }: DialogCloseProps) {
@@ -208,7 +218,7 @@ function DialogClose({ children, asChild, className, ...htmlProps }: DialogClose
         {...htmlProps}
         data-dialog-close
         aria-label="Close dialog"
-        className={[styles.close, className].filter(Boolean).join(' ')}
+        className={[styles.close, className].filter(Boolean).join(" ")}
       >
         <CloseIcon />
       </BaseDialog.Close>

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

@@ -1,15 +1,9 @@
 {
   "$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"
-  ],
+  "description": "Slides a panel in from a screen edge and dims the page behind it.",
+  "category": "overlays",
+  "tags": ["drawer", "sheet", "panel", "sidebar", "slide-over"],
   "status": "stable",
   "sourcePath": "src/components/Drawer/index.tsx",
   "exportName": "Drawer",
@@ -51,25 +45,23 @@
   },
   "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"
+      "Editing or creating alongside the page behind it",
+      "Touch-reachable action sheets",
+      "Navigation that slides in and back out",
+      "Detail views that overlay rather than replace"
     ],
     "whenNot": [
-      "Centered modal dialogs (use Dialog)",
-      "Non-blocking notifications (use Toast)",
-      "Permanent side navigation (use Sidebar)",
-      "Small contextual menus (use Menu or Popover)"
+      "A centred task (use Dialog)",
+      "Navigation that stays on screen (use Sidebar)",
+      "A short list of actions (use Menu or Popover)",
+      "Feedback the user does not act on (use Toast)"
     ],
     "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"
+      "Right for editing, left for navigation, bottom for touch",
+      "Always give the user a visible way out",
+      "One task per drawer",
+      "asChild on Trigger and Close needs a single element child",
+      "Set initialFocus={false} when you place focus yourself"
     ],
     "accessibility": [
       "Automatically traps focus within the drawer",
@@ -81,22 +73,22 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Right-side drawer with header, body, and footer",
+      "description": "Enters from the right, the default for editing and forms.",
       "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",
+      "description": "Enters from the left, where navigation belongs.",
       "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",
+      "description": "Rises from the bottom for touch-reachable 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",
+      "description": "Fields in the body, submit and cancel pinned to the footer.",
       "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>"
     }
   ],
@@ -126,11 +118,7 @@
       "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"
-    ]
+    "a11yRules": ["A11Y_DIALOG_FOCUS", "A11Y_DIALOG_ESCAPE", "A11Y_DIALOG_LABEL"]
   },
   "ai": {
     "compositionPattern": "compound",
@@ -145,9 +133,7 @@
       "Body",
       "Footer"
     ],
-    "requiredChildren": [
-      "Content"
-    ],
+    "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>"
     ]

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

@@ -1,14 +1,13 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+@use "../../recipes/action" as action;
+@use "../../recipes/overlay" as overlay;
 
-// Backdrop overlay
 .backdrop {
   position: fixed;
+  z-index: var(--fui-overlay-layer-backdrop, 50);
   inset: 0;
   background-color: var(--fui-backdrop, $fui-backdrop);
-  z-index: 50;
-
-  // Animation
   opacity: 0;
   transition: opacity var(--fui-transition-normal, $fui-transition-normal);
 
@@ -22,11 +21,12 @@
   }
 }
 
-// Viewport positioning container
 .viewport {
+  @include overlay.safe-viewport;
+
   position: fixed;
+  z-index: var(--fui-overlay-layer-modal, 51);
   inset: 0;
-  z-index: 51;
   pointer-events: none;
 
   &[data-open] {
@@ -34,24 +34,18 @@
   }
 }
 
-// The popup panel
 .popup {
-  @include surface-elevated;
-  @include text-base;
+  @include overlay.modal-shell;
 
   position: fixed;
-  z-index: 51;
+  z-index: var(--fui-overlay-layer-modal, 51);
   display: flex;
   flex-direction: column;
-  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
-  overflow-y: auto;
   pointer-events: auto;
-
-  // Animation
+  opacity: 0;
   transition:
     opacity var(--fui-transition-normal, $fui-transition-normal),
     transform var(--fui-transition-normal, $fui-transition-normal);
-  opacity: 0;
 
   &[data-open] {
     opacity: 1;
@@ -59,14 +53,16 @@
   }
 }
 
-// ============================================
-// Side positioning — swipe-aware transforms
-// ============================================
+.content {
+  display: flex;
+  min-block-size: 0;
+  block-size: 100%;
+  flex-direction: column;
+}
 
 .side-right {
-  top: 0;
-  right: 0;
-  bottom: 0;
+  inset-block: var(--_fui-overlay-safe-top) var(--_fui-overlay-safe-bottom);
+  inset-inline-end: var(--_fui-overlay-safe-right);
   transform: translateX(calc(100% + var(--drawer-swipe-movement-x, 0px)));
 
   &[data-open] {
@@ -80,9 +76,8 @@
 }
 
 .side-left {
-  top: 0;
-  left: 0;
-  bottom: 0;
+  inset-block: var(--_fui-overlay-safe-top) var(--_fui-overlay-safe-bottom);
+  inset-inline-start: var(--_fui-overlay-safe-left);
   transform: translateX(calc(-100% + var(--drawer-swipe-movement-x, 0px)));
 
   &[data-open] {
@@ -96,9 +91,8 @@
 }
 
 .side-top {
-  top: 0;
-  left: 0;
-  right: 0;
+  inset-block-start: var(--_fui-overlay-safe-top);
+  inset-inline: var(--_fui-overlay-safe-left) var(--_fui-overlay-safe-right);
   transform: translateY(calc(-100% + var(--drawer-swipe-movement-y, 0px)));
 
   &[data-open] {
@@ -112,9 +106,8 @@
 }
 
 .side-bottom {
-  bottom: 0;
-  left: 0;
-  right: 0;
+  inset-block-end: var(--_fui-overlay-safe-bottom);
+  inset-inline: var(--_fui-overlay-safe-left) var(--_fui-overlay-safe-right);
   transform: translateY(calc(100% + var(--drawer-swipe-movement-y, 0px)));
 
   &[data-open] {
@@ -127,95 +120,97 @@
   }
 }
 
-// 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; }
+  &.size-sm {
+    inline-size: min(#{overlay.drawer-inline("sm")}, var(--_fui-overlay-safe-inline));
+  }
+
+  &.size-md {
+    inline-size: min(#{overlay.drawer-inline("md")}, var(--_fui-overlay-safe-inline));
+  }
+
+  &.size-lg {
+    inline-size: min(#{overlay.drawer-inline("lg")}, var(--_fui-overlay-safe-inline));
+  }
+
+  &.size-xl {
+    inline-size: min(#{overlay.drawer-inline("xl")}, var(--_fui-overlay-safe-inline));
+  }
+
+  &.size-full {
+    inline-size: var(--_fui-overlay-safe-inline);
+  }
 }
 
-// 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; }
-}
+  &.size-sm {
+    block-size: min(#{overlay.drawer-block("sm")}, var(--_fui-overlay-safe-block));
+  }
+
+  &.size-md {
+    block-size: min(#{overlay.drawer-block("md")}, var(--_fui-overlay-safe-block));
+  }
 
-// ============================================
-// Content sections (mirror Dialog)
-// ============================================
+  &.size-lg {
+    block-size: min(#{overlay.drawer-block("lg")}, var(--_fui-overlay-safe-block));
+  }
+
+  &.size-xl {
+    block-size: min(#{overlay.drawer-block("xl")}, var(--_fui-overlay-safe-block));
+  }
+
+  &.size-full {
+    block-size: var(--_fui-overlay-safe-block);
+  }
+}
 
-// Header area
 .header {
-  padding: var(--fui-space-3, $fui-space-3) var(--fui-space-4, $fui-space-4);
+  @include overlay.header;
 }
 
-// Title
 .title {
+  @include overlay.modal-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);
+  @include overlay.description;
+
+  margin: 0;
   color: var(--fui-text-secondary, $fui-text-secondary);
-  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
 }
 
-// Body content
 .body {
+  @include overlay.body;
+
+  min-block-size: 0;
   flex: 1;
-  padding: 0 var(--fui-space-4, $fui-space-4) var(--fui-space-3, $fui-space-3);
-  overflow-y: auto;
+  overflow: 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);
+  @include overlay.footer;
+
+  border-top: var(--fui-stroke-hairline, 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;
+  @include overlay.close;
 
-  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;
+  z-index: 1;
   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);
@@ -223,33 +218,32 @@
   }
 
   svg {
-    width: 1rem;
-    height: 1rem;
+    inline-size: action.icon-size("sm");
+    block-size: action.icon-size("sm");
   }
 }
 
-// SwipeArea — invisible gesture zone at screen edge
+.popup:has(.close) .header {
+  padding-inline-end: calc(
+    var(--fui-overlay-close-inset, var(--fui-raw-space-12, 12px)) + #{action.track("sm")} +
+      var(--fui-overlay-section-gap, var(--fui-raw-space-8, 8px))
+  );
+}
+
 .swipeArea {
   position: fixed;
-  z-index: 49;
+  z-index: var(--fui-overlay-layer-swipe, 49);
 }
 
-// ============================================
-// Accessibility: Reduced Motion
-// ============================================
-
 @media (prefers-reduced-motion: reduce) {
-  .backdrop {
+  .backdrop,
+  .popup {
     transition: none;
   }
 
-  .popup {
-    transition: none;
+  .popup,
+  .popup[data-starting-style],
+  .popup[data-ending-style] {
     transform: none;
-
-    &[data-starting-style],
-    &[data-ending-style] {
-      transform: none;
-    }
   }
 }

package/src/components/Drawer/index.tsx

@@ -225,7 +225,7 @@ function DrawerContent({
           data-side={side}
           className={popupClasses}
         >
-          <BaseDrawer.Content>{children}</BaseDrawer.Content>
+          <BaseDrawer.Content className={styles.content}>{children}</BaseDrawer.Content>
         </BaseDrawer.Popup>
       </BaseDrawer.Viewport>
     </BaseDrawer.Portal>