@estiva-app/ui 0.12.9 → 0.13.0

package/src/InlineChip.test.tsx

@@ -0,0 +1,81 @@
+// @vitest-environment jsdom
+/**
+ * What the InlineChip page claims, pinned: without `href` it is a label, with
+ * one it is a link a router can take; every tone keeps the shape and its own
+ * size and colour through `cn()`; the icon sits in its 16px box; and the class
+ * function a string-only renderer uses gives the same classes as the component.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { INLINE_CHIP_CLASSES, INLINE_CHIP_TONE_CLASSES, InlineChip, inlineChipClassName } from './InlineChip'
+
+afterEach(cleanup)
+
+const classesOf = (el: Element) => el.getAttribute('class')?.split(' ').filter(Boolean) ?? []
+
+describe('InlineChip', () => {
+  it('without href it is a label, not a link', () => {
+    render(<InlineChip>Label</InlineChip>)
+    const chip = screen.getByText('Label')
+    expect(chip.tagName).toBe('SPAN')
+    expect(screen.queryByRole('link')).toBeNull()
+  })
+
+  it('with href it is a link, and a router app takes the click with the href intact', async () => {
+    const onClick = vi.fn((event: { preventDefault: () => void }) => event.preventDefault())
+    render(
+      <InlineChip href="/somewhere" onClick={onClick}>
+        Label
+      </InlineChip>,
+    )
+    const link = screen.getByRole('link', { name: 'Label' })
+    await userEvent.click(link)
+    expect(onClick).toHaveBeenCalledTimes(1)
+    expect(link.getAttribute('href')).toBe('/somewhere')
+  })
+
+  it('is one line high and pinned to the top of the line, in every tone', () => {
+    for (const tone of Object.keys(INLINE_CHIP_TONE_CLASSES) as (keyof typeof INLINE_CHIP_TONE_CLASSES)[]) {
+      const classes = inlineChipClassName(tone).split(' ')
+      expect(classes).toContain('align-top')
+      expect(classes).toContain('mx-0.5')
+      // One height only: 1.4em of the body size, or the same 19.6px written out where the text is smaller.
+      const heights = classes.filter((c) => c.startsWith('h-'))
+      expect(heights).toEqual([tone === 'quiet' ? 'h-[19.6px]' : 'h-[1.4em]'])
+    }
+  })
+
+  it('each tone keeps its size and its colour through cn()', () => {
+    const neutral = inlineChipClassName('neutral').split(' ')
+    expect(neutral).toContain('text-body-2')
+    expect(neutral).toContain('text-text-primary')
+    const person = inlineChipClassName('person').split(' ')
+    expect(person).toContain('text-body-2')
+    expect(person).toContain('text-accent-primary')
+    const urgent = inlineChipClassName('urgent').split(' ')
+    expect(urgent).toContain('text-warning-default')
+    // quiet is smaller: its caption size replaces the body size, and its colour survives beside it
+    const quiet = inlineChipClassName('quiet').split(' ')
+    expect(quiet).toContain('text-caption')
+    expect(quiet).not.toContain('text-body-2')
+    expect(quiet).toContain('text-text-muted')
+  })
+
+  it('the component and the class function give the same classes', () => {
+    render(
+      <InlineChip tone="person" className="max-w-[24ch]">
+        Label
+      </InlineChip>,
+    )
+    expect(classesOf(screen.getByText('Label'))).toEqual(inlineChipClassName('person', 'max-w-[24ch]').split(' '))
+    expect(INLINE_CHIP_CLASSES.split(' ').every((c) => classesOf(screen.getByText('Label')).includes(c))).toBe(true)
+  })
+
+  it('draws the icon first, in its 16px box', () => {
+    render(<InlineChip icon={<svg data-testid="icon" />}>Label</InlineChip>)
+    const box = screen.getByTestId('icon').parentElement!
+    expect(classesOf(box)).toEqual(expect.arrayContaining(['size-4', 'shrink-0']))
+    expect(box.parentElement!.firstElementChild).toBe(box)
+  })
+})

package/src/InlineChip.tsx

@@ -0,0 +1,90 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react'
+import { cn } from './cn'
+
+/**
+ * A word in a sentence that stands for something: a person, a place, a thing
+ * written into running text. One line high, level with the words around it.
+ *
+ * The shape is Peek's inline chip (D67, Peek PR #206, 2026-09-13), class for
+ * class, moved into the package so both apps draw one (UIG-27). Three things
+ * changed on the way, all ruled by Katerina:
+ *
+ * - the person tone is `person`, not `mention` — every chip here is a
+ *   mention of something;
+ * - the alignment is a class (`align-top h-[1.4em]`), not a `style` object,
+ *   so it is part of the class list like every other size in the package;
+ * - a chip that leads somewhere takes `href` and `onClick`, the way `NavItem`
+ *   does: the package draws an anchor, the app's router takes the click.
+ *
+ * **Why `align-top` and `1.4em`.** `1.4em` is the body text's line height,
+ * so the chip is exactly one line tall; `vertical-align: top` pins it to the
+ * line box, which keeps the line at 19.6px and the chip's words level with
+ * the sentence's, with or without an icon. Measured in Peek on 2026-09-13:
+ * `text-bottom` made the line 21.2px and lifted the chip's words 1.6px;
+ * `baseline` lifted them 3.8px once an icon came first.
+ */
+
+/** The shape every tone shares. Exported for a rich-text editor that renders chips from strings. */
+export const INLINE_CHIP_CLASSES =
+  'inline-flex h-[1.4em] items-center gap-1 rounded-sm px-1 mx-0.5 align-top text-body-2 font-normal select-none'
+
+/** What a chip is made of, by what it stands for. */
+export const INLINE_CHIP_TONE_CLASSES = {
+  /** A thing or a place — anything that is not a person. */
+  neutral: 'bg-bg-active text-text-primary',
+  /** A person. */
+  person: 'bg-accent-muted text-accent-primary',
+  /** A person, called urgently. */
+  urgent: 'bg-warning-muted text-warning-default',
+  /**
+   * A reference nobody could resolve — still a mention, just an anonymous one.
+   * Its height is the body line's 19.6px written out, because `1.4em` here is
+   * the caption's em: 16.8px, with the letters 1.8px above the sentence's
+   * baseline. At 19.6px they sit 0.4px off it (measured 2026-09-14; Peek's
+   * copy of this chip still has the 16.8px box).
+   */
+  quiet: 'h-[19.6px] bg-bg-active text-text-muted font-mono text-caption',
+} as const
+
+export type InlineChipTone = keyof typeof INLINE_CHIP_TONE_CLASSES
+
+/** The chip's classes for a tone, with anything the caller adds. For renderers that cannot use the component. */
+export function inlineChipClassName(tone: InlineChipTone, className?: string) {
+  return cn(INLINE_CHIP_CLASSES, INLINE_CHIP_TONE_CLASSES[tone], className)
+}
+
+export interface InlineChipProps extends Omit<ComponentPropsWithRef<'a'>, 'children'> {
+  /** What the chip stands for. Default `neutral`. */
+  tone?: InlineChipTone
+  /** Drawn before the label in a 16px box: a 16px icon, or a 14px one it centres. */
+  icon?: ReactNode
+  /**
+   * Where the chip leads. With it the chip is an anchor; without it, a span.
+   * A router app passes `onClick` too, and navigates there itself.
+   */
+  href?: string
+  children: ReactNode
+}
+
+export function InlineChip({ tone = 'neutral', icon, href, className, children, ...props }: InlineChipProps) {
+  const body = (
+    <>
+      {icon && <span className="flex size-4 shrink-0 items-center justify-center text-text-secondary">{icon}</span>}
+      {children}
+    </>
+  )
+  const classes = inlineChipClassName(tone, className)
+  // Without somewhere to go it is a label, and a label is not a link.
+  if (href === undefined) {
+    return (
+      <span className={classes} {...(props as ComponentPropsWithRef<'span'>)}>
+        {body}
+      </span>
+    )
+  }
+  return (
+    <a href={href} className={classes} {...props}>
+      {body}
+    </a>
+  )
+}

