@estiva-app/ui 0.57.4 → 0.59.0

package/src/MembersDialog.stories.tsx

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { MembersDialog } from './MembersDialog'
+
+const people = [
+  { id: 'ana', label: 'Ana Duarte' },
+  { id: 'ravi', label: 'Ravi Mehta' },
+  { id: 'marta', label: 'Marta Silva' },
+  { id: 'jonas', label: 'Jonas Weber' },
+]
+
+const meta = {
+  title: 'Primitives/MembersDialog',
+  component: MembersDialog,
+  args: {
+    members: [
+      { id: 'me', name: 'You', caption: 'Product designer' },
+      { id: 'ana', name: 'Ana Duarte', caption: 'Assignee' },
+    ],
+    self: { action: 'leave', onToggle: () => {} },
+    candidates: people,
+    onAdd: () => {},
+    onClose: () => {},
+  },
+} satisfies Meta<typeof MembersDialog>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** A member: Leave and "Add members" on top. */
+export const Member: Story = {}
+
+/** Not a member yet: Join on top, and nothing to add until you are in. */
+export const NotAMember: Story = {
+  args: {
+    members: [{ id: 'ana', name: 'Ana Duarte', caption: 'Assignee' }],
+    self: { action: 'join', onToggle: () => {} },
+    onAdd: undefined,
+  },
+}
+
+/** Membership still being read: no row on top rather than a wrong one. */
+export const Unknown: Story = {
+  args: { self: undefined, onAdd: undefined },
+}
+
+/** Someone who left but still holds a role, and a line about what membership covers. */
+export const WithNote: Story = {
+  args: {
+    members: [
+      { id: 'me', name: 'You' },
+      { id: 'ravi', name: 'Ravi Mehta', caption: 'Assignee · not following' },
+    ],
+    count: 1,
+    note: 'Leaving covers this page only; the items inside it still tell you about their comments.',
+  },
+}
+
+/** More rows than fit: the roster scrolls inside the dialog. */
+export const Long: Story = {
+  args: {
+    members: Array.from({ length: 14 }, (_, i) => ({ id: String(i), name: `Person ${i + 1}`, caption: i % 3 === 0 ? 'Owner' : undefined })),
+  },
+}
+
+/** Opened straight on the add layer. */
+export const AddLayer: Story = {
+  args: { initialView: 'add' },
+}

package/src/MembersDialog.test.tsx

