@duro-app/ui 5.1.0 → 5.2.0

package/dist/index.native.d.ts

@@ -28,5 +28,6 @@ export { Stack, type SpacingKey } from './components/Stack/Stack';
 export { Inline } from './components/Inline/Inline';
 export { Cluster } from './components/Cluster/Cluster';
 export { Grid } from './components/Grid/Grid';
+export type { GridTrack } from './shared/length';
 export { ThemeProvider, usePortalMount, type ThemeName, } from './components/ThemeProvider/ThemeProvider';
 //# sourceMappingURL=index.native.d.ts.map

package/dist/index.native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.native.d.ts","sourceRoot":"","sources":["../src/index.native.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAC,KAAK,EAAE,KAAK,YAAY,EAAE,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAA;AACjF,OAAO,EAAC,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAC,MAAM,4BAA4B,CAAA;AACtF,OAAO,EAAC,IAAI,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAC,MAAM,wBAAwB,CAAA;AAC5E,OAAO,EAAC,QAAQ,EAAC,MAAM,gCAAgC,CAAA;AACvD,OAAO,EAAC,OAAO,EAAE,KAAK,cAAc,EAAC,MAAM,8BAA8B,CAAA;AACzE,OAAO,EAAC,KAAK,EAAE,KAAK,YAAY,EAAC,MAAM,0BAA0B,CAAA;AACjE,OAAO,EAAC,MAAM,EAAC,MAAM,4BAA4B,CAAA;AACjD,OAAO,EAAC,IAAI,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAC,MAAM,wBAAwB,CAAA;AAC7E,OAAO,EAAC,QAAQ,EAAE,KAAK,eAAe,EAAC,MAAM,gCAAgC,CAAA;AAG7E,OAAO,EAAC,KAAK,EAAC,MAAM,0BAA0B,CAAA;AAC9C,OAAO,EAAC,UAAU,EAAC,MAAM,oCAAoC,CAAA;AAG7D,OAAO,EAAC,KAAK,EAAE,KAAK,UAAU,EAAC,MAAM,0BAA0B,CAAA;AAC/D,OAAO,EAAC,MAAM,EAAC,MAAM,4BAA4B,CAAA;AACjD,OAAO,EAAC,OAAO,EAAC,MAAM,8BAA8B,CAAA;AACpD,OAAO,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAA;AAI3C,OAAO,EACL,aAAa,EACb,cAAc,EACd,KAAK,SAAS,GACf,MAAM,0CAA0C,CAAA"}
+{"version":3,"file":"index.native.d.ts","sourceRoot":"","sources":["../src/index.native.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAC,KAAK,EAAE,KAAK,YAAY,EAAE,KAAK,SAAS,EAAC,MAAM,0BAA0B,CAAA;AACjF,OAAO,EAAC,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAC,MAAM,4BAA4B,CAAA;AACtF,OAAO,EAAC,IAAI,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAC,MAAM,wBAAwB,CAAA;AAC5E,OAAO,EAAC,QAAQ,EAAC,MAAM,gCAAgC,CAAA;AACvD,OAAO,EAAC,OAAO,EAAE,KAAK,cAAc,EAAC,MAAM,8BAA8B,CAAA;AACzE,OAAO,EAAC,KAAK,EAAE,KAAK,YAAY,EAAC,MAAM,0BAA0B,CAAA;AACjE,OAAO,EAAC,MAAM,EAAC,MAAM,4BAA4B,CAAA;AACjD,OAAO,EAAC,IAAI,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAC,MAAM,wBAAwB,CAAA;AAC7E,OAAO,EAAC,QAAQ,EAAE,KAAK,eAAe,EAAC,MAAM,gCAAgC,CAAA;AAG7E,OAAO,EAAC,KAAK,EAAC,MAAM,0BAA0B,CAAA;AAC9C,OAAO,EAAC,UAAU,EAAC,MAAM,oCAAoC,CAAA;AAG7D,OAAO,EAAC,KAAK,EAAE,KAAK,UAAU,EAAC,MAAM,0BAA0B,CAAA;AAC/D,OAAO,EAAC,MAAM,EAAC,MAAM,4BAA4B,CAAA;AACjD,OAAO,EAAC,OAAO,EAAC,MAAM,8BAA8B,CAAA;AACpD,OAAO,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAA;AAC3C,YAAY,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAA;AAI9C,OAAO,EACL,aAAa,EACb,cAAc,EACd,KAAK,SAAS,GACf,MAAM,0CAA0C,CAAA"}

package/dist/styles/visually-hidden.css.d.ts

@@ -6,5 +6,11 @@ export declare const visuallyHidden: Readonly<{
         readonly height: css.StyleXClassNameFor<"height", 1>;
         readonly overflow: css.StyleXClassNameFor<"overflow", "hidden">;
     }>;
+    readonly text: Readonly<{
+        readonly clip: css.StyleXClassNameFor<"clip", "rect(0, 0, 0, 0)">;
+        readonly whiteSpace: css.StyleXClassNameFor<"whiteSpace", "nowrap">;
+        readonly borderWidth: css.StyleXClassNameFor<"borderWidth", 0>;
+        readonly padding: css.StyleXClassNameFor<"padding", 0>;
+    }>;
 }>;
 //# sourceMappingURL=visually-hidden.css.d.ts.map