package/src/Link.mdx

@@ -0,0 +1,59 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as LinkStories from './Link.stories'
+
+<Meta of={LinkStories} />
+
+# Link
+
+A link, in one of four looks. It is a real anchor with a real address, and
+the app decides how it navigates.
+
+<Canvas of={LinkStories.AllVariants} />
+
+## When
+
+- **`text`** — a link written inside text: the info colour, always
+  underlined, dimming on hover.
+- **`quiet`** — a title or a time that is also a link. It takes the colour and
+  size of the text it sits in, and underlines on hover.
+- **`underlined`** — a short "open it there" beside a note. It takes the
+  note's colour, is always underlined, and brightens on hover.
+- **`plain`** — a box or a row that is a link as a whole. No look of its own:
+  what it wraps draws itself.
+- `external` — another site or app: it opens in a new tab, with
+  `noopener noreferrer`.
+
+## When not
+
+- An action — something happens, nothing is navigated to → **Button**.
+- A row of a sidebar → **NavItem**. A tile of a rail → **RailItem**.
+- The trail back up → **Breadcrumb**.
+- A word standing for a person or a thing, drawn in a small box → **InlineChip**
+  with `href`.
+
+## How
+
+```tsx
+import { Link } from '@estiva-app/ui'
+
+<p className="text-body-2">
+  Read <Link href="https://example.com" external>the guide</Link> first.
+</p>
+
+<h3 className="text-body-2 font-semibold text-text-primary">
+  <Link href={itemUrl} variant="quiet" onClick={navigate}>Item one</Link>
+</h3>
+```
+
+- It renders a plain anchor and passes every anchor prop through. A router app
+  passes `onClick`, prevents the default and navigates; the `href` stays a real
+  address, so a modified click or a new tab still works.
+- `quiet` and `underlined` set no size and no colour at rest: put them inside
+  the text whose look they should take.
+- `plain` wraps a block: give the Link `className="block"` and let the child
+  draw the border, the fill and the hover.
+- If your router also exports a `Link`, rename one of them on import.
+
+## Props
+
+<Controls of={LinkStories.Text} />

