@estiva-app/ui 0.8.0 → 0.10.0

package/src/PreviewCard.stories.tsx

@@ -0,0 +1,168 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconSquareRounded } from '@tabler/icons-react'
+import { MenuPanel } from './Menu'
+import { PreviewCard } from './PreviewCard'
+import { SkeletonBar } from './Skeleton'
+
+/**
+ * More of a thing, on hover.
+ *
+ * A list shows one line per thing because a list has to. This is where the
+ * rest of that thing goes: a card that opens beside the row when the pointer
+ * rests on it, so the reader can decide whether to open the thing without
+ * opening it.
+ *
+ * The canvas draws the surface with `MenuPanel`, since a live card portals and
+ * places itself; **`OnARow`** and **`Scrolling`** are the live ones (D25).
+ */
+const meta = {
+  title: 'Overlays/PreviewCard',
+  component: PreviewCard,
+  decorators: [(Story) => <div className="flex min-h-[260px] w-full items-center justify-center"><Story /></div>],
+  args: { content: null, children: null },
+  argTypes: { content: { control: false }, children: { control: false } },
+} satisfies Meta<typeof PreviewCard>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** A heading, a few named values and a paragraph — the shape most previews
+ *  take. What goes in is entirely the caller's. */
+function Detail() {
+  return (
+    <>
+      <span className="text-body-2-strong text-text-primary">Item one</span>
+      <div className="flex flex-col gap-1.5">
+        {[
+          ['Label', 'Value'],
+          ['Label', 'Another value'],
+          ['Label', 'A third value'],
+        ].map(([k, v], i) => (
+          <div key={i} className="flex items-baseline gap-2">
+            <span className="w-20 shrink-0 text-caption text-text-secondary">{k}</span>
+            <span className="min-w-0 flex-1 truncate text-[12px] leading-[1.45] text-text-primary">{v}</span>
+          </div>
+        ))}
+      </div>
+      <span className="text-[12px] leading-[1.45] text-text-secondary">
+        This is the card. It opened because the pointer came to rest on the row
+        and stayed there for 350ms, and it will close 200ms after the pointer
+        leaves — long enough to move into the card without losing it.
+      </span>
+    </>
+  )
+}
+
+function Row({ label, note }: { label: string; note?: string }) {
+  return (
+    <div className="flex w-full items-center gap-2 rounded-lg border border-border-default px-3 py-2 hover:bg-bg-hover">
+      <IconSquareRounded size={16} stroke={1.5} className="shrink-0 text-text-secondary" />
+      <span className="min-w-0 flex-1 truncate text-[14px] leading-[140%] text-text-primary">{label}</span>
+      {note && <span className="shrink-0 text-caption text-text-muted">{note}</span>}
+    </div>
+  )
+}
+
+/** The card at rest, so its anatomy can be read without hovering anything. */
+export const Default: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <MenuPanel className="w-[360px] gap-3 p-3">
+      <Detail />
+    </MenuPanel>
+  ),
+}
+
+/**
+ * While the content is still arriving.
+ *
+ * A skeleton rather than a spinner, on purpose: a preview has a known shape,
+ * and drawing that shape says "this is what is coming" where a spinner only
+ * says "wait". It also keeps the card the size it is about to be, so nothing
+ * jumps when the content lands.
+ */
+export const Loading: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    /* The skeleton is the shape of `Default`, line for line: a heading, three
+       label/value rows, and two lines of detail. That is what makes it a
+       skeleton rather than a placeholder — the card is the size it is about to
+       be, so nothing moves when the content lands. */
+    <MenuPanel className="w-[360px] gap-3 p-3">
+      <SkeletonBar className="h-4 w-24" />
+      <div className="flex flex-col gap-1.5">
+        {['w-16', 'w-24', 'w-20'].map((w, i) => (
+          <div key={i} className="flex items-center gap-2">
+            <SkeletonBar className="w-20 shrink-0" />
+            <SkeletonBar className={w} />
+          </div>
+        ))}
+      </div>
+      <div className="flex flex-col gap-1.5">
+        <SkeletonBar className="w-full" />
+        <SkeletonBar className="w-2/3" />
+      </div>
+    </MenuPanel>
+  ),
+}
+
+/** Live. Rest the pointer on the row and read what the card says. */
+export const OnARow: Story = {
+  // axe color-contrast is off here until PLAN.md stage 0.10 is ruled:
+  // the row's note is muted caption text, 3.93:1 on --bg-base in signal (AA 4.5:1).
+  parameters: { controls: { disable: true }, a11y: { config: { rules: [{ id: 'color-contrast', enabled: false }] } } },
+  render: () => (
+    <PreviewCard content={<Detail />} wrapperClassName="w-[320px]">
+      <Row label="Item one" note="Label" />
+    </PreviewCard>
+  ),
+}
+
+/**
+ * A card taller than its cap scrolls, **and you can reach the scrollbar** —
+ * which is the whole difference between this and a tooltip. Rest the pointer
+ * on the row, move into the card, and scroll it.
+ */
+export const Scrolling: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <PreviewCard
+      wrapperClassName="w-[320px]"
+      content={
+        <>
+          <span className="text-body-2-strong text-text-primary">Item with more than fits</span>
+          <span className="text-[12px] leading-[1.45] text-text-secondary">
+            There is more here than the card's 300px cap allows, so it scrolls.
+            You can reach that scrollbar because the pointer can enter this card.
+            A tooltip cannot be entered, so a tooltip that scrolled would be a
+            tooltip nobody could read to the end.
+          </span>
+          {Array.from({ length: 14 }, (_, i) => (
+            <div key={i} className="flex items-baseline gap-2">
+              <span className="w-20 shrink-0 text-caption text-text-secondary">Label</span>
+              <span className="min-w-0 flex-1 truncate text-[12px] leading-[1.45] text-text-primary">Value {i + 1}</span>
+            </div>
+          ))}
+        </>
+      }
+    >
+      <Row label="Item with more than fits" />
+    </PreviewCard>
+  ),
+}
+
+/**
+ * The side is a preference, not a promise: it flips when the side you asked
+ * for has no room. This one asks for the right in a row pinned to the right
+ * edge, so it opens on the left.
+ */
+export const FlippedAtAnEdge: Story = {
+  parameters: { controls: { disable: true }, layout: 'fullscreen' },
+  render: () => (
+    <div className="flex h-[260px] w-full items-center justify-end p-4">
+      <PreviewCard content={<Detail />} wrapperClassName="w-[320px]">
+        <Row label="A row against the right edge" />
+      </PreviewCard>
+    </div>
+  ),
+}

