@estiva-app/ui 0.38.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.38.0",
+  "version": "0.40.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.38.0",
-    "exports": 88,
-    "typeExports": 97,
+    "packageVersion": "0.40.0",
+    "exports": 90,
+    "typeExports": 101,
     "files": null
   },
   "storybook": {
@@ -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"
           ]
         }
       ],
@@ -4078,6 +4079,93 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "RichText",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/RichText.tsx",
+      "purpose": "Formatted text, drawn from a parsed tree: headings, paragraphs, both lists, a quote, code, a divider, a table and links, in one look for every app.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "blocks",
+          "takes": "readonly RichTextBlock[]",
+          "required": true,
+          "note": "The tree, already parsed."
+        },
+        {
+          "name": "size",
+          "takes": "default | small",
+          "required": false,
+          "note": "Default `default`, the size of text you read."
+        },
+        {
+          "name": "renderText",
+          "takes": "a handler",
+          "required": false,
+          "note": "Draws plain text: what is left of a run once its links are drawn."
+        },
+        {
+          "name": "renderReference",
+          "takes": "a handler",
+          "required": false,
+          "note": "Draws a run that stands for an address. By default its text."
+        },
+        {
+          "name": "renderBlock",
+          "takes": "a handler",
+          "required": false,
+          "note": "Draws a block this part has no design for (an attachment, a widget)."
+        }
+      ],
+      "variants": [
+        {
+          "prop": "size",
+          "values": [
+            "default",
+            "small"
+          ]
+        }
+      ],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "components-richtext--docs",
+      "storyId": "components-richtext--every-block",
+      "docPage": "src/RichText.mdx",
+      "app": null,
+      "looks": [
+        "[&>:is(h1,h2,h3)]:mb-1 [&>:is(h1,h2,h3)]:mt-2 [&>:is(h1,h2,h3):first-child]:mt-0 [&>:is(h1,h2,h3):last-child]:mb-0 [&>:is(h1,h2,h3)+:is(h1,h2,h3)]:mt-1 [&>:is(h1,h2)]:text-text-primary",
+        "[&_:is(ul,ol)]:pl-5 [&_li>p]:m-0 [&_li]:break-words [&_li]:marker:text-text-muted [&_ol]:list-decimal [&_ul]:list-disc",
+        "[&_blockquote>p]:m-0 [&_blockquote]:border-l-[3px] [&_blockquote]:border-border-strong [&_blockquote]:pl-2.5",
+        "[&_:not(pre)>code]:rounded-sm [&_:not(pre)>code]:bg-bg-code [&_:not(pre)>code]:px-1 [&_:not(pre)>code]:py-0.5 [&_code]:font-mono [&_code]:text-[0.9em] [&_code]:text-text-primary",
+        "[&_pre>code]:text-[1em] [&_pre]:whitespace-pre-wrap [&_pre]:break-words [&_pre]:rounded-md [&_pre]:bg-bg-code [&_pre]:p-2 [&_pre]:font-mono [&_pre]:text-[0.9em] [&_pre]:text-text-primary",
+        "[&_:is(th,td)>p]:m-0 [&_:is(th,td)]:border [&_:is(th,td)]:border-border-default [&_:is(th,td)]:px-2 [&_:is(th,td)]:py-1 [&_:is(th,td)]:text-left [&_:is(th,td)]:align-top [&_table]:w-full [&_table]:border-collapse [&_th]:bg-bg-code [&_th]:font-medium [&_th]:text-text-primary",
+        "[&_em]:italic [&_strong]:font-semibold [&_u]:underline [&_u]:underline-offset-2",
+        "text-body-2 [&>:is(h2,h3)]:text-body-2 [&>:is(h2,h3)]:font-semibold [&>h1]:text-h4",
+        "text-caption leading-snug [&>:is(h2,h3)]:text-caption [&>:is(h2,h3)]:font-semibold [&>h1]:text-body-2 [&>h1]:font-semibold"
+      ]
+    },
+    {
+      "name": "richTextClassName",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/RichText.tsx",
+      "purpose": "RichText's look, for a box you draw yourself: an editor's, so that what is being written looks the same as what is read.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "components-richtext--docs",
+      "storyId": "components-richtext--every-block",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "ScrollArea",
       "repo": "estiva-ui",
@@ -5412,7 +5500,7 @@
       "props": [
         {
           "name": "variant",
-          "takes": "solid | floating",
+          "takes": "solid | floating | inset",
           "required": false,
           "note": null
         },
@@ -5452,7 +5540,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/RichText.mdx

@@ -0,0 +1,79 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as RichTextStories from './RichText.stories'
+
+<Meta of={RichTextStories} />
+
+# RichText
+
+Formatted text, drawn from a parsed tree: headings, paragraphs, both lists, a
+quote, code, a divider, a table and links, in one look for every app.
+
+<Canvas of={RichTextStories.EveryBlock} />
+
+## When
+
+- **`default`** — text someone reads: a post, a reply, a description.
+- **`small`** — the same text one step down, with every heading, list, quote
+  and table kept: an item shown inside a card.
+- `renderReference` — a run that stands for an address: the app draws what it
+  points at, a person or an item.
+- `renderText` — words the app recognises in plain text, drawn as chips.
+- `renderBlock` — a block this part has no design for, such as an attachment.
+
+## When not
+
+- One word standing for a person or a thing, inside your own sentence →
+  **InlineChip**.
+- One link inside your own sentence → **Link**.
+- A value set out as a label and its value → **Property**.
+
+## How
+
+```tsx
+import { InlineChip, RichText } from '@estiva-app/ui'
+
+// toRenderTree comes from @estiva-app/protocol
+<RichText
+  blocks={toRenderTree(value, format)}
+  renderReference={(reference) => <InlineChip tone="person">{nameOf(reference)}</InlineChip>}
+/>
+```
+
+- **It takes the tree, not the text.** Parse first; the format comes from the
+  item's tag, never from its body. The protocol's `RenderBlock` fits
+  `RichTextBlock`. To draw a block somewhere else (below the text, as a card),
+  leave it out of `blocks`.
+- **The colour is set here**: the text is `text-secondary`, and headings
+  of level 1 and 2 are `text-primary`. Do not wrap it to recolour it.
+- **Links are found here**, in every run that is not code: `[words](address)`
+  and a bare `https://` address. Both open in a new tab, and a click on one
+  is not also a click on what the text sits in, such as a card. `renderText`
+  gets only the text between links, so an address is never read as a name.
+- **Nothing is set as HTML.** Every string reaches the page as text; a `<b>`
+  typed by an author shows as `<b>`.
+- A block of a kind it does not know shows its words and its children. It is
+  never dropped.
+- Code, in a sentence or as a block, is 0.9 of the text around it, so it
+  shrinks with `small`. A long line in a block wraps; nothing scrolls
+  sideways.
+- Each block carries its `id` as `data-block-id`, for an app that points at
+  one block.
+- **An editor wears the same look.** Put `richTextClassName()` (or
+  `richTextClassName('small')`) on the editor's root, so what is being written
+  looks exactly like what is read. It styles the elements inside the box,
+  including the paragraph an editor puts inside a list item, a quote and a
+  table cell.
+
+```tsx
+import { richTextClassName } from '@estiva-app/ui'
+
+const editorAttributes = { class: richTextClassName('default', 'outline-none') }
+```
+
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
+## Props
+
+<Controls of={RichTextStories.EveryBlock} />

package/src/RichText.stories.tsx

@@ -0,0 +1,91 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconSquareRounded } from '@tabler/icons-react'
+import { RichText, type RichTextBlock, type RichTextRun } from './RichText'
+import { InlineChip } from './InlineChip'
+import { Card } from './Card'
+
+const t = (text: string, ...marks: string[]): RichTextRun => ({ text, marks })
+const p = (...inline: RichTextRun[]): RichTextBlock => ({ type: 'paragraph', inline })
+const items = (...texts: string[]): RichTextBlock[] => texts.map((text) => ({ type: 'listItem', inline: [t(text)] }))
+const cell = (type: 'tableHeader' | 'tableCell', text: string): RichTextBlock => ({ type: 'unknown', typeName: type, children: [p(t(text))] })
+const row = (type: 'tableHeader' | 'tableCell', ...texts: string[]): RichTextBlock => ({ type: 'unknown', typeName: 'tableRow', children: texts.map((x) => cell(type, x)) })
+
+/** Every block the part draws, in the order a reader meets them. */
+const EVERY_BLOCK: RichTextBlock[] = [
+  { type: 'heading', level: 1, inline: [t('A heading')] },
+  { type: 'heading', level: 2, inline: [t('A smaller heading')] },
+  { type: 'heading', level: 3, inline: [t('A third level, in the text colour')] },
+  p(t('Text can be '), t('bold', 'bold'), t(', '), t('italic', 'italic'), t(' or '), t('underlined', 'underline'), t(', and hold '), t('code', 'code'), t(' in a sentence.\nA line break stays a line break.')),
+  { type: 'bulletList', children: items('An item', 'Another item') },
+  { type: 'orderedList', children: items('The first step', 'The second step') },
+  { type: 'blockquote', inline: [t('A quote, set in from a line.')] },
+  { type: 'codeBlock', language: 'ts', inline: [t('const item = 1 // a long line of code folds onto the next line instead of scrolling sideways')] },
+  { type: 'horizontalRule' },
+  {
+    type: 'table',
+    children: [row('tableHeader', 'Label', 'Value'), row('tableCell', 'Item one', 'One'), row('tableCell', 'Item two', 'Two')],
+  },
+]
+
+const meta = {
+  title: 'Components/RichText',
+  component: RichText,
+  args: { blocks: EVERY_BLOCK, size: 'default' },
+  argTypes: { size: { control: 'inline-radio', options: ['default', 'small'] } },
+  decorators: [(Story) => <div className="w-[480px]"><Story /></div>],
+} satisfies Meta<typeof RichText>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** Every block: headings, text and its marks, both lists, a quote, code, a divider and a table. */
+export const EveryBlock: Story = {}
+
+/** One step down, with every heading, list, quote and table kept: an item shown inside a card. */
+export const Small: Story = {
+  args: { size: 'small' },
+  render: (args) => (
+    <Card className="p-3">
+      <RichText {...args} />
+    </Card>
+  ),
+}
+
+/** A link written with its own words, and a bare address, which may break anywhere. Code is never read for links. */
+export const Links: Story = {
+  args: {
+    blocks: [
+      p(t('A link with its own words: [the guide](https://example.com/guide). A bare address: https://example.com/a/long/address/that/breaks/where/it/must.')),
+      p(t('Inside code it stays text: '), t('[not a link](https://example.com)', 'code')),
+    ],
+  },
+}
+
+/** What an app draws itself: a run that stands for an address, and words it recognises in plain text. */
+export const WithTheAppsOwnParts: Story = {
+  args: {
+    blocks: [
+      p(
+        t('Assigned to '),
+        { text: 'nostr:npub1example', marks: [], reference: 'nostr:npub1example' },
+        t(', see [[Item one]] for the rest.'),
+      ),
+    ],
+    renderReference: () => <InlineChip tone="person">Name</InlineChip>,
+    renderText: (text) =>
+      text.split(/(\[\[[^\]]+\]\])/).map((part, i) =>
+        part.startsWith('[[') ? (
+          <InlineChip key={i} icon={<IconSquareRounded size={16} stroke={1.5} />}>{part.slice(2, -2)}</InlineChip>
+        ) : (
+          part
+        ),
+      ),
+  },
+}
+
+/** A block this part has no design for, from a later version: its words are drawn, never dropped. */
+export const UnknownBlock: Story = {
+  args: {
+    blocks: [p(t('The block below is of a kind this part does not know.')), { type: 'unknown', typeName: 'later', inline: [t('Its words are still here.')] }],
+  },
+}