package/src/Link.stories.tsx

@@ -0,0 +1,102 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Link } from './Link'
+
+const meta = {
+  title: 'Navigation/Link',
+  component: Link,
+  args: { href: '#', variant: 'text', external: false, children: 'a link' },
+  argTypes: {
+    variant: { control: 'inline-radio', options: ['text', 'quiet', 'underlined', 'plain'] },
+  },
+} satisfies Meta<typeof Link>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** Inside written text: the info colour, always underlined. Hover dims it. */
+export const Text: Story = {
+  render: (args) => (
+    <p className="max-w-[480px] text-body-2 text-text-primary">
+      A sentence can hold <Link {...args} /> in the middle of it, and the words around it read on.
+    </p>
+  ),
+}
+
+/** A title, or a small time, that is also a link: it keeps its text's colour and size, and underlines on hover. */
+export const Quiet: Story = {
+  args: { variant: 'quiet', children: 'Item one' },
+  render: (args) => (
+    <div className="flex flex-col gap-2">
+      <p className="text-body-2 font-semibold text-text-primary">
+        <Link {...args} />
+      </p>
+      <p className="text-caption text-text-secondary">
+        <Link {...args}>2:14 PM</Link>
+      </p>
+    </div>
+  ),
+}
+
+/** Beside a note, a short way to open the thing somewhere else: the note's colour, always underlined. Hover brightens it. */
+export const Underlined: Story = {
+  args: { variant: 'underlined', external: true, children: 'Open it there ↗' },
+  render: (args) => (
+    <p className="max-w-[480px] text-caption text-text-secondary">
+      This can’t be shown here. <Link {...args} />
+    </p>
+  ),
+}
+
+/** No look of its own: what it wraps draws itself — a box, a row. */
+export const Plain: Story = {
+  args: { variant: 'plain', children: undefined },
+  render: (args) => (
+    <Link {...args} className="block w-[280px]">
+      <div className="rounded-lg border border-border-default bg-bg-surface p-3 text-body-2 text-text-primary transition-colors hover:border-border-strong">
+        Item one
+      </div>
+    </Link>
+  ),
+}
+
+/** Another site or app: a new tab, and `noopener noreferrer`. It looks the same; the difference is where it opens. */
+export const External: Story = {
+  args: { external: true, children: 'a page elsewhere' },
+  render: (args) => (
+    <p className="max-w-[480px] text-body-2 text-text-primary">
+      Read <Link {...args} /> in a new tab.
+    </p>
+  ),
+}
+
+/** The four looks, each where it belongs. */
+export const AllVariants: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex max-w-[480px] flex-col gap-4">
+      <p className="text-body-2 text-text-primary">
+        <span className="text-text-secondary">text — </span>a sentence with <Link href="#">a link</Link> in it.
+      </p>
+      <p className="text-body-2 font-semibold text-text-primary">
+        <span className="font-normal text-text-secondary">quiet — </span>
+        <Link href="#" variant="quiet">
+          Item one
+        </Link>
+      </p>
+      <p className="text-caption text-text-secondary">
+        underlined — This can’t be shown here.{' '}
+        <Link href="#" variant="underlined" external>
+          Open it there ↗
+        </Link>
+      </p>
+      <div className="flex flex-col gap-1">
+        <span className="text-body-2 text-text-secondary">plain —</span>
+        <Link href="#" variant="plain" className="block w-[280px]">
+          <div className="rounded-lg border border-border-default bg-bg-surface p-3 text-body-2 text-text-primary transition-colors hover:border-border-strong">
+            Item one
+          </div>
+        </Link>
+      </div>
+    </div>
+  ),
+}

