@estiva-app/ui 0.39.0 → 0.40.0

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/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)',

package/tokens.css

@@ -94,6 +94,9 @@
   --bg-field:     #F4F4F5;
   --border-field: #E4E4E7;
   --shadow-field: 0 0 #0000;
+  /* Code, in a sentence and as a block, and a table's header row (RichText, UIG-30).
+     Here, the hover fill: bg-active, #D4D4D8, was the darkest thing on a white card (Katerina, 28 September). */
+  --bg-code:     #E9E9EB;
 }
 
 /* ─── dark ─── Peek's dark theme (peek/src/index.css .dark, 2026-08-28). */
@@ -172,6 +175,9 @@
   --bg-field:     #27272A;
   --border-field: #2D2D31;
   --shadow-field: 0 0 #0000;
+  /* Code, in a sentence and as a block, and a table's header row (RichText, UIG-30).
+     Here, bg-active, as Peek draws code (Katerina, 28 September). */
+  --bg-code:     #2D2D31;
 }
 
 
@@ -254,6 +260,9 @@
   --bg-field:     #20242d;
   --border-field: rgba(255, 255, 255, 0.12);
   --shadow-field: 0 0 #0000;
+  /* Code, in a sentence and as a block, and a table's header row (RichText, UIG-30).
+     Here, bg-active, as Peek draws code (Katerina, 28 September). */
+  --bg-code:     rgba(255, 255, 255, 0.08);
 }
 
 /* ─── ship ─── Ship's palette (Katerina's ruling, 2026-08-28; ship/web/src/index.css). */
@@ -342,6 +351,9 @@
   --bg-field:     #1f2330;
   --border-field: rgba(255, 255, 255, 0.12);
   --shadow-field: 0 0 #0000;
+  /* Code, in a sentence and as a block, and a table's header row (RichText, UIG-30).
+     Here, bg-active, as Peek draws code (Katerina, 28 September). */
+  --bg-code:     rgba(255, 255, 255, 0.08);
 }
 
 /* ─── leaf ─── Leaf's theme: Linear's light theme on these same tokens (Katerina,
@@ -430,4 +442,7 @@
   --bg-field:     #ffffff;
   --border-field: #dedede; /* the default line, so a field shows on a white dialog (Katerina, 28 September); Linear's own is #f7f7f7 */
   --shadow-field: 0 3px 6px -2px rgba(0, 0, 0, 0.02), 0 1px 1px 0 rgba(0, 0, 0, 0.04);
+  /* Code, in a sentence and as a block, and a table's header row (RichText, UIG-30).
+     Here, the inset fill: lighter than bg-active on a white card (Katerina, 28 September). */
+  --bg-code:     #e9e9ea;
 }