@estiva-app/ui 0.36.0 → 0.37.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.36.0",
+  "version": "0.37.1",
   "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.36.0",
-    "exports": 87,
-    "typeExports": 96,
+    "packageVersion": "0.37.1",
+    "exports": 88,
+    "typeExports": 97,
     "files": null
   },
   "storybook": {
@@ -3303,6 +3303,80 @@
         "text-center font-mono text-caption tabular-nums text-text-muted"
       ]
     },
+    {
+      "name": "Panel",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/Panel.tsx",
+      "purpose": "A panel of a page: its name in a header, a body that scrolls whenever it is taller than the room it has, and a row fixed at the bottom when there is one.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "title",
+          "takes": "anything",
+          "required": true,
+          "note": "The panel's name, in its header. A node for a title that is more than words."
+        },
+        {
+          "name": "chevron",
+          "takes": "true/false",
+          "required": false,
+          "note": "A chevron after the title, as `ContainerHeader` draws it."
+        },
+        {
+          "name": "actions",
+          "takes": "anything",
+          "required": false,
+          "note": "The panel's own actions, at the header's right — a `Toolbar` of `ToolbarButton`s, or one `IconButton`."
+        },
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": true,
+          "note": "The body. It scrolls when it is taller than the panel."
+        },
+        {
+          "name": "footer",
+          "takes": "anything",
+          "required": false,
+          "note": "A row fixed under the body that never scrolls — a reply box."
+        },
+        {
+          "name": "bodyClassName",
+          "takes": "text",
+          "required": false,
+          "note": "The body's own box: its padding, gap and layout — `px-4 pt-3 pb-4`, `flex flex-col gap-2`."
+        },
+        {
+          "name": "bodyRef",
+          "takes": "Ref<HTMLDivElement>",
+          "required": false,
+          "note": "The body's scrolling box, for a panel that reads or drives its scroll: a thread that opens at its newest reply."
+        },
+        {
+          "name": "onBodyScroll",
+          "takes": "UIEventHandler<HTMLDivElement>",
+          "required": false,
+          "note": "Fires as the body scrolls."
+        },
+        {
+          "name": "className",
+          "takes": "text",
+          "required": false,
+          "note": "Placement only: a cap such as `max-h-[60%]` when it shares a column."
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "layout-panel--docs",
+      "storyId": "layout-panel--default",
+      "docPage": "src/Panel.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Person",
       "repo": "estiva-ui",

package/src/Panel.mdx

@@ -0,0 +1,78 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as PanelStories from './Panel.stories'
+
+<Meta of={PanelStories} />
+
+# Panel
+
+A panel of a page: its name in a header, a body that scrolls whenever it is
+taller than the room it has, and a row fixed at the bottom when there is one.
+
+<Canvas of={PanelStories.ALongBody} />
+
+## When
+
+- **Any panel of a page that is not a list**: a side column's details, a
+  thread, another app's card beside a file, the contents of what is open.
+  Its body scrolls by itself, so it is never cut off at the fold, even when
+  today's content fits.
+- `footer` for a row that stays put under the body while it scrolls: a reply
+  box.
+- Two panels in one column share it. Cap the first with a `max-h-*` in
+  `className`, and each scrolls in its own room.
+
+<Canvas of={PanelStories.WithAFooter} />
+
+<Canvas of={PanelStories.TwoInAColumn} />
+
+## When not
+
+- A list of things to open beside the page → **ListColumn**, which is a panel
+  with the list's own width and insets.
+- A window over the page → **DialogShell**.
+- A box inside a panel or a card that should scroll on its own → **ScrollArea**.
+
+## How
+
+```tsx
+import { Panel, IconButton } from '@estiva-app/ui'
+
+<Panel
+  title="Details"
+  actions={
+    <IconButton tooltip="More" aria-label="More" onClick={openMenu}>
+      <IconDotsVertical size={16} stroke={1.5} />
+    </IconButton>
+  }
+  bodyClassName="flex flex-col gap-3 px-4 pt-3 pb-4"
+>
+  {sections}
+</Panel>
+```
+
+- It takes the room its column gives it, never its content's height, so the
+  body is what scrolls. Put it straight into the column.
+- `bodyClassName` is the body's padding, gap and layout. The header is
+  ContainerHeader's: 48px, a hairline under it.
+- A panel that follows its scroll (a thread that opens at its newest reply)
+  reads it with `bodyRef` and `onBodyScroll`.
+- **A crash stays inside it.** If its body, its actions or its footer break,
+  it keeps its title and shows "Something went wrong in the panel… try again"
+  in the room the body had. It is **ErrorBoundary**'s.
+
+<Canvas of={PanelStories.WhenTheBodyBreaks} />
+
+## 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 |
+|---|---|---|
+| Draws the header: a ContainerHeader with the title and the actions | a header row of your own over a box | ContainerHeader used on its own in an app |
+| Scrolls its body in a ScrollArea whenever it is taller than the panel, with the bar showing | `overflow-auto`, or a box that cuts off what does not fit |  |
+| Keeps the footer fixed under the body | a flex column of your own around the body and the footer |  |
+| Keeps a crash inside itself: its title stays, the message and Try again sit in the room the body had | an error boundary of your own around it |  |
+
+## Props
+
+<Controls of={PanelStories.Default} />

package/src/Panel.stories.tsx

@@ -0,0 +1,111 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconDotsVertical } from '@tabler/icons-react'
+import { IconButton } from './IconButton'
+import { Panel } from './Panel'
+
+/**
+ * A panel of a page: a header, a body that scrolls whenever it is taller than
+ * the panel, and a row fixed under it when there is one. The body's words are
+ * stand-ins.
+ */
+const meta = {
+  title: 'Layout/Panel',
+  component: Panel,
+  parameters: { layout: 'fullscreen' },
+  args: { title: 'Details', children: null, bodyClassName: 'flex flex-col gap-3 px-4 pt-3 pb-4' },
+  argTypes: { children: { control: false }, actions: { control: false }, footer: { control: false } },
+  // A side column of the frame: 380px wide and a fixed height, where a panel sits beside a page.
+  decorators: [
+    (Story) => (
+      <div className="flex h-[560px] w-[380px] flex-col border-l border-border-subtle bg-bg-surface">
+        {Story()}
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof Panel>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const paragraph = (n: number) => (
+  <p key={n} className="text-body-2 text-text-secondary">
+    Paragraph {n}. What this item is for, who it is for, and what it leaves for later, written out in full the way a real description is.
+  </p>
+)
+const paragraphs = (count: number) => Array.from({ length: count }, (_, i) => paragraph(i + 1))
+const menu = <IconButton tooltip="More" aria-label="More"><IconDotsVertical size={16} stroke={1.5} /></IconButton>
+
+/** A short body: it fits, so there is no bar. */
+export const Default: Story = {
+  args: { actions: menu },
+  render: (args) => <Panel {...args}>{paragraphs(2)}</Panel>,
+}
+
+/** A title that opens something: the chevron after it, as ContainerHeader draws it. */
+export const WithChevron: Story = {
+  args: { chevron: true },
+  render: (args) => <Panel {...args}>{paragraphs(2)}</Panel>,
+}
+
+/** A body taller than the panel: it scrolls, and the bar shows at rest because there is more below. */
+export const ALongBody: Story = {
+  args: { actions: menu },
+  render: (args) => <Panel {...args}>{paragraphs(14)}</Panel>,
+}
+
+/** A row fixed under the body, such as a reply box: the body scrolls above it, and it stays put. */
+export const WithAFooter: Story = {
+  render: (args) => (
+    <Panel
+      {...args}
+      footer={
+        // A stand-in for whatever the footer holds: the part only keeps it in place.
+        <div className="border-t border-border-subtle p-3">
+          <div className="flex h-10 items-center justify-center rounded-md bg-bg-elevated text-caption text-text-muted">Footer</div>
+        </div>
+      }
+    >
+      {paragraphs(12)}
+    </Panel>
+  ),
+}
+
+/** Two panels in one column: the first capped at three fifths, each scrolls in its own room. */
+export const TwoInAColumn: Story = {
+  render: (args) => (
+    <>
+      <Panel {...args} title="Details" className="max-h-[60%]">
+        {paragraphs(10)}
+      </Panel>
+      <Panel {...args} title="Activity">
+        {paragraphs(6)}
+      </Panel>
+    </>
+  ),
+}
+
+/** In a plain box with a height, not a flex column: it still fills it, and the body still scrolls. */
+export const InAPlainBox: Story = {
+  decorators: [
+    (Story) => (
+      <div className="h-[560px] w-[380px] border-l border-border-subtle bg-bg-surface">
+        {Story()}
+      </div>
+    ),
+  ],
+  parameters: { layout: 'fullscreen' },
+  render: (args) => <Panel {...args}>{paragraphs(14)}</Panel>,
+}
+
+function Broken(): never {
+  throw new Error('The body could not draw itself')
+}
+
+/** A crash inside it stays inside it: the title stays, and the message takes the body's room. */
+export const WhenTheBodyBreaks: Story = {
+  render: (args) => (
+    <Panel {...args}>
+      <Broken />
+    </Panel>
+  ),
+}

package/src/Panel.tsx

@@ -0,0 +1,83 @@
+import type { ReactNode, Ref, UIEventHandler } from 'react'
+import { cn } from './cn'
+import { ContainerHeader } from './ContainerHeader'
+import { ErrorBoundary } from './ErrorBoundary'
+import { ScrollArea } from './ScrollArea'
+
+/**
+ * A panel of a page: its name in a `ContainerHeader`, a body under it that
+ * scrolls whenever it is taller than the room it has, and, when there is one,
+ * a row fixed at the bottom that never scrolls — a reply box.
+ *
+ * Made so that scrolling comes from the package, not from each app remembering
+ * it (Katerina, 26 September 2026). The apps built their panels from the
+ * package's header and a box of their own, and a box without a `ScrollArea`
+ * simply cut off what did not fit: Peek's widget panel on a Ship file lost the
+ * end of a long description and the status control under it, with no bar and
+ * nothing to scroll. Here the body is always a `ScrollArea`, so the bar shows
+ * as soon as there is more, and an empty panel or a short one has none.
+ *
+ * It takes the room it is given, never its content's height, so the body is
+ * what scrolls, not the page: the rest of a flex column (`flex-1 min-h-0`), or
+ * the whole of a plain box with a height (`h-full`). The second was missing in
+ * 0.37.0, and a panel in a plain box grew past it: Peek's thread story pushed
+ * its reply box out of its frame. Two panels in one column share it; a
+ * `max-h-*` in `className` caps one of them.
+ *
+ * It keeps a crash inside itself, as ListColumn does: if its body, its actions
+ * or its footer break, the panel keeps its title and shows `ErrorBoundary`'s
+ * message in the room the body had.
+ */
+export interface PanelProps {
+  /** The panel's name, in its header. A node for a title that is more than words. */
+  title: ReactNode
+  /** A chevron after the title, as `ContainerHeader` draws it. */
+  chevron?: boolean
+  /** The panel's own actions, at the header's right — a `Toolbar` of `ToolbarButton`s, or one `IconButton`. */
+  actions?: ReactNode
+  /** The body. It scrolls when it is taller than the panel. */
+  children: ReactNode
+  /** A row fixed under the body that never scrolls — a reply box. */
+  footer?: ReactNode
+  /** The body's own box: its padding, gap and layout — `px-4 pt-3 pb-4`, `flex flex-col gap-2`. */
+  bodyClassName?: string
+  /** The body's scrolling box, for a panel that reads or drives its scroll: a thread that opens at its newest reply. */
+  bodyRef?: Ref<HTMLDivElement>
+  /** Fires as the body scrolls. */
+  onBodyScroll?: UIEventHandler<HTMLDivElement>
+  /** Placement only: a cap such as `max-h-[60%]` when it shares a column. */
+  className?: string
+}
+
+function Frame({ title, chevron = false, actions, children, footer, bodyClassName, bodyRef, onBodyScroll, className, broken = false }: PanelProps & { broken?: boolean }) {
+  return (
+    <div className={cn('flex h-full min-h-0 flex-1 flex-col', className)}>
+      <ContainerHeader title={title} chevron={chevron} actions={actions} />
+      {broken ? (
+        // The message takes the room the body had and centres itself in it.
+        <div className="flex min-h-0 flex-1 flex-col px-4">{children}</div>
+      ) : (
+        <ScrollArea className="min-h-0 flex-1" contentClassName={bodyClassName} viewportRef={bodyRef} onScroll={onBodyScroll}>
+          {children}
+        </ScrollArea>
+      )}
+      {!broken && footer && <div className="shrink-0">{footer}</div>}
+    </div>
+  )
+}
+
+export function Panel(props: PanelProps) {
+  return (
+    <ErrorBoundary
+      label="panel"
+      frame={(message) => (
+        // Only the name comes back with the message: the actions and the footer may be what threw.
+        <Frame title={props.title} chevron={props.chevron} className={props.className} broken>
+          {message}
+        </Frame>
+      )}
+    >
+      <Frame {...props} />
+    </ErrorBoundary>
+  )
+}

package/src/ScrollArea.mdx

@@ -6,8 +6,8 @@ import * as ScrollAreaStories from './ScrollArea.stories'
 # ScrollArea
 
 A region that scrolls without taking width for its scrollbar. The bar is
-drawn over the content and shows while the pointer is over the region or
-the content is moving; nothing moves when it appears.
+drawn over the content and shows whenever there is more to scroll to, so a
+long list says so before anyone hovers it; nothing moves when it appears.
 
 <Canvas of={ScrollAreaStories.Default} />
 

package/src/ScrollArea.stories.tsx

@@ -15,7 +15,7 @@ type Story = StoryObj<typeof meta>
 
 const rows = Array.from({ length: 40 }, (_, i) => `Row ${i + 1}`)
 
-/** A list taller than its box. The bar shows while the pointer is over it or the list is moving. */
+/** A list taller than its box. The bar shows at rest, because there is more to scroll to. */
 export const Default: Story = {
   render: () => (
     <Card className="h-[240px] w-[280px]">

package/src/ScrollArea.tsx

@@ -10,8 +10,13 @@ import { cn } from './cn'
  * right-hand padding looks wider than the left. Katerina saw it in every
  * scrolling surface of both apps (2026-09-08). Base UI's `ScrollArea` hides
  * the native bar and draws its own over the content, so nothing moves when
- * it appears; the bar shows while the pointer is over the region or the
- * content is moving, and fades otherwise.
+ * it appears.
+ *
+ * The bar shows whenever the region has more to scroll to, at rest too
+ * (Katerina, 26 September: a long folder list in Peek's side column looked
+ * complete, because the bar waited for the pointer). Base UI writes
+ * `data-has-overflow-y` / `-x` on the bar while that axis overflows; a region
+ * with nothing more to show keeps no bar at all.
  *
  * Three boxes, and each class prop lands on one:
  *
@@ -99,12 +104,12 @@ export function ScrollArea({ orientation = 'vertical', className, viewportClassN
         </BaseScrollArea.Content>
       </BaseScrollArea.Viewport>
       {vertical && (
-        <BaseScrollArea.Scrollbar orientation="vertical" className={cn(BAR, 'w-1.5 justify-center py-0.5 pr-0.5')}>
+        <BaseScrollArea.Scrollbar orientation="vertical" className={cn(BAR, 'w-1.5 justify-center py-0.5 pr-0.5 data-[has-overflow-y]:opacity-100')}>
           <BaseScrollArea.Thumb className={cn(THUMB, 'w-full')} />
         </BaseScrollArea.Scrollbar>
       )}
       {horizontal && (
-        <BaseScrollArea.Scrollbar orientation="horizontal" className={cn(BAR, 'h-1.5 flex-col justify-center px-0.5 pb-0.5')}>
+        <BaseScrollArea.Scrollbar orientation="horizontal" className={cn(BAR, 'h-1.5 flex-col justify-center px-0.5 pb-0.5 data-[has-overflow-x]:opacity-100')}>
           <BaseScrollArea.Thumb className={cn(THUMB, 'h-full')} />
         </BaseScrollArea.Scrollbar>
       )}

package/src/eslint/no-handmade-header.test.ts

@@ -17,6 +17,10 @@ const handmade = [{ messageId: 'handmade' }]
 
 tester.run('no-handmade-header', noHandmadeHeader, {
   valid: [
+    // 26 September: the package's own parts import the header from their sibling file.
+    { name: 'the header inside the package, from its own file', code: `import { ContainerHeader } from './ContainerHeader'\n${component('<ContainerHeader title="Files" />')}` },
+    { name: 'Panel in an app', code: `import { Panel } from '@estiva-app/ui'\n${component('<Panel title="Files">x</Panel>')}` },
+    { name: 'the bare header in an app, escaped with its reason', code: `import { ContainerHeader } from '@estiva-app/ui'\n${component('// @estiva-escape(no-handmade-header): a header over a loading skeleton that cannot scroll\n<ContainerHeader title="Files" />')}` },
     { name: 'the part itself', code: component('<div className="flex h-full flex-col">\n<ContainerHeader title="Files" />\n<div />\n</div>') },
     {
       name: "a group heading inside a list: SectionHeader's row, not a column's bar (Ship's issue groups)",
@@ -37,6 +41,11 @@ tester.run('no-handmade-header', noHandmadeHeader, {
     },
   ],
   invalid: [
+    {
+      name: "the package's header on its own in an app: a panel made by hand, naming Panel (26 September)",
+      code: `import { ContainerHeader as Header } from '@estiva-app/ui'\n${component('<div className="flex flex-col">\n<Header title="Estiva Ship" />\n<div className="px-4">{title}</div>\n</div>')}`,
+      errors: [{ messageId: 'bare' }],
+    },
     {
       // The Folders page's right pane, at the commit before 3dc663b.
       name: 'a pane that heads itself around an editable name',

package/src/eslint/no-handmade-header.ts

@@ -121,20 +121,42 @@ const INTERACTIVE = ['onClick', 'href', 'role', 'onKeyDown', 'onPointerDown']
  * What it leaves alone, on purpose: a group heading inside a list (the row one
  * section starts with), a label strip on a card, and a row a person presses.
  * Only a lowercase element is judged: a part is already a part.
+ *
+ * And the package's `ContainerHeader` on its own in an app (26 September): a
+ * header over a box of the app's own is a panel made by hand, and the box is
+ * what forgot to scroll — Peek's widget panel cut off a long description. The
+ * message names `Panel`, whose body always scrolls.
  */
 export const noHandmadeHeader: Rule.RuleModule = {
   meta: {
     type: 'problem',
-    docs: { description: "A column's header bar drawn by hand where ContainerHeader is the part" },
+    docs: { description: "A column's header bar drawn by hand, or the package's header on its own in an app, where Panel is the part" },
     schema: [],
     messages: {
       handmade:
-        "A column's header bar drawn by hand. Use `ContainerHeader` from @estiva-app/ui: 48px, the title, the column's buttons at the right edge (`actions`), a hairline under it.",
+        "A column's header bar drawn by hand. Use `Panel` from @estiva-app/ui: its header (48px, the title, the column's buttons at the right edge in `actions`, a hairline under it) and a body under it that scrolls. For a list beside the page, `ListColumn`.",
+      bare:
+        "A panel put together by hand: `ContainerHeader` over a box of your own, which cuts off whatever does not fit. Use `Panel` from @estiva-app/ui: the same header (`title`, `actions`), a body that scrolls whenever it is taller, and a `footer` that stays put. For a list beside the page, `ListColumn`.",
       ...ESCAPE_MESSAGES,
     },
   },
   create(context) {
+    // The package's header, imported by name in an app (Katerina, 26 September): in an
+    // app it comes with Panel or ListColumn, whose body scrolls. The package's own parts
+    // import it from their sibling file, so this never reads them.
+    const bare = new Set<string>()
     return {
+      ImportDeclaration(node: Rule.Node) {
+        const declaration = node as unknown as { source: { value: unknown }; specifiers: { type: string; imported?: { name?: string }; local: { name: string } }[] }
+        if (declaration.source.value !== '@estiva-app/ui') return
+        for (const specifier of declaration.specifiers) if (specifier.type === 'ImportSpecifier' && specifier.imported?.name === 'ContainerHeader') bare.add(specifier.local.name)
+      },
+      JSXOpeningElement(node: Rule.Node) {
+        const element = node as unknown as JSXElement['openingElement']
+        if (element.name.type !== 'JSXIdentifier' || !bare.has(element.name.name ?? '')) return
+        if (isEscaped(context, element)) return
+        context.report({ loc: element.loc, messageId: 'bare' })
+      },
       JSXElement(node: Rule.Node) {
         const column = node as unknown as JSXElement
         const kids = meaningful(column)

package/src/eslint/no-native-title.ts

@@ -8,7 +8,7 @@ import { bindingOfTag, partsOfFile, type Node, type Parser, type PartBinding } f
  * the browser shows it as its tooltip. `no-native-title.test.ts` holds this
  * list to the catalogue: a part that gains a `title` of its own joins it.
  */
-export const PARTS_WITH_A_TITLE = ['CollapsibleSection', 'ConfirmDialog', 'ContainerHeader', 'DialogShell', 'ListColumn', 'SectionHeader'] as const
+export const PARTS_WITH_A_TITLE = ['CollapsibleSection', 'ConfirmDialog', 'ContainerHeader', 'DialogShell', 'ListColumn', 'Panel', 'SectionHeader'] as const
 
 const child = (node: Node, key: string) => node[key] as Node | null | undefined
 const nameOf = (node: Node | null | undefined): string | undefined =>

package/src/gates/app-checks.ts

@@ -31,7 +31,7 @@ export interface AppCheckOptions {
   chain?: { ref: string; owner: boolean }
   /** The token lint configs the app has, relative to the app. */
   tokenConfigs?: string[]
-  /** The part a hand-made column header should name (UIG-22): `ContainerHeader`. */
+  /** The part a hand-made column header should name (UIG-22): `Panel` since 0.37.0, `ContainerHeader` before. */
   headers?: string[]
 }
 
@@ -70,7 +70,7 @@ function all(h: GateHelpers, steps: (() => CheckResult | Promise<CheckResult>)[]
   }
 }
 
-export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG-3', owner: false }, tokenConfigs = ['eslint.tokens.config.js', 'eslint.config.js'], headers = ['ContainerHeader'] }: AppCheckOptions): GateTicket[] {
+export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG-3', owner: false }, tokenConfigs = ['eslint.tokens.config.js', 'eslint.config.js'], headers = ['Panel'] }: AppCheckOptions): GateTicket[] {
   const WEB = app === '.' ? '' : `${app.replace(/\/$/, '')}/`
   const cwd = app === '.' ? undefined : app
   const PROBE = 'src/components/__gates_probe__.tsx'
@@ -221,7 +221,9 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
     ]),
     ticket('UIG-22', [
       // The Folders pane's own row, at the commit before peek 3dc663b.
-      { what: 'a hand-made column header is an error naming ContainerHeader', run: all(h, headers.map((name) => probe(component('<div className="flex h-full flex-col"><div className="flex items-center gap-2 px-3 py-2"><span>Folders</span></div><div /></div>'), 'error', name)), 'a hand-made column header is an error naming ContainerHeader') },
+      { what: `a hand-made column header is an error naming ${headers.join(' or ')}`, run: all(h, headers.map((name) => probe(component('<div className="flex h-full flex-col"><div className="flex items-center gap-2 px-3 py-2"><span>Folders</span></div><div /></div>'), 'error', name)), `a hand-made column header is an error naming ${headers.join(' or ')}`) },
+      // 26 September: the package's header on its own is a panel made by hand, whose box forgot to scroll.
+      { what: "the package's ContainerHeader on its own is an error naming Panel", run: probe(`import { ContainerHeader } from '@estiva-app/ui'\n${component('<div className="flex flex-col"><ContainerHeader title="Details" /><div className="px-4">x</div></div>')}`, 'error', '`Panel`') },
       { what: 'a group heading inside a list is left alone', run: probe(component('<section className="flex flex-col gap-px"><h3 className="flex h-8 items-center gap-2 px-3"><span>Todo</span></h3><div /></section>'), 'none') },
     ]),
     ticket('UIG-23', [

package/src/index.ts

@@ -83,6 +83,7 @@ export { Reaction, type ReactionProps } from './Reaction'
 export { SearchInput, type SearchInputProps } from './SearchInput'
 export { SectionHeader, type SectionAction, type SectionHeaderProps } from './SectionHeader'
 export { ContainerHeader, type ContainerHeaderProps } from './ContainerHeader'
+export { Panel, type PanelProps } from './Panel'
 export { ListColumn, type ListColumnProps } from './ListColumn'
 export { CollapsibleSection, type CollapsibleSectionProps } from './CollapsibleSection'
 export { SectionLabel } from './SectionLabel'

package/src/registry/app.test.ts

@@ -567,7 +567,9 @@ describe('one search over the package and the apps', () => {
       repo: 'fixture',
     })
     const found = findInRegistries([packageRegistry, header], 'panel header', { limit: 5 }).map((f) => `${f.entry.repo}:${f.entry.name}`)
-    expect(found[0]).toBe('estiva-ui:ContainerHeader')
+    // Since 0.37.0 an app's panel header is Panel's (26 September): the package answers first either way.
+    expect(found[0]).toBe('estiva-ui:Panel')
+    expect(found).toContain('estiva-ui:ContainerHeader')
     expect(found).toContain('fixture:Header')
   })
 

package/src/registry/registry.test.ts

@@ -45,16 +45,16 @@ describe('the registry builds', () => {
     expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
   })
 
-  it('counts 87 names over 57 files: 80 components, 6 helpers and 1 hook (Lightbox joined in UIG-35)', () => {
+  it('counts 88 names over 58 files: 81 components, 6 helpers and 1 hook (Panel joined on 26 September)', () => {
     // The reconciliation GATES.md §24 explains. If this changes, that changes.
     const kinds = registry.entries.reduce<Record<string, number>>((all, one) => ({ ...all, [one.kind]: (all[one.kind] ?? 0) + 1 }), {})
-    expect(kinds).toEqual({ component: 80, helper: 6, hook: 1 })
-    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(57)
+    expect(kinds).toEqual({ component: 81, helper: 6, hook: 1 })
+    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(58)
   })
 
   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(57)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(58)
     expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(30)
   })
 

package/stories/Choosing.mdx

@@ -75,7 +75,7 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | You need | Reach for |
 |---|---|
 | 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** — one per column; the actions as IconButtons in `actions` |
+| 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 |
 | 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 |
 | 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 |
@@ -115,11 +115,12 @@ the **floating** TopBar goes with the **Rail** and the content card.
 | A 64px icon strip | **Rail**, filled with **RailItem** tiles |
 | The menu button and the logo | the TopBar's `menu` and `logo` slots — collapsing stays yours |
 | The list beside the thing that is open | **ListColumn** — 290px, its name in a **ContainerHeader**, the list under it scrolling |
+| A panel of a page that is not a list — details, a thread, what is open — with a body that must never be cut off | **Panel** — a header, a body that scrolls whenever it is taller, and a `footer` that stays put |
 
 ## Deliberately not in the package
 
 - Anything that knows your **product's objects** — its documents, threads,
   files, tickets. Build it in your app, out of these parts, and keep its
   stories in your app's own Storybook.
-- Page layouts beyond the list column (**ListColumn**) and a column's bar
-  (**ContainerHeader**) — split views, side rails — not here yet.
+- Page layouts beyond the list column (**ListColumn**) and a panel
+  (**Panel**) — split views, side rails — not here yet.