@duro-app/ui 5.5.0 → 5.6.0

package/dist/shared/ModalContext.d.ts

@@ -10,5 +10,12 @@
  * closes on a nested modal opening; no consumer needs it yet.
  */
 export declare const ModalContext: import('react').Context<boolean>;
+/**
+ * True inside a Dialog or Drawer, false outside. A floating surface that is not
+ * a Duro Popover picks its layer with it, the way a Popover does:
+ * `useInModal() ? layers.popover : layers.floating`, and for one that must
+ * cover another floating surface (a link editor over a format bar)
+ * `useInModal() ? layers.popoverRaised : layers.floatingRaised`.
+ */
 export declare function useInModal(): boolean;
 //# sourceMappingURL=ModalContext.d.ts.map

package/dist/shared/ModalContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModalContext.d.ts","sourceRoot":"","sources":["../../src/shared/ModalContext.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,kCAAuB,CAAA;AAEhD,wBAAgB,UAAU,YAEzB"}
+{"version":3,"file":"ModalContext.d.ts","sourceRoot":"","sources":["../../src/shared/ModalContext.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,kCAAuB,CAAA;AAEhD;;;;;;GAMG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC"}

package/dist/shared/exports.typecheck.d.ts

@@ -0,0 +1,9 @@
+import { ButtonSize, ControlSize, ToggleSize, useInModal } from '../index';
+type Same<T, U> = [T] extends [U] ? ([U] extends [T] ? true : false) : false;
+export declare const useInModalIsBoolean: Same<ReturnType<typeof useInModal>, boolean>;
+export declare const useInModalTakesNothing: Same<Parameters<typeof useInModal>, []>;
+export declare const controlSizes: Same<ControlSize, 'default' | 'small'>;
+export declare const buttonSizeIsControlSize: Same<ButtonSize, ControlSize>;
+export declare const toggleSizeIsControlSize: Same<ToggleSize, ControlSize>;
+export {};
+//# sourceMappingURL=exports.typecheck.d.ts.map

package/dist/shared/exports.typecheck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exports.typecheck.d.ts","sourceRoot":"","sources":["../../src/shared/exports.typecheck.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAC,MAAM,UAAU,CAAA;AAE7E,KAAK,IAAI,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC,GAAG,KAAK,CAAA;AAG5E,eAAO,MAAM,mBAAmB,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO,UAAU,CAAC,EAAE,OAAO,CAAQ,CAAA;AACrF,eAAO,MAAM,sBAAsB,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO,UAAU,CAAC,EAAE,EAAE,CAAQ,CAAA;AAGnF,eAAO,MAAM,YAAY,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,OAAO,CAAQ,CAAA;AACxE,eAAO,MAAM,uBAAuB,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,CAAQ,CAAA;AAC1E,eAAO,MAAM,uBAAuB,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,CAAQ,CAAA"}

package/dist/shared/types.d.ts

@@ -1,2 +1,4 @@
 export type Orientation = 'horizontal' | 'vertical';
+/** The two control sizes shared by Button, Toggle and the Select, Menu and Popover triggers. */
+export type ControlSize = 'default' | 'small';
 //# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,UAAU,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,UAAU,CAAA;AAEnD,gGAAgG;AAChG,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,OAAO,CAAA"}

package/dist/table.js

@@ -1,4 +1,4 @@
-import { M as F, m as xt, R as rt, H as kt, n as pt, o as bt, p as ft, q as mt, k as ht, t as yt, r as St, v as Tt } from "./Table-DYN-bp0e.js";
+import { M as F, m as xt, R as rt, H as kt, n as pt, o as bt, p as ft, q as mt, k as ht, t as yt, r as St, v as Tt } from "./Table-B1sWL3GA.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.5.0",
+  "version": "5.6.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -66,7 +66,7 @@
   },
   "dependencies": {
     "@tanstack/react-virtual": "^3.14.6",
-    "@duro-app/tokens": "^5.5.0"
+    "@duro-app/tokens": "^5.6.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/Button/Button.tsx

@@ -2,11 +2,12 @@ import type {ReactNode, Ref} from 'react'
 import {html} from 'react-strict-dom'
 import {isNative} from '../../platform'
 import {mergeRefs} from '../../shared/mergeRefs'
+import type {ControlSize} from '../../shared/types'
 import {useGroupedControl} from '../ButtonGroup/useGroupedControl'
 import {styles} from './styles.css'
 
 export type ButtonVariant = 'primary' | 'secondary' | 'inverseSecondary' | 'link' | 'danger'
-export type ButtonSize = 'default' | 'small'
+export type ButtonSize = ControlSize
 
 interface ButtonProps {
   variant?: ButtonVariant

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

@@ -4,6 +4,7 @@ import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
 import {typography} from '@duro-app/tokens/tokens/typography.css'
 import {duration, easing} from '@duro-app/tokens/tokens/motion.css'
 import {borders} from '@duro-app/tokens/tokens/borders.css'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 
 export const styles = css.create({
   base: {
@@ -62,6 +63,8 @@ export const styles = css.create({
     paddingLeft: spacing.sm,
     paddingRight: spacing.sm,
     fontSize: typography.fontSizeXs,
+    // Every small control is at least controlSm tall, whatever it holds (5.6).
+    minHeight: sizes.controlSm,
   },
   primary: {
     backgroundColor: {

package/src/components/ButtonGroup/ButtonGroup.stories.tsx

@@ -1,9 +1,21 @@
 import {useState} from 'react'
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect, userEvent, within} from 'storybook/test'
-import {BORDERS_PX, LAYERS, RADII_PX} from '@duro-app/tokens/keys'
+import {expect, userEvent, waitFor, within} from 'storybook/test'
+import {
+  BORDERS_PX,
+  FONT_SIZE_REM,
+  LAYERS,
+  RADII_PX,
+  SIZES_PX,
+  SPACING_PX,
+} from '@duro-app/tokens/keys'
+import {withCoarsePointer, withFinePointer} from '../../docs/coarsePointer'
 import {ButtonGroup} from './ButtonGroup'
+import type {ControlSize} from '../../shared/types'
 import {Button} from '../Button/Button'
+import {Icon} from '../Icon/Icon'
+import {Inline} from '../Inline/Inline'
+import {Menu} from '../Menu/Menu'
 import {Popover} from '../Popover/Popover'
 import {Select} from '../Select/Select'
 import {Stack} from '../Stack/Stack'
@@ -146,11 +158,11 @@ async function expectJoined(controls: Element[]) {
   }
 }
 
-function TextStyleSelects({named = false}: {named?: boolean}) {
+function TextStyleSelects({named = false, size}: {named?: boolean; size?: ControlSize}) {
   return (
     <ButtonGroup attached aria-label="Text style">
       <Select.Root name={named ? 'block' : undefined} defaultValue="normal">
-        <Select.Trigger aria-label="Block type">
+        <Select.Trigger aria-label="Block type" size={size}>
           <Select.Value />
           <Select.Icon />
         </Select.Trigger>
@@ -160,7 +172,7 @@ function TextStyleSelects({named = false}: {named?: boolean}) {
         </Select.Popup>
       </Select.Root>
       <Select.Root name={named ? 'font' : undefined} defaultValue="arial">
-        <Select.Trigger aria-label="Font">
+        <Select.Trigger aria-label="Font" size={size}>
           <Select.Value />
           <Select.Icon />
         </Select.Trigger>
@@ -170,7 +182,7 @@ function TextStyleSelects({named = false}: {named?: boolean}) {
         </Select.Popup>
       </Select.Root>
       <Select.Root name={named ? 'size' : undefined} defaultValue="15">
-        <Select.Trigger aria-label="Font size">
+        <Select.Trigger aria-label="Font size" size={size}>
           <Select.Value />
           <Select.Icon />
         </Select.Trigger>
@@ -242,25 +254,37 @@ export const AttachedFocusMiddle: Story = {
   },
 }
 
-function FormatGroup() {
+function FormatGroup({size}: {size?: ControlSize}) {
   const [pressed, setPressed] = useState<Record<string, boolean>>({u: true})
   const toggle = (key: string) => (next: boolean) => setPressed((p) => ({...p, [key]: next}))
   return (
     <ButtonGroup attached aria-label="Format">
-      <Toggle aria-label="Bold" pressed={!!pressed.b} onPressedChange={toggle('b')}>
+      <Toggle aria-label="Bold" size={size} pressed={!!pressed.b} onPressedChange={toggle('b')}>
         B
       </Toggle>
-      <Toggle aria-label="Italic" pressed={!!pressed.i} onPressedChange={toggle('i')}>
+      <Toggle aria-label="Italic" size={size} pressed={!!pressed.i} onPressedChange={toggle('i')}>
         I
       </Toggle>
-      <Toggle aria-label="Underline" pressed={!!pressed.u} onPressedChange={toggle('u')}>
+      <Toggle
+        aria-label="Underline"
+        size={size}
+        pressed={!!pressed.u}
+        onPressedChange={toggle('u')}
+      >
         U
       </Toggle>
-      <Toggle aria-label="Code" pressed={!!pressed.code} onPressedChange={toggle('code')}>
+      <Toggle
+        aria-label="Code"
+        size={size}
+        pressed={!!pressed.code}
+        onPressedChange={toggle('code')}
+      >
         {'<>'}
       </Toggle>
       <Popover.Root>
-        <Popover.Trigger aria-label="Link">↗</Popover.Trigger>
+        <Popover.Trigger aria-label="Link" size={size}>
+          ↗
+        </Popover.Trigger>
         <Popover.Popup label="Link">
           <Stack gap="sm">
             <Text>Paste a URL.</Text>
@@ -268,10 +292,10 @@ function FormatGroup() {
           </Stack>
         </Popover.Popup>
       </Popover.Root>
-      <Button variant="secondary" aria-label="Clear formatting">
+      <Button variant="secondary" size={size} aria-label="Clear formatting">
         T
       </Button>
-      <Button variant="secondary" aria-label="Highlight">
+      <Button variant="secondary" size={size} aria-label="Highlight">
         H
       </Button>
     </ButtonGroup>
@@ -372,3 +396,137 @@ export const BothPressedFocusSecond: Story = {
     await expect(drawnAt(bold, b.left + b.width / 2, ringPixels(b).bottom)).toBe(true)
   },
 }
+
+// --- Small triggers (5.6) ---
+
+/** fontSizeXs in px, from the root font size. */
+const smallFontPx = () =>
+  `${parseFloat(getComputedStyle(document.documentElement).fontSize) * FONT_SIZE_REM.fontSizeXs}px`
+
+/** [Normal | Arial | 15px] at size="small": joined like the default size. */
+export const AttachedSelectsSmall: Story = {
+  render: () => <TextStyleSelects size="small" />,
+  play: async ({canvas}) => {
+    const triggers = canvas.getAllByRole('combobox')
+    await expectJoined(triggers)
+    for (const el of triggers) {
+      await expect(getComputedStyle(el).fontSize).toBe(smallFontPx())
+    }
+  },
+}
+
+/** The mixed format group at size="small": Toggles, the Popover trigger and
+ *  the Buttons stay joined. */
+export const AttachedMixedSmall: Story = {
+  render: () => <FormatGroup size="small" />,
+  play: async ({canvas}) => {
+    const group = canvas.getByRole('group', {name: 'Format'})
+    await expectJoined(within(group).getAllByRole('button'))
+  },
+}
+
+function SmallControlsRow() {
+  return (
+    <Inline gap="sm" align="center">
+      <Toggle size="small" aria-label="Bold">
+        B
+      </Toggle>
+      <Toggle size="small" aria-label="Search">
+        <Icon name="search" size="md" />
+      </Toggle>
+      <Button size="small" variant="secondary">
+        Clear
+      </Button>
+      <Select.Root defaultValue="normal">
+        <Select.Trigger size="small" aria-label="Block type">
+          <Select.Value />
+          <Select.Icon />
+        </Select.Trigger>
+        <Select.Popup>
+          <Select.Item value="normal">Normal</Select.Item>
+          <Select.Item value="h1">Heading 1</Select.Item>
+        </Select.Popup>
+      </Select.Root>
+      <Menu.Root>
+        <Menu.Trigger size="small">Insert</Menu.Trigger>
+        <Menu.Popup>
+          <Menu.Item onClick={() => undefined}>Image</Menu.Item>
+        </Menu.Popup>
+      </Menu.Root>
+      <Popover.Root>
+        <Popover.Trigger size="small" aria-label="Text colour">
+          A
+        </Popover.Trigger>
+        <Popover.Popup label="Text colour">
+          <Text>Pick a colour.</Text>
+        </Popover.Popup>
+      </Popover.Root>
+      <Menu.Root>
+        <Menu.Trigger size="small" variant="ghost" aria-label="More">
+          <Icon name="menu" size="sm" />
+        </Menu.Trigger>
+        <Menu.Popup>
+          <Menu.Item onClick={() => undefined}>Settings</Menu.Item>
+        </Menu.Popup>
+      </Menu.Root>
+    </Inline>
+  )
+}
+
+/** Small Toggles (text and an 18px icon), a small Button and small Select,
+ *  Menu and Popover triggers in a plain Inline (no attached group to stretch
+ *  them): every one is controlSm tall whatever it holds, with Toggle's
+ *  padding and font. The ghost Menu trigger is the small icon-button size. */
+export const SmallTriggersRow: Story = {
+  render: () => <SmallControlsRow />,
+  play: async ({canvas}) => {
+    await withFinePointer()
+    const controls = [
+      canvas.getByRole('button', {name: 'Bold'}),
+      canvas.getByRole('button', {name: 'Search'}),
+      canvas.getByRole('button', {name: 'Clear'}),
+    ]
+    const triggers = [
+      canvas.getByRole('combobox', {name: 'Block type'}),
+      canvas.getByRole('button', {name: 'Insert'}),
+      canvas.getByRole('button', {name: 'Text colour'}),
+    ]
+    for (const el of [...controls, ...triggers]) {
+      await expect(el.offsetHeight).toBe(SIZES_PX.controlSm)
+    }
+    for (const el of triggers) {
+      const cs = getComputedStyle(el)
+      await expect(cs.paddingTop).toBe(`${SPACING_PX.xs}px`)
+      await expect(cs.paddingLeft).toBe(`${SPACING_PX.sm}px`)
+      await expect(cs.fontSize).toBe(smallFontPx())
+    }
+    const ghost = canvas.getByRole('button', {name: 'More'})
+    await expect(ghost.offsetHeight).toBe(SIZES_PX.iconButtonSm)
+    await expect(ghost.offsetWidth).toBe(SIZES_PX.iconButtonSm)
+    await expect(getComputedStyle(ghost).fontSize).toBe(smallFontPx())
+  },
+}
+
+/** The same row under a coarse pointer: Toggle and the three triggers reach
+ *  touchTarget, the ghost Menu too. Button has no touch size at any size, so the small Button stays
+ *  controlSm (the 5.5 plan's addendum). */
+export const SmallTriggersRowCoarsePointer: Story = {
+  render: () => <SmallControlsRow />,
+  play: async ({canvas}) => {
+    const touch = [
+      canvas.getByRole('button', {name: 'Bold'}),
+      canvas.getByRole('button', {name: 'Search'}),
+      canvas.getByRole('combobox', {name: 'Block type'}),
+      canvas.getByRole('button', {name: 'Insert'}),
+      canvas.getByRole('button', {name: 'Text colour'}),
+      canvas.getByRole('button', {name: 'More'}),
+    ]
+    const button = canvas.getByRole('button', {name: 'Clear'})
+    await withCoarsePointer(async () => {
+      for (const el of touch) {
+        await waitFor(() => expect(el.offsetHeight).toBe(SIZES_PX.touchTarget))
+      }
+      await expect(button.offsetHeight).toBe(SIZES_PX.controlSm)
+    })
+  },
+}

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

@@ -4,6 +4,7 @@ import {spacing, radii} from '@duro-app/tokens/tokens/spacing.css'
 import {typography} from '@duro-app/tokens/tokens/typography.css'
 import {duration, easing} from '@duro-app/tokens/tokens/motion.css'
 import {borders} from '@duro-app/tokens/tokens/borders.css'
+import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 
 export const styles = css.create({
   base: {
@@ -34,6 +35,9 @@ export const styles = css.create({
     paddingLeft: spacing.sm,
     paddingRight: spacing.sm,
     fontSize: typography.fontSizeXs,
+
+    // Matches Button: every small control is at least controlSm tall (5.6).
+    minHeight: sizes.controlSm,
   },
   primary: {
     backgroundColor: {

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

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Dropdown action menu. Triggers actions (not value selection). Compound component — Root is required (throws without it). Menu.Trigger renders the button itself: give it the label (text, an Icon), never a Button; an icon-only trigger takes aria-label, and variant="ghost" suits toolbars. The popup is portalled and placed against the trigger (never clipped by a sticky or overflow ancestor), capped at sizes.listMaxH with scrolling, and takes focus on open (WAI-ARIA menu button); Escape closes only the menu, not an enclosing Popover or Dialog.',
+    'Dropdown action menu. Triggers actions (not value selection). Compound component — Root is required (throws without it). Menu.Trigger renders the button itself: give it the label (text, an Icon), never a Button; an icon-only trigger takes aria-label, and variant="ghost" suits toolbars; size="small" matches small Toggles and Buttons (a small ghost trigger is iconButtonSm). The popup is portalled and placed against the trigger (never clipped by a sticky or overflow ancestor), capped at sizes.listMaxH with scrolling, and takes focus on open (WAI-ARIA menu button); Escape closes only the menu, not an enclosing Popover or Dialog.',
   whenToUse: [
     'Context menu or "more actions" dropdown',
     'Navigation links in a dropdown',

package/src/components/Menu/Menu.tsx

@@ -15,6 +15,7 @@ import {styles} from './styles.css'
 import {MenuContext, useMenu} from './MenuContext'
 import {useMenuRoot} from './useMenuRoot'
 import {devWarnOnce} from '../../shared/devWarnOnce'
+import type {ControlSize} from '../../shared/types'
 import {usePortalMount} from '../ThemeProvider/ThemeProvider'
 import {computePopoverPosition} from '../Popover/position'
 import {usePopoverLayer} from '../Popover/PopoverLayerContext'
@@ -58,10 +59,18 @@ interface TriggerProps {
   'aria-label'?: string
   /** `ghost`: no border or fill until hover, for toolbars. Default: `default`. */
   variant?: MenuTriggerVariant
+  /** `small` matches a small Toggle or Button beside it; a small ghost trigger is `iconButtonSm`. Default: `default`. */
+  size?: ControlSize
   ref?: Ref<HTMLButtonElement>
 }
 
-function Trigger({children, 'aria-label': ariaLabel, variant = 'default', ref}: TriggerProps) {
+function Trigger({
+  children,
+  'aria-label': ariaLabel,
+  variant = 'default',
+  size = 'default',
+  ref,
+}: TriggerProps) {
   const {open, toggle, menuId, triggerId, triggerRef} = useMenu()
   const grouped = useGroupedControl<HTMLButtonElement>()
   const groupedRef = grouped.ref
@@ -99,7 +108,13 @@ function Trigger({children, 'aria-label': ariaLabel, variant = 'default', ref}:
       aria-expanded={open}
       aria-haspopup="menu"
       aria-controls={open ? menuId : undefined}
-      style={[styles.trigger, variant === 'ghost' && styles.triggerGhost, grouped.style]}
+      style={[
+        styles.trigger,
+        variant === 'ghost'
+          ? [styles.triggerGhost, size === 'small' && styles.triggerGhostSmall]
+          : size === 'small' && styles.triggerSmall,
+        grouped.style,
+      ]}
     >
       {children}
     </html.button>

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

@@ -47,6 +47,24 @@ export const styles = css.create({
     paddingRight: spacing.xs,
     borderColor: 'transparent',
   },
+  // size="small": Toggle sizeSmall's values, as longhands so they win over the
+  // trigger's own longhands. Every small control is at least controlSm tall,
+  // whatever it holds, and the touch target under a coarse pointer.
+  triggerSmall: {
+    gap: spacing.xs,
+    paddingTop: spacing.xs,
+    paddingBottom: spacing.xs,
+    paddingLeft: spacing.sm,
+    paddingRight: spacing.sm,
+    fontSize: typography.fontSizeXs,
+    minHeight: {default: sizes.controlSm, '@media (pointer: coarse)': sizes.touchTarget},
+  },
+  // A small ghost trigger keeps the ghost's xs padding at the small icon-button size.
+  triggerGhostSmall: {
+    fontSize: typography.fontSizeXs,
+    minWidth: sizes.iconButtonSm,
+    minHeight: {default: sizes.iconButtonSm, '@media (pointer: coarse)': sizes.touchTarget},
+  },
   popup: {
     position: 'fixed',
     top: 0,

package/src/components/Popover/Popover.meta.ts

@@ -2,10 +2,11 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Non-modal anchored overlay for small interactive content. Compound component — Root is required (throws without it). Anchored to Popover.Trigger, or to a virtual anchor (a () => DOMRect) when there is no Trigger; call reposition() through a ref when the anchor moves.',
+    'Non-modal anchored overlay for small interactive content. Compound component — Root is required (throws without it). Anchored to Popover.Trigger, or to a virtual anchor (a () => DOMRect) when there is no Trigger; call reposition() through a ref when the anchor moves. Popover.Trigger takes size="small" beside small Toggles. Popover.Popup raised draws it over another floating surface (floatingRaised, popoverRaised in a modal), never over a modal.',
   whenToUse: [
     'A small form or controls tied to one element that stay open while you work in them',
     'Anchoring to a spot that is not a button (a canvas point, a text selection) with a virtual anchor',
+    'One floating surface over another (a link editor over a selection format bar) — Popover.Popup raised',
     'Holding a Select or Combobox: their portalled list counts as inside the popover, so choosing an item keeps it open; Escape closes an open Select, Combobox or Menu before the popover',
   ],
   whenNotToUse: [

package/src/components/Popover/Popover.tsx

@@ -22,6 +22,7 @@ import {PopoverLayerContext, type PopoverLayerContextValue} from './PopoverLayer
 import {useGroupedControl} from '../ButtonGroup/useGroupedControl'
 import {ControlContextBoundary} from '../Toolbar/ControlContextBoundary'
 import {mergeRefs} from '../../shared/mergeRefs'
+import type {ControlSize} from '../../shared/types'
 import {useInModal} from '../../shared/ModalContext'
 
 // --- Context ---
@@ -166,6 +167,8 @@ function Root({
           unregisterParent?.()
         }
       },
+      // Inside a raised Popup, this Popover is raised too.
+      raised: parentLayer?.raised,
     }),
     [parentLayer],
   )
@@ -201,11 +204,13 @@ interface TriggerProps {
   children: ReactNode
   /** Accessible name: required when the label is an icon only. */
   'aria-label'?: string
+  /** `small` matches a small Toggle or Button beside it. Default: `default`. */
+  size?: ControlSize
   /** The trigger <button>, e.g. to measure it or return focus to it. */
   ref?: Ref<HTMLButtonElement>
 }
 
-function Trigger({children, 'aria-label': ariaLabel, ref}: TriggerProps) {
+function Trigger({children, 'aria-label': ariaLabel, size = 'default', ref}: TriggerProps) {
   const {open, setOpen, popoverId, triggerRef} = usePopover('Trigger')
   const grouped = useGroupedControl<HTMLButtonElement>()
 
@@ -220,7 +225,7 @@ function Trigger({children, 'aria-label': ariaLabel, ref}: TriggerProps) {
       aria-haspopup="dialog"
       aria-expanded={open}
       aria-controls={open ? popoverId : undefined}
-      style={[styles.trigger, grouped.style]}
+      style={[styles.trigger, size === 'small' && styles.triggerSmall, grouped.style]}
     >
       {children}
     </html.button>
@@ -233,9 +238,18 @@ interface PopupProps {
   children: ReactNode
   /** Accessible name for the dialog. */
   label: string
+  /**
+   * Draw over another floating surface: `layers.floatingRaised` outside a
+   * modal, `layers.popoverRaised` inside a Dialog or Drawer, instead of
+   * `floating` / `popover`. For one floating thing that must cover a sibling
+   * one (a link editor over a format bar), never for covering a modal: a
+   * Dialog opened later still covers it. A Popover nested inside a raised one
+   * is raised too. Default: inherited, else `false`.
+   */
+  raised?: boolean
 }
 
-function Popup({children, label}: PopupProps) {
+function Popup({children, label, raised}: PopupProps) {
   const {open, popoverId, side, align, anchor, triggerRef, popupRef, repositionRef} =
     usePopover('Popup')
   const [coords, setCoords] = useState({top: 0, left: 0})
@@ -243,6 +257,14 @@ function Popup({children, label}: PopupProps) {
   // tokens cascade into the popup and it stacks above dialogs.
   const mount = usePortalMount()
   const inModal = useInModal()
+  const layer = useContext(PopoverLayerContext)
+  const isRaised = raised ?? layer?.raised ?? false
+  // Re-provided around the children: the Root can't see this prop, and a
+  // Popover nested in here reads it to stay above this one.
+  const raisedLayer = useMemo<PopoverLayerContextValue | null>(
+    () => (layer ? {...layer, raised: isRaised} : null),
+    [layer, isRaised],
+  )
 
   // Measure before paint on open; re-measure on scroll/resize (capture phase
   // catches any scrolling ancestor) and when Root.reposition() is called.
@@ -291,10 +313,13 @@ function Popup({children, label}: PopupProps) {
       style={[
         styles.popup,
         inModal && styles.popupInModal,
+        isRaised && (inModal ? styles.popupInModalRaised : styles.popupRaised),
         styles.popupPosition(coords.top, coords.left),
       ]}
     >
-      <ControlContextBoundary>{children}</ControlContextBoundary>
+      <PopoverLayerContext.Provider value={raisedLayer}>
+        <ControlContextBoundary>{children}</ControlContextBoundary>
+      </PopoverLayerContext.Provider>
     </html.div>,
     mount ?? document.body,
   )

package/src/components/Popover/PopoverLayerContext.ts

@@ -5,6 +5,9 @@ import {type RefObject, createContext, useContext, useLayoutEffect} from 'react'
 // on them counts as inside the Popover.
 export interface PopoverLayerContextValue {
   register: (el: Element) => () => void
+  /** Set by a `raised` Popup for what it holds, so a Popover nested in it is
+   *  raised too and is not drawn under its parent. */
+  raised?: boolean
 }
 
 export const PopoverLayerContext = createContext<PopoverLayerContextValue | null>(null)