@duro-app/ui 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -52,7 +52,7 @@
     }
   },
   "dependencies": {
-    "@duro-app/tokens": "^0.19.0"
+    "@duro-app/tokens": "^0.20.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/DetailPanel/DetailPanel.meta.ts

@@ -0,0 +1,41 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Non-modal side panel for right-side inspection. Click a table row to show details, click another to update in place. Built on Panel internally. In-flow (flex child), not fixed/modal — content behind remains interactive.',
+  whenToUse: [
+    'Table row detail inspection (click row → see details)',
+    'Side-by-side master-detail layouts',
+    'Non-modal content inspection that keeps context visible',
+  ],
+  whenNotToUse: [
+    'Modal overlays — use Dialog or Drawer',
+    'Mobile slide-in panels — compose with Drawer',
+    'Left-side navigation — use SideNav',
+  ],
+  anatomy: {
+    required: ['Root', 'Content', 'Header', 'Body'],
+    optional: ['Title', 'Footer', 'Close'],
+  },
+  relatedTo: [
+    {component: 'Drawer', relationship: 'Drawer is modal with backdrop; DetailPanel is non-modal and in-flow'},
+    {component: 'Panel', relationship: 'DetailPanel uses Panel structure internally'},
+    {component: 'Table', relationship: 'Common pattern: Table + DetailPanel for master-detail'},
+  ],
+  example: `<html.div style={layoutStyles.container}>
+  <html.div style={layoutStyles.main}>
+    <Table.Root columns={3}>...</Table.Root>
+  </html.div>
+  <DetailPanel.Root open={selectedId != null} onOpenChange={handleOpenChange}>
+    <DetailPanel.Content size="sm" label="User details">
+      <DetailPanel.Header>
+        <DetailPanel.Title>{user.name}</DetailPanel.Title>
+        <DetailPanel.Close />
+      </DetailPanel.Header>
+      <DetailPanel.Body>
+        <Stack gap="md">...</Stack>
+      </DetailPanel.Body>
+    </DetailPanel.Content>
+  </DetailPanel.Root>
+</html.div>`,
+}

package/src/components/DetailPanel/DetailPanel.stories.tsx