@@ -0,0 +1,69 @@
+// @vitest-environment jsdom
+/** What the MembersDialog page claims, pinned. */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { MembersDialog } from './MembersDialog'
+import { MembersPill } from './MembersPill'
+
+afterEach(cleanup)
+
+const members = [
+  { id: 'me', name: 'You' },
+  { id: 'ana', name: 'Ana Duarte', caption: 'Assignee' },
+]
+
+describe('MembersDialog', () => {
+  it('lists every member with their caption, and counts them in the title', async () => {
+    render(<MembersDialog members={members} onClose={() => {}} />)
+    const dialog = await screen.findByRole('dialog', { name: /Members/ })
+    expect(dialog.textContent).toContain('Ana Duarte')
+    expect(dialog.textContent).toContain('Assignee')
+    expect(dialog.textContent).toContain('2')
+  })
+
+  it('offers no Join, Leave or Add when none is given', async () => {
+    render(<MembersDialog members={members} onClose={() => {}} />)
+    await screen.findByRole('dialog')
+    expect(screen.queryByRole('button', { name: /^(Join|Leave|Add members)$/ })).toBeNull()
+  })
+
+  it('says Join to a non-member and Leave to a member, and calls onToggle once', async () => {
+    const user = userEvent.setup()
+    const onToggle = vi.fn()
+    const { rerender } = render(<MembersDialog members={members} self={{ action: 'join', onToggle }} onClose={() => {}} />)
+    await user.click(await screen.findByRole('button', { name: 'Join' }))
+    expect(onToggle).toHaveBeenCalledTimes(1)
+    rerender(<MembersDialog members={members} self={{ action: 'leave', onToggle }} onClose={() => {}} />)
+    expect(await screen.findByRole('button', { name: 'Leave' })).toBeTruthy()
+  })
+
+  it('goes to the add layer and back, and Invite waits for a choice', async () => {
+    const user = userEvent.setup()
+    render(<MembersDialog members={members} candidates={[{ id: 'ravi', label: 'Ravi Mehta' }]} onAdd={() => {}} onClose={() => {}} />)
+    await user.click(await screen.findByRole('button', { name: 'Add members' }))
+    expect((await screen.findByRole('button', { name: 'Invite' })).hasAttribute('disabled')).toBe(true)
+    await user.click(screen.getByRole('button', { name: 'Back to members' }))
+    expect(await screen.findByRole('button', { name: 'Add members' })).toBeTruthy()
+  })
+
+  it('stays on the add layer when onAdd returns false', async () => {
+    const user = userEvent.setup()
+    const onAdd = vi.fn(() => false)
+    render(<MembersDialog members={members} candidates={[{ id: 'ravi', label: 'Ravi Mehta' }]} onAdd={onAdd} initialView="add" onClose={() => {}} />)
+    await user.type(await screen.findByRole('combobox'), 'Ravi')
+    await user.click(await screen.findByRole('option', { name: /Ravi Mehta/ }))
+    await user.click(screen.getByRole('button', { name: 'Invite' }))
+    expect(onAdd).toHaveBeenCalledWith([{ id: 'ravi', label: 'Ravi Mehta' }])
+    expect(screen.getByRole('button', { name: 'Invite' })).toBeTruthy()
+  })
+})
+
+describe('MembersPill', () => {
+  it('names the total, and draws nothing for none', () => {
+    const { container, rerender } = render(<MembersPill members={[{ name: 'Ana Duarte' }]} count={4} onClick={() => {}} />)
+    expect(screen.getByRole('button', { name: '4 members' })).toBeTruthy()
+    rerender(<MembersPill members={[]} />)
+    expect(container.textContent).toBe('')
+  })
+})

package/src/MembersDialog.tsx

