@estiva-app/ui 0.9.0 → 0.10.1

package/src/MenuItem.stories.tsx

@@ -1,98 +1,135 @@
-import type { Meta, StoryObj } from '@storybook/react-vite'
-import { IconCopy, IconPin, IconTrash } from '@tabler/icons-react'
-import { Avatar } from './Avatar'
-import { EnterHint, Menu, MenuItem } from './Menu'
-
-/**
- * One row of a menu. Anatomy: `leading` (a 16px icon or an Avatar) · label
- * with an optional `description` line · one thing at the right edge —
- * `trailing` (any hint), else `shortcut` (the kbd chip), else the `submenu`
- * chevron. Stories sit inside a pinned-open Menu so the row is seen on the
- * surface it lives on.
- */
-const meta = {
-  title: 'Overlays/MenuItem',
-  component: MenuItem,
-  decorators: [
-    (Story) => (
-      <div className="flex min-h-[120px] w-full items-center justify-center">
-        <Menu onClose={() => {}} className="static w-72">
-          <Story />
-        </Menu>
-      </div>
-    ),
-  ],
-  args: { label: 'Rename', onClick: () => {} },
-  argTypes: {
-    onClick: { control: false },
-    leading: { control: false },
-    trailing: { control: false },
-  },
-} satisfies Meta<typeof MenuItem>
-
-export default meta
-type Story = StoryObj<typeof meta>
-
-export const Default: Story = {}
-
-export const WithAnIcon: Story = {
-  args: { label: 'Pin', leading: <IconPin size={16} stroke={1.5} className="text-text-secondary" /> },
-}
-
-export const WithAShortcut: Story = {
-  args: { label: 'Copy link', leading: <IconCopy size={16} stroke={1.5} className="text-text-secondary" />, shortcut: 'Ctrl+C' },
-}
-
-/** The row opens another menu. */
-export const Submenu: Story = {
-  args: { label: 'Move to…', submenu: true },
-}
-
-/** A person as a row — the face, the name, a second line, a trailing hint. Peek's mention rows. */
-export const APerson: Story = {
-  args: {
-    label: 'Ana Duarte',
-    description: 'Product designer',
-    leading: <Avatar name="Ana Duarte" size={32} />,
-    trailing: <EnterHint />,
-  },
-}
-
-/** The submenu's chosen value. */
-export const Selected: Story = {
-  args: { label: 'Newest first', selected: true },
-}
-
-export const Destructive: Story = {
-  args: { label: 'Delete', destructive: true, leading: <IconTrash size={16} stroke={1.5} className="text-error-default" /> },
-}
-
-/** Every shape on one canvas. */
-export const AllVariants: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <>
-      <MenuItem label="Bare" onClick={() => {}} />
-      <MenuItem label="With an icon" leading={<IconPin size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => {}} />
-      <MenuItem label="With a shortcut" shortcut="Ctrl+K" onClick={() => {}} />
-      <MenuItem label="Icon and shortcut" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} shortcut="Ctrl+C" onClick={() => {}} />
-      <MenuItem label="Opens another menu" submenu onClick={() => {}} />
-      <MenuItem label="Ana Duarte" description="Product designer" leading={<Avatar name="Ana Duarte" size={32} />} trailing={<EnterHint />} onClick={() => {}} />
-      <MenuItem label="The chosen value" selected onClick={() => {}} />
-      <MenuItem label="Destructive" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
-      <MenuItem label="A very long label that runs out of room and truncates" onClick={() => {}} />
-    </>
-  ),
-}
-
-/** The tall picker row — 48px, px-3, a 32px face or tile, the description line, and the hint while highlighted. TopicMenu, MentionMenu, the files menu and the launcher all draw this row. */
-export const Tall: Story = {
-  args: {
-    size: 'tall',
-    label: 'Ana Duarte',
-    description: 'Product designer',
-    leading: <Avatar name="Ana Duarte" size={32} />,
-    selected: true,
-    trailing: <EnterHint />,
-  },
-}
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconCopy, IconPin, IconTrash } from '@tabler/icons-react'
+import { Avatar } from './Avatar'
+import { useRef, useState } from 'react'
+import { Button } from './Button'
+import { Divider } from './Divider'
+import { EnterHint, Menu, MenuItem, MenuPanel, MenuSub } from './Menu'
+
+/**
+ * One row of a menu. Anatomy: `leading` (a 16px icon or an Avatar) · label
+ * with an optional `description` line · one thing at the right edge —
+ * `trailing` (any hint), else `shortcut` (the kbd chip), else the `submenu`
+ * chevron. Stories sit on a `MenuPanel` — the menu's surface, drawn without
+ * its behaviour — so the row is seen where it lives. A live menu portals and
+ * places itself, so it cannot stand in the page (Katerina, D25); **Menu →
+ * FromATrigger** is where the keyboard and the placement are.
+ */
+const meta = {
+  title: 'Overlays/MenuItem',
+  component: MenuItem,
+  decorators: [
+    (Story) => (
+      <div className="flex min-h-[120px] w-full items-center justify-center">
+        <MenuPanel className="w-72">
+          <Story />
+        </MenuPanel>
+      </div>
+    ),
+  ],
+  args: { label: 'Rename', onClick: () => {} },
+  argTypes: {
+    onClick: { control: false },
+    leading: { control: false },
+    trailing: { control: false },
+  },
+} satisfies Meta<typeof MenuItem>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+export const WithAnIcon: Story = {
+  args: { label: 'Pin', leading: <IconPin size={16} stroke={1.5} className="text-text-secondary" /> },
+}
+
+export const WithAShortcut: Story = {
+  args: { label: 'Copy link', leading: <IconCopy size={16} stroke={1.5} className="text-text-secondary" />, shortcut: 'Ctrl+C' },
+}
+
+/** The row opens another menu. */
+export const Submenu: Story = {
+  args: { label: 'Move to…', submenu: true },
+}
+
+/**
+ * The submenu, working. The story above draws the row at rest — the chevron is
+ * the whole affordance — but a row that opens another menu can only be tried
+ * inside a real one, so here is one.
+ *
+ * Hover **Move to…**, or arrow onto it and press →. The panel opens beside the
+ * row, flips to the other side at a screen edge, and stays open while you
+ * cross the diagonal into it.
+ *
+ * From the keyboard: → opens it and leaves the highlight on the row, ↓ steps
+ * into it, and ← closes it and puts the highlight back on the row. Measured in
+ * that order — → then ← alone does nothing, because focus has not entered yet.
+ */
+export const SubmenuLive: Story = {
+  parameters: { controls: { disable: true } },
+  decorators: [(Story) => <Story />],
+  render: () => (
+    <div className="flex min-h-[220px] w-full items-start justify-center pt-4">
+      <Menu trigger={<Button variant="outlined">Open the menu</Button>}>
+        <MenuItem label="Rename" onClick={() => {}} />
+        <MenuSub label="Move to…">
+          <MenuItem label="Item one" onClick={() => {}} />
+          <MenuItem label="Item two" onClick={() => {}} />
+          <MenuItem label="Item three" onClick={() => {}} />
+        </MenuSub>
+        <Divider className="my-1" />
+        <MenuItem label="Delete" destructive onClick={() => {}} />
+      </Menu>
+    </div>
+  ),
+}
+
+/** A person as a row — the face, the name, a second line, a trailing hint. Peek's mention rows. */
+export const APerson: Story = {
+  args: {
+    label: 'Ana Duarte',
+    description: 'Product designer',
+    leading: <Avatar name="Ana Duarte" size={32} />,
+    trailing: <EnterHint />,
+  },
+}
+
+/** The submenu's chosen value. */
+export const Selected: Story = {
+  args: { label: 'Item one', selected: true },
+}
+
+export const Destructive: Story = {
+  args: { label: 'Delete', destructive: true, leading: <IconTrash size={16} stroke={1.5} className="text-error-default" /> },
+}
+
+/** Every shape on one canvas. */
+export const AllVariants: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <>
+      <MenuItem label="Bare" onClick={() => {}} />
+      <MenuItem label="With an icon" leading={<IconPin size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => {}} />
+      <MenuItem label="With a shortcut" shortcut="Ctrl+K" onClick={() => {}} />
+      <MenuItem label="Icon and shortcut" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} shortcut="Ctrl+C" onClick={() => {}} />
+      <MenuItem label="Opens another menu" submenu onClick={() => {}} />
+      <MenuItem label="Ana Duarte" description="Product designer" leading={<Avatar name="Ana Duarte" size={32} />} trailing={<EnterHint />} onClick={() => {}} />
+      <MenuItem label="The chosen value" selected onClick={() => {}} />
+      <MenuItem label="Destructive" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
+      <MenuItem label="A very long label that runs out of room and truncates" onClick={() => {}} />
+    </>
+  ),
+}
+
+/** The tall picker row — 48px, px-3, a 32px face or tile, the description line, and the hint while highlighted. TopicMenu, MentionMenu, the files menu and the launcher all draw this row. */
+export const Tall: Story = {
+  args: {
+    size: 'tall',
+    label: 'Ana Duarte',
+    description: 'Product designer',
+    leading: <Avatar name="Ana Duarte" size={32} />,
+    selected: true,
+    trailing: <EnterHint />,
+  },
+}