package/src/PreviewCard.test.tsx

@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+/**
+ * What the PreviewCard page claims, pinned.
+ *
+ * Split out of `Popover.test.tsx` on 2026-09-08: the two arrived in one
+ * commit and shared a file, and every other component in this package is
+ * tested beside itself. Placement is Floating UI's and is measured in a
+ * browser — jsdom lays nothing out — so what is here is the behaviour.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { PreviewCard } from './PreviewCard'
+
+afterEach(cleanup)
+
+describe('PreviewCard', () => {
+  it('renders its trigger, and nothing of its content, until it opens', () => {
+    render(
+      <PreviewCard content={<span>The rest of it</span>}>
+        <span>A row</span>
+      </PreviewCard>,
+    )
+    expect(screen.getByText('A row')).toBeTruthy()
+    // `content` is not rendered while closed, so a preview that fetches does
+    // not fetch once per row on screen.
+    expect(screen.queryByText('The rest of it')).toBeNull()
+  })
+
+  it('opens when the pointer rests on the trigger, and closes when it leaves', async () => {
+    const user = userEvent.setup()
+    render(
+      <PreviewCard content={<span>The rest of it</span>} delay={0} closeDelay={0}>
+        <span>A row</span>
+      </PreviewCard>,
+    )
+    await user.hover(screen.getByText('A row'))
+    expect(await screen.findByText('The rest of it')).toBeTruthy()
+    await user.unhover(screen.getByText('A row'))
+    expect(screen.queryByText('The rest of it')).toBeNull()
+  })
+
+  /*
+   * Not here: "the pointer can move into the card, and it scrolls" — the one
+   * claim that separates this from a tooltip.
+   *
+   * It cannot be tested in jsdom. No stylesheet is loaded there, so the
+   * `pointer-events: none` Base UI puts on the positioner is never reset by
+   * the popup's own class, and user-event refuses to move the pointer into
+   * something it reads as untouchable. Measured in Chrome instead
+   * (2026-09-08, the `Scrolling` story): the popup computes
+   * `pointer-events: auto`, the card stays open when the pointer moves into
+   * it, its 537px of content scrolls inside a 298px box — scrollTop 0 → 200
+   * on a wheel — and it closes when the pointer leaves for good.
+   */
+
+  /** The page says so in its Keys table, and a card the pointer can enter is
+   *  a layer, so it owes the exit every layer owes. */
+  it('closes on Escape', async () => {
+    const user = userEvent.setup()
+    render(
+      <PreviewCard content={<span>The rest of it</span>} delay={0} closeDelay={0}>
+        <span>A row</span>
+      </PreviewCard>,
+    )
+    await user.hover(screen.getByText('A row'))
+    await screen.findByText('The rest of it')
+    await user.keyboard('{Escape}')
+    expect(screen.queryByText('The rest of it')).toBeNull()
+  })
+
+  it('the trigger is the wrapper, and the row inside it is untouched', () => {
+    const { container } = render(
+      <PreviewCard content={<span>x</span>} wrapperClassName="block w-full">
+        <div data-testid="row">A row</div>
+      </PreviewCard>,
+    )
+    const wrapper = container.firstElementChild as HTMLElement
+    expect(wrapper.tagName).toBe('SPAN')
+    expect(wrapper.className).toContain('block')
+    expect(wrapper.firstElementChild?.getAttribute('data-testid')).toBe('row')
+  })
+})