package/dist/styles/visually-hidden.css.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"visually-hidden.css.d.ts","sourceRoot":"","sources":["../../src/styles/visually-hidden.css.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,GAAG,EAAC,MAAM,kBAAkB,CAAA;AAQpC,eAAO,MAAM,cAAc;;;;;;;EAOzB,CAAA"}
+{"version":3,"file":"visually-hidden.css.d.ts","sourceRoot":"","sources":["../../src/styles/visually-hidden.css.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,GAAG,EAAC,MAAM,kBAAkB,CAAA;AAQpC,eAAO,MAAM,cAAc;;;;;;;;;;;;;EAezB,CAAA"}

package/dist/table.js

@@ -1,4 +1,4 @@
-import { M as F, a as xt, R as rt, H as kt, c as pt, B as bt, d as ft, C as mt, b as ht, e as yt, r as St, f as Tt } from "./Table-BkrgH0jb.js";
+import { M as F, g as xt, R as rt, H as kt, h as pt, B as bt, j as ft, C as mt, e as ht, k as yt, r as St, l as Tt } from "./Table-C70zdSkM.js";
 import { jsx as u, jsxs as q } from "react/jsx-runtime";
 import { c as H, m as p, d as b } from "./compiler-runtime-B2IcI8_O.js";
 import { flexRender as E, useReactTable as it, getPaginationRowModel as Ct, getFilteredRowModel as vt, getSortedRowModel as at, getCoreRowModel as st } from "@tanstack/react-table";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -66,7 +66,7 @@
   },
   "dependencies": {
     "@tanstack/react-virtual": "^3.14.6",
-    "@duro-app/tokens": "^5.1.0"
+    "@duro-app/tokens": "^5.2.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/Button/Button.stories.tsx

@@ -1,5 +1,6 @@
 import type {Meta, StoryObj} from '@storybook/react'
 import {expect, fn} from 'storybook/test'
+import {useRef, useState} from 'react'
 import {css, html} from 'react-strict-dom'
 import {Button} from './Button'
 import {spacing} from '@duro-app/tokens/tokens/spacing.css'
@@ -129,3 +130,43 @@ export const AllVariants: Story = {
     await expect(disabledButtons.length).toBe(3)
   },
 }
+
+// A disclosure: aria-expanded / aria-controls pass through, and the ref
+// reaches the <button> (to return focus to it).
+function DisclosureDemo() {
+  const [open, setOpen] = useState(false)
+  const ref = useRef<HTMLButtonElement>(null)
+  return (
+    <html.div>
+      <Button
+        ref={ref}
+        variant="secondary"
+        aria-expanded={open}
+        aria-controls="filters-panel"
+        onClick={() => setOpen(!open)}
+      >
+        Filters
+      </Button>
+      {open && (
+        <html.div id="filters-panel" role="region" aria-label="Filters panel">
+          <Button variant="link" onClick={() => ref.current?.focus()}>
+            Back to Filters
+          </Button>
+        </html.div>
+      )}
+    </html.div>
+  )
+}
+
+export const RefAndDisclosure: Story = {
+  render: () => <DisclosureDemo />,
+  play: async ({canvas, userEvent}) => {
+    const toggle = canvas.getByRole('button', {name: 'Filters'})
+    await expect(toggle).toHaveAttribute('aria-expanded', 'false')
+    await userEvent.click(toggle)
+    await expect(toggle).toHaveAttribute('aria-expanded', 'true')
+    await expect(toggle).toHaveAttribute('aria-controls', 'filters-panel')
+    await userEvent.click(canvas.getByRole('button', {name: 'Back to Filters'}))
+    await expect(toggle).toHaveFocus()
+  },
+}

