@estiva-app/ui 0.24.1 → 0.26.0

package/src/Lightbox.mdx

@@ -0,0 +1,71 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as LightboxStories from './Lightbox.stories'
+
+<Meta of={LightboxStories} />
+
+# Lightbox
+
+A picture, full screen, on a scrim — what a thumbnail opens into. Built on
+Base UI's `Dialog`, like DialogShell.
+
+<Canvas of={LightboxStories.APicture} />
+
+## When
+
+- Somebody presses a picture that is cropped or scaled down where it sits — a
+  screenshot on a message, a photo in a thread — and wants to see the whole of
+  it.
+- **AttachmentCard opens one by itself**, so an image attachment needs nothing
+  here: this is for a picture that is not an attachment card.
+
+## When not
+
+- Anything that is not a picture → **DialogShell**.
+- A picture small enough to read where it is — don't; an overlay that shows the
+  same thing at the same size is a click that did nothing.
+- A gallery of several pictures with next and previous. This shows one. Ask for
+  the part rather than building the arrows around it.
+
+## How
+
+```tsx
+import { Lightbox } from '@estiva-app/ui'
+
+{opened && <Lightbox src={pictureUrl} alt={name} onClose={() => setOpened(false)} />}
+```
+
+- It is mounted while it is open: there is no `open` prop, and a caller renders
+  it or does not — DialogShell's rule.
+- **Swapping `src` swaps the picture**, with no flash of nothing. That is how a
+  thumbnail stands in while the original is still being fetched.
+- The picture is contained: as large as the screen allows, never cropped, never
+  stretched.
+- `alt` names the picture, and names the viewer itself to assistive technology.
+
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Floats on top of the page, over its own scrim | a portal, a fixed layer, a `z-index` to win | ✓ |
+| Takes its keys by itself — Escape closes it | a `keydown` listener on the page | ✓ |
+| Holds focus inside while open, and gives it back to whatever opened it | focus code, Tab compared by hand | ✓ |
+| Stops the page behind it scrolling | `overflow` written onto the body | ✓ |
+| Closes on a press on the scrim, and **not** on a press on the picture | a click handler that tests the target |  |
+| Carries its own close button, sized to be findable on a photograph | an IconButton on a corner |  |
+
+## Keys
+
+| Input | What happens |
+|---|---|
+| Escape | closes |
+| scrim click | closes |
+| picture click | nothing — clicking what you opened should not close it |
+| close button | closes |
+| Tab / Shift+Tab | stays inside the viewer |
+| on close | focus returns to the picture that opened it |
+
+## Props
+
+<Controls of={LightboxStories.APicture} />

package/src/Lightbox.stories.tsx

