@estiva-app/ui 0.12.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.12.0",
+  "version": "0.12.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/src/AppShell.mdx

@@ -39,6 +39,21 @@ Layout only: no data, no routes.
 
 ## How
 
+**The page contract, in the solid manner.** The frame owns the page's
+scrollbar: the content column is a ScrollArea, and `main` inside it is a
+flex column. A page is a flex child of `main`, and says one of two things:
+
+- `flex-1` — it fills the frame and, when taller, scrolls in the frame's
+  bar. A list page. (Its empty state centres on its own.)
+- `flex-1 min-h-0 [contain:size]` — it takes exactly the frame's height
+  and scrolls inside itself, in regions of its own. A detail page with a
+  content column and a rail.
+
+Never `h-full`: the frame's content box is *at least* the viewport's
+height and grows with a tall page — which is what lets the bar know the
+page changed — so a percentage height has nothing to resolve against.
+Measured on all four of Ship's pages (2026-09-09).
+
 ```tsx
 import { AppShell, Banner, IdentityMenu, Rail, RailItem } from '@estiva-app/ui'
 

package/src/AppShell.stories.tsx

@@ -74,6 +74,21 @@ export const Solid: Story = {
 }
 
 /** The banner belongs to the content area — at its top, never across the navigation. */
+/** A page taller than the frame: it scrolls in the frame's own bar — the region every page passes through — never a native one. */
+export const SolidScrolls: Story = {
+  render: (args) => (
+    <AppShell {...args} logo="Estiva" search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />} identity={identity} nav={sidebar}>
+      <div className="flex flex-col gap-px px-6 py-5">
+        {Array.from({ length: 60 }, (_, i) => (
+          <p key={i} className="rounded-md px-2 py-1.5 text-body-2 text-text-primary">
+            Row {i + 1}
+          </p>
+        ))}
+      </div>
+    </AppShell>
+  ),
+}
+
 export const SolidWithBanner: Story = {
   render: (args) => (
     <AppShell {...args} logo="Estiva" identity={identity} nav={sidebar} banner={<Banner tone="ok">Public key copied.</Banner>}>

package/src/AppShell.test.tsx

@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+/**
+ * The frame owns the page's scrollbar (2026-09-09): in the solid manner the
+ * page lands inside a ScrollArea's viewport — Base UI's `overflow: scroll`
+ * box — so no page can scroll in a native bar. Whether the bar takes width,
+ * and whether an inner region still scrolls on its own, is measured in
+ * Chrome on Ship's four pages.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { AppShell } from './AppShell'
+
+afterEach(cleanup)
+
+describe('AppShell', () => {
+  it('puts the page inside the frame’s scrolling region in the solid manner', () => {
+    render(
+      <AppShell nav={<nav>Nav</nav>}>
+        <p>Page</p>
+      </AppShell>,
+    )
+    const main = screen.getByRole('main')
+    const viewport = main.closest('[style*="overflow: scroll"]') as HTMLElement | null
+    expect(viewport).not.toBeNull()
+    expect(viewport!.contains(screen.getByText('Page'))).toBe(true)
+    expect(main.className).not.toContain('overflow-y-auto')
+  })
+
+  it('leaves the floating manner’s card as it was', () => {
+    render(
+      <AppShell variant="floating" nav={<nav>Nav</nav>}>
+        <p>Page</p>
+      </AppShell>,
+    )
+    const main = screen.getByRole('main')
+    expect(main.className).toContain('overflow-hidden')
+    expect(main.closest('[style*="overflow: scroll"]')).toBeNull()
+  })
+})

package/src/AppShell.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react'
 import { cn } from './cn'
+import { ScrollArea } from './ScrollArea'
 import { TopBar } from './TopBar'
 
 /**
@@ -63,7 +64,9 @@ export function AppShell({ variant = 'solid', menu, logo, search, identity, bann
   }
 
   return (
-    /* `relative overflow-hidden` is the seal the floating manner already has,
+    /* `relative overflow-hidden` is the seal the floating manner already has
+       (and the ScrollArea's own root is `relative`, so an absolutely placed
+       stray inside a page now belongs to the region and scrolls with it),
        and it takes both halves: an absolutely positioned descendant with no
        positioned ancestor belongs to the *viewport*, so a scroll container
        never clips it and the document itself gains its position as scroll
@@ -76,12 +79,24 @@ export function AppShell({ variant = 'solid', menu, logo, search, identity, bann
         {nav}
         <div className="flex min-h-0 min-w-0 flex-1 flex-col">
           {banner}
-          {/* Not a ScrollArea: the apps' pages scroll inside themselves (Ship's
-              detail columns are `h-full` grids with their own regions), and a
-              region here kept a bar on Ship's page for overflow that was not
-              there (2026-09-09). A page that does scroll here gets its region
-              where it scrolls. */}
-          <main className="min-w-0 flex-1 overflow-y-auto">{children}</main>
+          {/* The frame owns the page's scrollbar (Katerina, 2026-09-09: the
+              Issues page still had a native bar — D40 said everywhere, and the
+              one place every page passes through had been left out). A
+              `ScrollArea` here means no page can forget it. The content box is
+              at least the viewport's height and grows with a tall page, so Base
+              UI sees its size change (the morning's phantom bar was a content
+              box it could not watch); `main` fills it as a flex column. The
+              page contract (the AppShell page says it): a page is a flex
+              child of `main` — `flex-1` to fill and scroll here; `flex-1
+              min-h-0 [contain:size]` to take exactly the frame's height and
+              scroll inside itself, as Ship's detail grids do — and the outer
+              region, with nothing to scroll, passes the wheel through. Never
+              `h-full`: a box that is *at least* the viewport's height gives a
+              percentage nothing to resolve against — measured, all four Ship
+              pages, 2026-09-09. */}
+          <ScrollArea className="min-h-0 flex-1" contentClassName="flex min-h-full flex-col">
+            <main className="flex min-w-0 flex-1 flex-col">{children}</main>
+          </ScrollArea>
         </div>
       </div>
     </div>

package/src/EmptyState.mdx

@@ -29,8 +29,9 @@ message is still a `page`; a tall section with nothing in it is still a
 Start the thread." — not just that it is empty.
 
 A `page` sits in the middle of its box both ways. Inside a flex column
-it takes the room left (`flex-1`) and centres in it; drawn straight into
-a page, give it the height — `className="h-full"`.
+— the frame's `main` is one — it takes the room left (`flex-1`) and
+centres in it, with nothing to add; only outside a flex column does it
+need a height from the caller (`className="h-full"`).
 
 ## When not
 
@@ -44,8 +45,8 @@ a page, give it the height — `className="h-full"`.
 ```tsx
 import { EmptyState } from '@estiva-app/ui'
 
-// the whole page, drawn straight into it
-<EmptyState className="h-full" message="No documents yet. Create the first one." />
+// the whole page, in the frame: it fills and centres on its own
+<EmptyState message="No documents yet. Create the first one." />
 
 // one section of a page
 <EmptyState scope="section" message="No comments yet." />