package/src/components/Button/Button.tsx

@@ -1,4 +1,4 @@
-import type {ReactNode} from 'react'
+import type {ReactNode, Ref} from 'react'
 import {html} from 'react-strict-dom'
 import {isNative} from '../../platform'
 import {styles} from './styles.css'
@@ -15,6 +15,15 @@ interface ButtonProps {
   onClick?: () => void
   /** Accessible name override — e.g. for buttons whose visible text isn't unique. */
   'aria-label'?: string
+  /** For a button that shows or hides another element (a disclosure, a panel). */
+  'aria-expanded'?: boolean
+  /** Id of the element this button controls. */
+  'aria-controls'?: string
+  /**
+   * The underlying <button>, e.g. to anchor a Popover or return focus to it.
+   * Web only: on native the ref is not attached.
+   */
+  ref?: Ref<HTMLButtonElement>
   children: ReactNode
 }
 
@@ -31,14 +40,20 @@ export function Button({
   type = 'button',
   onClick,
   'aria-label': ariaLabel,
+  'aria-expanded': ariaExpanded,
+  'aria-controls': ariaControls,
+  ref,
   children,
 }: ButtonProps) {
   return (
     <html.button
+      ref={isNative ? undefined : ref}
       type={type}
       disabled={disabled}
       onClick={onClick}
       aria-label={ariaLabel}
+      aria-expanded={ariaExpanded}
+      aria-controls={ariaControls}
       style={[
         styles.base,
         isNative && styles.nativeFlex,

package/src/components/Combobox/Combobox.tsx

@@ -1,11 +1,9 @@
-import {type ReactNode, useRef, useId, useEffect, useLayoutEffect, useState} from 'react'
-import {createPortal} from 'react-dom'
+import {type ReactNode, useCallback, useRef, useId, useEffect, useState} from 'react'
 import {html} from 'react-strict-dom'
 import {styles} from './styles.css'
 import {ComboboxContext, useCombobox} from './ComboboxContext'
 import {useComboboxRoot} from './useComboboxRoot'
-import {usePortalMount} from '../ThemeProvider/ThemeProvider'
-import {usePopoverLayer} from '../Popover/PopoverLayerContext'
+import {Listbox, getAnchorProps} from '../Listbox/Listbox'
 
 // --- Root ---
 interface RootProps {
@@ -54,6 +52,7 @@ function Input({placeholder, children}: {placeholder?: string; children?: ReactN
     useCombobox()
   const localRef = useRef<HTMLInputElement>(null)
   const [focused, setFocused] = useState(false)
+  const anchor = getAnchorProps({id: listboxId, open, highlightedId})
 
   useEffect(() => {
     inputRef.current = localRef.current
@@ -67,10 +66,10 @@ function Input({placeholder, children}: {placeholder?: string; children?: ReactN
         role={'combobox' as 'listbox'}
         value={inputValue}
         placeholder={placeholder}
-        aria-expanded={open}
+        aria-expanded={anchor['aria-expanded']}
         aria-haspopup="listbox"
-        aria-controls={open ? listboxId : undefined}
-        aria-activedescendant={highlightedId ?? undefined}
+        aria-controls={anchor['aria-controls']}
+        aria-activedescendant={anchor['aria-activedescendant']}
         aria-autocomplete={'list' as 'none'}
         autoComplete="off"
         style={styles.input}
@@ -132,58 +131,27 @@ function Trigger({children}: {children?: ReactNode}) {
 }
 
 // --- Popup ---
-// Rendered into the ThemeProvider portal mount and positioned with viewport
-// coordinates so it escapes ancestor `overflow: hidden` / `transform`
-// containing blocks (notably Dialog and Drawer).
+// A Listbox placed under the input, as wide as the field: rendered into the
+// ThemeProvider portal mount so it escapes ancestor `overflow: hidden` /
+// `transform` containing blocks (notably Dialog and Drawer).
 function Popup({children}: {children: ReactNode}) {
-  const {open, listboxId, rootRef} = useCombobox()
-  const mount = usePortalMount()
-  const listboxRef = useRef<HTMLDivElement>(null)
-  const [coords, setCoords] = useState<{top: number; left: number; width: number} | null>(null)
+  const {open, listboxId, rootRef, highlightedId, setHighlightedId, setValue} = useCombobox()
+  const anchor = useCallback(() => rootRef.current?.getBoundingClientRect(), [rootRef])
 
-  // Measure the root each time the popup opens, and re-measure on scroll/resize
-  // so the dropdown follows the input. Capture-phase scroll listener catches
-  // scroll on any ancestor (e.g. Dialog body).
-  useLayoutEffect(() => {
-    if (!open) {
-      setCoords(null)
-      return
-    }
-    const update = () => {
-      const el = rootRef.current
-      if (!el) return
-      const rect = el.getBoundingClientRect()
-      // Position immediately below the input with a small gap. `xs` token = 4px.
-      setCoords({top: rect.bottom + 4, left: rect.left, width: rect.width})
-    }
-    update()
-    window.addEventListener('resize', update)
-    window.addEventListener('scroll', update, true)
-    return () => {
-      window.removeEventListener('resize', update)
-      window.removeEventListener('scroll', update, true)
-    }
-  }, [open, rootRef])
-
-  usePopoverLayer(listboxRef, {active: open && coords !== null})
-
-  if (!open || !coords) return null
-
-  const node = (
-    <html.div
-      ref={listboxRef}
+  return (
+    <Listbox.Root
       id={listboxId}
-      role="listbox"
-      style={[styles.popup, styles.popupPosition(coords.top, coords.left, coords.width)]}
+      open={open}
+      anchor={anchor}
+      matchAnchorWidth
+      highlightedId={highlightedId}
+      onHighlight={setHighlightedId}
+      onSelect={setValue}
+      maxHeight="listMaxHSm"
     >
       {children}
-    </html.div>
+    </Listbox.Root>
   )
-
-  // SSR / pre-mount fallback: render inline (will be invisible under
-  // overflow:hidden parents but won't crash). Once the mount is available,
-  // portal into it.
-  return mount ? createPortal(node, mount) : node
 }
 
 // --- Item ---
@@ -193,20 +161,10 @@ interface ItemProps {
 }
 
 function Item({value: itemValue, children}: ItemProps) {
-  const {
-    value: selectedValue,
-    setValue,
-    inputValue,
-    labels,
-    registerLabel,
-    highlightedId,
-    setHighlightedId,
-    registerItem,
-  } = useCombobox()
+  const {value: selectedValue, inputValue, labels, registerLabel, registerItem} = useCombobox()
   const id = useId()
   const ref = useRef<HTMLDivElement>(null)
   const isSelected = selectedValue === itemValue
-  const isHighlighted = highlightedId === id
 
   // Filter: check if this item matches the input
   const label = labels[itemValue] ?? itemValue
@@ -229,21 +187,9 @@ function Item({value: itemValue, children}: ItemProps) {
   if (!isVisible) return null
 
   return (
-    <html.div
-      ref={ref}
-      id={id}
-      role="option"
-      aria-selected={isSelected}
-      onClick={() => setValue(itemValue)}
-      onPointerEnter={() => setHighlightedId(id)}
-      style={[
-        styles.item,
-        isSelected && styles.itemSelected,
-        isHighlighted && styles.itemHighlighted,
-      ]}
-    >
+    <Listbox.Option ref={ref} id={id} value={itemValue} selected={isSelected}>
       {children}
-    </html.div>
+    </Listbox.Option>
   )
 }
 
@@ -266,7 +212,7 @@ function Empty({children}: {children: ReactNode}) {
 
   if (hasVisibleItems) return null
 
-  return <html.div style={styles.empty}>{children}</html.div>
+  return <Listbox.Empty>{children}</Listbox.Empty>
 }
 
 export const Combobox = {

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

@@ -2,9 +2,7 @@ import {css} from 'react-strict-dom'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
 import {typography} from '@duro-app/tokens/tokens/typography.css'
-import {shadows} from '@duro-app/tokens/tokens/shadows.css'
 import {duration} from '@duro-app/tokens/tokens/motion.css'
-import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 import {borders} from '@duro-app/tokens/tokens/borders.css'
 
 export const styles = css.create({
@@ -57,76 +55,4 @@ export const styles = css.create({
     color: colors.textMuted,
     cursor: 'pointer',
   },
-  backdrop: {
-    position: 'fixed',
-    top: 0,
-    left: 0,
-    right: 0,
-    bottom: 0,
-    // Above Dialog/Drawer (1000/1001): they portal into the same mount, so a
-    // popup opened from inside a dialog must out-rank the dialog itself.
-    zIndex: 1049,
-  },
-  popup: {
-    // Position is `fixed` and the top/left/width are applied inline by Popup
-    // (computed from the root's bounding rect) so the dropdown can escape any
-    // ancestor with `overflow: hidden` or `transform` (e.g. inside a Dialog).
-    position: 'fixed',
-    backgroundColor: colors.bgCard,
-    borderWidth: borders.hairline,
-    borderStyle: 'solid',
-    borderColor: colors.border,
-    borderRadius: radii.sm,
-    boxShadow: shadows.md,
-    paddingTop: spacing.xs,
-    paddingBottom: spacing.xs,
-    maxHeight: sizes.listMaxHSm,
-    overflowY: 'auto',
-    zIndex: 1050,
-    // Re-enable pointer events: the portal mount is pointer-events: none so
-    // clicks fall through except on the popup itself.
-    pointerEvents: 'auto',
-  },
-  item: {
-    display: 'flex',
-    alignItems: 'center',
-    paddingTop: spacing.sm,
-    paddingBottom: spacing.sm,
-    paddingLeft: spacing.md,
-    paddingRight: spacing.md,
-    fontSize: typography.fontSizeSm,
-    fontFamily: typography.fontFamily,
-    color: colors.text,
-    cursor: 'pointer',
-    backgroundColor: 'transparent',
-    transitionProperty: 'background-color',
-    transitionDuration: duration.fast,
-  },
-  itemSelected: {
-    color: colors.accent,
-    fontWeight: typography.fontWeightMedium,
-  },
-  itemHighlighted: {
-    backgroundColor: colors.bgCardHover,
-  },
-  itemHidden: {
-    display: 'none',
-  },
-  empty: {
-    paddingTop: spacing.sm,
-    paddingBottom: spacing.sm,
-    paddingLeft: spacing.md,
-    paddingRight: spacing.md,
-    fontSize: typography.fontSizeSm,
-    color: colors.textMuted,
-  },
-  hidden: {
-    display: 'none',
-  },
-  // Dynamic position — applied at runtime from the input's bounding rect.
-  popupPosition: (top: number, left: number, width: number) => ({
-    top,
-    left,
-    width,
-  }),
 })

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

@@ -2,7 +2,7 @@ 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.',
+    'Modal dialog with backdrop overlay. Centered on screen with scale+fade animation. Moves focus in on open (initialFocus, else the first focusable element, else the dialog) and back on close; dismisses on backdrop click (dismissable) or Escape (closeOnEscape, independent of dismissable). 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',

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

@@ -1,7 +1,7 @@
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect, within, userEvent} from 'storybook/test'
+import {expect, screen, waitFor, within, userEvent} from 'storybook/test'
 import {css, html} from 'react-strict-dom'
-import {useState} from 'react'
+import {useRef, useState} from 'react'
 import {Dialog} from './Dialog'
 import {Button} from '../Button/Button'
 import {Text} from '../Text/Text'
@@ -260,7 +260,7 @@ export const DangerConfirmation: Story = {
 
 export const NonDismissable: Story = {
   render: () => (
-    <Dialog.Root dismissable={false}>
+    <Dialog.Root dismissable={false} closeOnEscape={false}>
       <Dialog.Trigger>
         <Button>Open non-dismissable</Button>
       </Dialog.Trigger>
@@ -454,3 +454,109 @@ export const BackdropClickDismisses: Story = {
     await expect(await canvas.findByText('Last action: Dismissed')).toBeInTheDocument()
   },
 }
+
+// --- Focus and Escape (5.2) ---
+
+// dismissable only governs the backdrop: Escape still closes.
+export const EscapeClosesNonDismissable: Story = {
+  render: () => (
+    <Dialog.Root dismissable={false}>
+      <Dialog.Trigger>
+        <Button>Open terms</Button>
+      </Dialog.Trigger>
+      <Dialog.Portal size="sm">
+        <Dialog.Header>
+          <Dialog.Title>Terms</Dialog.Title>
+        </Dialog.Header>
+        <Dialog.Body>
+          <Text>Read before continuing.</Text>
+        </Dialog.Body>
+      </Dialog.Portal>
+    </Dialog.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    const opener = canvas.getByRole('button', {name: 'Open terms'})
+    await userEvent.click(opener)
+    const dialog = await screen.findByRole('dialog', {name: 'Terms'})
+    // Nothing focusable inside: the dialog itself takes focus.
+    await waitFor(() => expect(dialog).toHaveFocus())
+    await userEvent.keyboard('{Escape}')
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument())
+    await waitFor(() => expect(opener).toHaveFocus())
+  },
+}
+
+function InitialFocusDemo() {
+  const nameRef = useRef<HTMLInputElement>(null)
+  return (
+    <Dialog.Root initialFocus={nameRef}>
+      <Dialog.Trigger>
+        <Button>Rename</Button>
+      </Dialog.Trigger>
+      <Dialog.Portal size="sm">
+        <Dialog.Header>
+          <Dialog.Title>Rename file</Dialog.Title>
+          <Dialog.Close />
+        </Dialog.Header>
+        <Dialog.Body>
+          <Field.Root>
+            <Field.Label>Name</Field.Label>
+            <Input ref={nameRef} defaultValue="notes.md" />
+          </Field.Root>
+        </Dialog.Body>
+      </Dialog.Portal>
+    </Dialog.Root>
+  )
+}
+
+export const InitialFocus: Story = {
+  render: () => <InitialFocusDemo />,
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Rename'}))
+    const input = await screen.findByRole('textbox', {name: 'Name'})
+    await waitFor(() => expect(input).toHaveFocus())
+  },
+}
+
+export const FirstFocusableByDefault: Story = {
+  render: () => (
+    <Dialog.Root>
+      <Dialog.Trigger>
+        <Button>Open</Button>
+      </Dialog.Trigger>
+      <Dialog.Portal size="sm">
+        <Dialog.Header>
+          <Dialog.Title>Share</Dialog.Title>
+          <Dialog.Close aria-label="Close share" />
+        </Dialog.Header>
+      </Dialog.Portal>
+    </Dialog.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    await userEvent.click(canvas.getByRole('button', {name: 'Open'}))
+    const close = await screen.findByRole('button', {name: 'Close share'})
+    await waitFor(() => expect(close).toHaveFocus())
+  },
+}
+
+export const CloseOnEscapeOff: Story = {
+  render: () => (
+    <Dialog.Root defaultOpen closeOnEscape={false}>
+      <Dialog.Portal size="sm">
+        <Dialog.Header>
+          <Dialog.Title>Required step</Dialog.Title>
+        </Dialog.Header>
+        <Dialog.Footer>
+          <Dialog.Close>
+            <Button>Done</Button>
+          </Dialog.Close>
+        </Dialog.Footer>
+      </Dialog.Portal>
+    </Dialog.Root>
+  ),
+  play: async ({userEvent}) => {
+    await screen.findByRole('dialog', {name: 'Required step'})
+    await userEvent.keyboard('{Escape}')
+    await expect(screen.getByRole('dialog', {name: 'Required step'})).toBeInTheDocument()
+  },
+}

package/src/components/Dialog/Dialog.tsx

@@ -14,9 +14,13 @@ import {html} from 'react-strict-dom'
 import {DURATION_MS, type DurationToken} from '@duro-app/tokens/keys'
 import {styles} from './styles.css'
 import {usePortalMount} from '../ThemeProvider/ThemeProvider'
+import {devWarnOnce} from '../../shared/devWarnOnce'
 
 // --- Types ---
 
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
 export type DialogSize = 'sm' | 'md' | 'lg'
 
 const closeDurationMap = {
@@ -41,6 +45,8 @@ interface DialogContextValue {
   titleId: string
   descriptionId: string
   popupRef: RefObject<HTMLDivElement | null>
+  /** Dialog.Close parts currently rendered (for the closeOnEscape dev warning). */
+  registerClose: () => () => void
 }
 
 const DialogContext = createContext<DialogContextValue | null>(null)
@@ -61,8 +67,16 @@ interface RootProps {
   defaultOpen?: boolean
   /** Called when dialog open state changes */
   onOpenChange?: (open: boolean) => void
-  /** Whether clicking backdrop closes the dialog. Default: true */
+  /** Whether clicking the backdrop closes the dialog. Default: true */
   dismissable?: boolean
+  /**
+   * Whether Escape closes the dialog. Default: true, also when `dismissable`
+   * is false. Turning it off leaves the keyboard no way out but a
+   * Dialog.Close, so render one.
+   */
+  closeOnEscape?: boolean
+  /** Element to focus on open. Default: the first focusable element, else the dialog itself. */
+  initialFocus?: RefObject<HTMLElement | null>
   /** Motion token for the close animation. Default: 'fast' (150ms) */
   closeAnimationDuration?: DurationToken
 }
@@ -73,6 +87,8 @@ function Root({
   defaultOpen = false,
   onOpenChange,
   dismissable = true,
+  closeOnEscape = true,
+  initialFocus,
   closeAnimationDuration = 'fast',
 }: RootProps) {
   const isControlled = controlledOpen !== undefined
@@ -120,20 +136,55 @@ function Root({
     }
   }, [])
 
-  // Handle Escape key
+  // Handle Escape key. A layer inside the dialog (a Menu, a Select) that
+  // already handled it marks the event, and the dialog stays open.
   useEffect(() => {
     if (!isOpen && !closing) return
-    if (!dismissable) return
+    if (!closeOnEscape) return
 
     function onKeyDown(e: KeyboardEvent) {
-      if (e.key === 'Escape') {
-        e.stopPropagation()
-        requestClose()
-      }
+      if (e.key !== 'Escape' || e.defaultPrevented) return
+      e.stopPropagation()
+      requestClose()
     }
     document.addEventListener('keydown', onKeyDown)
     return () => document.removeEventListener('keydown', onKeyDown)
-  }, [isOpen, closing, dismissable, requestClose])
+  }, [isOpen, closing, closeOnEscape, requestClose])
+
+  // Focus: into the dialog on open (initialFocus, else the first focusable
+  // element, else the dialog itself), back to what had it on close. The
+  // Portal is a descendant, so its popup is mounted when this effect runs.
+  const closeCountRef = useRef(0)
+  const registerClose = useCallback(() => {
+    closeCountRef.current += 1
+    return () => {
+      closeCountRef.current -= 1
+    }
+  }, [])
+  const previousFocusRef = useRef<HTMLElement | null>(null)
+  const wasOpenRef = useRef(false)
+  useEffect(() => {
+    if (isOpen && !wasOpenRef.current) {
+      previousFocusRef.current = document.activeElement as HTMLElement | null
+      const popup = popupRef.current
+      if (popup) {
+        const target = initialFocus?.current ?? popup.querySelector<HTMLElement>(FOCUSABLE) ?? popup
+        target.focus({preventScroll: true})
+      }
+      if (!closeOnEscape && closeCountRef.current === 0) {
+        devWarnOnce(
+          'Dialog',
+          'no-escape-no-close',
+          'Dialog.Root has closeOnEscape={false} and no Dialog.Close: a keyboard user cannot leave this dialog. Render a Dialog.Close, or keep Escape.',
+        )
+      }
+    } else if (!isOpen && !closing && wasOpenRef.current) {
+      const target = previousFocusRef.current
+      previousFocusRef.current = null
+      if (target?.isConnected) target.focus({preventScroll: true})
+    }
+    wasOpenRef.current = isOpen || closing
+  }, [isOpen, closing, initialFocus, closeOnEscape])
 
   // Lock body scroll when open
   useEffect(() => {
@@ -158,6 +209,7 @@ function Root({
         titleId,
         descriptionId,
         popupRef,
+        registerClose,
       }}
     >
       {children}
@@ -229,6 +281,7 @@ function Portal({children, size = 'md'}: PortalProps) {
           ref={popupRef}
           role="dialog"
           aria-modal={true}
+          tabIndex={-1}
           aria-labelledby={titleId}
           aria-describedby={descriptionId}
           style={[
@@ -301,7 +354,8 @@ interface CloseProps {
 }
 
 function Close({children, 'aria-label': ariaLabel = 'Close'}: CloseProps) {
-  const {requestClose} = useDialog()
+  const {requestClose, registerClose} = useDialog()
+  useEffect(() => registerClose(), [registerClose])
 
   if (children) {
     return (