@duro-app/ui 0.19.0 → 0.20.1

package/src/components/DetailPanel/styles.css.ts

@@ -0,0 +1,187 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {shadows} from '@duro-app/tokens/tokens/shadows.css'
+
+/** Apple-standard ease: aggressive deceleration, feels like "arriving" */
+const APPLE_EASE_OUT = 'cubic-bezier(0.32, 0.72, 0, 1)'
+const APPLE_EASE_IN = 'cubic-bezier(0.72, 0, 0.68, 0.28)'
+
+const OPEN_DURATION = '280ms'
+const CLOSE_DURATION = '220ms'
+
+export const styles = css.create({
+  // --- Outer wrapper: animates width from 0 → target ---
+  wrapper: {
+    overflow: 'hidden',
+    flexShrink: 0,
+    position: 'relative',
+  },
+
+  // --- Wrapper open/close: SM (360px) ---
+  wrapperOpenSm: {
+    animationName: css.keyframes({
+      from: {width: 0},
+      to: {width: 360},
+    }),
+    animationDuration: OPEN_DURATION,
+    animationTimingFunction: APPLE_EASE_OUT,
+    animationFillMode: 'both',
+  },
+  wrapperCloseSm: {
+    animationName: css.keyframes({
+      from: {width: 360},
+      to: {width: 0},
+    }),
+    animationDuration: CLOSE_DURATION,
+    animationTimingFunction: APPLE_EASE_IN,
+    animationFillMode: 'both',
+  },
+
+  // --- Wrapper open/close: MD (480px) ---
+  wrapperOpenMd: {
+    animationName: css.keyframes({
+      from: {width: 0},
+      to: {width: 480},
+    }),
+    animationDuration: OPEN_DURATION,
+    animationTimingFunction: APPLE_EASE_OUT,
+    animationFillMode: 'both',
+  },
+  wrapperCloseMd: {
+    animationName: css.keyframes({
+      from: {width: 480},
+      to: {width: 0},
+    }),
+    animationDuration: CLOSE_DURATION,
+    animationTimingFunction: APPLE_EASE_IN,
+    animationFillMode: 'both',
+  },
+
+  // --- Content panel ---
+  content: {
+    height: '100%',
+    display: 'flex',
+    flexDirection: 'column',
+    backgroundColor: colors.bgCard,
+    borderLeftWidth: 1,
+    borderLeftStyle: 'solid',
+    borderLeftColor: colors.border,
+    boxShadow: shadows.sm,
+    position: 'relative',
+  },
+
+  // Content must maintain its target width even while wrapper is narrower
+  contentSm: {width: 360},
+  contentMd: {width: 480},
+
+  // --- Content slide + fade animations ---
+  slideIn: {
+    animationName: css.keyframes({
+      from: {
+        transform: 'translateX(40px)',
+        opacity: 0,
+      },
+      to: {
+        transform: 'translateX(0)',
+        opacity: 1,
+      },
+    }),
+    animationDuration: OPEN_DURATION,
+    animationTimingFunction: APPLE_EASE_OUT,
+    animationFillMode: 'both',
+  },
+  slideOut: {
+    animationName: css.keyframes({
+      from: {
+        transform: 'translateX(0)',
+        opacity: 1,
+      },
+      to: {
+        transform: 'translateX(40px)',
+        opacity: 0,
+      },
+    }),
+    animationDuration: CLOSE_DURATION,
+    animationTimingFunction: APPLE_EASE_IN,
+    animationFillMode: 'both',
+  },
+
+  // --- Header ---
+  header: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    paddingTop: spacing.lg,
+    paddingLeft: spacing.lg,
+    paddingRight: spacing.lg,
+    paddingBottom: spacing.lg,
+    gap: spacing.md,
+    borderBottomWidth: 1,
+    borderBottomStyle: 'solid',
+    borderBottomColor: colors.border,
+  },
+
+  // --- Title ---
+  title: {
+    fontSize: 18,
+    fontWeight: 600,
+    lineHeight: 1.4,
+    color: colors.text,
+    margin: 0,
+    flex: 1,
+    minWidth: 0,
+  },
+
+  // --- Body ---
+  body: {
+    flex: 1,
+    overflowY: 'auto',
+  },
+  bodyPadded: {
+    paddingTop: spacing.lg,
+    paddingLeft: spacing.lg,
+    paddingRight: spacing.lg,
+    paddingBottom: spacing.lg,
+  },
+
+  // --- Footer ---
+  footer: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'flex-end',
+    gap: spacing.sm,
+    paddingTop: spacing.md,
+    paddingBottom: spacing.md,
+    paddingLeft: spacing.lg,
+    paddingRight: spacing.lg,
+    borderTopWidth: 1,
+    borderTopStyle: 'solid',
+    borderTopColor: colors.border,
+  },
+
+  // --- Close button ---
+  closeButton: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: 32,
+    height: 32,
+    borderRadius: 8,
+    borderWidth: 0,
+    backgroundColor: {
+      default: 'transparent',
+      ':hover': colors.bgCardHover,
+    },
+    color: colors.textMuted,
+    cursor: 'pointer',
+    padding: 0,
+    flexShrink: 0,
+    transitionProperty: 'background-color',
+    transitionDuration: '150ms',
+  },
+
+  inlineWrapper: {
+    display: 'inline-flex',
+  },
+})