@@ -0,0 +1,72 @@
+import { useState } from 'react'
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Button } from './Button'
+import { Lightbox } from './Lightbox'
+
+/** A drawn picture rather than a photograph, so the story needs no network. */
+const svg = (w: number, h: number, body: string) =>
+  `data:image/svg+xml;utf8,${encodeURIComponent(
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}"><rect width="${w}" height="${h}" fill="#0f1720"/>${body}</svg>`,
+  )}`
+
+const WIDE = svg(
+  960,
+  540,
+  `<circle cx="240" cy="180" r="104" fill="#56c8ff"/><rect x="392" y="300" width="440" height="140" rx="24" fill="#4ade8c"/>`,
+)
+
+const TALL = svg(
+  540,
+  960,
+  `<rect x="80" y="120" width="380" height="380" rx="32" fill="#b18cff"/><circle cx="270" cy="740" r="140" fill="#ffc94d"/>`,
+)
+
+const meta = {
+  title: 'Overlays/Lightbox',
+  component: Lightbox,
+  parameters: {
+    layout: 'fullscreen',
+    // Portals a full-screen overlay to document.body — render in an iframe on
+    // the Docs page so it does not cover the docs.
+    docs: { story: { inline: false, height: '520px' } },
+  },
+  args: {
+    src: WIDE,
+    alt: 'checkout-flow.png',
+    onClose: () => {},
+  },
+} satisfies Meta<typeof Lightbox>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * A wide picture, as large as the screen allows and never larger: it is
+ * contained, so nothing is cropped and nothing is stretched.
+ */
+export const APicture: Story = {}
+
+/** A tall one in the same viewer — the height is what runs out first. */
+export const ATallPicture: Story = { args: { src: TALL, alt: 'signup-screen.png' } }
+
+/**
+ * **Open it and close it**, which is the whole point of the part.
+ *
+ * Escape closes it, so does the ✕ and so does a press on the scrim — a press on
+ * the picture does not. Focus is trapped while it is open and returns to the
+ * button that opened it, which is what neither hand-built viewer did.
+ */
+export const OpenAndClose: Story = {
+  parameters: { controls: { disable: true } },
+  render: (args) => {
+    const [open, setOpen] = useState(false)
+    return (
+      <div className="flex h-screen items-center justify-center">
+        <Button variant="primary" onClick={() => setOpen(true)}>
+          Open the picture
+        </Button>
+        {open && <Lightbox {...args} onClose={() => setOpen(false)} />}
+      </div>
+    )
+  },
+}

package/src/Lightbox.test.tsx

@@ -0,0 +1,65 @@
+// @vitest-environment jsdom
+/**
+ * What the Lightbox page claims, pinned: it floats over the page on its own
+ * scrim, it names itself, Escape closes it, a press on the scrim closes it and
+ * a press on the picture does not, and the close button closes it.
+ *
+ * The behaviours the two hand-built viewers never had are Base UI's, so what
+ * is tested here is that this part is wired to them — not Base UI itself.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Lightbox } from './Lightbox'
+
+afterEach(cleanup)
+
+const PICTURE = 'data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%2F%3E'
+
+describe('Lightbox', () => {
+  it('floats over the page: it portals out of its parent, and carries the strong scrim', () => {
+    const { container } = render(<Lightbox src={PICTURE} alt="checkout-flow.png" onClose={() => {}} />)
+    // Nothing is left where it was written.
+    expect(container.firstElementChild).toBeNull()
+    const picture = screen.getByAltText('checkout-flow.png')
+    expect(document.body.contains(picture)).toBe(true)
+    expect(document.querySelector('.bg-scrim-strong')).toBeTruthy()
+  })
+
+  it('names itself with the picture, so a reader is told what opened', () => {
+    render(<Lightbox src={PICTURE} alt="signup-screen.png" onClose={() => {}} />)
+    expect(screen.getByRole('dialog', { name: 'signup-screen.png' })).toBeTruthy()
+  })
+
+  it('Escape closes it', async () => {
+    const onClose = vi.fn()
+    render(<Lightbox src={PICTURE} alt="a.png" onClose={onClose} />)
+    await userEvent.keyboard('{Escape}')
+    expect(onClose).toHaveBeenCalled()
+  })
+
+  it('the close button closes it', async () => {
+    const onClose = vi.fn()
+    render(<Lightbox src={PICTURE} alt="a.png" onClose={onClose} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Close' }))
+    expect(onClose).toHaveBeenCalled()
+  })
+
+  it('a press on the scrim closes it; a press on the picture does not', async () => {
+    const onClose = vi.fn()
+    render(<Lightbox src={PICTURE} alt="a.png" onClose={onClose} />)
+
+    await userEvent.click(screen.getByAltText('a.png'))
+    expect(onClose).not.toHaveBeenCalled()
+
+    await userEvent.click(screen.getByRole('dialog'))
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('swapping the picture swaps what is on screen — a thumbnail, then the original', () => {
+    const { rerender } = render(<Lightbox src={PICTURE} alt="a.png" onClose={() => {}} />)
+    expect(screen.getByAltText('a.png').getAttribute('src')).toBe(PICTURE)
+    rerender(<Lightbox src="blob:original" alt="a.png" onClose={() => {}} />)
+    expect(screen.getByAltText('a.png').getAttribute('src')).toBe('blob:original')
+  })
+})

package/src/Lightbox.tsx

@@ -0,0 +1,87 @@
+import { useRef } from 'react'
+import { Dialog } from '@base-ui/react/dialog'
+import { IconX } from '@tabler/icons-react'
+import { cn } from './cn'
+
+/**
+ * A picture, full screen, on a scrim — the thing a thumbnail opens into.
+ *
+ * Both apps had written this by hand and neither had got it right: Peek's
+ * `ImageLightbox` and the `FrameLightbox` before it were `createPortal` plus a
+ * fixed `<div>`, with no Escape, no focus trap and nothing to return focus to
+ * (Peek scan F5, P4; migration B22, Katerina 10 September). Ship never had one
+ * at all, so a screenshot in an issue could not be looked at.
+ *
+ * On Base UI's `Dialog`, like `DialogShell`: the portal, the backdrop, Escape,
+ * the outside press and the focus trap are its, and what is written here is the
+ * picture, the scrim and the close button.
+ *
+ * **The close button is this component's own**, not an `IconButton`: a 26px
+ * square with no fill is hard to find on top of a photograph, which is why Peek
+ * had written an escape note beside its own. A 32px round button on an elevated
+ * fill with a hairline reads on any picture.
+ */
+export interface LightboxProps {
+  /** The picture to show. Swapping it — a thumbnail for the original, once it
+   *  arrives — swaps what is on screen, with no flash of nothing. */
+  src: string
+  /** What the picture is. Names the viewer for assistive tech too. */
+  alt: string
+  onClose: () => void
+  /** Extra classes on the picture itself. */
+  className?: string
+}
+
+export function Lightbox({ src, alt, onClose, className }: LightboxProps) {
+  const popupRef = useRef<HTMLDivElement>(null)
+  return (
+    <Dialog.Root
+      open
+      onOpenChange={(open) => {
+        if (!open) onClose()
+      }}
+    >
+      <Dialog.Portal>
+        <Dialog.Backdrop className="fixed inset-0 z-40 bg-scrim-strong" />
+        <Dialog.Popup
+          ref={popupRef}
+          /*
+            Focus the layer, not the ✕ — DialogShell's rule, for the same
+            reason: Base UI's default is the first tabbable element, which here
+            would open every picture with a ring drawn on its close button. The
+            trap is armed either way, and Tab reaches the ✕ first.
+          */
+          initialFocus={popupRef}
+          aria-label={alt}
+          /*
+            The popup IS the layer: a picture viewer has no card, so the popup
+            fills the screen and centres what it holds. `outline-none` because
+            it is a programmatic focus target rather than something tabbed to —
+            the same reason DialogShell gives.
+
+            A press anywhere on the layer closes it, which is what a full-screen
+            picture teaches people to expect. Base UI's outside-press cannot do
+            that here: there is no outside.
+          */
+          className="fixed inset-0 z-50 flex items-center justify-center p-8 outline-none"
+          onClick={onClose}
+        >
+          <img
+            src={src}
+            alt={alt}
+            /* The press on the picture is not a press on the scrim: clicking
+               the thing you opened should not close it. */
+            onClick={(e) => e.stopPropagation()}
+            className={cn('max-w-full max-h-full object-contain rounded-lg', className)}
+          />
+          <Dialog.Close
+            aria-label="Close"
+            className="absolute top-4 right-4 size-8 rounded-full bg-bg-elevated border border-border-strong flex items-center justify-center text-text-secondary hover:text-text-primary"
+          >
+            <IconX size={16} stroke={1.5} />
+          </Dialog.Close>
+        </Dialog.Popup>
+      </Dialog.Portal>
+    </Dialog.Root>
+  )
+}

package/src/ListColumn.mdx

@@ -16,9 +16,9 @@ The list column of a page: 290px wide with a line on its right, its name in a
   Nothing around it sets its width, and nothing squeezes it.
 - A page that lists things beside the one that is open: the list on the left,
   the chosen thing to its right.
-- `spacing="rows"` (the default, 2px between rows) for a list of one kind of
-  row. `spacing="sections"` (4px) for groups with labels and dividers of their
-  own.
+- Its rows sit 2px apart, one kind of row or groups alike. A group that folds
+  is a **CollapsibleSection**; a group that does not is a **SectionHeader**
+  over its rows. Never a heading row drawn by hand.
 - `above` for a row that stays put while the list scrolls: a field that adds
   to the list.
 - `collapsed` closes it with the rail: it narrows to nothing and fades, in
@@ -71,6 +71,13 @@ import { ListColumn, Toolbar, ToolbarButton } from '@estiva-app/ui'
 
 <Canvas of={ListColumnStories.ManyRows} />
 
+- **A crash stays inside it.** If its rows, its actions or the row above
+  break, it keeps its title and shows "Something went wrong in the list
+  panel… try again" in the middle of the room the list had. The rest of the page keeps working.
+  It is **ErrorBoundary**'s, held by the column itself.
+
+<Canvas of={ListColumnStories.WhenARowBreaks} />
+
 ## What it owns
 
 It does these by itself. Write none of them around it.
@@ -81,6 +88,7 @@ It does these by itself. Write none of them around it.
 | Scrolls its rows in a ScrollArea, 16px under the header, 12px in from each side | `overflow-auto`, or padding of your own around the rows |  |
 | Closes with the rail when `collapsed`: narrows to nothing and fades | a width transition of your own |  |
 | Keeps its 290px beside a main area that grows | `shrink-0` |  |
+| Keeps a crash inside itself: its title stays, the message and Try again sit in the middle of the room the list had | an error boundary of your own around it |  |
 
 ## Props
 

package/src/ListColumn.stories.tsx

@@ -2,11 +2,12 @@ import type { Meta, StoryObj } from '@storybook/react-vite'
 import { IconSortDescending, IconSquareRounded } from '@tabler/icons-react'
 import { useState } from 'react'
 import { Button } from './Button'
+import { CollapsibleSection } from './CollapsibleSection'
 import { Divider } from './Divider'
 import { Form } from './Form'
 import { ListColumn } from './ListColumn'
 import { NavItem } from './NavItem'
-import { SectionLabel } from './SectionLabel'
+import { SectionHeader } from './SectionHeader'
 import { SkeletonList } from './Skeleton'
 import { TextInput } from './TextInput'
 import { Toolbar, ToolbarButton } from './Toolbar'
@@ -58,19 +59,24 @@ export const Default: Story = {
   render: (args) => <ListColumn {...args}>{rows(6)}</ListColumn>,
 }
 
-/** Groups with labels and a divider of their own: 4px between rows. */
+/**
+ * Groups. Each is headed by a package part, never by a row drawn by hand: a
+ * group that folds is a `CollapsibleSection`; a group that does not fold is a
+ * `SectionHeader` over its rows.
+ */
 export const Sections: Story = {
-  args: { title: 'Items', spacing: 'sections' },
+  args: { title: 'Items' },
   render: (args) => (
     <ListColumn {...args}>
-      <div className="flex h-8 shrink-0 items-center px-2">
-        <SectionLabel>Group one</SectionLabel>
-      </div>
-      {rows(3)}
+      <CollapsibleSection title="Group one" contentClassName="mt-1 gap-0.5">
+        {rows(3)}
+      </CollapsibleSection>
       <Divider className="my-2" />
-      <div className="flex h-8 shrink-0 items-center px-2">
-        <SectionLabel>Group two</SectionLabel>
-      </div>
+      <SectionHeader
+        title="Group two"
+        hover="none"
+        actions={[{ icon: <IconSortDescending size={16} stroke={1.5} />, tooltip: 'Sort by', onClick: () => {} }]}
+      />
       {rows(4)}
     </ListColumn>
   ),
@@ -115,6 +121,24 @@ export const Loading: Story = {
   ),
 }
 
+function Broken(): never {
+  throw new Error('A row could not draw itself')
+}
+
+/**
+ * When a row breaks: the column keeps its title and says so in the middle of
+ * the room the list had, with Try again. The rest of the page keeps working.
+ */
+export const WhenARowBreaks: Story = {
+  args: { title: 'Items', actions },
+  render: (args) => (
+    <ListColumn {...args}>
+      {rows(2)}
+      <Broken />
+    </ListColumn>
+  ),
+}
+
 /** Closed with the rail: it narrows to nothing and fades. Press the button to watch it. */
 export const Collapsing: Story = {
   parameters: { controls: { disable: true } },

package/src/ListColumn.test.tsx

@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 /** What the ListColumn page claims, pinned. Sizes are measured in the browser; these pin the parts. */
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render, screen } from '@testing-library/react'
 import { ListColumn } from './ListColumn'
 
@@ -39,12 +39,25 @@ describe('ListColumn', () => {
     expect(list.contains(screen.getByText('Above'))).toBe(false)
   })
 
-  it('sections: 4px between rows', () => {
-    render(
-      <ListColumn title="Items" spacing="sections">
-        <p>Row</p>
-      </ListColumn>,
+  it('a row that breaks: the column keeps its title, the message is where the list was, the rest stays', () => {
+    const quiet = vi.spyOn(console, 'error').mockImplementation(() => {})
+    function Broken(): never {
+      throw new Error('boom')
+    }
+    const { container } = render(
+      <>
+        <ListColumn title="Items" actions={<button>Sort</button>}>
+          <Broken />
+        </ListColumn>
+        <p>The rest of the page</p>
+      </>,
     )
-    expect((screen.getByText('Row').parentElement as HTMLElement).className.split(' ')).toContain('gap-1')
+    expect(screen.getByText('Items')).toBeTruthy()
+    expect(screen.getByText(/Something went wrong in the list panel/)).toBeTruthy()
+    // Only the name comes back: the actions may be what threw.
+    expect(screen.queryByText('Sort')).toBeNull()
+    expect(screen.getByText('The rest of the page')).toBeTruthy()
+    expect((container.firstElementChild as HTMLElement).className.split(' ')).toContain('w-[290px]')
+    quiet.mockRestore()
   })
 })

package/src/ListColumn.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react'
 import { cn } from './cn'
 import { ContainerHeader } from './ContainerHeader'
+import { ErrorBoundary } from './ErrorBoundary'
 import { ScrollArea } from './ScrollArea'
 
 /**
@@ -11,12 +12,18 @@ import { ScrollArea } from './ScrollArea'
  * Moved in from Peek as it looks (UIG-14, N9), where five pages drew it by
  * hand and each carried the same numbers: the frame's 290px and its line, and
  * the list's steps — 16px under the header, 12px above the bottom, rows 12px
- * in from each side. The numbers live here now, once.
+ * in from each side and 2px apart. The numbers live here now, once. One
+ * spacing for every list (Katerina, D5): a list of groups heads each with a
+ * `CollapsibleSection` or a `SectionHeader`.
  *
  * It scrolls its rows itself. A list column that did not was the first of the
  * eight mistakes on the page that led to UIG-15: the frame's card clips, so a
  * list that grew past the fold was simply cut off, with nothing to scroll.
  *
+ * It keeps a crash inside itself (D1, D3): if its rows, its actions or the row
+ * above break, the column keeps its title and shows `ErrorBoundary`'s message
+ * in the middle of the room the list had, and the rest of the page keeps working.
+ *
  * `collapsed` closes it with the rail, as Peek's did: it narrows to nothing
  * and fades, in 300ms. What opens and closes the rail stays the app's.
  */
@@ -29,20 +36,15 @@ export interface ListColumnProps {
   actions?: ReactNode
   /** A row between the header and the list that stays put while the list scrolls — a field that adds to the list. */
   above?: ReactNode
-  /**
-   * The room between rows. `rows` (2px) for a list of one kind of row;
-   * `sections` (4px) for groups with labels and dividers of their own.
-   */
-  spacing?: 'rows' | 'sections'
   /** Closes the column with the rail: it narrows to nothing and fades. */
   collapsed?: boolean
-  /** The rows. */
+  /** The rows, 2px apart. Groups are headed by a `CollapsibleSection` or a `SectionHeader`. */
   children: ReactNode
   /** Placement only. */
   className?: string
 }
 
-export function ListColumn({ title, chevron = false, actions, above, spacing = 'rows', collapsed = false, children, className }: ListColumnProps) {
+function Column({ title, chevron = false, actions, above, collapsed = false, children, className, broken = false }: ListColumnProps & { broken?: boolean }) {
   return (
     <div
       className={cn(
@@ -55,9 +57,30 @@ export function ListColumn({ title, chevron = false, actions, above, spacing = '
     >
       <ContainerHeader title={title} chevron={chevron} actions={actions} />
       {above}
-      <ScrollArea className="flex-1" contentClassName={cn('flex flex-col px-3 pt-4 pb-3', spacing === 'rows' ? 'gap-0.5' : 'gap-1')}>
-        {children}
-      </ScrollArea>
+      {broken ? (
+        // The message takes the room the list had and centres itself in it (Katerina, 19 September).
+        <div className="flex min-h-0 flex-1 flex-col px-3">{children}</div>
+      ) : (
+        <ScrollArea className="flex-1" contentClassName="flex flex-col gap-0.5 px-3 pt-4 pb-3">
+          {children}
+        </ScrollArea>
+      )}
     </div>
   )
 }
+
+export function ListColumn(props: ListColumnProps) {
+  return (
+    <ErrorBoundary
+      label="list panel"
+      frame={(message) => (
+        // Only the name comes back with the message: the actions and the row above may be what threw.
+        <Column title={props.title} chevron={props.chevron} collapsed={props.collapsed} className={props.className} broken>
+          {message}
+        </Column>
+      )}
+    >
+      <Column {...props} />
+    </ErrorBoundary>
+  )
+}

package/src/Menu.mdx

@@ -140,8 +140,11 @@ Four surfaces used to claim menu items of nothing.
 
 A menu whose rows are `px-3` (tall picker rows) aligns its headings by passing
 `className="px-3"` to `MenuSection` — the heading row is `px-2` by default,
-matching the default rows. A `Divider` inside a menu needs nothing: the panel
-already runs it the width of the rows it separates.
+matching the default rows.
+
+**Between groups, a `MenuSeparator`**: the line, the width of the rows it
+separates, with its own 4px above and below. Not a `Divider`, whose room is
+its caller's.
 
 ## Props
 

package/src/Menu.stories.tsx

@@ -1,9 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { IconCopy, IconDots, IconPencil, IconSquareRounded, IconTrash } from '@tabler/icons-react'
 import { Button } from './Button'
-import { Divider } from './Divider'
 import { IconButton } from './IconButton'
-import { Menu, MenuItem, MenuPanel, MenuRow, MenuSection, MenuSub } from './Menu'
+import { Menu, MenuItem, MenuPanel, MenuRow, MenuSection, MenuSeparator, MenuSub } from './Menu'
 import { SectionLabel } from './SectionLabel'
 
 /**
@@ -41,7 +40,7 @@ export const Items: Story = {
     <MenuPanel className="min-w-[180px]">
       <MenuItem label="Rename" leading={icon(IconPencil)} onClick={() => {}} />
       <MenuItem label="Duplicate" leading={icon(IconCopy)} shortcut="Ctrl+D" onClick={() => {}} />
-      <Divider className="my-1" />
+      <MenuSeparator />
       <MenuItem label="Delete" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
     </MenuPanel>
   ),
@@ -57,7 +56,7 @@ export const Sections: Story = {
         <MenuItem label="Item one" selected onClick={() => {}} />
         <MenuItem label="Item two" onClick={() => {}} />
       </MenuSection>
-      <Divider className="my-1" />
+      <MenuSeparator />
       <MenuSection label="Another section">
         <MenuItem label="Option one" onClick={() => {}} />
         <MenuItem label="Option two" onClick={() => {}} />
@@ -75,7 +74,7 @@ export const WithARow: Story = {
         <span className="min-w-0 flex-1 truncate text-body-2 text-text-primary">Item one</span>
         <SectionLabel tone="secondary">Label</SectionLabel>
       </MenuRow>
-      <Divider className="my-1" />
+      <MenuSeparator />
       <MenuItem label="An action" onClick={() => {}} />
     </MenuPanel>
   ),
@@ -99,7 +98,7 @@ export const FromATrigger: Story = {
         <MenuItem label="Item two" onClick={() => {}} />
         <MenuItem label="Item three" onClick={() => {}} />
       </MenuSub>
-      <Divider className="my-1" />
+      <MenuSeparator />
       <MenuItem label="Delete" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
     </Menu>
   ),
@@ -149,7 +148,7 @@ export const OnACard: Story = {
             <MenuItem label="Item two" onClick={() => {}} />
           </MenuSub>
         </MenuSection>
-        <Divider className="my-1" />
+        <MenuSeparator />
         <MenuItem label="Delete" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
       </Menu>
     </div>

package/src/Menu.test.tsx

@@ -11,7 +11,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render, screen, waitFor } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 import { Button } from './Button'
-import { Menu, MenuItem, MenuPanel, MenuSection, MenuSub } from './Menu'
+import { Menu, MenuItem, MenuPanel, MenuSection, MenuSeparator, MenuSub } from './Menu'
 
 afterEach(cleanup)
 
@@ -269,6 +269,24 @@ describe('Menu', () => {
  * plugin already owns the keyboard — so `MenuItem` and `MenuSection` have to
  * work with no `Menu` above them.
  */
+describe('MenuSeparator', () => {
+  // UIG-14: the line between groups brings its own 4px above and below; a plain
+  // Divider left that to each caller, and Peek's main menus had none.
+  it('is a separator with its own room, the width of the rows', async () => {
+    render(
+      <Menu open trigger={<Button>More</Button>}>
+        <MenuItem label="One" />
+        <MenuSeparator />
+        <MenuItem label="Two" />
+      </Menu>,
+    )
+    const line = await screen.findByRole('separator')
+    const classes = (line.getAttribute('class') ?? '').split(' ')
+    expect(classes).toContain('my-1')
+    expect(classes).toContain('mx-0')
+  })
+})
+
 describe('rows on a bare MenuPanel', () => {
   /**
    * It is a button, and it does NOT claim to be a menu item. ARIA requires a

package/src/Menu.tsx

@@ -2,7 +2,7 @@ import { createContext, useContext, type ComponentPropsWithRef, type ReactElemen
 import { IconChevronRight } from '@tabler/icons-react'
 import { Menu as BaseMenu } from '@base-ui/react/menu'
 import { cn } from './cn'
-import { DividerInPanel } from './Divider'
+import { Divider, DividerInPanel } from './Divider'
 import { triggerDisabled } from './triggerDisabled'
 import { ScrollArea } from './ScrollArea'
 import { Kbd } from './Kbd'
@@ -590,6 +590,16 @@ export function MenuSection({ label, children, className }: { label: string; chi
   )
 }
 
+/**
+ * The line between two groups of a menu, with its own 4px above and below
+ * (UIG-14, Katerina 19 September). A plain `Divider` left that room to each
+ * caller, and Peek's menus drew it three ways — none, 4px, 4px and inset — so
+ * the lines in its main menus touched the rows.
+ */
+export function MenuSeparator() {
+  return <Divider className="my-1" />
+}
+
 /** A non-interactive row inside a menu, at the item's own geometry. */
 export function MenuRow({ children, className }: { children: ReactNode; className?: string }) {
   return <div className={cn('flex items-center gap-2 px-2 py-1.5', className)}>{children}</div>