package/src/PreviewCard.tsx

@@ -0,0 +1,91 @@
+import type { ReactNode } from 'react'
+import { PreviewCard as BasePreviewCard } from '@base-ui/react/preview-card'
+import { cn } from './cn'
+import { MenuPanel } from './Menu'
+
+/**
+ * More of a thing, on hover — a card beside a row that is only a snippet.
+ * New at stage 4 (2026-09-07).
+ *
+ * **It exists because Peek's Screener preview is this, hand-written**: its own
+ * `createPortal`, its own "prefer the right, flip left if it would run off
+ * screen" arithmetic against `window.innerWidth`, and its own clamp against
+ * the bottom edge (`ScreenerPreviewCard.tsx`). Floating UI does all three.
+ *
+ * **Not a Tooltip.** A tooltip is a word for a control, is
+ * `pointer-events: none`, and may hold nothing you can reach. A preview card
+ * holds *content* — faces, text, a link — and you can move the pointer into
+ * it, which is what a preview is for. If what you have is a label, use
+ * `WithTooltip`.
+ *
+ * The surface is the package's elevated panel, the same one a `Menu` draws, so
+ * there is one definition of that box. Width, height and internal rhythm are
+ * the caller's: a preview of a conversation is not the size of a preview of a
+ * person.
+ */
+export interface PreviewCardProps {
+  /** What the card holds. Rendered only while it is open. */
+  content: ReactNode
+  /** The row, name or avatar the card previews. */
+  children: ReactNode
+  /** Which side of the trigger to prefer. It flips when that side has no room. Default right. */
+  side?: 'top' | 'bottom' | 'left' | 'right'
+  /** Before it opens, in ms. Long enough that crossing a list does not flash a card at every row. */
+  delay?: number
+  /** After the pointer leaves, in ms — the grace that lets you cross the gap into the card. */
+  closeDelay?: number
+  /** On the card's surface: its width, its padding, a max height. */
+  className?: string
+  /** Extra classes on the trigger wrapper — e.g. `block w-full` for a row. */
+  wrapperClassName?: string
+}
+
+/** The card's own numbers: 12px from the trigger, 8px clear of every screen
+ *  edge. Peek's hand-written preview used 12 and 12; the 8 is the package's
+ *  viewport margin, shared with every other floating surface. */
+const GAP = 12
+const VIEWPORT_PAD = 8
+/** 350ms, which is Peek's number: `ScreenerItem`'s `HOVER_DELAY_MS`. Long
+ *  enough not to flash a card at every row while a pointer crosses a list,
+ *  short enough to feel like an answer. Taken rather than invented, because
+ *  this component exists to replace that one. */
+const OPEN_DELAY = 350
+/** The diagonal from the row to the card has to survive. Peek's has no grace
+ *  at all — it closes on `mouseleave` — because its card is
+ *  `pointer-events: none` and there is nothing to cross to. Which also means
+ *  **the `overflow-y-auto` on its 300px-capped card can never be scrolled**;
+ *  here the card can be reached, so it can. */
+const CLOSE_DELAY = 200
+
+export function PreviewCard({ content, children, side = 'right', delay = OPEN_DELAY, closeDelay = CLOSE_DELAY, className, wrapperClassName }: PreviewCardProps) {
+  return (
+    <BasePreviewCard.Root>
+      {/* The part renders an `<a>` by default, which a row is not; `render`
+          makes it the wrapper this component has always been, and the trigger
+          inside keeps whatever element it already is. */}
+      <BasePreviewCard.Trigger
+        delay={delay}
+        closeDelay={closeDelay}
+        render={<span className={cn('inline-flex', wrapperClassName)} />}
+      >
+        {children}
+      </BasePreviewCard.Trigger>
+      <BasePreviewCard.Portal>
+        <BasePreviewCard.Positioner
+          side={side}
+          align="start"
+          sideOffset={GAP}
+          collisionPadding={VIEWPORT_PAD}
+          className="z-50 data-[anchor-hidden]:hidden"
+        >
+          <BasePreviewCard.Popup
+            className={cn('w-[360px] max-h-[min(300px,var(--available-height))] gap-3 overflow-y-auto p-3 outline-none [&>*]:shrink-0', className)}
+            render={<MenuPanel />}
+          >
+            {content}
+          </BasePreviewCard.Popup>
+        </BasePreviewCard.Positioner>
+      </BasePreviewCard.Portal>
+    </BasePreviewCard.Root>
+  )
+}

