@estiva-app/ui 0.57.3 → 0.58.0

package/dist/looks.d.ts

@@ -29,6 +29,8 @@ export declare const FIELD_SIZE_CLASSES: {
 export declare const FIELD_SHELL_CLASSES = "bg-bg-field border border-border-field shadow-field hover:border-border-strong group-hover/field:border-border-strong rounded-lg transition-colors";
 /** A panel that floats over the page: Menu's panel and Tooltip. */
 export declare const FLOATING_SURFACE_CLASSES = "rounded-lg border border-border-default bg-bg-elevated shadow-lg";
+/** A count beside a label, in the muted colour: NavItem's number and SectionHeader's `count`. */
+export declare const COUNT_TEXT_CLASSES = "font-mono text-caption tabular-nums text-text-muted";
 /** A chip's words: Chip's label and Reaction's count. */
 export declare const CHIP_TEXT_CLASSES = "text-chip signal:font-mono signal:text-small signal:font-semibold signal:tabular-nums";
 /** Words typed straight into an input with no box of its own: SearchInput and ChipInput. */

package/dist/looks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"looks.d.ts","sourceRoot":"","sources":["../src/looks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,2MAA2M,CAAA;AAEzO,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,kDAAkD,CAAA;AAEjF,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,iKAAiK,CAAA;AAEpM,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,4DAA4D,CAAA;AAEjG,kJAAkJ;AAClJ,eAAO,MAAM,kBAAkB;;;CAGrB,CAAA;AAEV,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,uJAAuJ,CAAA;AAEvL,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,qEAAqE,CAAA;AAE1G,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,0FAA0F,CAAA;AAExH,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,8EAA8E,CAAA;AAE7G,4IAA4I;AAE5I,eAAO,MAAM,mBAAmB,iCAAiC,CAAA;AACjE,eAAO,MAAM,wBAAwB,gDAAgD,CAAA;AAErF,2FAA2F;AAC3F,eAAO,MAAM,qBAAqB,kEAAkE,CAAA;AAEpG,2IAA2I;AAC3I,eAAO,MAAM,oBAAoB,gGAAgG,CAAA;AAEjI;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,kLAAkL,CAAA"}
+{"version":3,"file":"looks.d.ts","sourceRoot":"","sources":["../src/looks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,2MAA2M,CAAA;AAEzO,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,kDAAkD,CAAA;AAEjF,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,iKAAiK,CAAA;AAEpM,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,4DAA4D,CAAA;AAEjG,kJAAkJ;AAClJ,eAAO,MAAM,kBAAkB;;;CAGrB,CAAA;AAEV,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,uJAAuJ,CAAA;AAEvL,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,qEAAqE,CAAA;AAE1G,iGAAiG;AACjG,eAAO,MAAM,kBAAkB,wDAAwD,CAAA;AAEvF,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,0FAA0F,CAAA;AAExH,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,8EAA8E,CAAA;AAE7G,4IAA4I;AAE5I,eAAO,MAAM,mBAAmB,iCAAiC,CAAA;AACjE,eAAO,MAAM,wBAAwB,gDAAgD,CAAA;AAErF,2FAA2F;AAC3F,eAAO,MAAM,qBAAqB,kEAAkE,CAAA;AAEpG,2IAA2I;AAC3I,eAAO,MAAM,oBAAoB,gGAAgG,CAAA;AAEjI;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,kLAAkL,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.57.3",
+  "version": "0.58.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/registry.json

@@ -4,9 +4,9 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.57.3",
-    "exports": 130,
-    "typeExports": 134,
+    "packageVersion": "0.58.0",
+    "exports": 131,
+    "typeExports": 135,
     "files": null
   },
   "storybook": {
@@ -4428,7 +4428,7 @@
         },
         {
           "name": "finalFocus",
-          "takes": "RefObject<HTMLElement | null>",
+          "takes": "RefObject<HTMLElement | null> | false",
           "required": false,
           "note": "Where focus goes when the panel closes. With a `trigger` it goes back to the trigger and this is not needed."
         },
@@ -5278,6 +5278,12 @@
           "required": false,
           "note": "Beside the title and always visible, before the actions — a count."
         },
+        {
+          "name": "count",
+          "takes": "number",
+          "required": false,
+          "note": "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)."
+        },
         {
           "name": "actions",
           "takes": "SectionAction[]",
@@ -5362,6 +5368,7 @@
         "opacity-0 transition-[opacity,transform] duration-150 group-hover:opacity-100",
         "opacity-0 transition-[opacity,transform] duration-150 group-hover:opacity-100 rotate-90",
         "transition-transform duration-150 text-text-secondary rotate-90",
+        "font-mono text-caption tabular-nums text-text-muted",
         "rounded-lg transition-colors text-text-secondary hover:text-text-primary",
         "rounded-lg transition-colors text-text-secondary hover:text-text-primary hover:bg-bg-hover",
         "opacity-0 transition-opacity group-hover:opacity-100 [@media(hover:none)]:opacity-100"
@@ -5646,6 +5653,61 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "ShowMore",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/ShowMore.tsx",
+      "purpose": "Long content cut at a height behind a fade, with \"Show more\" under it.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": true,
+          "note": null
+        },
+        {
+          "name": "maxHeight",
+          "takes": "number",
+          "required": false,
+          "note": "The height to cut at, in px. Default 96: about seven lines of caption text."
+        },
+        {
+          "name": "surface",
+          "takes": "surface | inset",
+          "required": false,
+          "note": "What the content sits on, for the fade to end in: a panel's `surface` (default), or an inset card's `inset`."
+        },
+        {
+          "name": "className",
+          "takes": "text",
+          "required": false,
+          "note": null
+        }
+      ],
+      "variants": [
+        {
+          "prop": "surface",
+          "values": [
+            "surface",
+            "inset"
+          ]
+        }
+      ],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "layout-showmore--docs",
+      "storyId": "layout-showmore--long",
+      "docPage": "src/ShowMore.mdx",
+      "app": null,
+      "looks": [
+        "pointer-events-none bg-gradient-to-t to-transparent from-bg-surface",
+        "pointer-events-none bg-gradient-to-t to-transparent from-bg-inset"
+      ]
+    },
     {
       "name": "Sidebar",
       "repo": "estiva-ui",

package/src/ComposerTriggers.test.tsx

@@ -367,6 +367,9 @@ describe('leaving the box', () => {
     expect(isSuggestionOpen()).toBe(true)
     await act(async () => other().focus())
     expect(screen.queryByRole('listbox')).toBeNull()
+    // The closing list does not pull focus back into the box that was left.
+    await act(async () => new Promise((resolve) => setTimeout(resolve, 50)))
+    expect(document.activeElement).toBe(other())
     // So the other box's own Escape and Enter are its own — no grace either.
     expect(isSuggestionOpen()).toBe(false)
     expect(isSuggestionActive()).toBe(false)

package/src/ContainerHeader.mdx

@@ -66,7 +66,7 @@ It does these by itself. Write none of them around it.
 
 | It does | So you never write | Refused when written by hand |
 |---|---|---|
-| Draws the column's bar: 48px tall, the title 20px in at 14px medium, the actions 16px from the right, a hairline under it | a row of your own with padding and a border |  |
+| Draws the column's bar: 48px tall, the title 16px in at 14px medium, the actions 16px from the right, a hairline under it | a row of your own with padding and a border |  |
 | Keeps its 48px in a scrolling column | `shrink-0` |  |
 
 ## Props

package/src/ContainerHeader.tsx

@@ -43,11 +43,12 @@ export function ContainerHeader({ title, chevron = false, titleMenu, actions, cl
     </div>
   )
   return (
+    // The title 16px in, where the column's content starts (Katerina, 7 October; it was 20px).
     // With a title menu the bar gives the button 6px of its left padding
-    // (pl-3.5 + the button's px-1.5 = pl-5): the words stay where a title's
+    // (pl-2.5 + the button's px-1.5 = pl-4): the words stay where a title's
     // are, and the fill is inside the bar — a negative margin had it clipped
     // (Katerina, 5 October).
-    <div className={cn('flex h-12 shrink-0 items-center justify-between overflow-hidden border-b border-border-subtle py-2 pr-4', titleMenu != null ? 'pl-3.5' : 'pl-5', className)}>
+    <div className={cn('flex h-12 shrink-0 items-center justify-between overflow-hidden border-b border-border-subtle py-2 pr-4', titleMenu != null ? 'pl-2.5' : 'pl-4', className)}>
       <div className={cn('flex items-center gap-2 overflow-hidden', text ? 'shrink-0' : 'min-w-0 flex-1')}>
         {titleMenu != null ? (
           <Menu

package/src/DialogShell.tsx

@@ -118,7 +118,9 @@ export function DialogShell({ title, onClose, headerContent, footer, children, b
             {/* Header: the package's one header bar, with the dialog's own title in it (UIG-22).
                 The title keeps to its one line and ends in "…": a long name wrapped to
                 two lines in the 48px bar and lost its top (Katerina, 1 October). */}
+            {/* `pl-5`: a dialog's title stays 20px in, over its body and footer, which are. */}
             <ContainerHeader
+              className="pl-5"
               title={
                 headerContent ?? (
                   <Parts.Title className="block truncate text-h4 text-text-primary" render={<span />}>

package/src/ListColumn.mdx

@@ -60,7 +60,7 @@ import { ListColumn, Toolbar, ToolbarButton } from '@estiva-app/ui'
 - It sits beside the page's main area, inside AppShell's card: put both in a
   flex row, the main area `flex-1`.
 - The numbers: 290px wide, a 1px line on the right. The header is
-  ContainerHeader's: 48px, the title 20px in. The list starts 16px under the
+  ContainerHeader's: 48px, the title 16px in. The list starts 16px under the
   header and ends 12px above the bottom, and its rows sit 12px in from each
   side.
 - The rows are yours. It scrolls them, so a list that grows with its data is

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/Popover.mdx

@@ -99,7 +99,9 @@ so it is the one case the caller drives:
 - **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.
+  take focus into — a field the person clicked. `finalFocus={false}` moves
+  nothing on close: a panel that closes because focus left for somewhere else
+  (a type-ahead list whose box was clicked out of) must not pull it back.
 - **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.

package/src/Popover.tsx

@@ -82,9 +82,10 @@ export interface PopoverProps {
    * the trigger and this is not needed. An anchored panel never took focus, so
    * this only matters when something inside it did — a field the person tabbed
    * or clicked into: point it at what they came from, or focus is left on the
-   * document body.
+   * document body. `false` moves nothing: a panel that closes because focus
+   * left for somewhere else must not pull it back (`SuggestionMenu`).
    */
-  finalFocus?: RefObject<HTMLElement | null>
+  finalFocus?: RefObject<HTMLElement | null> | false
   /** Base UI's imperative handle. `actions.current?.close()` shuts the panel —
    *  for the Cancel and Save buttons a form panel ends with. */
   actionsRef?: RefObject<{ close: () => void; unmount: () => void } | null>

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>
+  ),
+}

package/src/ShowMore.test.tsx

@@ -0,0 +1,44 @@
+// @vitest-environment jsdom
+/**
+ * The page's claims: content taller than the limit is cut with "Show more",
+ * which opens it and says so; content that fits has no button at all.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { ShowMore } from './ShowMore'
+
+afterEach(() => {
+  cleanup()
+  vi.restoreAllMocks()
+})
+
+/** jsdom lays nothing out: every box says it is this tall. */
+const contentHeight = (px: number) => vi.spyOn(HTMLElement.prototype, 'scrollHeight', 'get').mockReturnValue(px)
+
+describe('ShowMore', () => {
+  it('cuts content taller than the limit, and opens it', async () => {
+    contentHeight(300)
+    render(<ShowMore maxHeight={96}><p>Long</p></ShowMore>)
+    const button = screen.getByRole('button', { name: 'Show more' })
+    expect(button.getAttribute('aria-expanded')).toBe('false')
+    expect(screen.getByText('Long').parentElement!.style.maxHeight).toBe('96px')
+    await userEvent.click(button)
+    expect(screen.getByRole('button', { name: 'Show less' }).getAttribute('aria-expanded')).toBe('true')
+    expect(screen.getByText('Long').parentElement!.style.maxHeight).toBe('')
+  })
+
+  it('opens when focus arrives inside the cut content', async () => {
+    contentHeight(300)
+    render(<ShowMore maxHeight={96}><input aria-label="Field" /></ShowMore>)
+    await userEvent.click(screen.getByRole('textbox', { name: 'Field' }))
+    expect(screen.getByRole('button', { name: 'Show less' })).toBeTruthy()
+  })
+
+  it('draws content that fits whole, with no button', () => {
+    contentHeight(40)
+    render(<ShowMore maxHeight={96}><p>Short</p></ShowMore>)
+    expect(screen.queryByRole('button')).toBeNull()
+    expect(screen.getByText('Short').parentElement!.style.maxHeight).toBe('')
+  })
+})

package/src/ShowMore.tsx

@@ -0,0 +1,63 @@
+import { useLayoutEffect, useRef, useState, type ReactNode } from 'react'
+import { Button } from './Button'
+import { cn } from './cn'
+
+/**
+ * Long content cut at a height behind a fade, with "Show more" under it
+ * (Katerina, 7 October: a long description on a side panel pushed what was
+ * under it out of sight).
+ *
+ * Content no taller than `maxHeight` is drawn whole, with no fade and no
+ * button: the cut is for what would not fit, never a look. The height is
+ * measured, and measured again whenever the content changes size, so an
+ * edit that makes it long or short brings the button or takes it away.
+ *
+ * The fade ends in the surface the content sits on, which only the caller
+ * knows: `surface`, by name, so no app writes a colour into the part.
+ *
+ * Focus arriving inside the cut content opens it: a field or a link there,
+ * reached by Tab or a click, is never worked on out of sight.
+ */
+export interface ShowMoreProps {
+  children: ReactNode
+  /** The height to cut at, in px. Default 96: about seven lines of caption text. */
+  maxHeight?: number
+  /** What the content sits on, for the fade to end in: a panel's `surface` (default), or an inset card's `inset`. */
+  surface?: 'surface' | 'inset'
+  className?: string
+}
+
+const FADE_CLASSES = { surface: 'from-bg-surface', inset: 'from-bg-inset' } as const
+
+export function ShowMore({ children, maxHeight = 96, surface = 'surface', className }: ShowMoreProps) {
+  const box = useRef<HTMLDivElement>(null)
+  const [open, setOpen] = useState(false)
+  const [overflows, setOverflows] = useState(false)
+
+  useLayoutEffect(() => {
+    const el = box.current
+    if (!el) return
+    const measure = () => setOverflows(el.scrollHeight > maxHeight + 1)
+    measure()
+    if (typeof ResizeObserver === 'undefined') return
+    const observer = new ResizeObserver(measure)
+    observer.observe(el)
+    return () => observer.disconnect()
+  }, [maxHeight])
+
+  const cut = overflows && !open
+  return (
+    <div className={cn('flex flex-col items-start', className)}>
+      <div ref={box} className={cn('relative w-full', cut && 'overflow-hidden')} style={cut ? { maxHeight } : undefined} onFocus={cut ? () => setOpen(true) : undefined}>
+        {children}
+        {cut && <div aria-hidden className={cn('pointer-events-none absolute inset-x-0 bottom-0 h-10 bg-gradient-to-t to-transparent', FADE_CLASSES[surface])} />}
+      </div>
+      {overflows && (
+        // `-ml-1.5`: the small button's own 6px inset, so its words start where the content's do.
+        <Button variant="muted" size="small" className="-ml-1.5 mt-1" aria-expanded={open} onClick={() => setOpen((o) => !o)}>
+          {open ? 'Show less' : 'Show more'}
+        </Button>
+      )}
+    </div>
+  )
+}

package/src/SuggestionMenu.tsx

@@ -186,7 +186,8 @@ export function SuggestionMenu<T>({ rect, editorElement, ariaLabel, width, maxHe
   }
 
   return (
-    <Popover anchor={rect} open={rect !== null} side="top" align="left" className={width} maxHeight={maxHeight} ariaLabel={ariaLabel}>
+    // finalFocus={false}: focus never left the text, and a list that closes because focus moved elsewhere must not pull it back (71a4577b).
+    <Popover anchor={rect} open={rect !== null} side="top" align="left" className={width} maxHeight={maxHeight} ariaLabel={ariaLabel} finalFocus={false}>
       {/* The list the editor drives from its caret: a listbox, because Base UI's lists need a text field of their own.
           `gap-0.5`: 2px between rows, as a menu's — a section with a heading
           had them from `MenuSection`, and rows without one touched. */}

package/src/eslint/no-restyled-part.ts

@@ -151,6 +151,7 @@ export const PART_LOOK_PROPS: Record<string, string[]> = {
   RichText: ['size'],
   SectionHeader: ['hover', 'look'],
   SectionLabel: ['tone', 'truncate'],
+  ShowMore: ['surface'],
   Select: ['size'],
   Tabs: ['size'],
   TextInput: ['size'],

package/src/index.ts

@@ -76,6 +76,7 @@ export { NavTree, NavTreeSection, type NavTreeGroup, type NavTreeNode, type NavT
 export { Popover, type PopoverProps } from './Popover'
 export { SuggestionMenu, type SuggestionMenuHandle, type SuggestionMenuProps, type SuggestionMenuRow, type SuggestionMenuSection } from './SuggestionMenu'
 export { ScrollArea, type ScrollAreaProps } from './ScrollArea'
+export { ShowMore, type ShowMoreProps } from './ShowMore'
 export { ReactionPicker, type ReactionOption, type ReactionPickerProps } from './ReactionPicker'
 export { Toolbar, ToolbarButton, ToolbarInput, ToolbarLink, ToolbarSeparator, type ToolbarProps, type ToolbarButtonProps, type ToolbarInputProps, type ToolbarLinkProps } from './Toolbar'
 export { PreviewCard, type PreviewCardProps } from './PreviewCard'

package/src/looks.ts

@@ -37,6 +37,9 @@ export const FIELD_SHELL_CLASSES = 'bg-bg-field border border-border-field shado
 /** A panel that floats over the page: Menu's panel and Tooltip. */
 export const FLOATING_SURFACE_CLASSES = 'rounded-lg border border-border-default bg-bg-elevated shadow-lg'
 
+/** A count beside a label, in the muted colour: NavItem's number and SectionHeader's `count`. */
+export const COUNT_TEXT_CLASSES = 'font-mono text-caption tabular-nums text-text-muted'
+
 /** A chip's words: Chip's label and Reaction's count. */
 export const CHIP_TEXT_CLASSES = 'text-chip signal:font-mono signal:text-small signal:font-semibold signal:tabular-nums'
 

package/src/registry/registry.test.ts

@@ -48,19 +48,19 @@ describe('the registry builds', () => {
     expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
   })
 
-  it('counts 130 names over 69 files: 100 components, 29 helpers and 1 hook (NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, and moveBlock and blockDropCursor, the drop in the gutter, on 5 October)', () => {
+  it('counts 131 names over 70 files: 101 components, 29 helpers and 1 hook (NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, and ShowMore on 7 October)', () => {
     // The reconciliation GATES.md §24 explains. If this changes, that changes.
     // The ten `EDITOR_EXTENSIONS` count as components by their names; they are
     // editor extensions, documented on SelectionToolbar's, BlockNodes' and
     // ComposerTriggers' pages.
     const kinds = registry.entries.reduce<Record<string, number>>((all, one) => ({ ...all, [one.kind]: (all[one.kind] ?? 0) + 1 }), {})
-    expect(kinds).toEqual({ component: 100, helper: 29, hook: 1 })
-    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(69)
+    expect(kinds).toEqual({ component: 101, helper: 29, hook: 1 })
+    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(70)
   })
 
   it('gives every entry a purpose, from its own page or from the comment above it', () => {
     expect(registry.entries.filter((one) => one.purpose.trim() === '')).toEqual([])
-    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(65)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(66)
     expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(65)
   })
 

package/stories/Choosing.mdx

@@ -83,10 +83,11 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | Label–value rows (a details rail) | **Property** — `row` and `stacked` |
 | The bar across the top of a column: its title, and the buttons that act on the whole column | **ContainerHeader** — inside the package's columns; in an app, the header comes with **Panel** or **ListColumn** |
 | A box that can hold more than fits — a list that grows with its data counts, even when today's data fits | **ScrollArea** — its bar is drawn over the content and takes no width |
+| Text that can run long above things the reader needs, cut behind a fade | **ShowMore** — measures; what fits has no button |
 | A status, a count or a category, in a small pill | **Chip** — six colour types; the colour is the message, the label makes it legible |
 | Something new on a row or a card, no count | **UnreadDot** — the 6px dot in a 24px slot; in a sidebar row, **NavItem** `unread` draws it |
 | One thing — a conversation, a project, an object — as a box you can pick | **Card** — the fill by what it sits on; `href` for a link, `hover="fill"` in a feed |
-| A section heading, chevron, hover actions | **SectionHeader** |
+| A section heading, chevron, hover actions, a count beside the title | **SectionHeader** |
 | A group of rows that opens and closes, and stays how you left it | **CollapsibleSection** — `storageKey` remembers |
 | The uppercase micro-label | **SectionLabel** |
 | A hairline | **Divider** |