@duro-app/ui 0.18.0 → 0.20.0

package/src/components/Drawer/useSwipeDismiss.ts

@@ -0,0 +1,295 @@
+import {useRef, useCallback, useEffect} from 'react'
+import type {DrawerAnchor} from './Drawer'
+
+/** Threshold: fraction of panel size the user must drag to dismiss */
+const DISMISS_THRESHOLD = 0.3
+
+/** Minimum velocity (px/ms) to dismiss even below threshold */
+const VELOCITY_THRESHOLD = 0.5
+
+/** Duration for the dismiss slide-out animation (ms) */
+const DISMISS_DURATION = 160
+
+/**
+ * Max pixels the panel visually "grows" when dragged in the opposite direction.
+ * iOS-style: panel stays anchored to its edge, doesn't translate.
+ * Instead we show a subtle shadow/scale hint capped at this value.
+ */
+const OPPOSITE_MAX_OVERSCROLL = 12
+
+interface UseSwipeDismissOptions {
+  anchor: DrawerAnchor
+  enabled: boolean
+  onDismiss: () => void
+  panelRef: React.RefObject<HTMLDivElement | null>
+}
+
+interface SwipeState {
+  startX: number
+  startY: number
+  currentX: number
+  currentY: number
+  startTime: number
+  swiping: boolean
+  panelSize: number
+}
+
+/**
+ * Hook that adds swipe-to-dismiss gesture to a drawer panel.
+ *
+ * Dismiss direction: panel follows finger 1:1, backdrop fades.
+ * Opposite direction: iOS-style — panel stays anchored, shows subtle
+ * overscroll feedback (box-shadow intensifies), then snaps back.
+ */
+export function useSwipeDismiss({anchor, enabled, onDismiss, panelRef}: UseSwipeDismissOptions) {
+  const stateRef = useRef<SwipeState>({
+    startX: 0,
+    startY: 0,
+    currentX: 0,
+    currentY: 0,
+    startTime: 0,
+    swiping: false,
+    panelSize: 0,
+  })
+
+  const isHorizontal = anchor === 'left' || anchor === 'right'
+
+  /** Returns positive = dismiss direction, negative = opposite */
+  const getMovement = useCallback(
+    (state: SwipeState) => {
+      if (isHorizontal) {
+        const dx = state.currentX - state.startX
+        return anchor === 'right' ? dx : -dx
+      }
+      return state.currentY - state.startY
+    },
+    [anchor, isHorizontal],
+  )
+
+  const applyTransform = useCallback(
+    (movement: number, panelEl: HTMLDivElement) => {
+      const size = Number(panelEl.dataset.panelSize) || 1
+
+      if (movement >= 0) {
+        // Dismiss direction — 1:1 tracking
+        const progress = movement / size
+
+        if (isHorizontal) {
+          const sign = anchor === 'right' ? 1 : -1
+          panelEl.style.transform = `translateX(${sign * movement}px)`
+        } else {
+          panelEl.style.transform = `translateY(${movement}px)`
+        }
+
+        // Fade backdrop proportionally
+        const backdrop = panelEl.closest('[data-drawer-viewport]')
+          ?.previousElementSibling as HTMLElement | null
+        if (backdrop) {
+          backdrop.style.opacity = String(Math.max(0, 1 - progress))
+        }
+      } else {
+        // Opposite direction — iOS behavior:
+        // Panel stays anchored (no translate). Show subtle overscroll via box-shadow.
+        // Diminishing resistance: asymptotically approaches OPPOSITE_MAX_OVERSCROLL.
+        const absMovement = Math.abs(movement)
+        const overscroll = (absMovement / (absMovement + size * 0.5)) * OPPOSITE_MAX_OVERSCROLL
+        const shadowSpread = Math.round(overscroll)
+
+        panelEl.style.transform = ''
+        panelEl.style.boxShadow =
+          shadowSpread > 0
+            ? `0 0 ${shadowSpread * 2}px ${shadowSpread}px rgba(0, 0, 0, 0.15)`
+            : ''
+      }
+    },
+    [anchor, isHorizontal],
+  )
+
+  /** Reset all inline styles (snap back) */
+  const resetStyles = useCallback((panelEl: HTMLDivElement) => {
+    panelEl.style.transform = ''
+    panelEl.style.boxShadow = ''
+
+    const backdrop = panelEl.closest('[data-drawer-viewport]')
+      ?.previousElementSibling as HTMLElement | null
+    if (backdrop) {
+      backdrop.style.opacity = ''
+    }
+  }, [])
+
+  /** Animate to fully dismissed position, then call onDismiss */
+  const animateDismiss = useCallback(
+    (panelEl: HTMLDivElement) => {
+      const dismissTransform = isHorizontal
+        ? `translateX(${anchor === 'right' ? '100%' : '-100%'})`
+        : 'translateY(100%)'
+
+      panelEl.style.transition = `transform ${DISMISS_DURATION}ms ease-in`
+      panelEl.style.transform = dismissTransform
+
+      const backdrop = panelEl.closest('[data-drawer-viewport]')
+        ?.previousElementSibling as HTMLElement | null
+      if (backdrop) {
+        backdrop.style.transition = `opacity ${DISMISS_DURATION}ms ease-in`
+        backdrop.style.opacity = '0'
+      }
+
+      // When the slide-out transition finishes, just call onDismiss.
+      // Do NOT reset inline styles before unmount — that causes a 1-frame flash
+      // where the panel appears at its original position. React will unmount the
+      // DOM node entirely, so the inline styles don't need cleanup.
+      let dismissed = false
+      const done = () => {
+        if (dismissed) return
+        dismissed = true
+        onDismiss()
+      }
+      panelEl.addEventListener('transitionend', done, {once: true})
+      setTimeout(done, DISMISS_DURATION + 50)
+    },
+    [anchor, isHorizontal, onDismiss],
+  )
+
+  /** Animate snap-back for dismiss-direction undershoot */
+  const animateSnapBack = useCallback((panelEl: HTMLDivElement) => {
+    panelEl.style.transition = 'transform 200ms cubic-bezier(0.25, 1, 0.5, 1)'
+    panelEl.style.transform = ''
+
+    const backdrop = panelEl.closest('[data-drawer-viewport]')
+      ?.previousElementSibling as HTMLElement | null
+    if (backdrop) {
+      backdrop.style.transition = 'opacity 200ms cubic-bezier(0.25, 1, 0.5, 1)'
+      backdrop.style.opacity = ''
+    }
+
+    const cleanup = () => {
+      panelEl.style.transition = ''
+      if (backdrop) backdrop.style.transition = ''
+    }
+    panelEl.addEventListener('transitionend', cleanup, {once: true})
+    setTimeout(cleanup, 250)
+  }, [])
+
+  useEffect(() => {
+    if (!enabled) return
+    const panel = panelRef.current
+    if (!panel) return
+
+    function handlePointerDown(e: PointerEvent) {
+      if (e.button !== 0) return
+      const target = e.target as HTMLElement
+      if (target.closest('button, a, input, textarea, select, [role="button"]')) {
+        return
+      }
+
+      const rect = panel!.getBoundingClientRect()
+      const state = stateRef.current
+      state.startX = e.clientX
+      state.startY = e.clientY
+      state.currentX = e.clientX
+      state.currentY = e.clientY
+      state.startTime = Date.now()
+      state.swiping = false
+      state.panelSize = isHorizontal ? rect.width : rect.height
+
+      panel!.dataset.panelSize = String(state.panelSize)
+      panel!.setPointerCapture(e.pointerId)
+
+      // Freeze CSS animation — we take over positioning.
+      // Never restore it; the panel is already at its final resting position.
+      panel!.style.animation = 'none'
+    }
+
+    function handlePointerMove(e: PointerEvent) {
+      const state = stateRef.current
+      if (state.startTime === 0) return
+
+      state.currentX = e.clientX
+      state.currentY = e.clientY
+
+      const dx = Math.abs(state.currentX - state.startX)
+      const dy = Math.abs(state.currentY - state.startY)
+
+      if (!state.swiping) {
+        const totalMovement = Math.sqrt(dx * dx + dy * dy)
+        if (totalMovement < 8) return
+
+        if (isHorizontal && dx > dy) {
+          state.swiping = true
+        } else if (!isHorizontal && dy > dx) {
+          state.swiping = true
+        } else {
+          // Wrong axis — abort gesture
+          state.startTime = 0
+          return
+        }
+      }
+
+      if (state.swiping) {
+        e.preventDefault()
+        const movement = getMovement(state)
+        applyTransform(movement, panel!)
+      }
+    }
+
+    function handlePointerUp(_e: PointerEvent) {
+      const state = stateRef.current
+      if (state.startTime === 0) return
+
+      const movement = getMovement(state)
+      const elapsed = Date.now() - state.startTime
+      const velocity = movement / elapsed
+
+      state.startTime = 0
+
+      if (!state.swiping) {
+        return
+      }
+
+      state.swiping = false
+
+      if (movement <= 0) {
+        // Was dragging in opposite direction — just reset (no translate was applied)
+        resetStyles(panel!)
+        return
+      }
+
+      const fraction = movement / state.panelSize
+      const shouldDismiss =
+        fraction > DISMISS_THRESHOLD || velocity > VELOCITY_THRESHOLD
+
+      if (shouldDismiss) {
+        animateDismiss(panel!)
+      } else {
+        animateSnapBack(panel!)
+      }
+    }
+
+    function handlePointerCancel() {
+      const state = stateRef.current
+      state.startTime = 0
+      state.swiping = false
+      resetStyles(panel!)
+    }
+
+    panel.addEventListener('pointerdown', handlePointerDown)
+    panel.addEventListener('pointermove', handlePointerMove)
+    panel.addEventListener('pointerup', handlePointerUp)
+    panel.addEventListener('pointercancel', handlePointerCancel)
+
+    function handleTouchMove(e: TouchEvent) {
+      if (stateRef.current.swiping) {
+        e.preventDefault()
+      }
+    }
+    panel.addEventListener('touchmove', handleTouchMove, {passive: false})
+
+    return () => {
+      panel.removeEventListener('pointerdown', handlePointerDown)
+      panel.removeEventListener('pointermove', handlePointerMove)
+      panel.removeEventListener('pointerup', handlePointerUp)
+      panel.removeEventListener('pointercancel', handlePointerCancel)
+      panel.removeEventListener('touchmove', handleTouchMove)
+    }
+  }, [enabled, panelRef, anchor, isHorizontal, getMovement, applyTransform, resetStyles, animateSnapBack, animateDismiss])
+}