package/src/Rail.mdx

@@ -0,0 +1,63 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as RailStories from './Rail.stories'
+
+<Meta of={RailStories} />
+
+# Rail
+
+The 64px strip of icon tiles down the left of an app. It is the container and
+nothing else: **RailItem** is the tile, and where a tile goes is the app's.
+
+<Canvas of={RailStories.Default} />
+
+## When
+
+- The top level of an app's navigation, when there are few enough places to
+  fit down one strip: five or six, each with a shape you can learn.
+- Beside a **Sidebar**, when an app has both — the rail picks the area and the
+  sidebar picks the thing inside it.
+
+<Canvas of={RailStories.BesideAColumn} />
+
+## When not
+
+- A list of named places → **Sidebar**. A rail's label is 9px; a name that
+  needs more than a word needs a row.
+- More entries than fit down a screen → fewer entries. The rail does not
+  scroll, on purpose.
+- A strip of *actions* rather than places → a toolbar of **IconButton**s.
+
+<Canvas of={RailStories.ManyItems} />
+
+## How
+
+```tsx
+import { Rail, RailItem } from '@estiva-app/ui'
+
+<Rail aria-label="Areas">
+  <RailItem href="/inbox" label="Inbox" icon={<IconInbox size={16} stroke={1.5} />} active />
+  <RailItem href="/people" label="People" icon={<IconUsers size={16} stroke={1.5} />} />
+</Rail>
+```
+
+- It renders a `<nav>`, so **it is a landmark** and owes a name. `aria-label`
+  defaults to "Navigation", which is right when there is one; name it when an
+  app has a rail *and* a sidebar, or a screen reader offers two navigations
+  called the same thing.
+- **No border, no surface.** It stands on the app background and the column
+  beside it draws the edge, so a frame keeps one hairline rather than two.
+- **Collapsing is the caller's.** The rail does not know about a burger; it is
+  given less room, or none.
+- Desktop only. A narrow screen gets the app's own answer, not a squeezed rail.
+
+<Canvas of={RailStories.OneItem} />
+
+## Keys
+
+The rail has no keyboard of its own: its tiles are links, and Tab walks them in
+order like any other list of links. `RailItem` marks the current one
+`aria-current="page"`.
+
+## Props
+
+<Controls of={RailStories.Default} />