@@ -0,0 +1,270 @@
+import type {Meta, StoryObj} from '@storybook/react'
+import {useState} from 'react'
+import {css, html} from 'react-strict-dom'
+import {DetailPanel} from './DetailPanel'
+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 {Badge} from '../Badge/Badge'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+
+const meta: Meta = {
+  title: 'Components/DetailPanel',
+}
+
+export default meta
+type Story = StoryObj
+
+const layoutStyles = css.create({
+  container: {
+    display: 'flex',
+    height: 400,
+    borderWidth: 1,
+    borderStyle: 'solid',
+    borderColor: colors.border,
+  },
+  main: {
+    flex: 1,
+    padding: spacing.lg,
+    overflowY: 'auto',
+  },
+})
+
+// --- Default ---
+
+function DefaultDemo() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <html.div style={layoutStyles.container}>
+      <html.div style={layoutStyles.main}>
+        <Stack gap="md">
+          <Heading level={3}>Main Content</Heading>
+          <Text>Click the button to open the detail panel.</Text>
+          <Button onClick={() => setOpen(true)}>Open Detail Panel</Button>
+        </Stack>
+      </html.div>
+
+      <DetailPanel.Root open={open} onOpenChange={setOpen}>
+        <DetailPanel.Content label="Details">
+          <DetailPanel.Header>
+            <DetailPanel.Title>Details</DetailPanel.Title>
+            <DetailPanel.Close />
+          </DetailPanel.Header>
+          <DetailPanel.Body>
+            <Text>
+              This is a non-modal detail panel. The content behind it
+              remains interactive — you can still click, scroll, and
+              interact with the main area.
+            </Text>
+          </DetailPanel.Body>
+          <DetailPanel.Footer>
+            <Button variant="secondary" onClick={() => setOpen(false)}>
+              Done
+            </Button>
+          </DetailPanel.Footer>
+        </DetailPanel.Content>
+      </DetailPanel.Root>
+    </html.div>
+  )
+}
+
+export const Default: Story = {
+  render: () => <DefaultDemo />,
+}
+
+// --- Table Selection ---
+
+interface User {
+  id: number
+  name: string
+  role: string
+  status: string
+  email: string
+}
+
+const users: User[] = [
+  {id: 1, name: 'Alice Johnson', role: 'Admin', status: 'Active', email: 'alice@example.com'},
+  {id: 2, name: 'Bob Smith', role: 'Editor', status: 'Inactive', email: 'bob@example.com'},
+  {id: 3, name: 'Carol Davis', role: 'Viewer', status: 'Active', email: 'carol@example.com'},
+  {id: 4, name: 'Dan Wilson', role: 'Editor', status: 'Active', email: 'dan@example.com'},
+]
+
+const tableStyles = css.create({
+  row: {
+    display: 'flex',
+    gap: spacing.lg,
+    paddingTop: spacing.sm,
+    paddingBottom: spacing.sm,
+    paddingLeft: spacing.md,
+    paddingRight: spacing.md,
+    cursor: 'pointer',
+    backgroundColor: {
+      default: 'transparent',
+      ':hover': colors.bgCardHover,
+    },
+  },
+  rowSelected: {
+    backgroundColor: colors.bgCardHover,
+  },
+  headerRow: {
+    display: 'flex',
+    gap: spacing.lg,
+    paddingTop: spacing.sm,
+    paddingBottom: spacing.sm,
+    paddingLeft: spacing.md,
+    paddingRight: spacing.md,
+    borderBottomWidth: 1,
+    borderBottomStyle: 'solid',
+    borderBottomColor: colors.border,
+  },
+  cellText: {
+    flex: 1,
+  },
+})
+
+function TableSelectionDemo() {
+  const [selectedId, setSelectedId] = useState<number | null>(null)
+  const selectedUser = users.find((u) => u.id === selectedId)
+
+  return (
+    <html.div style={layoutStyles.container}>
+      <html.div style={layoutStyles.main}>
+        <Stack gap="md">
+          <Heading level={3}>Users</Heading>
+          <html.div>
+            <html.div style={tableStyles.headerRow}>
+              <html.span style={tableStyles.cellText}><Text variant="label">Name</Text></html.span>
+              <html.span style={tableStyles.cellText}><Text variant="label">Role</Text></html.span>
+              <html.span style={tableStyles.cellText}><Text variant="label">Status</Text></html.span>
+            </html.div>
+            {users.map((user) => (
+              <html.div
+                key={user.id}
+                style={[tableStyles.row, selectedId === user.id && tableStyles.rowSelected]}
+                onClick={() => setSelectedId(selectedId === user.id ? null : user.id)}
+              >
+                <html.span style={tableStyles.cellText}><Text>{user.name}</Text></html.span>
+                <html.span style={tableStyles.cellText}><Text>{user.role}</Text></html.span>
+                <html.span style={tableStyles.cellText}><Text>{user.status}</Text></html.span>
+              </html.div>
+            ))}
+          </html.div>
+        </Stack>
+      </html.div>
+
+      <DetailPanel.Root
+        open={selectedId != null}
+        onOpenChange={(open) => {
+          if (!open) setSelectedId(null)
+        }}
+      >
+        <DetailPanel.Content size="sm" label="User details">
+          <DetailPanel.Header>
+            <DetailPanel.Title>{selectedUser?.name}</DetailPanel.Title>
+            <DetailPanel.Close />
+          </DetailPanel.Header>
+          <DetailPanel.Body>
+            {selectedUser && (
+              <Stack gap="md">
+                <Stack gap="xs">
+                  <Text variant="label">Email</Text>
+                  <Text variant="bodySm">{selectedUser.email}</Text>
+                </Stack>
+                <Stack gap="xs">
+                  <Text variant="label">Role</Text>
+                  <Text variant="bodySm">{selectedUser.role}</Text>
+                </Stack>
+                <Stack gap="xs">
+                  <Text variant="label">Status</Text>
+                  <Inline gap="sm">
+                    <Badge variant={selectedUser.status === 'Active' ? 'success' : 'default'}>
+                      {selectedUser.status}
+                    </Badge>
+                  </Inline>
+                </Stack>
+              </Stack>
+            )}
+          </DetailPanel.Body>
+          <DetailPanel.Footer>
+            <Button variant="danger">Revoke Access</Button>
+          </DetailPanel.Footer>
+        </DetailPanel.Content>
+      </DetailPanel.Root>
+    </html.div>
+  )
+}
+
+export const TableSelection: Story = {
+  render: () => <TableSelectionDemo />,
+}
+
+// --- Medium Size ---
+
+function MediumSizeDemo() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <html.div style={layoutStyles.container}>
+      <html.div style={layoutStyles.main}>
+        <Stack gap="md">
+          <Heading level={3}>Main Content</Heading>
+          <Text>This demo uses the medium (480px) panel width.</Text>
+          <Button onClick={() => setOpen(true)}>Open Medium Panel</Button>
+        </Stack>
+      </html.div>
+
+      <DetailPanel.Root open={open} onOpenChange={setOpen}>
+        <DetailPanel.Content size="md" label="Medium detail panel">
+          <DetailPanel.Header>
+            <DetailPanel.Title>Medium Panel</DetailPanel.Title>
+            <DetailPanel.Close />
+          </DetailPanel.Header>
+          <DetailPanel.Body>
+            <Text>
+              This panel is 480px wide, providing more room for complex
+              content like forms or detailed information.
+            </Text>
+          </DetailPanel.Body>
+        </DetailPanel.Content>
+      </DetailPanel.Root>
+    </html.div>
+  )
+}
+
+export const MediumSize: Story = {
+  render: () => <MediumSizeDemo />,
+}
+
+// --- Uncontrolled ---
+
+function UncontrolledDemo() {
+  return (
+    <html.div style={layoutStyles.container}>
+      <html.div style={layoutStyles.main}>
+        <Stack gap="md">
+          <Heading level={3}>Uncontrolled Mode</Heading>
+          <Text>This panel manages its own open state internally.</Text>
+          <DetailPanel.Root defaultOpen>
+            <DetailPanel.Content label="Uncontrolled panel">
+              <DetailPanel.Header>
+                <DetailPanel.Title>Uncontrolled</DetailPanel.Title>
+                <DetailPanel.Close />
+              </DetailPanel.Header>
+              <DetailPanel.Body>
+                <Text>This panel started open and manages its own state.</Text>
+              </DetailPanel.Body>
+            </DetailPanel.Content>
+          </DetailPanel.Root>
+        </Stack>
+      </html.div>
+    </html.div>
+  )
+}
+
+export const Uncontrolled: Story = {
+  render: () => <UncontrolledDemo />,
+}