package/src/Link.test.tsx

@@ -0,0 +1,100 @@
+// @vitest-environment jsdom
+/**
+ * What the Link page claims, pinned: it is a real anchor with a real address;
+ * `external` opens a new tab that cannot reach back; a router app takes the
+ * click through `onClick` and the address survives it; each look is its own
+ * class list and `plain` carries none; a ref reaches the anchor.
+ */
+import { createRef } from 'react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Link } from './Link'
+
+afterEach(cleanup)
+
+const classesOf = (el: Element) => el.getAttribute('class')?.split(' ').filter(Boolean) ?? []
+
+describe('Link', () => {
+  it('is an anchor with its address', () => {
+    render(<Link href="/documents">Documents</Link>)
+    const link = screen.getByRole('link', { name: 'Documents' })
+    expect(link.tagName).toBe('A')
+    expect(link.getAttribute('href')).toBe('/documents')
+  })
+
+  it('stays in the same tab unless it is external', () => {
+    render(<Link href="/documents">Documents</Link>)
+    const link = screen.getByRole('link', { name: 'Documents' })
+    expect(link.getAttribute('target')).toBeNull()
+    expect(link.getAttribute('rel')).toBeNull()
+  })
+
+  it('external opens a new tab that cannot reach back into this page', () => {
+    render(
+      <Link href="https://example.com" external>
+        Example
+      </Link>,
+    )
+    const link = screen.getByRole('link', { name: 'Example' })
+    expect(link.getAttribute('target')).toBe('_blank')
+    expect(link.getAttribute('rel')).toBe('noopener noreferrer')
+  })
+
+  it('a router app takes the click through onClick, and the href stays a real address', async () => {
+    const onClick = vi.fn((event: { preventDefault: () => void }) => event.preventDefault())
+    render(
+      <Link href="/documents" onClick={onClick}>
+        Documents
+      </Link>,
+    )
+    await userEvent.click(screen.getByRole('link', { name: 'Documents' }))
+    expect(onClick).toHaveBeenCalledTimes(1)
+    expect(screen.getByRole('link', { name: 'Documents' }).getAttribute('href')).toBe('/documents')
+  })
+
+  it('text is the info colour, always underlined, and is the default', () => {
+    render(<Link href="#">Label</Link>)
+    const classes = classesOf(screen.getByRole('link'))
+    expect(classes).toContain('text-info-default')
+    expect(classes).toContain('underline')
+    expect(classes).toContain('underline-offset-2')
+  })
+
+  it('quiet sets no colour and no size of its own, and underlines on hover', () => {
+    render(
+      <Link href="#" variant="quiet">
+        Label
+      </Link>,
+    )
+    expect(classesOf(screen.getByRole('link'))).toEqual(['hover:underline'])
+  })
+
+  it('underlined sets no colour at rest, is always underlined, and brightens on hover', () => {
+    render(
+      <Link href="#" variant="underlined">
+        Label
+      </Link>,
+    )
+    expect(classesOf(screen.getByRole('link'))).toEqual(['underline', 'underline-offset-2', 'hover:text-text-primary'])
+  })
+
+  it('plain carries no class at all, so what it wraps draws itself', () => {
+    render(
+      <Link href="#" variant="plain">
+        Label
+      </Link>,
+    )
+    expect(classesOf(screen.getByRole('link'))).toEqual([])
+  })
+
+  it('a ref reaches the anchor', () => {
+    const ref = createRef<HTMLAnchorElement>()
+    render(
+      <Link href="#" ref={ref}>
+        Label
+      </Link>,
+    )
+    expect(ref.current?.tagName).toBe('A')
+  })
+})