@@ -0,0 +1,184 @@
+import { useId, useState, type ReactNode } from 'react'
+import { IconArrowLeft, IconUserMinus, IconUserPlus } from '@tabler/icons-react'
+import { Avatar } from './Avatar'
+import { Button } from './Button'
+import { Chip } from './Chip'
+import { ChipInput, type ChipInputOption } from './ChipInput'
+import { DialogShell } from './DialogShell'
+import { Field } from './Field'
+import { Form } from './Form'
+import { IconButton } from './IconButton'
+import { MenuItem } from './Menu'
+
+/** One row of the roster: a face, a name, and an optional second line. */
+export interface MembersDialogMember {
+  id: string
+  name: string
+  /** A picture URL, resolved by the caller, as `Avatar` takes its `src`. */
+  picture?: string
+  /** The line under the name: a role, a relation ("Assignee"), or a state. */
+  caption?: string
+}
+
+/** Somebody who can be added: a `ChipInput` option with a face. */
+export interface MembersDialogCandidate extends ChipInputOption {
+  picture?: string
+}
+
+/** What the viewer's own row offers: in when they are out, out when they are in. */
+export type MembersDialogSelfAction = 'join' | 'leave'
+
+export interface MembersDialogProps {
+  /** The roster, in the order to draw it. The viewer's own row is the caller's to name ("You"). */
+  members: MembersDialogMember[]
+  /** The number in the title's chip. Defaults to how many rows there are. */
+  count?: number
+  /**
+   * The viewer's own row on top: "Join" when they are not in, "Leave" when
+   * they are. Absent while it is not known, or where they cannot change it —
+   * no row is better than a wrong one.
+   */
+  self?: {
+    action: MembersDialogSelfAction
+    onToggle: () => void | Promise<unknown>
+  }
+  /** Who "Add members" may offer. Members are left out by id. */
+  candidates?: MembersDialogCandidate[]
+  /**
+   * Adds the people chosen. With it, the "Add members" row shows and opens the
+   * add layer. Return `false` (or a promise of it) to stay on the add layer —
+   * nothing was added; anything else goes back to the roster.
+   */
+  onAdd?: (chosen: MembersDialogCandidate[]) => void | boolean | Promise<void | boolean>
+  /** One line under the roster — what membership does and does not cover. */
+  note?: ReactNode
+  /** `add` opens straight on the add layer. */
+  initialView?: 'list' | 'add'
+  onClose: () => void
+}
+
+const LEADING_CLASSES = 'size-8 rounded-md bg-accent-muted flex items-center justify-center shrink-0 text-accent-primary'
+
+/**
+ * Who is in this, with joining, leaving and adding people — the list a
+ * `MembersPill` opens.
+ *
+ * Moved from Peek's `MembersDialog` (2026-10-06; Katerina's design of 22 July,
+ * with the row and inset rulings of 15 September). Two layers in one dialog:
+ * the roster, with the viewer's Join or Leave and "Add members" on top, and the
+ * add layer, whose back arrow returns to the roster. Adding returns to the
+ * roster so the new people are visible at once.
+ */
+export function MembersDialog({ members, count, self, candidates = [], onAdd, note, initialView = 'list', onClose }: MembersDialogProps) {
+  const [view, setView] = useState<'list' | 'add'>(onAdd ? initialView : 'list')
+  const [chosen, setChosen] = useState<MembersDialogCandidate[]>([])
+  const [toggling, setToggling] = useState(false)
+  const formId = useId()
+
+  const toggle = async () => {
+    if (!self || toggling) return
+    setToggling(true)
+    try {
+      await self.onToggle()
+    } finally {
+      setToggling(false)
+    }
+  }
+
+  const add = async () => {
+    if (!onAdd || chosen.length === 0) return
+    if ((await onAdd(chosen)) === false) return
+    setChosen([])
+    setView('list')
+  }
+
+  if (view === 'add' && onAdd) {
+    return (
+      <DialogShell
+        title="Add members"
+        onClose={onClose}
+        headerContent={
+          <div className="flex min-w-0 items-center gap-2">
+            <IconButton tooltip="Back to members" aria-label="Back to members" className="-ml-2" onClick={() => setView('list')}>
+              <IconArrowLeft size={16} stroke={1.5} />
+            </IconButton>
+            <span className="truncate text-h4 text-text-primary">Add members</span>
+          </div>
+        }
+        bodyClassName="flex flex-col gap-6"
+        footer={
+          <>
+            <Button variant="muted" onClick={onClose}>Cancel</Button>
+            <Button variant="primary" type="submit" form={formId} disabled={chosen.length === 0}>Invite</Button>
+          </>
+        }
+      >
+        <Form id={formId} onSubmit={add}>
+          <Field label="Invite people" required>
+            <ChipInput
+              value={chosen}
+              onChange={setChosen}
+              options={candidates}
+              placeholder="Search people..."
+              excludeIds={members.map((m) => m.id)}
+              chipLeading={(o) => <Avatar name={o.label} src={o.picture} size={16} />}
+              rowLeading={(o) => <Avatar name={o.label} src={o.picture} size={32} />}
+              autoFocus
+            />
+          </Field>
+        </Form>
+      </DialogShell>
+    )
+  }
+
+  return (
+    <DialogShell
+      title="Members"
+      onClose={onClose}
+      headerContent={
+        <div className="flex min-w-0 items-center gap-2">
+          <span className="truncate text-h4 text-text-primary">Members</span>
+          <Chip label={String(count ?? members.length)} />
+        </div>
+      }
+      bodyMaxHeight="max-h-[400px]"
+      bodyClassName="p-0 py-2"
+    >
+      {/* MenuItem outside a Menu is a plain button. Its fill sits 8px in from the dialog's sides,
+          and its own 12px inset puts the square over the rows' faces, 20px in, at the same 48px. */}
+      {(self || onAdd) && (
+        <div className="flex flex-col px-2">
+          {self && (
+            <MenuItem
+              size="tall"
+              className="py-2"
+              disabled={toggling}
+              onClick={() => void toggle()}
+              leading={<span className={LEADING_CLASSES}>{self.action === 'join' ? <IconUserPlus size={16} stroke={1.5} /> : <IconUserMinus size={16} stroke={1.5} />}</span>}
+              label={self.action === 'join' ? 'Join' : 'Leave'}
+            />
+          )}
+          {onAdd && (
+            <MenuItem
+              size="tall"
+              className="py-2"
+              onClick={() => setView('add')}
+              leading={<span className={LEADING_CLASSES}><IconUserPlus size={16} stroke={1.5} /></span>}
+              label="Add members"
+            />
+          )}
+        </div>
+      )}
+      {members.map((member) => (
+        <div key={member.id} className="flex h-12 items-center gap-3 px-5">
+          <Avatar size={32} name={member.name} src={member.picture} />
+          <div className="flex min-w-0 flex-1 flex-col justify-center gap-[2px]">
+            <div className="truncate text-body-2 text-text-primary">{member.name}</div>
+            {member.caption && <div className="truncate text-caption text-text-secondary">{member.caption}</div>}
+          </div>
+        </div>
+      ))}
+      {note && <div className="px-5 pb-2 pt-3 text-caption text-text-secondary">{note}</div>}
+    </DialogShell>
+  )
+}