package/src/components/Dialog/Dialog.meta.ts

@@ -0,0 +1,44 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Modal dialog with backdrop overlay. Centered on screen with scale+fade animation. Traps focus, dismisses on backdrop click or Escape. Use for confirmations, forms, or content that requires user attention before continuing.',
+  whenToUse: [
+    'Confirmation prompts (delete, revoke, destructive actions)',
+    'Short forms or data entry that blocks the main flow',
+    'Viewing detail content in a focused overlay (e.g. certificate details)',
+    'Any modal interaction that requires user acknowledgment',
+  ],
+  whenNotToUse: [
+    'Non-modal side panels — use DetailPanel',
+    'Sliding panels from screen edges — use Drawer',
+    'Inline content expansion — use disclosure or accordion patterns',
+    'Toast/notification messages — use Alert or a toast system',
+  ],
+  anatomy: {
+    required: ['Root', 'Portal'],
+    optional: ['Trigger', 'Header', 'Title', 'Description', 'Body', 'Footer', 'Close'],
+  },
+  relatedTo: [
+    {component: 'Drawer', relationship: 'Drawer slides from an edge; Dialog is centered with scale animation'},
+    {component: 'DetailPanel', relationship: 'DetailPanel is non-modal and in-flow; Dialog is modal with backdrop'},
+  ],
+  example: `<Dialog.Root open={open} onOpenChange={setOpen}>
+  <Dialog.Trigger>
+    <Button>Open dialog</Button>
+  </Dialog.Trigger>
+  <Dialog.Portal size="md">
+    <Dialog.Header>
+      <Dialog.Title>Confirm action</Dialog.Title>
+      <Dialog.Close />
+    </Dialog.Header>
+    <Dialog.Body>
+      <Text>Are you sure you want to proceed?</Text>
+    </Dialog.Body>
+    <Dialog.Footer>
+      <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
+      <Button variant="danger" onClick={handleConfirm}>Confirm</Button>
+    </Dialog.Footer>
+  </Dialog.Portal>
+</Dialog.Root>`,
+}

package/src/components/Dialog/Dialog.stories.tsx