package/src/Link.tsx

@@ -0,0 +1,58 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react'
+import { cn } from './cn'
+
+/**
+ * A link: an anchor with one of four looks, and nothing else of its own.
+ *
+ * It exists because both apps hand-wrote every link they have — 18 raw `<a>`
+ * on 13 September 2026, in three jobs (UIG-27). The looks are the ones those
+ * links already had, reduced by Katerina's ruling:
+ *
+ * - `text` — a link inside written text: the info colour, always underlined,
+ *   dimming on hover. The look a link in a body of text already had.
+ * - `quiet` — a title or a timestamp that is also a link. It takes the colour
+ *   and size of the text it sits in and underlines on hover. Two looks that
+ *   differed only in their text became this one (her ruling, 13 September).
+ * - `underlined` — a short "open it elsewhere" beside a note. It takes the
+ *   note's colour, is always underlined, and brightens on hover. A dotted
+ *   and a solid version became this one, solid (her ruling, 13 September).
+ * - `plain` — no look at all: a card or a row that is a link draws itself.
+ *
+ * **Navigation is the app's.** The package cannot know a router, so like
+ * `NavItem` it renders a real anchor and passes every anchor prop through: a
+ * router app hands in `onClick`, prevents the default and navigates, and the
+ * `href` stays a real address for a modified click or a new tab.
+ */
+export type LinkVariant = 'text' | 'quiet' | 'underlined' | 'plain'
+
+const VARIANT_CLASSES: Record<LinkVariant, string> = {
+  text: 'text-info-default underline underline-offset-2 hover:opacity-80',
+  quiet: 'hover:underline',
+  underlined: 'underline underline-offset-2 hover:text-text-primary',
+  plain: '',
+}
+
+export interface LinkProps extends ComponentPropsWithRef<'a'> {
+  href: string
+  /** Default `text`. */
+  variant?: LinkVariant
+  /**
+   * Another site, or another app: opens in a new tab, with `noopener
+   * noreferrer` so the page it opens cannot reach back into this one.
+   */
+  external?: boolean
+  children: ReactNode
+}
+
+export function Link({ href, variant = 'text', external = false, className, children, ...props }: LinkProps) {
+  return (
+    <a
+      href={href}
+      {...(external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+      className={cn(VARIANT_CLASSES[variant], className)}
+      {...props}
+    >
+      {children}
+    </a>
+  )
+}

package/src/Menu.test.tsx

@@ -326,3 +326,23 @@ describe('rows on a bare MenuPanel', () => {
     expect(screen.queryByRole('group')).toBeNull()
   })
 })