package/src/MembersPill.mdx

@@ -0,0 +1,45 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as MembersPillStories from './MembersPill.stories'
+
+<Meta of={MembersPillStories} />
+
+# MembersPill
+
+Who is in this: up to three faces and the total, in a small outlined pill
+that opens the full list.
+
+<Canvas of={MembersPillStories.TwoMembers} />
+
+## When
+
+- A page or conversation header that says, at a glance, who is in it, and
+  opens the list — a **MembersDialog** — on a press.
+
+## When not
+
+- The faces alone, with nothing to open → **AvatarGroup**.
+- The people need to be readable → **MembersDialog**, or a list of **Person** rows.
+
+## How
+
+```tsx
+import { MembersPill } from '@estiva-app/ui'
+
+const people: { name: string; picture?: string }[] = []
+const [open, setOpen] = useState(false)
+
+<MembersPill members={people} onClick={() => setOpen(true)} />
+```
+
+- `members` is what **AvatarGroup** takes; the first three are drawn.
+- `count` is the number beside the faces when it is not `members.length` —
+  pass three faces and the real total.
+- No `onClick` disables it; no members draws nothing.
+
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
+## Props
+
+<Controls of={MembersPillStories.TwoMembers} />

package/src/MembersPill.stories.tsx

@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { MembersPill } from './MembersPill'
+
+const meta = {
+  title: 'Primitives/MembersPill',
+  component: MembersPill,
+  args: {
+    members: [{ name: 'Ana Duarte' }, { name: 'Ravi Mehta' }],
+    onClick: () => {},
+  },
+} satisfies Meta<typeof MembersPill>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const TwoMembers: Story = {}
+
+export const One: Story = {
+  args: { members: [{ name: 'Ana Duarte' }] },
+}
+
+/** Twelve members, three faces: the count says the rest. */
+export const Many: Story = {
+  args: {
+    members: [{ name: 'Ana Duarte' }, { name: 'Ravi Mehta' }, { name: 'Marta Silva' }],
+    count: 12,
+  },
+}
+
+/** Nothing to open — the pill is disabled, not another element. */
+export const Disabled: Story = {
+  args: { onClick: undefined },
+}
+
+/** No members draws nothing at all. */
+export const Empty: Story = {
+  args: { members: [] },
+}