package/src/Rail.stories.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconSquareRounded } from '@tabler/icons-react'
+import { Rail } from './Rail'
+import { RailItem } from './RailItem'
+
+const placeholder = <IconSquareRounded size={16} stroke={1.5} />
+
+/**
+ * The 64px strip the icon tiles stand in. It is the container and nothing
+ * else: **RailItem** is the tile, and what a rail leads to is the app's.
+ *
+ * It has no border and no surface of its own — it stands on the app
+ * background, so every canvas here is full height against one.
+ */
+const meta = {
+  title: 'Frame/Rail',
+  component: Rail,
+  parameters: { layout: 'fullscreen' },
+  args: { 'aria-label': 'Navigation', children: null },
+  argTypes: { children: { control: false } },
+  decorators: [(Story) => <div className="flex h-screen bg-bg-base">{Story()}</div>],
+} satisfies Meta<typeof Rail>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** Three tiles, the first current. */
+export const Default: Story = {
+  render: (args) => (
+    <Rail {...args}>
+      <RailItem href="#" label="Item" icon={placeholder} active />
+      <RailItem href="#" label="Item" icon={placeholder} />
+      <RailItem href="#" label="Item" icon={placeholder} />
+    </Rail>
+  ),
+}
+
+/** One tile, so the strip's own width is visible against nothing else. */
+export const OneItem: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Rail>
+      <RailItem href="#" label="Item" icon={placeholder} active />
+    </Rail>
+  ),
+}
+
+/**
+ * Beside the thing it navigates. The rail draws no edge of its own — the
+ * column beside it draws its own, which is what keeps a frame to one hairline.
+ */
+export const BesideAColumn: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <>
+      <Rail>
+        <RailItem href="#" label="Item" icon={placeholder} active />
+        <RailItem href="#" label="Item" icon={placeholder} />
+      </Rail>
+      <div className="flex-1 border-l border-border-subtle bg-bg-surface p-6">
+        <span className="text-body-2 text-text-secondary">The column the rail stands beside.</span>
+      </div>
+    </>
+  ),
+}
+
+/**
+ * More tiles than the screen is tall. The rail does not scroll on its own —
+ * a rail with more entries than fit is a rail with too many entries, and the
+ * answer is fewer, not a scrollbar in a 64px strip.
+ */
+export const ManyItems: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Rail>
+      {Array.from({ length: 12 }, (_, i) => (
+        <RailItem key={i} href="#" label="Item" icon={placeholder} active={i === 0} />
+      ))}
+    </Rail>
+  ),
+}

package/src/Reaction.mdx

@@ -24,8 +24,10 @@ An emoji, how many people chose it, and whether you are one of them. A
 
 - Standing information nobody can toggle — a status, a category → **Chip**
   (a Chip is not a control).
-- Adding a reaction that is not there yet: that is a picker, and a strip of
-  icon actions is a toolbar of **IconButton**s.
+- **Offering the reactions to choose from** → **ReactionPicker**. This is the
+  answer; that is the question, and it is a `Toolbar` so the whole row is one
+  Tab stop.
+- Any other strip of icon actions → **Toolbar**.
 - An action with a verb for a label → **Button**.
 
 ## How

package/src/Reaction.tsx