package/src/components/Field/Field.meta.ts

@@ -7,9 +7,7 @@ export const meta: ComponentMeta = {
     'Any form input that needs a label and/or error message',
     'Standalone labeled input (without Form) with manual error display',
   ],
-  whenNotToUse: [
-    'Bare input without label — use Input directly (rare)',
-  ],
+  whenNotToUse: ['Bare input without label — use Input directly (rare)'],
   anatomy: {
     required: ['Root'],
     optional: ['Label', 'Description', 'Error'],

package/src/components/Fieldset/Fieldset.meta.ts

@@ -7,9 +7,7 @@ export const meta: ComponentMeta = {
     'Grouping related fields within a form (e.g., "Personal Info", "Address")',
     'Applying consistent vertical gap between form fields',
   ],
-  whenNotToUse: [
-    'Non-form content grouping — use Stack or Card',
-  ],
+  whenNotToUse: ['Non-form content grouping — use Stack or Card'],
   anatomy: {
     required: ['Root'],
     optional: ['Legend'],

package/src/components/Form/Form.meta.ts

@@ -3,10 +3,7 @@ import type {ComponentMeta} from '../component-meta'
 export const meta: ComponentMeta = {
   description:
     'Form wrapper with Effect Schema validation and react-hook-form integration. Provides FormContext to child Field components.',
-  whenToUse: [
-    'Any form that needs validation',
-    'Multi-field forms with submit handling',
-  ],
+  whenToUse: ['Any form that needs validation', 'Multi-field forms with submit handling'],
   whenNotToUse: [
     'Single standalone field without validation — use Field.Root directly',
     'Non-form interactive UIs — use individual components',

package/src/components/Grid/Grid.meta.ts

@@ -11,9 +11,7 @@ export const meta: ComponentMeta = {
     'Single-column vertical layout — use Stack',
     'Simple horizontal row — use Inline or Cluster',
   ],
-  relatedTo: [
-    {component: 'Stack', relationship: 'Single-column vertical layout'},
-  ],
+  relatedTo: [{component: 'Stack', relationship: 'Single-column vertical layout'}],
   example: `// Responsive: columns auto-fit based on min width
 <Grid minColumnWidth="280px" gap="md">
   <Card>A</Card>

package/src/components/Inline/Inline.meta.ts

@@ -1,8 +1,7 @@
 import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
-  description:
-    'Horizontal flex layout with NO wrapping. Items stay on one line and may overflow.',
+  description: 'Horizontal flex layout with NO wrapping. Items stay on one line and may overflow.',
   whenToUse: [
     'Toolbar or button group that must stay on one row',
     'Horizontal alignment of a known, small number of items',

package/src/components/Input/Input.meta.ts

@@ -3,13 +3,8 @@ import type {ComponentMeta} from '../component-meta'
 export const meta: ComponentMeta = {
   description:
     'Text input with automatic Field/Form integration. Variant auto-switches to error when inside an invalid Field.',
-  whenToUse: [
-    'Single-line text entry (text, email, password, url, tel, number, search)',
-  ],
-  whenNotToUse: [
-    'Multi-line text — use Textarea',
-    'Picking from predefined options — use Select',
-  ],
+  whenToUse: ['Single-line text entry (text, email, password, url, tel, number, search)'],
+  whenNotToUse: ['Multi-line text — use Textarea', 'Picking from predefined options — use Select'],
   relatedTo: [
     {component: 'Field', relationship: 'Wrap in Field.Root for label + error'},
     {component: 'InputGroup', relationship: 'Wrap in InputGroup.Root for prefix/suffix addons'},

package/src/components/LinkButton/LinkButton.meta.ts

@@ -11,9 +11,7 @@ export const meta: ComponentMeta = {
     'Triggering in-page actions — use Button',
     'Plain text links — use a styled <a> tag',
   ],
-  relatedTo: [
-    {component: 'Button', relationship: 'Button for actions; LinkButton for navigation'},
-  ],
+  relatedTo: [{component: 'Button', relationship: 'Button for actions; LinkButton for navigation'}],
   example: `<LinkButton href="/signup" variant="primary">
   Get started
 </LinkButton>

package/src/components/Menu/Menu.meta.ts

@@ -8,10 +8,7 @@ export const meta: ComponentMeta = {
     'Navigation links in a dropdown',
     'Overflow menu for toolbar actions',
   ],
-  whenNotToUse: [
-    'Picking a value — use Select',
-    'Primary navigation — use SideNav or Tabs',
-  ],
+  whenNotToUse: ['Picking a value — use Select', 'Primary navigation — use SideNav or Tabs'],
   anatomy: {
     required: ['Root', 'Trigger', 'Popup', 'Item'],
     optional: ['LinkItem'],

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>
+  ),
+}

package/src/components/Panel/Panel.tsx

@@ -0,0 +1,56 @@
+import type {ReactNode} from 'react'
+import {html} from 'react-strict-dom'
+import {styles} from './styles.css'
+
+// --- Root ---
+
+interface RootProps {
+  children: ReactNode
+  /** Adds an outer border. Default: false */
+  bordered?: boolean
+}
+
+function Root({children, bordered = false}: RootProps) {
+  return (
+    <html.div style={[styles.root, bordered && styles.bordered]}>
+      {children}
+    </html.div>
+  )
+}
+
+// --- Header ---
+
+function Header({children}: {children: ReactNode}) {
+  return <html.div style={styles.header}>{children}</html.div>
+}
+
+// --- Body ---
+
+interface BodyProps {
+  children: ReactNode
+  /** Adds inner padding. Default: true */
+  padded?: boolean
+}
+
+function Body({children, padded = true}: BodyProps) {
+  return (
+    <html.div style={[styles.body, padded && styles.bodyPadded]}>
+      {children}
+    </html.div>
+  )
+}
+
+// --- Footer ---
+
+function Footer({children}: {children: ReactNode}) {
+  return <html.div style={styles.footer}>{children}</html.div>
+}
+
+// --- Export ---
+
+export const Panel = {
+  Root,
+  Header,
+  Body,
+  Footer,
+}

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

@@ -0,0 +1,55 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+
+export const styles = css.create({
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    backgroundColor: colors.bgCard,
+  },
+  bordered: {
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+  },
+
+  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,
+  },
+
+  body: {
+    flex: 1,
+    overflowY: 'auto',
+  },
+  bodyPadded: {
+    paddingTop: spacing.lg,
+    paddingLeft: spacing.lg,
+    paddingRight: spacing.lg,
+    paddingBottom: spacing.lg,
+  },
+
+  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,
+  },
+})

package/src/components/SideNav/SideNav.meta.ts

@@ -3,10 +3,7 @@ import type {ComponentMeta} from '../component-meta'
 export const meta: ComponentMeta = {
   description:
     'Vertical side navigation with collapsible groups. Supports controlled and uncontrolled active item. Compound component — Root is required.',
-  whenToUse: [
-    'App-level sidebar navigation',
-    'Settings navigation with grouped sections',
-  ],
+  whenToUse: ['App-level sidebar navigation', 'Settings navigation with grouped sections'],
   whenNotToUse: [
     'In-page content switching — use Tabs',
     'Top-level horizontal nav — use Inline with LinkButton',