package/src/MembersPill.tsx

@@ -0,0 +1,35 @@
+import { AvatarGroup, type AvatarGroupMember } from './AvatarGroup'
+import { Button } from './Button'
+import { cn } from './cn'
+import { MONO_CAPTION_CLASSES } from './looks'
+
+export interface MembersPillProps {
+  /** Who is in it, in order. Up to three faces are drawn. */
+  members: AvatarGroupMember[]
+  /** The number beside the faces. Defaults to how many members there are. */
+  count?: number
+  /** Opens the list — usually a `MembersDialog`. Without it the pill is disabled. */
+  onClick?: () => void
+  className?: string
+}
+
+/**
+ * Who is in this: up to three faces and the total, in a small outlined pill
+ * that opens the full list.
+ *
+ * Moved from Peek's `MembersPill` (2026-10-06), unchanged: the package's
+ * Button, outlined, at its default 32px — the faces sit 3px inside the
+ * hairline on the top, the bottom and the left, 8px from the count (Katerina's
+ * pick of 15 September). `disabled` rather than another element when there is
+ * nothing to press, so one element keeps one set of pixels.
+ */
+export function MembersPill({ members, count, onClick, className }: MembersPillProps) {
+  const total = count ?? members.length
+  if (total === 0) return null
+  return (
+    <Button variant="outlined" aria-label={`${total} ${total === 1 ? 'member' : 'members'}`} disabled={!onClick} onClick={onClick} className={cn('gap-2 pl-[3px] pr-2', className)}>
+      <AvatarGroup members={members} />
+      <span className={cn(MONO_CAPTION_CLASSES, 'signal:tabular-nums')}>{total}</span>
+    </Button>
+  )
+}

package/src/NavItem.tsx

@@ -2,7 +2,7 @@ import { useId, useState, type ComponentPropsWithoutRef, type ReactNode } from '
 import { Collapsible } from '@base-ui/react/collapsible'
 import { IconAlertSquareRounded, IconChevronRight, IconDotsVertical } from '@tabler/icons-react'
 import { cn } from './cn'
-import { COLLAPSIBLE_PANEL_CLASSES, SIDEBAR_ROW_CLASSES, SIDEBAR_ROW_TEXT_CLASSES } from './looks'
+import { COLLAPSIBLE_PANEL_CLASSES, COUNT_TEXT_CLASSES, SIDEBAR_ROW_CLASSES, SIDEBAR_ROW_TEXT_CLASSES } from './looks'
 import { IconButton } from './IconButton'
 import { Menu } from './Menu'
 import { UnreadDot } from './UnreadDot'
@@ -160,7 +160,8 @@ export function NavItem({
               2026-09-09). A three-digit count grows the box leftwards. */}
           <span
             className={cn(
-              'min-w-4 shrink-0 text-center font-mono text-caption tabular-nums text-text-muted',
+              'min-w-4 shrink-0 text-center',
+              COUNT_TEXT_CLASSES,
               // With a menu and no mark after it, the ⋮ takes this place while it shows.
               !mark && stepsAside,
             )}

package/src/SectionHeader.mdx

@@ -66,10 +66,12 @@ import { IconPlus } from '@tabler/icons-react'
 - An action is `{ icon, tooltip, onClick }` — the tooltip doubles as the
   action's accessible name. The actions sit beside the title button, not
   inside it, so a click on one never also toggles the section.
-- `trailing` is a count beside the title, held on screen while the actions
-  come and go: a count is information, not an affordance. It sits outside
-  the title button too, so it is neither part of the toggle's name nor part
-  of its hit target.
+- `count` is how many there are, 8px after the title, in a tab's count
+  style: a heading over a list says its number beside its name.
+- `trailing` sits at the row's end, before the actions, and stays on screen
+  while they come and go: a chip, or an unread dot. It is outside the title
+  button, so it is neither part of the toggle's name nor part of its hit
+  target.
 - `render` swaps the title's element in Base UI's manner; it is how
   CollapsibleSection makes the title a `Collapsible.Trigger`.
 

