@estiva-app/ui 0.38.0 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.38.0",
+  "version": "0.39.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,7 +4,7 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.38.0",
+    "packageVersion": "0.39.0",
     "exports": 88,
     "typeExports": 97,
     "files": null
@@ -21,12 +21,12 @@
       "kind": "component",
       "importPath": "@estiva-app/ui",
       "sourceFile": "src/AppShell.tsx",
-      "purpose": "The frame of an app, in the two manners that pair: `solid` — the structured frame, a solid TopBar over a Sidebar and the content beside it — and `floating` — the TopBar floating over the top edge, a Rail standing on the background, and the content living in the rounded card.",
+      "purpose": "The frame of an app, in three manners: `solid` — the structured frame, a solid TopBar over a Sidebar and the content beside it — `inset` — the same frame the other way round, the TopBar and the Sidebar standing on the ground and the content a lighter card beside them — and `floating` — the TopBar floating over the top edge, a Rail standing on the background, and the content living in the rounded card.",
       "purposeFrom": "page",
       "props": [
         {
           "name": "variant",
-          "takes": "solid | floating",
+          "takes": "solid | floating | inset",
           "required": false,
           "note": null
         },
@@ -78,7 +78,8 @@
           "prop": "variant",
           "values": [
             "solid",
-            "floating"
+            "floating",
+            "inset"
           ]
         }
       ],
@@ -5412,7 +5413,7 @@
       "props": [
         {
           "name": "variant",
-          "takes": "solid | floating",
+          "takes": "solid | floating | inset",
           "required": false,
           "note": null
         },
@@ -5452,7 +5453,8 @@
           "prop": "variant",
           "values": [
             "solid",
-            "floating"
+            "floating",
+            "inset"
           ]
         }
       ],

package/src/AppShell.mdx

@@ -5,14 +5,18 @@ import * as AppShellStories from './AppShell.stories'
 
 # AppShell
 
-The frame of an app, in the two manners that pair: **`solid`** — the
-structured frame, a solid TopBar over a Sidebar and the content beside
-it — and **`floating`** — the TopBar floating over the top edge, a Rail
+The frame of an app, in three manners: **`solid`** — the structured
+frame, a solid TopBar over a Sidebar and the content beside it —
+**`inset`** — the same frame the other way round, the TopBar and the
+Sidebar standing on the ground and the content a lighter card beside
+them — and **`floating`** — the TopBar floating over the top edge, a Rail
 standing on the background, and the content living in the rounded card.
 Layout only: no data, no routes.
 
 <Canvas of={AppShellStories.Solid} />
 
+<Canvas of={AppShellStories.Inset} />
+
 <Canvas of={AppShellStories.Floating} />
 
 ## When
@@ -20,6 +24,10 @@ Layout only: no data, no routes.
 - **`solid` + Sidebar** — a place-by-place app: labelled entries, counts,
   groups. Sidebar and main scroll independently, so a long list never
   scrolls the navigation away.
+- **`inset` + Sidebar** — the same place-by-place app, when its pages
+  read as one sheet on a desk: the content is a card 16px from the right
+  and bottom, with 8px corners, and the Sidebar drops its line and surface
+  by itself. Any theme: the ground and the card are its base and surface.
 - **`floating` + Rail** — an app with a handful of top-level places and
   its content in one card; the `menu` button in the bar collapses the
   rail (the collapsing stays the app's).

package/src/AppShell.stories.tsx

@@ -95,6 +95,25 @@ export const SolidWithBanner: Story = {
   ),
 }
 