@@ -177,9 +177,7 @@ function FormDialogDemo() {
           <Dialog.Title>Edit profile</Dialog.Title>
           <Dialog.Close />
         </Dialog.Header>
-        <Dialog.Description>
-          Update your display name and email address.
-        </Dialog.Description>
+        <Dialog.Description>Update your display name and email address.</Dialog.Description>
         <Dialog.Body>
           <Stack gap="md">
             <Field.Root>
@@ -270,8 +268,8 @@ export const NonDismissable: Story = {
         <Dialog.Body>
           <Stack gap="md">
             <Text>
-              You must accept the terms of service to continue. This dialog cannot be
-              dismissed by clicking outside or pressing Escape.
+              You must accept the terms of service to continue. This dialog cannot be dismissed by
+              clicking outside or pressing Escape.
             </Text>
             <Text variant="bodySm" color="muted">
               Try clicking the backdrop or pressing Escape — the dialog stays open.
@@ -309,8 +307,8 @@ function BackdropDismissDemo() {
           </Dialog.Header>
           <Dialog.Body>
             <Text>
-              Click the dark backdrop behind this dialog to dismiss it.
-              You can also press Escape or use the close button.
+              Click the dark backdrop behind this dialog to dismiss it. You can also press Escape or
+              use the close button.
             </Text>
           </Dialog.Body>
         </Dialog.Portal>

package/src/components/Dialog/Dialog.tsx

@@ -278,11 +278,7 @@ function Close({children, 'aria-label': ariaLabel = 'Close'}: CloseProps) {
   }
 
   return (
-    <html.button
-      onClick={requestClose}
-      aria-label={ariaLabel}
-      style={styles.closeButton}
-    >
+    <html.button onClick={requestClose} aria-label={ariaLabel} style={styles.closeButton}>
       <svg width={16} height={16} viewBox="0 0 16 16" fill="none">
         <path
           d="M4 4l8 8M12 4l-8 8"

package/src/components/Drawer/Drawer.meta.ts

@@ -0,0 +1,45 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Modal sliding panel from a screen edge (right, left, or bottom). Slides in with backdrop overlay. Supports swipe-to-dismiss gestures on mobile, backdrop click dismiss, and Escape key. Use for secondary workflows, settings panels, or mobile-friendly detail views.',
+  whenToUse: [
+    'Settings or configuration panels that slide in from the side',
+    'Mobile-friendly detail views (bottom sheet pattern)',
+    'Secondary workflows that need more space than a dialog',
+    'Filters, navigation drawers, or form panels',
+  ],
+  whenNotToUse: [
+    'Centered modal confirmations — use Dialog',
+    'Non-modal side inspection panels — use DetailPanel',
+    'Inline content expansion — use disclosure patterns',
+    'Primary navigation — use SideNav',
+  ],
+  anatomy: {
+    required: ['Root', 'Portal'],
+    optional: ['Trigger', 'Header', 'Title', 'Description', 'Body', 'Footer', 'Close'],
+  },
+  relatedTo: [
+    {component: 'Dialog', relationship: 'Dialog is centered modal; Drawer slides from an edge'},
+    {component: 'DetailPanel', relationship: 'DetailPanel is non-modal and in-flow; Drawer is modal with backdrop'},
+  ],
+  example: `<Drawer.Root anchor="right" open={open} onOpenChange={setOpen}>
+  <Drawer.Trigger>
+    <Button>Open drawer</Button>
+  </Drawer.Trigger>
+  <Drawer.Portal size="md">
+    <Drawer.Header>
+      <Drawer.Title>Settings</Drawer.Title>
+      <Drawer.Close />
+    </Drawer.Header>
+    <Drawer.Body>
+      <Stack gap="md">
+        <Text>Drawer content goes here.</Text>
+      </Stack>
+    </Drawer.Body>
+    <Drawer.Footer>
+      <Button variant="secondary" onClick={() => setOpen(false)}>Done</Button>
+    </Drawer.Footer>
+  </Drawer.Portal>
+</Drawer.Root>`,
+}

package/src/components/Drawer/Drawer.stories.tsx

@@ -31,8 +31,8 @@ export const Default: Story = {
         </Drawer.Header>
         <Drawer.Body>
           <Text>
-            This drawer slides in from the right edge. It's useful for showing details,
-            settings panels, or supplementary content without leaving the current page.
+            This drawer slides in from the right edge. It's useful for showing details, settings
+            panels, or supplementary content without leaving the current page.
           </Text>
         </Drawer.Body>
         <Drawer.Footer>
@@ -93,9 +93,15 @@ export const BottomAnchor: Story = {
         </Drawer.Header>
         <Drawer.Body>
           <Stack gap="sm">
-            <Button variant="secondary" fullWidth>Share</Button>
-            <Button variant="secondary" fullWidth>Duplicate</Button>
-            <Button variant="danger" fullWidth>Delete</Button>
+            <Button variant="secondary" fullWidth>
+              Share
+            </Button>
+            <Button variant="secondary" fullWidth>
+              Duplicate
+            </Button>
+            <Button variant="danger" fullWidth>
+              Delete
+            </Button>
           </Stack>
         </Drawer.Body>
       </Drawer.Portal>
@@ -125,7 +131,10 @@ function SizesDemo() {
               <Drawer.Close />
             </Drawer.Header>
             <Drawer.Body>
-              <Text>This drawer uses the {s} size preset ({s === 'sm' ? '360' : s === 'md' ? '480' : '640'}px max-width).</Text>
+              <Text>
+                This drawer uses the {s} size preset (
+                {s === 'sm' ? '360' : s === 'md' ? '480' : '640'}px max-width).
+              </Text>
             </Drawer.Body>
             <Drawer.Footer>
               <Drawer.Close>
@@ -164,9 +173,7 @@ function FormDrawerDemo() {
           <Drawer.Title>Edit profile</Drawer.Title>
           <Drawer.Close />
         </Drawer.Header>
-        <Drawer.Description>
-          Update your account information below.
-        </Drawer.Description>
+        <Drawer.Description>Update your account information below.</Drawer.Description>
         <Drawer.Body>
           <Stack gap="md">
             <Field.Root>
@@ -269,8 +276,8 @@ export const NonDismissable: Story = {
         <Drawer.Body>
           <Stack gap="md">
             <Text>
-              This drawer cannot be dismissed by clicking the backdrop or pressing Escape.
-              You must use the explicit close action below.
+              This drawer cannot be dismissed by clicking the backdrop or pressing Escape. You must
+              use the explicit close action below.
             </Text>
             <Text variant="bodySm" color="muted">
               Try clicking outside or pressing Escape — nothing happens.
@@ -302,8 +309,8 @@ export const NoSwipeDismiss: Story = {
         </Drawer.Header>
         <Drawer.Body>
           <Text>
-            This bottom drawer has swipe-to-dismiss disabled. On mobile, you cannot
-            swipe down to close it — use the close button or tap the backdrop instead.
+            This bottom drawer has swipe-to-dismiss disabled. On mobile, you cannot swipe down to
+            close it — use the close button or tap the backdrop instead.
           </Text>
         </Drawer.Body>
       </Drawer.Portal>
@@ -326,12 +333,10 @@ export const SwipeDismiss: Story = {
         </Drawer.Header>
         <Drawer.Body>
           <Stack gap="md">
-            <Text>
-              Drag this drawer downward to dismiss it. The backdrop fades as you drag.
-            </Text>
+            <Text>Drag this drawer downward to dismiss it. The backdrop fades as you drag.</Text>
             <Text variant="bodySm" color="muted">
-              Swipe past 30% of the panel height or flick quickly to dismiss.
-              Otherwise it snaps back.
+              Swipe past 30% of the panel height or flick quickly to dismiss. Otherwise it snaps
+              back.
             </Text>
           </Stack>
         </Drawer.Body>
@@ -354,9 +359,7 @@ export const SwipeDismissRight: Story = {
           <Drawer.Close />
         </Drawer.Header>
         <Drawer.Body>
-          <Text>
-            Drag this panel to the right to dismiss it. Works with touch and mouse.
-          </Text>
+          <Text>Drag this panel to the right to dismiss it. Works with touch and mouse.</Text>
         </Drawer.Body>
       </Drawer.Portal>
     </Drawer.Root>

package/src/components/Drawer/Drawer.tsx

@@ -252,10 +252,7 @@ function Portal({children, size = 'md'}: PortalProps) {
       />
 
       {/* Viewport */}
-      <html.div
-        style={[styles.viewport, viewportAnchorMap[anchor]]}
-        data-drawer-viewport=""
-      >
+      <html.div style={[styles.viewport, viewportAnchorMap[anchor]]} data-drawer-viewport="">
         <html.div
           ref={panelRef}
           role="dialog"
@@ -338,11 +335,7 @@ function Close({children, 'aria-label': ariaLabel = 'Close'}: CloseProps) {
   }
 
   return (
-    <html.button
-      onClick={requestClose}
-      aria-label={ariaLabel}
-      style={styles.closeButton}
-    >
+    <html.button onClick={requestClose} aria-label={ariaLabel} style={styles.closeButton}>
       <svg width={16} height={16} viewBox="0 0 16 16" fill="none">
         <path
           d="M4 4l8 8M12 4l-8 8"

package/src/components/Drawer/useSwipeDismiss.ts

@@ -97,9 +97,7 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panelRef}: UseSwipe
 
         panelEl.style.transform = ''
         panelEl.style.boxShadow =
-          shadowSpread > 0
-            ? `0 0 ${shadowSpread * 2}px ${shadowSpread}px rgba(0, 0, 0, 0.15)`
-            : ''
+          shadowSpread > 0 ? `0 0 ${shadowSpread * 2}px ${shadowSpread}px rgba(0, 0, 0, 0.15)` : ''
       }
     },
     [anchor, isHorizontal],
@@ -255,8 +253,7 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panelRef}: UseSwipe
       }
 
       const fraction = movement / state.panelSize
-      const shouldDismiss =
-        fraction > DISMISS_THRESHOLD || velocity > VELOCITY_THRESHOLD
+      const shouldDismiss = fraction > DISMISS_THRESHOLD || velocity > VELOCITY_THRESHOLD
 
       if (shouldDismiss) {
         animateDismiss(panel!)
@@ -291,5 +288,15 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panelRef}: UseSwipe
       panel.removeEventListener('pointercancel', handlePointerCancel)
       panel.removeEventListener('touchmove', handleTouchMove)
     }
-  }, [enabled, panelRef, anchor, isHorizontal, getMovement, applyTransform, resetStyles, animateSnapBack, animateDismiss])
+  }, [
+    enabled,
+    panelRef,
+    anchor,
+    isHorizontal,
+    getMovement,
+    applyTransform,
+    resetStyles,
+    animateSnapBack,
+    animateDismiss,
+  ])
 }

package/src/components/Panel/Panel.meta.ts

@@ -0,0 +1,37 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Structural primitive for grouping content with header, body, and footer slots. A "workspace surface" for forms, settings sections, and inspectors. Sub-components are purely structural — no context required.',
+  whenToUse: [
+    'Organizing content with distinct header/body/footer sections',
+    'Settings panels, form containers, inspector views',
+    'When you need more structure than Card but less than a full page layout',
+  ],
+  whenNotToUse: [
+    'Repeating item cards — use Card',
+    'Modal/overlay content — use Dialog or Drawer',
+    'Page-level layout — use PageShell',
+  ],
+  anatomy: {
+    required: [],
+    optional: ['Root', 'Header', 'Body', 'Footer'],
+  },
+  relatedTo: [
+    {component: 'Card', relationship: 'Card is for shallow, repeated items; Panel is for deep, organized content'},
+    {component: 'DetailPanel', relationship: 'DetailPanel uses Panel internally for its structural layout'},
+    {component: 'PageShell', relationship: 'PageShell is for page-level layout; Panel is for section-level'},
+  ],
+  example: `<Panel.Root bordered>
+  <Panel.Header>
+    <Heading level={3}>Section Title</Heading>
+    <Button variant="secondary" size="small">Action</Button>
+  </Panel.Header>
+  <Panel.Body>
+    {/* Content */}
+  </Panel.Body>
+  <Panel.Footer>
+    <Button>Save</Button>
+  </Panel.Footer>
+</Panel.Root>`,
+}

package/src/components/Panel/Panel.stories.tsx

@@ -0,0 +1,124 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {Panel} from './Panel'
+import {Button} from '../Button/Button'
+import {Text} from '../Text/Text'
+import {Heading} from '../Heading/Heading'
+import {Stack} from '../Stack/Stack'
+import {Inline} from '../Inline/Inline'
+import {Field} from '../Field/Field'
+import {Input} from '../Input/Input'
+
+const meta: Meta = {
+  title: 'Components/Panel',
+}
+
+export default meta
+type Story = StoryObj
+
+// --- Default ---
+
+export const Default: Story = {
+  render: () => (
+    <Panel.Root>
+      <Panel.Header>
+        <Heading level={3}>Section Title</Heading>
+      </Panel.Header>
+      <Panel.Body>
+        <Text>
+          Panel is a structural primitive for grouping content with
+          header, body, and footer slots. It fills the gap between Card
+          and page-level layout.
+        </Text>
+      </Panel.Body>
+      <Panel.Footer>
+        <Button variant="secondary">Cancel</Button>
+        <Button>Save</Button>
+      </Panel.Footer>
+    </Panel.Root>
+  ),
+}
+
+// --- Bordered ---
+
+export const Bordered: Story = {
+  render: () => (
+    <Panel.Root bordered>
+      <Panel.Header>
+        <Heading level={3}>Bordered Panel</Heading>
+        <Button variant="secondary" size="small">Action</Button>
+      </Panel.Header>
+      <Panel.Body>
+        <Text>
+          The bordered variant adds an outer border, useful when the panel
+          needs visual separation from its surroundings.
+        </Text>
+      </Panel.Body>
+      <Panel.Footer>
+        <Button>Confirm</Button>
+      </Panel.Footer>
+    </Panel.Root>
+  ),
+}
+
+// --- Body Only ---
+
+export const BodyOnly: Story = {
+  render: () => (
+    <Panel.Root bordered>
+      <Panel.Body>
+        <Text>
+          Panel sub-components can be used independently. This panel only
+          has a Body — no Header or Footer.
+        </Text>
+      </Panel.Body>
+    </Panel.Root>
+  ),
+}
+
+// --- Unpadded Body ---
+
+export const UnpaddedBody: Story = {
+  render: () => (
+    <Panel.Root bordered>
+      <Panel.Header>
+        <Heading level={3}>Full-bleed Content</Heading>
+      </Panel.Header>
+      <Panel.Body padded={false}>
+        <Text>
+          Setting padded=false removes body padding, useful for content
+          that needs to extend edge-to-edge (tables, images, etc).
+        </Text>
+      </Panel.Body>
+    </Panel.Root>
+  ),
+}
+
+// --- With Form ---
+
+export const WithForm: Story = {
+  render: () => (
+    <Panel.Root bordered>
+      <Panel.Header>
+        <Heading level={3}>Profile Settings</Heading>
+      </Panel.Header>
+      <Panel.Body>
+        <Stack gap="md">
+          <Field.Root>
+            <Field.Label>Display name</Field.Label>
+            <Input placeholder="Enter your name" />
+          </Field.Root>
+          <Field.Root>
+            <Field.Label>Email</Field.Label>
+            <Input type="email" placeholder="you@example.com" />
+          </Field.Root>
+        </Stack>
+      </Panel.Body>
+      <Panel.Footer>
+        <Inline gap="sm">
+          <Button variant="secondary">Cancel</Button>
+          <Button>Save changes</Button>
+        </Inline>
+      </Panel.Footer>
+    </Panel.Root>
+  ),
+}