+
+/** As `Popover`: the padding is the content's, and a caller sets it there
+ *  (PLAN Finding 60 — Peek's Later menu asked for `p-1` on `className` and got
+ *  12px from 0.12.6 on). */
+describe('Menu, padding', () => {
+  it('takes a caller’s padding on contentClassName, instead of the 8px', async () => {
+    render(
+      <Menu trigger={<Button>Open</Button>} contentClassName="p-1">
+        <MenuItem label="Item one" onClick={() => {}} />
+      </Menu>,
+    )
+    await userEvent.click(screen.getByRole('button', { name: 'Open' }))
+    const row = await screen.findByRole('menuitem', { name: 'Item one' })
+    // The scrolling content is the box that carries the separator rule.
+    const content = row.closest('[class*="role=separator"]') as HTMLElement
+    const classes = content.className.split(/\s+/)
+    expect(classes).toContain('p-1')
+    expect(classes).not.toContain('p-2')
+  })
+})

package/src/Menu.tsx

@@ -142,8 +142,18 @@ export interface MenuProps {
    *  closes the menu by itself, so this is only for content that is not one. */
   actionsRef?: RefObject<{ close: () => void; unmount: () => void } | null>
   children: ReactNode
-  /** On the menu's surface — its width, its internal rhythm. */
+  /** On the menu's surface — its width. **Not its padding**: see
+   *  `contentClassName`. */
   className?: string
+  /**
+   * The padding around the rows, as a class. Default `p-2`, 8px.
+   *
+   * It is on the scrolling content, not on the panel, so the scrollbar hugs the
+   * panel's edge (D63) — and so a padding class on `className` adds to it
+   * rather than replacing it. Peek's Later menu asked for `p-1` there and got
+   * 12px from `0.12.6` on (PLAN Finding 60). Set it here.
+   */
+  contentClassName?: string
 }
 
 /**
@@ -163,7 +173,7 @@ const VIEWPORT_PAD = 8
 const HOVER_OPEN_DELAY = 0
 const HOVER_CLOSE_DELAY = 150
 
-export function Menu({ trigger, align = 'left', openOnHover = false, open, onOpenChange, actionsRef, children, className }: MenuProps) {
+export function Menu({ trigger, align = 'left', openOnHover = false, open, onOpenChange, actionsRef, children, className, contentClassName }: MenuProps) {
   return (
     <BaseMenu.Root
       open={open}
@@ -227,9 +237,11 @@ export function Menu({ trigger, align = 'left', openOnHover = false, open, onOpe
              * as tall as Floating UI allowed.
              *
              * A caller's `className` still lands on the panel, so a caller
-             * asking for different padding needs `contentClassName` — which is
-             * what `MenuPanel` is for when one is used on its own. */}
-            <ScrollArea viewportClassName="max-h-[var(--available-height)]" contentClassName="flex flex-col p-2 [&>[role=separator]]:mx-0">
+             * asking for different padding needs `contentClassName`. That
+             * sentence was written at 0.12.6 and the prop was not: a `p-1` on
+             * `className` added 4px to these 8px instead of replacing them
+             * (PLAN Finding 60). The prop exists now. */}
+            <ScrollArea viewportClassName="max-h-[var(--available-height)]" contentClassName={cn('flex flex-col p-2 [&>[role=separator]]:mx-0', contentClassName)}>
               <MenuContext.Provider value={{ openOnHover }}>{children}</MenuContext.Provider>
             </ScrollArea>
           </BaseMenu.Popup>