package/src/SectionHeader.stories.tsx

@@ -10,7 +10,7 @@ const meta = {
   component: SectionHeader,
   decorators: [(Story) => <div className="w-[280px]"><Story /></div>],
   args: { title: 'Section', showActions: 'hover' },
-  argTypes: { showActions: { control: 'inline-radio', options: ['hover', 'always'] }, chevron: { control: false }, isExpanded: { control: false }, trailing: { control: false } },
+  argTypes: { showActions: { control: 'inline-radio', options: ['hover', 'always'] }, chevron: { control: false }, isExpanded: { control: false }, trailing: { control: false }, count: { control: 'number' } },
 } satisfies Meta<typeof SectionHeader>
 
 export default meta
@@ -67,7 +67,12 @@ export const WithMenu: Story = {
   },
 }
 
-/** A count beside the title, held on screen while the actions come and go. */
+/** `count`: how many, right after the title. */
+export const WithCount: Story = {
+  args: { count: 2, hover: 'none' },
+}
+
+/** `trailing`: a chip at the row's end, held on screen while the actions come and go. */
 export const WithTrailing: Story = {
   args: {
     trailing: <Chip type="brand" label="2" />,

package/src/SectionHeader.test.tsx

@@ -160,4 +160,10 @@ describe('SectionHeader, the trailing slot', () => {
     const { container } = render(<SectionHeader title="Section" trailing={<UnreadDot />} />)
     expect(container.querySelector('[data-unread]')!.parentElement!.className.split(' ')).toContain('has-[[data-unread]]:-mr-1')
   })
+
+  it('a count sits right after the title, inside the title, not at the row end', () => {
+    render(<SectionHeader title="Section" count={2} />)
+    const count = screen.getByText('2')
+    expect(count.previousElementSibling?.textContent).toBe('Section')
+  })
 })

package/src/SectionHeader.tsx

@@ -2,7 +2,7 @@ import type { ReactNode } from 'react'
 import { IconChevronRight, IconDotsVertical } from '@tabler/icons-react'
 import { useRender } from '@base-ui/react/use-render'
 import { cn } from './cn'
-import { SIDEBAR_ROW_CLASSES, SIDEBAR_ROW_TEXT_CLASSES } from './looks'
+import { COUNT_TEXT_CLASSES, SIDEBAR_ROW_CLASSES, SIDEBAR_ROW_TEXT_CLASSES } from './looks'
 import { IconButton } from './IconButton'
 import { Menu } from './Menu'
 import { SectionLabel } from './SectionLabel'
@@ -66,6 +66,12 @@ export interface SectionHeaderProps {
    * app for want of the slot (ADOPTION B23).
    */
   trailing?: ReactNode
+  /**
+   * How many there are, 8px after the title — not at the row's end, where
+   * `trailing` goes (Katerina, 7 October: a heading over a list says its
+   * count beside its name, as a tab does).
+   */
+  count?: number
   /** Right-aligned, in the order given. */
   actions?: SectionAction[]
   /**
@@ -102,7 +108,7 @@ export interface SectionHeaderProps {
   className?: string
 }
 
-export function SectionHeader({ title, chevron = false, icon, isExpanded = true, onToggle, trailing, actions, menu, menuLabel, showActions = 'hover', hover = 'fill', look = 'heading', render, className }: SectionHeaderProps) {
+export function SectionHeader({ title, chevron = false, icon, isExpanded = true, onToggle, trailing, count, actions, menu, menuLabel, showActions = 'hover', hover = 'fill', look = 'heading', render, className }: SectionHeaderProps) {
   const row = look === 'row'
   /*
     One arrow for everything that folds, a NavItem's 16px, and the title 8px
@@ -179,6 +185,8 @@ export function SectionHeader({ title, chevron = false, icon, isExpanded = true,
           ) : (
             <SectionLabel folds={chevron}>{title}</SectionLabel>
           )}
+          {/* 8px after the title with the 4px gap, in a row's count style. */}
+          {count != null && <span className={cn('ml-1 shrink-0', COUNT_TEXT_CLASSES)}>{count}</span>}
         </>
       ),
     },

