@estiva-app/ui 0.38.0 → 0.40.0

package/src/RichText.test.tsx

@@ -0,0 +1,149 @@
+// @vitest-environment jsdom
+/**
+ * What the RichText page claims, pinned: every block draws as its element; text
+ * is text, never HTML; links are found in text and never in code, and a click
+ * on one stays on it; an unknown block keeps its words; a table's first row of
+ * header cells is its header; the app's own parts go where the page says.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { RichText, richTextClassName, type RichTextBlock, type RichTextRun } from './RichText'
+
+afterEach(cleanup)
+
+const t = (text: string, ...marks: string[]): RichTextRun => ({ text, marks })
+const p = (...inline: RichTextRun[]): RichTextBlock => ({ type: 'paragraph', inline })
+const cell = (typeName: string, text: string): RichTextBlock => ({ type: 'unknown', typeName, children: [p(t(text))] })
+const row = (typeName: string, ...texts: string[]): RichTextBlock => ({ type: 'unknown', typeName: 'tableRow', children: texts.map((x) => cell(typeName, x)) })
+
+const draw = (blocks: RichTextBlock[], props = {}) => render(<RichText blocks={blocks} {...props} />).container
+
+describe('RichText', () => {
+  it('draws each block as its element', () => {
+    const c = draw([
+      { type: 'heading', level: 1, inline: [t('One')] },
+      { type: 'heading', level: 2, inline: [t('Two')] },
+      { type: 'heading', level: 3, inline: [t('Three')] },
+      p(t('Text')),
+      { type: 'bulletList', children: [{ type: 'listItem', inline: [t('a')] }] },
+      { type: 'orderedList', start: 3, children: [{ type: 'listItem', inline: [t('b')] }] },
+      { type: 'blockquote', inline: [t('quoted')] },
+      { type: 'codeBlock', inline: [t('const a = 1')] },
+      { type: 'horizontalRule' },
+    ])
+    expect(c.querySelector('h1')?.textContent).toBe('One')
+    expect(c.querySelector('h2')?.textContent).toBe('Two')
+    expect(c.querySelector('h3')?.textContent).toBe('Three')
+    expect(c.querySelector('ul li')?.textContent).toBe('a')
+    expect(c.querySelector('ol')?.getAttribute('start')).toBe('3')
+    expect(c.querySelector('blockquote')?.textContent).toBe('quoted')
+    expect(c.querySelector('pre code')?.textContent).toBe('const a = 1')
+    expect(c.querySelector('hr')).not.toBeNull()
+  })
+
+  it('draws the marks as elements, and a line break as a break', () => {
+    const c = draw([p(t('b', 'bold'), t('i', 'italic'), t('u', 'underline'), t('c', 'code'), t('one\ntwo'))])
+    expect(c.querySelector('strong')?.textContent).toBe('b')
+    expect(c.querySelector('em')?.textContent).toBe('i')
+    expect(c.querySelector('u')?.textContent).toBe('u')
+    expect(c.querySelector('p > code')?.textContent).toBe('c')
+    expect(c.querySelectorAll('br').length).toBe(1)
+  })
+
+  it('sets text as text, never as HTML', () => {
+    const c = draw([p(t('<b>stays text</b><img src=x onerror=alert(1)>'))])
+    expect(c.querySelector('b')).toBeNull()
+    expect(c.querySelector('img')).toBeNull()
+    expect(c.textContent).toContain('<b>stays text</b>')
+  })
+
+  it('finds a written link and a bare address, and leaves punctuation after it', () => {
+    draw([p(t('Read [the guide](https://example.com/guide) or https://example.com/a.'))])
+    const guide = screen.getByRole('link', { name: 'the guide' })
+    expect(guide.getAttribute('href')).toBe('https://example.com/guide')
+    expect(guide.getAttribute('target')).toBe('_blank')
+    const bare = screen.getByRole('link', { name: 'https://example.com/a' })
+    expect(bare.getAttribute('href')).toBe('https://example.com/a')
+    expect(bare.parentElement?.textContent).toBe('https://example.com/a.')
+  })
+
+  it('never reads code for links', () => {
+    const c = draw([p(t('[not a link](https://example.com)', 'code'))])
+    expect(c.querySelector('a')).toBeNull()
+  })
+
+  it('keeps a click on a link to the link', () => {
+    const outer = vi.fn()
+    render(
+      <div onClick={outer}>
+        <RichText blocks={[p(t('https://example.com'))]} />
+      </div>,
+    )
+    fireEvent.click(screen.getByRole('link'))
+    expect(outer).not.toHaveBeenCalled()
+  })
+
+  it('hands the app only the text between links', () => {
+    const seen: string[] = []
+    draw([p(t('before https://example.com/@name after'))], { renderText: (text: string) => (seen.push(text), text) })
+    expect(seen).toEqual(['before ', ' after'])
+  })
+
+  it('lets the app draw a reference, and draws its text when it does not', () => {
+    const run: RichTextRun = { text: 'nostr:npub1x', marks: [], reference: 'nostr:npub1x' }
+    expect(draw([p(run)]).textContent).toBe('nostr:npub1x')
+    cleanup()
+    draw([p(run)], { renderReference: (reference: string) => <mark>{reference.slice(6)}</mark> })
+    expect(document.querySelector('mark')?.textContent).toBe('npub1x')
+  })
+
+  it('draws the words of a block it does not know, never dropping it', () => {
+    const c = draw([{ type: 'unknown', typeName: 'later', inline: [t('still here')], children: [p(t('and this'))] }])
+    const block = c.querySelector('[data-block-type="later"]')
+    expect(block?.textContent).toBe('still hereand this')
+  })
+
+  it('lets the app draw a block, or leave it to the part', () => {
+    const own = (block: RichTextBlock) => (block.type === 'attachment' ? <figure>own</figure> : undefined)
+    const c = draw([{ type: 'attachment' }, p(t('text'))], { renderBlock: own })
+    expect(c.querySelector('figure')?.textContent).toBe('own')
+    expect(c.querySelector('p')?.textContent).toBe('text')
+  })
+
+  it('draws a table, its first row of header cells as the header', () => {
+    const c = draw([{ type: 'table', children: [row('tableHeader', 'Label', 'Value'), row('tableCell', 'a', 'b')] }])
+    expect([...c.querySelectorAll('thead th')].map((th) => th.textContent)).toEqual(['Label', 'Value'])
+    expect([...c.querySelectorAll('tbody td')].map((td) => td.textContent)).toEqual(['a', 'b'])
+  })
+
+  it('draws a table it cannot read as its words', () => {
+    const c = draw([{ type: 'table', inline: [t('flat')] }])
+    expect(c.querySelector('table')).toBeNull()
+    expect(c.textContent).toBe('flat')
+  })
+
+  it('carries each block id', () => {
+    const c = draw([{ type: 'paragraph', id: 'b1', inline: [t('x')] }])
+    expect(c.querySelector('p')?.getAttribute('data-block-id')).toBe('b1')
+  })
+
+  it('draws nothing for no blocks', () => {
+    expect(draw([]).innerHTML).toBe('')
+  })
+
+  it('keeps the same elements at the small size', () => {
+    const blocks: RichTextBlock[] = [{ type: 'heading', level: 1, inline: [t('One')] }, { type: 'bulletList', children: [{ type: 'listItem', inline: [t('a')] }] }]
+    const c = draw(blocks, { size: 'small' })
+    expect(c.querySelector('h1')).not.toBeNull()
+    expect(c.querySelector('ul li')).not.toBeNull()
+    expect(c.firstElementChild?.className).toContain('text-caption')
+  })
+
+  it('gives an editor the same look: the classes on its box are the ones an editor gets', () => {
+    for (const size of ['default', 'small'] as const) {
+      const c = draw([p(t('x'))], { size })
+      expect(c.firstElementChild?.className).toBe(richTextClassName(size))
+    }
+    expect(richTextClassName('default', 'outline-none')).toContain('outline-none')
+  })
+})

package/src/RichText.tsx

@@ -0,0 +1,294 @@
+import type { MouseEvent, ReactNode } from 'react'
+import { cn } from './cn'
+import { Link } from './Link'
+
+/**
+ * Formatted text, drawn: headings, paragraphs, lists, a quote, code, a divider,
+ * a table and links.
+ *
+ * Both apps drew the same thing twice, from the same source — the text tree the
+ * protocol package builds (`toRenderTree` → `RenderBlock`, `RenderInline`) —
+ * and the two had drifted: headings, list markers, quotes and code differed,
+ * one app had tables and the other dropped them, one had links and the other
+ * printed the brackets (UIG-30). The look here is Katerina's picks of
+ * 28 September, one per difference, most of them Peek's.
+ *
+ * **It takes the tree, not the text.** The caller parses (the format comes from
+ * the item's tag, never from the body) and hands the blocks in. So this package
+ * does not depend on the protocol, and a caller can leave out a block it draws
+ * elsewhere before passing the rest. The types below are the tree's shape; the
+ * protocol's own types fit them.
+ *
+ * **Safe by construction.** The tree has nothing left to parse, and every
+ * string here reaches the page as a React child, so it is text. Nothing is set
+ * as HTML.
+ *
+ * **What a word points at stays the app's.** A person, an item from another
+ * app, a name the app recognises in plain text: `renderReference`,
+ * `renderText` and `renderBlock` are where each app draws its own.
+ */
+
+/** A run of text and the marks on it — the protocol's `RenderInline`. */
+export interface RichTextRun {
+  text: string
+  marks: readonly string[]
+  /** A `nostr:` address this run stands for. `text` is the address itself. */
+  reference?: string
+}
+
+/** A block of the tree — the protocol's `RenderBlock`. */
+export interface RichTextBlock {
+  type: string
+  /** What the document called a block the tree does not know. */
+  typeName?: string
+  /** The block's address, when it has one. Drawn as `data-block-id`. */
+  id?: string
+  level?: 1 | 2 | 3
+  language?: string
+  /** A numbered list's first number. */
+  start?: number
+  attrs?: Record<string, unknown>
+  inline?: readonly RichTextRun[]
+  children?: readonly RichTextBlock[]
+}
+
+export type RichTextSize = 'default' | 'small'
+
+export interface RichTextProps {
+  /** The tree, already parsed. */
+  blocks: readonly RichTextBlock[]
+  /**
+   * Default `default`, the size of text you read. `small` is the same text one
+   * step down, with every heading, list, quote and table kept: an item shown
+   * inside a card.
+   */
+  size?: RichTextSize
+  /**
+   * Draws plain text: what is left of a run once its links are drawn. Where an
+   * app turns words it recognises into chips. By default the text as it is.
+   */
+  renderText?: (text: string) => ReactNode
+  /** Draws a run that stands for an address. By default its text. */
+  renderReference?: (reference: string, run: RichTextRun) => ReactNode
+  /**
+   * Draws a block this part has no design for (an attachment, a widget). Return
+   * `undefined` to leave it to the part, which draws its words.
+   */
+  renderBlock?: (block: RichTextBlock) => ReactNode | undefined
+}
+
+/**
+ * The whole look, as classes on the box around the text: the elements inside
+ * carry none. That is so an editor can wear the same classes on its own box and
+ * look the same as what it writes — ProseMirror draws the same elements, with a
+ * paragraph inside each list item, quote and table cell (the `> p` lines).
+ */
+const RICH_TEXT_CLASSES = {
+  base: 'flex flex-col gap-1 break-words text-text-secondary',
+  /* A heading binds to what follows it: 12px above (8 and the 4px gap), 8px below (4 and the gap); two headings in a row, 12px apart. Level 3 keeps the text's colour, one step lower. */
+  headings: '[&>: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',
+  lists: '[&_:is(ul,ol)]:pl-5 [&_li>p]:m-0 [&_li]:break-words [&_li]:marker:text-text-muted [&_ol]:list-decimal [&_ul]:list-disc',
+  // eslint-disable-next-line token-spacing/no-restricted-classes -- @estiva-escape: the quote line is Peek's, 3px, between the ramp's 2 and 4
+  quote: '[&_blockquote>p]:m-0 [&_blockquote]:border-l-[3px] [&_blockquote]:border-border-strong [&_blockquote]:pl-2.5',
+  // eslint-disable-next-line token-values/no-restricted-classes -- @estiva-escape: code is 0.9 of the text around it, so it scales with a heading and with `small`; a named size is fixed
+  code: '[&_: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',
+  // eslint-disable-next-line token-values/no-restricted-classes -- @estiva-escape: code is 0.9 of the text around it; the code inside the block is the block's own size, not 0.9 of it again
+  codeBlock: '[&_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',
+  divider: '[&_hr]:border-border-default',
+  table: '[&_: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',
+  marks: '[&_em]:italic [&_strong]:font-semibold [&_u]:underline [&_u]:underline-offset-2',
+  default: 'text-body-2 [&>:is(h2,h3)]:text-body-2 [&>:is(h2,h3)]:font-semibold [&>h1]:text-h4',
+  small: 'text-caption leading-snug [&>:is(h2,h3)]:text-caption [&>:is(h2,h3)]:font-semibold [&>h1]:text-body-2 [&>h1]:font-semibold',
+}
+
+/**
+ * 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. Put it on the editor's root.
+ */
+export function richTextClassName(size: RichTextSize = 'default', className?: string) {
+  const { base, headings, lists, quote, code, codeBlock, divider, table, marks } = RICH_TEXT_CLASSES
+  return cn(base, headings, lists, quote, code, codeBlock, divider, table, marks, RICH_TEXT_CLASSES[size], className)
+}
+
+/**
+ * A link written as `[words](address)`, then a bare address. The written form
+ * first, so its address is not found a second time on its own.
+ */
+const LINK_SPLIT = /(\[[^[\]\n]+\]\((?:https?:\/\/|mailto:)[^\s)]+\)|https?:\/\/[^\s]+)/g
+const WRITTEN_LINK = /^\[([^[\]\n]+)\]\(((?:https?:\/\/|mailto:)[^\s)]+)\)$/
+/** Punctuation after a bare address ends the sentence, not the address. */
+const BARE_LINK = /^(https?:\/\/\S+?)([.,;:!?)\]]*)$/
+
+/** A link in text is not also a click on what the text sits in, such as a card. */
+const keepToLink = (event: MouseEvent) => event.stopPropagation()
+
+function textWithLinks(text: string, renderText: (text: string) => ReactNode): ReactNode {
+  const parts = text.split(LINK_SPLIT)
+  if (parts.length === 1) return renderText(text)
+  return parts.map((part, i) => {
+    const written = part.match(WRITTEN_LINK)
+    if (written) {
+      return (
+        <span key={i} className="break-words">
+          <Link href={written[2]} external onClick={keepToLink}>{written[1]}</Link>
+        </span>
+      )
+    }
+    const bare = i % 2 === 1 ? part.match(BARE_LINK) : null
+    if (bare) {
+      return (
+        // An address has no spaces to wrap at, so it may break anywhere.
+        <span key={i} className="break-all">
+          <Link href={bare[1]} external onClick={keepToLink}>{bare[1]}</Link>
+          {bare[2]}
+        </span>
+      )
+    }
+    return part ? <span key={i}>{renderText(part)}</span> : null
+  })
+}
+
+interface Draw {
+  renderText: (text: string) => ReactNode
+  renderReference: (reference: string, run: RichTextRun) => ReactNode
+  renderBlock?: (block: RichTextBlock) => ReactNode | undefined
+}
+
+function Runs({ runs, draw }: { runs?: readonly RichTextRun[]; draw: Draw }) {
+  return (
+    <>
+      {(runs ?? []).map((run, i) => {
+        if (run.reference) return <span key={i}>{draw.renderReference(run.reference, run)}</span>
+        // Code carries no other mark, and its words are never read for links.
+        if (run.marks.includes('code')) {
+          return <code key={i}>{run.text}</code>
+        }
+        // A line break inside a run is a line break.
+        let node: ReactNode = run.text.split('\n').map((line, j) => (
+          <span key={j}>
+            {j > 0 && <br />}
+            {textWithLinks(line, draw.renderText)}
+          </span>
+        ))
+        if (run.marks.includes('underline')) node = <u>{node}</u>
+        if (run.marks.includes('italic')) node = <em>{node}</em>
+        if (run.marks.includes('bold')) node = <strong>{node}</strong>
+        return <span key={i}>{node}</span>
+      })}
+    </>
+  )
+}
+
+const named = (block: RichTextBlock) => block.typeName ?? block.type
+
+/**
+ * A table's rows and cells are named by whatever wrote the document; these are
+ * the editor's names. A first row of header cells is the header. Returns null
+ * for a nesting it does not recognise, which is then drawn as words.
+ */
+function Table({ block, draw }: { block: RichTextBlock; draw: Draw }) {
+  const rows = (block.children ?? []).filter((row) => named(row) === 'tableRow')
+  if (!rows.length) return null
+  const cells = (row: RichTextBlock) =>
+    (row.children ?? []).map((cell, i) => {
+      const header = named(cell) === 'tableHeader'
+      const Cell = header ? 'th' : 'td'
+      const { colspan, rowspan } = (cell.attrs ?? {}) as { colspan?: number; rowspan?: number }
+      return (
+        <Cell
+          key={cell.id ?? i}
+          data-block-id={cell.id}
+          colSpan={colspan && colspan > 1 ? colspan : undefined}
+          rowSpan={rowspan && rowspan > 1 ? rowspan : undefined}
+        >
+          {(cell.children ?? []).map((child, j) => <Runs key={j} runs={child.inline} draw={draw} />)}
+          <Runs runs={cell.inline} draw={draw} />
+        </Cell>
+      )
+    })
+  const first = rows[0].children ?? []
+  const headerRow = first.length > 0 && first.every((cell) => named(cell) === 'tableHeader')
+  return (
+    <table data-block-id={block.id}>
+      {headerRow && (
+        <thead>
+          <tr data-block-id={rows[0].id}>{cells(rows[0])}</tr>
+        </thead>
+      )}
+      <tbody>
+        {(headerRow ? rows.slice(1) : rows).map((row, i) => (
+          <tr key={row.id ?? i} data-block-id={row.id}>{cells(row)}</tr>
+        ))}
+      </tbody>
+    </table>
+  )
+}
+
+function Block({ block, draw }: { block: RichTextBlock; draw: Draw }): ReactNode {
+  const own = draw.renderBlock?.(block)
+  if (own !== undefined) return own
+  const runs = <Runs runs={block.inline} draw={draw} />
+  switch (block.type) {
+    case 'heading': {
+      if (block.level === 1) return <h1 data-block-id={block.id}>{runs}</h1>
+      if (block.level === 3) return <h3 data-block-id={block.id}>{runs}</h3>
+      return <h2 data-block-id={block.id}>{runs}</h2>
+    }
+    case 'paragraph':
+      return <p data-block-id={block.id}>{runs}</p>
+    case 'bulletList':
+    case 'orderedList': {
+      const items = (block.children ?? []).map((item, i) => (
+        <li key={item.id ?? i} data-block-id={item.id}>
+          <Runs runs={item.inline} draw={draw} />
+        </li>
+      ))
+      return block.type === 'bulletList'
+        ? <ul data-block-id={block.id}>{items}</ul>
+        : <ol data-block-id={block.id} start={block.start}>{items}</ol>
+    }
+    case 'blockquote':
+      return <blockquote data-block-id={block.id}>{runs}</blockquote>
+    case 'codeBlock':
+      // Literal: no marks, no links, no chips. A long line wraps; nothing scrolls sideways.
+      return (
+        <pre data-block-id={block.id} data-language={block.language}>
+          <code>{(block.inline ?? []).map((run) => run.text).join('')}</code>
+        </pre>
+      )
+    case 'horizontalRule':
+      return <hr data-block-id={block.id} />
+    case 'table': {
+      const table = <Table block={block} draw={draw} />
+      if ((block.children ?? []).some((row) => named(row) === 'tableRow')) return table
+      break
+    }
+  }
+  /*
+    Anything else — a type this part has no design for, or one published after
+    it was written — is drawn as its words, never dropped: a block that
+    vanishes looks like one you are not allowed to see.
+  */
+  return (
+    <div data-block-id={block.id} data-block-type={named(block)}>
+      {runs}
+      {(block.children ?? []).map((child, i) => <Block key={child.id ?? i} block={child} draw={draw} />)}
+    </div>
+  )
+}
+
+export function RichText({
+  blocks,
+  size = 'default',
+  renderText = (text) => text,
+  renderReference = (_reference, run) => run.text,
+  renderBlock,
+}: RichTextProps) {
+  if (blocks.length === 0) return null
+  const draw: Draw = { renderText, renderReference, renderBlock }
+  return (
+    <div data-rich-text className={richTextClassName(size)}>
+      {blocks.map((block, i) => <Block key={block.id ?? i} block={block} draw={draw} />)}
+    </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,
       )}
     >

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