package/src/components/DetailPanel/DetailPanel.tsx

@@ -0,0 +1,312 @@
+import {
+  type ReactNode,
+  type RefObject,
+  createContext,
+  useContext,
+  useState,
+  useEffect,
+  useCallback,
+  useId,
+  useRef,
+} from 'react'
+import {html} from 'react-strict-dom'
+import {styles} from './styles.css'
+
+// --- Types ---
+
+export type DetailPanelSize = 'sm' | 'md'
+
+// --- Context ---
+
+interface DetailPanelContextValue {
+  present: boolean
+  closing: boolean
+  requestOpen: () => void
+  requestClose: () => void
+  titleId: string
+  labelId: string | undefined
+  registerTitle: (id: string) => void
+  unregisterTitle: () => void
+  panelRef: RefObject<HTMLDivElement | null>
+}
+
+const DetailPanelContext = createContext<DetailPanelContextValue | null>(null)
+
+function useDetailPanel() {
+  const ctx = useContext(DetailPanelContext)
+  if (!ctx) throw new Error('DetailPanel compound components must be used within DetailPanel.Root')
+  return ctx
+}
+
+// --- Root ---
+
+interface RootProps {
+  children: ReactNode
+  /** Controlled open state */
+  open?: boolean
+  /** Default open state (uncontrolled) */
+  defaultOpen?: boolean
+  /** Called when open state changes */
+  onOpenChange?: (open: boolean) => void
+  /** Duration of the close animation in ms. Default: 220 */
+  closeAnimationDuration?: number
+}
+
+function Root({
+  children,
+  open: controlledOpen,
+  defaultOpen = false,
+  onOpenChange,
+  closeAnimationDuration = 220,
+}: RootProps) {
+  const isControlled = controlledOpen !== undefined
+  const [internalOpen, setInternalOpen] = useState(defaultOpen)
+  const [present, setPresent] = useState(defaultOpen)
+  const [closing, setClosing] = useState(false)
+  const closingTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const panelRef = useRef<HTMLDivElement>(null)
+  const previousFocusRef = useRef<Element | null>(null)
+
+  const titleId = useId()
+  const [labelId, setLabelId] = useState<string | undefined>(undefined)
+
+  const isOpen = isControlled ? controlledOpen : internalOpen
+
+  // Sync presence with open state
+  useEffect(() => {
+    if (isOpen && !present) {
+      setPresent(true)
+      setClosing(false)
+    } else if (!isOpen && present && !closing) {
+      setClosing(true)
+      closingTimerRef.current = setTimeout(() => {
+        setClosing(false)
+        setPresent(false)
+        closingTimerRef.current = null
+      }, closeAnimationDuration)
+    }
+  }, [isOpen, present, closing, closeAnimationDuration])
+
+  // Focus management: move focus on open, restore on close
+  useEffect(() => {
+    if (present && !closing) {
+      previousFocusRef.current = document.activeElement
+      panelRef.current?.focus()
+    }
+  }, [present]) // eslint-disable-line react-hooks/exhaustive-deps -- only on present change
+
+  useEffect(() => {
+    if (!present && previousFocusRef.current) {
+      const el = previousFocusRef.current as HTMLElement
+      if (typeof el.focus === 'function') {
+        el.focus()
+      }
+      previousFocusRef.current = null
+    }
+  }, [present])
+
+  // ESC handler
+  useEffect(() => {
+    if (!present || closing) return
+
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        e.stopPropagation()
+        requestClose()
+      }
+    }
+    document.addEventListener('keydown', onKeyDown)
+    return () => document.removeEventListener('keydown', onKeyDown)
+  }, [present, closing]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Clean up timer on unmount
+  useEffect(() => {
+    return () => {
+      if (closingTimerRef.current) clearTimeout(closingTimerRef.current)
+    }
+  }, [])
+
+  const requestOpen = useCallback(() => {
+    if (closingTimerRef.current) {
+      clearTimeout(closingTimerRef.current)
+      closingTimerRef.current = null
+      setClosing(false)
+    }
+    if (!isControlled) setInternalOpen(true)
+    onOpenChange?.(true)
+  }, [isControlled, onOpenChange])
+
+  const requestClose = useCallback(() => {
+    if (!isControlled) setInternalOpen(false)
+    onOpenChange?.(false)
+  }, [isControlled, onOpenChange])
+
+  const registerTitle = useCallback((id: string) => {
+    setLabelId(id)
+  }, [])
+
+  const unregisterTitle = useCallback(() => {
+    setLabelId(undefined)
+  }, [])
+
+  return (
+    <DetailPanelContext.Provider
+      value={{
+        present,
+        closing,
+        requestOpen,
+        requestClose,
+        titleId,
+        labelId,
+        registerTitle,
+        unregisterTitle,
+        panelRef,
+      }}
+    >
+      {children}
+    </DetailPanelContext.Provider>
+  )
+}
+
+// --- Content ---
+
+interface ContentProps {
+  children: ReactNode
+  /** Width of the panel. Default: 'sm' (360px) */
+  size?: DetailPanelSize
+  /** Accessible name for the complementary landmark */
+  label: string
+}
+
+const wrapperOpenMap = {
+  sm: styles.wrapperOpenSm,
+  md: styles.wrapperOpenMd,
+} as const
+
+const wrapperCloseMap = {
+  sm: styles.wrapperCloseSm,
+  md: styles.wrapperCloseMd,
+} as const
+
+function Content({children, size = 'sm', label}: ContentProps) {
+  const {present, closing, labelId, panelRef} = useDetailPanel()
+
+  if (!present) return null
+
+  return (
+    <html.div
+      style={[
+        styles.wrapper,
+        closing ? wrapperCloseMap[size] : wrapperOpenMap[size],
+      ]}
+    >
+      <html.div
+        ref={panelRef}
+        role="complementary"
+        aria-label={!labelId ? label : undefined}
+        aria-labelledby={labelId || undefined}
+        tabIndex={-1}
+        style={[
+          styles.content,
+          size === 'sm' ? styles.contentSm : styles.contentMd,
+          closing ? styles.slideOut : styles.slideIn,
+        ]}
+      >
+        {children}
+      </html.div>
+    </html.div>
+  )
+}
+
+// --- Header ---
+
+function Header({children}: {children: ReactNode}) {
+  return <html.div style={styles.header}>{children}</html.div>
+}
+
+// --- Title ---
+
+function Title({children}: {children: ReactNode}) {
+  const {titleId, registerTitle, unregisterTitle} = useDetailPanel()
+
+  useEffect(() => {
+    registerTitle(titleId)
+    return () => unregisterTitle()
+  }, [titleId, registerTitle, unregisterTitle])
+
+  return (
+    <html.h2 id={titleId} style={styles.title}>
+      {children}
+    </html.h2>
+  )
+}
+
+// --- 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>
+}
+
+// --- Close ---
+
+interface CloseProps {
+  children?: ReactNode
+  'aria-label'?: string
+}
+
+function Close({children, 'aria-label': ariaLabel = 'Close'}: CloseProps) {
+  const {requestClose} = useDetailPanel()
+
+  if (children) {
+    return (
+      <html.div onClick={requestClose} style={styles.inlineWrapper}>
+        {children}
+      </html.div>
+    )
+  }
+
+  return (
+    <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"
+          stroke="currentColor"
+          strokeWidth={1.5}
+          strokeLinecap="round"
+        />
+      </svg>
+    </html.button>
+  )
+}
+
+// --- Export ---
+
+export const DetailPanel = {
+  Root,
+  Content,
+  Header,
+  Title,
+  Body,
+  Footer,
+  Close,
+}