+/** The structured frame the other way round: the bar and the sidebar on the ground, the content a lighter card beside them. */
+export const Inset: Story = {
+  args: { variant: 'inset' },
+  render: (args) => (
+    <AppShell {...args} logo="Estiva" search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />} identity={identity} nav={sidebar}>
+      <EmptyState message="Nothing here yet." />
+    </AppShell>
+  ),
+}
+
+export const InsetWithBanner: Story = {
+  args: { variant: 'inset' },
+  render: (args) => (
+    <AppShell {...args} logo="Estiva" identity={identity} nav={sidebar} banner={<Banner tone="ok">Public key copied.</Banner>}>
+      <EmptyState message="Nothing here yet." />
+    </AppShell>
+  ),
+}
+
 /** The floating frame: the bar floats over the top edge, the rail stands on the background, and the content lives in the rounded card. */
 export const Floating: Story = {
   render: (args) => (

package/src/AppShell.test.tsx

@@ -9,6 +9,7 @@
 import { afterEach, describe, expect, it } from 'vitest'
 import { cleanup, render, screen } from '@testing-library/react'
 import { AppShell } from './AppShell'
+import { Sidebar } from './Sidebar'
 
 afterEach(cleanup)
 
@@ -26,6 +27,25 @@ describe('AppShell', () => {
     expect(main.className).not.toContain('overflow-y-auto')
   })
 
+  it('stands the sidebar on the ground and makes the content a panel in the inset manner, and only there', () => {
+    const frame = (variant: 'solid' | 'inset') =>
+      render(
+        <AppShell variant={variant} nav={<Sidebar>Rows</Sidebar>}>
+          <p>Page</p>
+        </AppShell>,
+      )
+    const { unmount } = frame('solid')
+    expect(screen.getByRole('navigation').className).toContain('border-r')
+    expect(screen.getByRole('banner').className).toContain('border-b')
+    unmount()
+    frame('inset')
+    expect(screen.getByRole('navigation').className).not.toMatch(/border-r|bg-bg-surface/)
+    expect(screen.getByRole('banner').className).not.toMatch(/border-b|bg-bg-surface/)
+    const panel = screen.getByRole('main').closest('.rounded-lg')
+    expect(panel?.className).toContain('bg-bg-surface')
+    expect(panel?.className).toContain('mr-4')
+  })
+
   it('leaves the floating manner’s card as it was', () => {
     render(
       <AppShell variant="floating" nav={<nav>Nav</nav>}>

package/src/AppShell.tsx

@@ -1,10 +1,12 @@
 import type { ReactNode } from 'react'
 import { cn } from './cn'
+import { Card } from './Card'
 import { ScrollArea } from './ScrollArea'
+import { SidebarOnGround } from './Sidebar'
 import { TopBar } from './TopBar'
 
 /**
- * The frame of an app, in the two manners that pair with the TopBar's
+ * The frame of an app, in the manners that pair with the TopBar's
  * (Katerina, 2026-09-02: the two shells go together — the solid bar with
  * the sidebar, the floating bar with the rail):
  *
@@ -15,6 +17,9 @@ import { TopBar } from './TopBar'
  *   edge, the rail stands on the app background, and the content lives
  *   in the rounded card beside it (2026-09-02, the floating app's frame
  *   geometry; its collapse animation and launcher stay in the app).
+ * - `inset` — the structured frame, the other way round: the TopBar and
+ *   the Sidebar stand on the ground, and the content is a lighter card
+ *   beside them (Katerina, 28 September: Linear's layout, in any theme).
  *
  * The banner belongs to the content area (her ruling, 2026-09-02): it
  * renders at the top of the main column — inside the card, in the
@@ -24,7 +29,7 @@ import { TopBar } from './TopBar'
  * has no data and no routes.
  */
 export interface AppShellProps {
-  variant?: 'solid' | 'floating'
+  variant?: 'solid' | 'floating' | 'inset'
   /** The top bar's menu button, in an app whose navigation collapses. */
   menu?: ReactNode
   /** The top bar's left: the app's logo mark, or its name as text. */
@@ -42,6 +47,7 @@ export interface AppShellProps {
 
 export function AppShell({ variant = 'solid', menu, logo, search, identity, banner, nav, children }: AppShellProps) {
   const bar = <TopBar variant={variant} menu={menu} logo={logo} search={search} right={identity} />
+  const inset = variant === 'inset'
 
   if (variant === 'floating') {
     return (
@@ -66,6 +72,30 @@ export function AppShell({ variant = 'solid', menu, logo, search, identity, bann
     )
   }
 
+  const column = (
+    <>
+      {banner}
+      {/* 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>
+    </>
+  )
+
   return (
     /* `relative overflow-hidden` is the seal the floating manner already has
        (and the ScrollArea's own root is `relative`, so an absolutely placed
@@ -79,28 +109,17 @@ export function AppShell({ variant = 'solid', menu, logo, search, identity, bann
     <div className="relative flex h-full min-h-0 flex-col overflow-hidden bg-bg-base text-text-primary">
       {bar}
       <div className="flex min-h-0 flex-1">
-        {nav}
-        <div className="flex min-h-0 min-w-0 flex-1 flex-col">
-          {banner}
-          {/* 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>
+        <SidebarOnGround.Provider value={inset}>{nav}</SidebarOnGround.Provider>
+        {/* `inset`: the content is a card on the ground, the Card's own surface look,
+            16px from the right and bottom as the floating card is, 8px corners (Katerina,
+            28 September). */}
+        {inset ? (
+          <Card fill="surface" clip className="mb-4 mr-4 flex min-h-0 min-w-0 flex-1 flex-col">
+            {column}
+          </Card>
+        ) : (
+          <div className="flex min-h-0 min-w-0 flex-1 flex-col">{column}</div>
+        )}
       </div>
     </div>
   )

package/src/Sidebar.tsx

@@ -1,4 +1,4 @@
-import type { ReactNode } from 'react'
+import { createContext, useContext, type ReactNode } from 'react'
 import { cn } from './cn'
 import { ScrollArea } from './ScrollArea'
 
@@ -10,6 +10,10 @@ import { ScrollArea } from './ScrollArea'
  * What goes inside is the caller's: NavItem rows, a SectionLabel heading
  * in a 32px row over a group. Desktop only — there is no narrow-screen
  * drawer.
+ *
+ * In AppShell's `inset` frame it stands on the ground instead: no hairline,
+ * no surface, the content's card beside it (Katerina, 28 September). The
+ * frame tells it so; the caller passes nothing.
  */
 export interface SidebarProps {
   /** Names the navigation region for assistive tech. */
@@ -18,11 +22,15 @@ export interface SidebarProps {
   className?: string
 }
 
+/** Set by AppShell's `inset` frame: the sidebar stands on the ground, with no line or surface of its own. */
+export const SidebarOnGround = createContext(false)
+
 export function Sidebar({ 'aria-label': ariaLabel = 'Workspace', children, className }: SidebarProps) {
+  const onGround = useContext(SidebarOnGround)
   return (
     <nav
       aria-label={ariaLabel}
-      className={cn('flex w-60 shrink-0 flex-col border-r border-border-default bg-bg-surface', className)}
+      className={cn('flex w-60 shrink-0 flex-col', !onGround && 'border-r border-border-default bg-bg-surface', className)}
     >
       {/* The rows scroll in a ScrollArea: the bar takes no width, so the
           column's padding reads the same with a long list as with a short

package/src/TopBar.mdx

@@ -6,10 +6,10 @@ import * as TopBarStories from './TopBar.stories'
 # TopBar
 
 The 52px top bar: `menu` and `logo` on the left, a `search` slot in the
-centre, the identity cluster on the right. Two manners — **`solid`**, in
-flow with a hairline and a surface, and **`floating`**, an overlay with
-neither, whose bar ignores the pointer so the content underneath stays
-reachable.
+centre, the identity cluster on the right. Three manners — **`solid`**,
+in flow with a hairline and a surface; **`inset`**, in flow with neither,
+standing on the ground; and **`floating`**, an overlay with neither, whose
+bar ignores the pointer so the content underneath stays reachable.
 
 <Canvas of={TopBarStories.Solid} />
 
@@ -19,6 +19,8 @@ reachable.
 
 - **`solid`** — the structured frame's first row, above the sidebar
   (AppShell's `solid` variant wires exactly this).
+- **`inset`** — the first row of AppShell's `inset` frame, on the ground
+  above a sidebar that is on the ground too.
 - **`floating`** — an app whose content runs to the top edge; the bar
   floats over it and only its clusters catch clicks (AppShell's
   `floating` variant).

package/src/TopBar.tsx

@@ -2,7 +2,7 @@ import type { ReactNode } from 'react'
 import { cn } from './cn'
 
 /**
- * The 52px top bar, in two manners:
+ * The 52px top bar, in three manners:
  *
  * - `solid` — in flow: a hairline under it, the surface behind it, the
  *   frame's first row (2026-09-02, verbatim from the structured app; its
@@ -11,6 +11,9 @@ import { cn } from './cn'
  *   background, and the bar itself ignores the pointer — only its clusters
  *   catch clicks, so the content underneath stays reachable (2026-09-02,
  *   verbatim from the floating app).
+ * - `inset` — in flow like `solid`, but standing on the ground: no hairline
+ *   and no surface, above a sidebar on the ground and the content's card
+ *   (Katerina, 28 September).
  *
  * Geometry both apps agreed on before extraction: 52px tall, `pl-5
  * pr-[26px]`, right cluster `gap-[6px]`. The left region is two slots
@@ -20,7 +23,7 @@ import { cn } from './cn'
  * searched; it only knows where those go.
  */
 export interface TopBarProps {
-  variant?: 'solid' | 'floating'
+  variant?: 'solid' | 'floating' | 'inset'
   /** Far left: the menu button, in an app whose navigation collapses. Stays the caller's — the bar only places it. */
   menu?: ReactNode
   /** Beside the menu button: the app's logo mark, or its name as text. */
@@ -40,7 +43,7 @@ export function TopBar({ variant = 'solid', menu, logo, search, right, className
         'flex h-[52px] items-center pl-5 pr-[26px]',
         floating
           ? 'pointer-events-none absolute left-0 right-0 top-0 z-10'
-          : 'shrink-0 gap-4 border-b border-border-default bg-bg-surface',
+          : cn('shrink-0 gap-4', variant === 'solid' && 'border-b border-border-default bg-bg-surface'),
         className,
       )}
     >