package/src/Person.stories.tsx

@@ -3,7 +3,7 @@ import { Person } from './Person'
 
 /** A face beside a name — never a key. */
 const meta = {
-  title: 'Primitives/Person',
+  title: 'Components/Person',
   component: Person,
   args: { name: 'Ana Duarte', size: 20 },
 } satisfies Meta<typeof Person>

package/src/PersonTrigger.stories.tsx

@@ -3,7 +3,7 @@ import { PersonTrigger } from './PersonTrigger'
 
 /** The person, as the button that opens the account menu. The menu itself stays in the app. */
 const meta = {
-  title: 'Primitives/PersonTrigger',
+  title: 'Components/PersonTrigger',
   component: PersonTrigger,
   args: { name: 'Ana Duarte', open: false, compact: false },
 } satisfies Meta<typeof PersonTrigger>

package/src/Popover.mdx

@@ -64,8 +64,10 @@ import { Popover } from '@estiva-app/ui'
   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.
+- **Width goes on `className`, padding on `contentClassName`.** The padding
+  sits on the scrolling content so the scrollbar hugs the panel's edge, and a
+  padding class on `className` adds to it rather than replacing it. Default
+  8px; **a toolbar asks for `contentClassName="p-1"`**.
 
 <Canvas of={PopoverStories.FromATrigger} />
 

package/src/Popover.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { IconBold, IconItalic, IconLink } from '@tabler/icons-react'
-import { useRef, useState, type KeyboardEvent, useCallback } from 'react'
+import { useRef, useState, type KeyboardEvent } from 'react'
 import { Button } from './Button'
 import { MenuPanel } from './Menu'
 import { Popover } from './Popover'
@@ -105,7 +105,8 @@ export const AToolbar: Story = {
            when there is no room, which is the reason the placement is its job
            and not ours. */
         side="top"
-        className="w-auto min-w-0 p-1"
+        className="w-auto min-w-0"
+        contentClassName="p-1"
       >
         {/* The strip is a `Toolbar`, so the whole row is ONE Tab stop and the
             arrow keys walk it — four stops before, one after. */}
@@ -234,17 +235,18 @@ export const Capped: Story = {
   parameters: { controls: { disable: true }, layout: 'fullscreen' },
   render: function Capped() {
     /* Anchored and open, so the cap is the thing you see rather than a button
-       you have to press first. A rect is all an anchor needs. */
-    const [rect, setRect] = useState<DOMRect | null>(null)
-    const mark = useCallback((el: HTMLDivElement | null) => {
-      setRect(el ? el.getBoundingClientRect() : null)
-    }, [])
+       you have to press first. Anchored on the ELEMENT, held in state from a
+       callback ref: an element is re-measured. It used to be a rect read once
+       in the ref, and arriving at this story from another one read it before
+       the canvas was laid out — 0 × 0 at the corner, a 0px panel, only the
+       line of text showing (PLAN Finding 61). */
+    const [marker, setMarker] = useState<HTMLDivElement | null>(null)
     return (
       <div className="flex h-[420px] w-full items-center justify-center">
-        <div ref={mark} className="text-body-2 text-text-secondary">
+        <div ref={setMarker} className="text-body-2 text-text-secondary">
           twenty rows, capped at 160px
         </div>
-        <Popover anchor={rect} open ariaLabel="A long panel" className="w-[240px]" maxHeight="max-h-[160px]">
+        <Popover anchor={marker} open ariaLabel="A long panel" className="w-[240px]" maxHeight="max-h-[160px]">
           {Array.from({ length: 20 }, (_, i) => (
             <span key={i} className="text-body-2 text-text-primary py-1">
               Row {i + 1}