package/src/NavItem.mdx

@@ -34,7 +34,7 @@ count — a muted mono number whose tooltip says what it counts.
 import { NavItem } from '@estiva-app/ui'
 
 <NavItem
-  href="#/documents"
+  href="/documents"
   label="Documents"
   icon={<IconListDetails size={16} stroke={1.5} />}
   count={openCount}

package/src/PersonTrigger.mdx

@@ -29,23 +29,29 @@ fill, because the face fills the whole control.
 ## How
 
 ```tsx
-import { PersonTrigger } from '@estiva-app/ui'
+import { Menu, PersonTrigger } from '@estiva-app/ui'
 
-<PersonTrigger name={me.name} picture={me.picture} open={open}
-  onMouseDown={(e) => e.stopPropagation()} onClick={() => setOpen((v) => !v)} />
+<Menu trigger={<PersonTrigger name={me.name} picture={me.picture} />}>
+  …
+</Menu>
 ```
 
-- `open` holds the row's hover fill while the menu is up, and feeds
-  `aria-expanded`.
-- **The accessible name**: the row shape is named by the visible name —
-  do **not** add an `aria-label`, it would override the person. The
-  `compact` face has no visible text, so there an `aria-label` is
-  required.
-- A toggle trigger must swallow its `mousedown` (as above) or the menu's
-  outside-click dismiss turns each press into close-then-reopen — the
-  trap is spelled out on the Menu page.
-- It is a native `<button>` on Base UI's Button: it takes a `ref` and
-  every native button prop — anchor your menu on it.
+- **Hand it to the menu and write nothing else.** Since stage 4 a `Menu` owns
+  its trigger, so the open state, the toggle, `aria-expanded`, the placement
+  and the focus return are all its. The `onMouseDown` + `stopPropagation`
+  guard this page used to show is gone with the trap it worked around.
+- `open` is still there for a caller driving something that is not a `Menu`;
+  it holds the row's hover fill and feeds `aria-expanded`. Under a `Menu` it
+  is unnecessary — the trigger carries `data-popup-open`, which holds the
+  same fill.
+- **The accessible name comes from the person, in both shapes.** The row is
+  named by its visible name, and the `compact` face — which has no visible
+  text — takes the same name through an `aria-label` of its own, so nothing
+  is owed. Until 2026-09-08 that face announced **"AD"**: the initials, read
+  as text. Pass an `aria-label` only to name what it *opens* rather than who
+  it shows; `IdentityMenu`'s compact shape says "Account menu".
+- It is a native `<button>` on Base UI's Button: it takes a `ref` and every
+  native button prop.
 
 ## Keys
 