@@ -129,6 +129,7 @@ export const PART_LOOK_PROPS: Record<string, string[]> = {
   RailItem: ['active'],
   Reaction: ['pressed'],
   ReactionPicker: ['surface'],
+  RichText: ['size'],
   SectionHeader: ['hover'],
   SectionLabel: ['tone', 'truncate'],
   Select: ['size'],

package/src/gates/app-checks.ts

@@ -254,8 +254,15 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
         return probe(code, 'none', undefined, 'src/components/__gates_probe__.test.tsx', config)()
       }), 'a test file is not checked for hand-written values, while source is') },
     ]),
+    // Built 28 September: both apps drew the protocol's text tree by hand, and drifted apart.
+    // A file that reads the protocol and draws a quote or a numbered list itself is a third copy.
     ticket('UIG-30', [
       { what: 'the installed package has RichText', run: () => h.contains(installed, /\bRichText\b/, 'the installed @estiva-app/ui exports RichText') },
+      { what: "no file draws the protocol's text tree by hand", run: () => {
+        const sources = h.listFiles(at('src'), (n) => /\.tsx$/.test(n) && !/\.(test|stories)\.tsx$/.test(n))
+        const own = sources.filter((f) => { const text = h.read(f); return /from ['"]@estiva-app\/protocol['"]/.test(text) && /<(?:blockquote|ol)\b/.test(text) })
+        return own.length ? h.FAIL(`draws the text tree itself (${own.join(', ')}): pass the tree to RichText`) : h.PASS('formatted text is drawn by RichText only')
+      } },
     ]),
     // Katerina's ruling of 17 September (docs/GATES.md §23): one copy, in the package. An app made
     // by create-estiva-app passes this from its first commit; Peek and Ship do once UIG-32 lands.

package/src/index.ts

@@ -46,6 +46,7 @@ export {
 } from './InlineChip'
 export { Lightbox, type LightboxProps } from './Lightbox'
 export { Link, type LinkProps, type LinkVariant } from './Link'
+export { RichText, richTextClassName, type RichTextProps, type RichTextBlock, type RichTextRun, type RichTextSize } from './RichText'
 export { IconButton, type IconButtonProps, type IconButtonVariant } from './IconButton'
 export { Kbd, type KbdProps } from './Kbd'
 export { IdentityMenu, IdentityPanel, type Identity, type IdentityMenuProps, type IdentityPanelProps } from './IdentityMenu'

package/src/registry/registry.test.ts

@@ -45,17 +45,17 @@ describe('the registry builds', () => {
     expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
   })
 
-  it('counts 88 names over 58 files: 81 components, 6 helpers and 1 hook (Panel joined on 26 September)', () => {
+  it('counts 90 names over 59 files: 82 components, 7 helpers and 1 hook (RichText and richTextClassName joined on 28 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: 81, helper: 6, hook: 1 })
-    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(58)
+    expect(kinds).toEqual({ component: 82, helper: 7, hook: 1 })
+    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(59)
   })
 
   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(58)
-    expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(30)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(59)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(31)
   })
 
   it('takes a name with a page of its own from the page, and a name without one from the code', () => {

package/stories/Choosing.mdx

@@ -87,6 +87,7 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | A link — in text, on a title, beside a note, or a whole box | **Link** — `text`, `quiet`, `underlined`, `plain`; `external` for a new tab |
 | A document or an image attached to something, posted or waiting to be sent | **AttachmentCard** — the file decides the shape; `pending` in a composer |
 | A person or a thing named inside a sentence | **InlineChip** — one line high, level with the words; `href` makes it a link |
+| Formatted text: headings, lists, a quote, code, a table, links | **RichText** — pass the parsed tree; `small` inside a card |
 | The key that does this too | **Kbd** — or the `shortcut` prop on **MenuItem**, **Tooltip** and **SearchInput** |
 
 ## Feedback

package/tailwind-preset.js

@@ -153,6 +153,7 @@ export default {
         'bg-tooltip':   'var(--bg-tooltip)',
         'bg-tooltip-key': 'var(--bg-tooltip-key)',
         'bg-field':     'var(--bg-field)',
+        'bg-code':      'var(--bg-code)',
         // text
         'text-primary':   'var(--text-primary)',
         'text-secondary': 'var(--text-secondary)',