package/src/ShowMore.mdx

@@ -0,0 +1,62 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as ShowMoreStories from './ShowMore.stories'
+
+<Meta of={ShowMoreStories} />
+
+# ShowMore
+
+Long content cut at a height behind a fade, with "Show more" under it.
+
+<Canvas of={ShowMoreStories.Long} />
+
+## When
+
+- A block of text that can run long beside other things the reader needs:
+  a description above controls, a summary above a list. Cut, it keeps what
+  is under it in view.
+- Content whose length you do not know. It measures: what fits is drawn
+  whole, with no fade and no button.
+
+<Canvas of={ShowMoreStories.Short} />
+
+## When not
+
+- A whole section that opens and closes under its heading → **CollapsibleSection**.
+- A message or reply in a conversation: read it whole.
+- Content the reader came for, the page's own subject: show it all.
+- A preview of something that lives elsewhere, on hover → **PreviewCard**.
+
+## How
+
+```tsx
+import { ShowMore } from '@estiva-app/ui'
+
+<ShowMore surface="inset">
+  <p className="text-caption text-text-secondary">{description}</p>
+</ShowMore>
+```
+
+- Wrap only the part that runs long. Keep titles and controls outside it, so
+  they are never the part that is cut.
+- `surface` is what the content sits on, for the fade to end in: `surface`
+  (a panel, the default) or `inset` (inside an inset card). A fade into the
+  wrong colour shows as a band.
+- `maxHeight` is in px, 96 by default.
+
+<Canvas of={ShowMoreStories.InACard} />
+
+## 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 |
+|---|---|---|
+| Measures the content, and again whenever it changes size, to decide whether to cut | a length check on the text, or a `line-clamp` |  |
+| Draws the fade and the "Show more" / "Show less" button, which says whether it is open (`aria-expanded`) | a gradient and a toggle of your own |  |
+| Opens when focus arrives inside the cut part: a field or link there is never used out of sight | a focus handler that opens it |  |
+
+The cut content stays in the page, so assistive technology reads all of it.
+
+## Props
+
+<Controls of={ShowMoreStories.Long} />

package/src/ShowMore.stories.tsx

@@ -0,0 +1,39 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Card } from './Card'
+import { ShowMore } from './ShowMore'
+
+const LONG = Array.from(
+  { length: 6 },
+  (_, i) => `Paragraph ${i + 1}. A long description written out in full, the way a real brief is, so that it runs past the height the box allows and needs cutting.`,
+).join(' ')
+
+/** Long content cut behind a fade, with "Show more" under it. Short content is drawn whole. */
+const meta = {
+  title: 'Layout/ShowMore',
+  component: ShowMore,
+  decorators: [(Story) => <div className="w-[320px]"><Story /></div>],
+  args: { children: <p className="text-caption text-text-secondary">{LONG}</p> },
+  argTypes: { children: { control: false } },
+} satisfies Meta<typeof ShowMore>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** Taller than 96px: cut, faded into the surface, "Show more" under it. */
+export const Long: Story = {}
+
+/** No taller than the limit: drawn whole, no fade, no button. */
+export const Short: Story = {
+  args: { children: <p className="text-caption text-text-secondary">One line of description.</p> },
+}
+
+/** Inside an inset card: `surface="inset"`, so the fade ends in the card's fill. */
+export const InACard: Story = {
+  args: { surface: 'inset' },
+  render: (args) => (
+    <Card fill="inset" className="p-3">
+      <p className="text-body-2-strong text-text-primary">Title</p>
+      <ShowMore {...args} className="mt-1" />
+    </Card>
+  ),
+}