package/src/PersonTrigger.tsx

@@ -35,7 +35,24 @@ export function PersonTrigger({ name, picture, fallback, size, open = false, com
         type="button"
         aria-haspopup="menu"
         aria-expanded={open}
-        className={cn('cursor-pointer rounded-full focus:outline-none', className)}
+        /*
+          The face alone is an icon-only control, so it owes a name. It has
+          one already — the person — and taking it from there means no caller
+          can forget: measured 2026-09-08, this button announced **"AD"**, the
+          initials, with no `aria-label` anywhere. A caller that wants to name
+          the destination rather than the person still can, and `IdentityMenu`
+          does ("Account menu").
+        */
+        aria-label={props['aria-label'] ?? name ?? fallback}
+        /*
+          No `focus:outline-none` here any more. It removed the browser's ring
+          and put nothing in its place, so this control — the account trigger
+          in Peek's top bar — had **no visible focus at all** (measured
+          2026-09-08: `outline: solid 2px rgba(0,0,0,0)`, no shadow). Left
+          alone it wears the same ring `Button`, `IconButton` and a `Tab`
+          wear, which is the ring the rest of the package already relies on.
+        */
+        className={cn('cursor-pointer rounded-full', className)}
         {...props}
       >
         <Avatar name={name} src={picture} size={size ?? 36} />
@@ -50,6 +67,11 @@ export function PersonTrigger({ name, picture, fallback, size, open = false, com
       className={cn(
         'flex h-8 cursor-pointer items-center gap-1.5 rounded-md pl-1.5 pr-1.5 text-body-2 text-text-primary transition-colors hover:bg-bg-hover',
         open && 'bg-bg-hover',
+        // Under a `Menu` the open state is Base UI's, not a prop: the trigger
+        // carries `data-popup-open` while its menu is up, and sets its own
+        // `aria-expanded`. Both spellings hold the fill, so this works whether
+        // the caller drives it or the menu does.
+        'data-[popup-open]:bg-bg-hover',
         className,
       )}
       {...props}

package/src/Popover.mdx

@@ -0,0 +1,130 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as PopoverStories from './Popover.stories'
+
+<Meta of={PopoverStories} />
+
+# Popover
+
+A floating panel from a trigger: the same elevated surface a **Menu** draws,
+with none of a menu's semantics. Its contents are contents — Tab walks them
+in order, nothing is a menu item, and typing goes where you are typing.
+
+<Canvas of={PopoverStories.Default} />
+
+## When
+
+- A small form beside its trigger: rename, a date, a link address.
+- A row of controls over a text selection — a formatting toolbar.
+- A panel of settings or toggles.
+- Anything you would have reached for `Menu` for because you wanted the box.
+
+<Canvas of={PopoverStories.AToolbar} />
+
+## When not
+
+- A list of actions → **Menu**. That is what the arrow keys, the typeahead
+  and `role="menuitem"` are for, and a Popover has none of them.
+- One value from a known set → **Select**.
+- A word for a control → **WithTooltip** — it cannot be pointed at, which
+  is the difference.
+- More of a thing on hover → **PreviewCard**.
+- A title, a body and a footer, with the page behind it out of reach →
+  **DialogShell**.
+
+## How
+
+The panel owns the trigger, exactly as `Menu` does: hand it the control and the
+contents, and write no open state, no placement and no dismiss.
+
+```tsx
+import { Popover } from '@estiva-app/ui'
+
+<Popover trigger={<Button variant="outlined">Rename</Button>} ariaLabel="Rename this">
+  <TextInput value={name} onChange={onChange} aria-label="Name" />
+</Popover>
+```
+
+- **`trigger`** is any element that forwards its ref and spreads its props —
+  this package's `Button`, `IconButton` and `PersonTrigger` all do.
+- **Focus lands on the first thing in the panel** when it opens — the field, in
+  the panel this component exists for — and goes back to the trigger when it
+  closes. Nothing is written to get that.
+- **`actionsRef`** gives `close()`, for the Cancel and Save a form panel ends
+  with. Unlike a menu row, a control inside a panel does not close it by being
+  pressed: it is content, and content may be used more than once.
+- **`align="right"`** hangs the panel's right edge from the trigger's.
+- **`side` is a preference, not a promise.** It says which side to try; Base UI
+  measures the room and flips when there is none — which is the reason the
+  placement is its job rather than arithmetic of ours. **A panel holding a
+  `Toolbar` asks for `top`**: a strip of controls acts on what is under it, so
+  it stands over that rather than on top of it.
+- **`open` / `onOpenChange`** are there for a caller that must know or must
+  force it. Leave them off and the panel keeps its own state.
+- `ariaLabel` names the panel. A panel with a visible heading can point at it
+  with `aria-labelledby` instead.
+- Width, padding and internal rhythm are yours, through `className` — the
+  panel is a surface, not a layout.
+
+<Canvas of={PopoverStories.FromATrigger} />
+
+### A panel with no trigger
+
+A toolbar over a text selection hangs from the selection, and there is no
+control that opened it. That is the one case with nothing for Base UI to watch,
+so it is the one case the caller drives:
+
+```tsx
+<Popover
+  anchor={selectionRect}
+  open={selectionRect !== null}
+  onOpenChange={(open) => !open && setSelectionRect(null)}
+  ariaLabel="Formatting"
+>
+```
+
+- **`anchor`** takes an element or a rect. A new rect moves the panel, so
+  re-measuring as the selection changes is all the tracking needed.
+- **It does not take focus**, on purpose: the person is still in the text, and
+  a toolbar that moved the caret out of it would end the edit it exists to
+  serve. `finalFocus` is therefore only for a panel something inside it *did*
+  take focus into — a field the person clicked.
+- **Render it always and toggle `open`.** Not `{rect && <Popover…>}`: mounting
+  the panel only while it is open takes Base UI's state machine with it, and
+  its exits go too — measured, Escape and re-opening both became intermittent.
+- **Two traps that come with this shape**, both measured rather than reasoned
+  about, and both belonging to the caller:
+  - **Escape must not reopen what it just closed.** The keydown closes the
+    panel; if focus is on the element that reads the selection, the same key's
+    *keyup* re-reads a selection that is still perfectly alive. Ignore Escape
+    in that handler.
+  - **A press in the text is a press outside the panel.** It closes it, and the
+    same gesture's new selection opens it again. That is right, but it means
+    the panel is remade rather than moved.
+
+**The gap, stated: an anchored panel cannot be reached by keyboard.** There is
+no trigger to Tab from and it does not take focus, so everything in one must be
+reachable another way — a shortcut, a menu. A panel that is the only route to
+something belongs on a `trigger`.
+
+<Canvas of={PopoverStories.FromASelection} />
+
+### When the side it asks for has no room
+
+<Canvas of={PopoverStories.FlippedForRoom} />
+
+## Keys
+
+| Input | What happens |
+|---|---|
+| click / Enter / Space on the trigger | opens, and focus moves to the first thing inside |
+| Tab / Shift-Tab | walks the contents, in order |
+| Escape | closes, and gives focus back to the trigger |
+| a press outside | closes |
+| a second press of the trigger | closes — it is the trigger's own toggle, not a press outside |
+
+An anchored panel has the same two exits — Escape and a press outside — but no
+trigger row: it is not opened from the keyboard and does not take focus.
+
+## Props
+
+<Controls of={PopoverStories.FromATrigger} />