@@ -76,8 +76,10 @@ export function Reaction({ emoji, count, pressed = false, className, type, ...pr
       <span aria-hidden="true" className="shrink-0 text-[16px] leading-none">
         {emoji}
       </span>
-      {/* `text-chip` is a plain class, never merged — the same guard Chip uses,
-          because tailwind-merge drops a token size that follows a text colour. */}
+      {/* `text-chip` stands alone here, so there is nothing to merge it with.
+          The old note said it must NEVER be merged; that stopped being true
+          when `cn()` was taught the ramp — `chip` is in it, and `cn.test.ts`
+          pins that. */}
       <span className="text-chip signal:font-mono signal:text-[10px] signal:font-semibold signal:tabular-nums">
         {count}
       </span>

package/src/ReactionPicker.mdx

@@ -0,0 +1,85 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as ReactionPickerStories from './ReactionPicker.stories'
+
+<Meta of={ReactionPickerStories} />
+
+# ReactionPicker
+
+The reactions on offer, to choose one from — icon buttons holding emoji, on a
+**Toolbar**. **`Reaction` is the answer; this is the question.**
+
+<Canvas of={ReactionPickerStories.Default} />
+
+## When
+
+- **Offering a reaction** — from a control on a card, or from a `Toolbar` of
+  actions. This is the case it exists for, and the only one.
+- **However many are on offer.** The row is whatever `options` holds; nothing
+  here caps or wraps it.
+
+<Canvas of={ReactionPickerStories.FromATrigger} />
+
+## When not
+
+- **Showing the reactions that have been made** — the pills with their counts,
+  in a row on the card → **Reaction**. That is the answer; this only asks.
+  Which reactions are yours is *its* state, not this one's.
+- Any other strip of controls → **Toolbar**, which this is built on.
+- A list of verbs → **Menu**.
+
+## How
+
+```tsx
+import { ReactionPicker } from '@estiva-app/ui'
+
+<Popover side="top" align="right" trigger={reactButton} ariaLabel="Reactions" className="w-auto p-1">
+  <ReactionPicker
+    surface={false}
+    options={[
+      { emoji: '👍', label: 'Makes sense' },
+      { emoji: '🎉', label: 'Congrats' },
+    ]}
+    onSelect={react}
+  />
+</Popover>
+```
+
+- **The vocabulary is yours.** Which emoji an app offers, and what each one
+  means, is product knowledge — so it arrives as `options`, and every option
+  owes a `label`.
+- **`label` is not decoration.** The emoji is `aria-hidden`, for the same
+  reason it is on `Reaction`: a glyph read aloud is noise, and its spoken name
+  differs per screen reader. The label is what a screen reader says and what
+  the tooltip shows, so write the *meaning* — "Makes sense", not "thumbs up".
+- **`onSelect` reports the emoji**, which is what an app stores. What happens
+  to it — a new reaction, or one of yours removed — is the caller's.
+- **It opens above the control that was pressed**, not below: the thing being
+  reacted to is underneath. `Popover`'s `side="top"`.
+- **It draws the box**, from `Toolbar` — so it floats correctly on its own.
+  Inside a `Popover`, which draws that box already, pass `surface={false}`.
+- **It is one Tab stop**, because it is a `Toolbar`. The hand-written version
+  it replaces was one stop per emoji, inside a hover panel — five things to
+  Tab past to reach anything after the card.
+
+### What it produces
+
+Picking puts a **Reaction** in the row on the card — the pill with the count
+and, when it is yours, the accent fill. The picker asks; the pill answers.
+
+<Canvas of={ReactionPickerStories.AndWhatItProduces} />
+
+## Keys
+
+| Input | What happens |
+|---|---|
+| Tab | onto the row — once, however many reactions are offered |
+| ← / → | move between them, and wrap at the ends |
+| Enter / Space | choose the focused one |
+| Tab again | leaves the row entirely |
+
+The keys are `Toolbar`'s, and its gap is this one's: **Home and End do
+nothing.**
+
+## Props
+
+<Controls of={ReactionPickerStories.Default} />