@estiva-app/ui 0.39.0 → 0.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.39.0",
+  "version": "0.41.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.39.0",
-    "exports": 88,
-    "typeExports": 97,
+    "packageVersion": "0.41.0",
+    "exports": 90,
+    "typeExports": 101,
     "files": null
   },
   "storybook": {
@@ -792,6 +792,18 @@
           "required": false,
           "note": null
         },
+        {
+          "name": "href",
+          "takes": "text",
+          "required": false,
+          "note": "The chip is a link: a real anchor with the chip's own round shape, so the keyboard ring is round too."
+        },
+        {
+          "name": "onClick",
+          "takes": "MouseEventHandler<HTMLAnchorElement>",
+          "required": false,
+          "note": "With `href`: a router app takes the click here, like `Link`."
+        },
         {
           "name": "className",
           "takes": "text",
@@ -825,13 +837,13 @@
         "bg-warning-muted text-warning-default signal:border signal:border-warning-outline signal:shadow-glow-warning",
         "bg-success-muted text-success-default signal:border signal:border-success-outline",
         "bg-error-muted text-error-default signal:border signal:border-error-outline",
+        "overflow-x-clip text-ellipsis whitespace-nowrap signal:tracking-wide text-chip signal:font-mono signal:text-small signal:font-semibold signal:tabular-nums",
+        "overflow-x-clip text-ellipsis whitespace-nowrap signal:tracking-wide",
         "rounded-full bg-accent-muted text-accent-primary signal:border signal:border-accent-outline",
         "rounded-full bg-info-muted text-info-default signal:border signal:border-info-outline",
         "rounded-full bg-warning-muted text-warning-default signal:border signal:border-warning-outline signal:shadow-glow-warning",
         "rounded-full bg-success-muted text-success-default signal:border signal:border-success-outline",
-        "rounded-full bg-error-muted text-error-default signal:border signal:border-error-outline",
-        "overflow-x-clip text-ellipsis whitespace-nowrap signal:tracking-wide text-chip signal:font-mono signal:text-small signal:font-semibold signal:tabular-nums",
-        "overflow-x-clip text-ellipsis whitespace-nowrap signal:tracking-wide"
+        "rounded-full bg-error-muted text-error-default signal:border signal:border-error-outline"
       ]
     },
     {
@@ -2749,6 +2761,12 @@
           "required": false,
           "note": "One line, cut with an ellipsis when it does not fit — a title that is a link."
         },
+        {
+          "name": "cover",
+          "takes": "true/false",
+          "required": false,
+          "note": "The link covers the row it sits in: a click anywhere on the row opens it, and the keyboard ring goes round the whole row."
+        },
         {
           "name": "children",
           "takes": "anything",
@@ -2785,8 +2803,13 @@
       "app": null,
       "looks": [
         "text-info-default underline underline-offset-2 hover:opacity-80",
+        "text-info-default underline underline-offset-2 hover:opacity-80 after:rounded-md focus-visible:outline-none",
         "text-info-default underline underline-offset-2 hover:opacity-80 truncate",
-        "underline underline-offset-2 hover:text-text-primary truncate"
+        "text-info-default underline underline-offset-2 hover:opacity-80 truncate after:rounded-md focus-visible:outline-none",
+        "hover:underline truncate after:rounded-md focus-visible:outline-none",
+        "underline underline-offset-2 hover:text-text-primary after:rounded-md focus-visible:outline-none",
+        "underline underline-offset-2 hover:text-text-primary truncate",
+        "underline underline-offset-2 hover:text-text-primary truncate after:rounded-md focus-visible:outline-none"
       ]
     },
     {
@@ -4079,6 +4102,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",

package/src/Chip.mdx

@@ -20,8 +20,8 @@ muted tints; the label is the `chip` type token, 11px / 500.
 
 ## When not
 
-- Something clickable → **Button** (small) or **MenuItem** — a Chip is not
-  a control.
+- Something that does an action → **Button** (small) or **MenuItem**. A Chip
+  is not a control. It can only be a link, with `href`.
 - A removable token in a multi-select → **InputChip** (see ChipInput).
 - A count beside a tab label → **Tabs** draws its own mono number, not a
   Chip.
@@ -37,6 +37,17 @@ import { Chip } from '@estiva-app/ui'
 - `leadingIcon` / `trailingIcon` take a 12px icon; the slots centre it, so
   it never rides the text baseline.
 - A count alone works too — `label="3"`, no icon.
+- `href` makes the chip a link to the thing it names: a real anchor with the
+  chip's round shape, so the keyboard ring is round too. A router app passes
+  `onClick`, as with **Link**. Inside a row whose **Link** has `cover`, it
+  stays clickable on its own: the row opens one thing, the chip another.
+
+```tsx
+<div className="relative flex items-center gap-3">
+  <Link href={itemUrl} variant="plain" cover>Item one</Link>
+  <Chip href={groupUrl} label="Group" />
+</div>
+```
 
 ## What it owns
 

package/src/Chip.stories.tsx

@@ -27,6 +27,8 @@ export const WithLeadingIcon: Story = { args: { type: 'info', label: 'Replies',
 export const WithTrailingIcon: Story = { args: { type: 'success', label: 'Sorted', trailingIcon: <IconArrowUp className="size-3" stroke={1.5} /> } }
 /** A count alone. */
 export const CountOnly: Story = { args: { type: 'neutral', label: '2' } }
+/** A link to the thing it names. Tab to it: the ring is round, like the chip. */
+export const AsLink: Story = { args: { type: 'neutral', label: 'Group', href: '#' } }
 
 /** All six colour types. */
 export const AllTypes: Story = {

package/src/Chip.test.tsx

@@ -0,0 +1,36 @@
+// @vitest-environment jsdom
+/**
+ * What the Chip page claims about `href`, pinned: without it the chip is not a
+ * link; with it the chip is a real anchor named by its label, keeps its round
+ * shape, sits above a covering link (`relative`), and hands the click to a
+ * router app through `onClick`.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Chip } from './Chip'
+
+afterEach(cleanup)
+
+describe('Chip', () => {
+  it('is not a link without href', () => {
+    render(<Chip label="Group" />)
+    expect(screen.queryByRole('link')).toBeNull()
+    expect(screen.getByText('Group').parentElement?.tagName).toBe('DIV')
+  })
+
+  it('with href is an anchor named by its label, round, and lifted above a covering link', () => {
+    render(<Chip label="Group" href="/groups/one" />)
+    const link = screen.getByRole('link', { name: 'Group' })
+    expect(link.getAttribute('href')).toBe('/groups/one')
+    expect(link.classList.contains('rounded-full')).toBe(true)
+    expect(link.classList.contains('relative')).toBe(true)
+  })
+
+  it('a router app takes the click through onClick', async () => {
+    const onClick = vi.fn((event: { preventDefault: () => void }) => event.preventDefault())
+    render(<Chip label="Group" href="/groups/one" onClick={onClick} />)
+    await userEvent.click(screen.getByRole('link', { name: 'Group' }))
+    expect(onClick).toHaveBeenCalledTimes(1)
+  })
+})

package/src/Chip.tsx

@@ -1,4 +1,4 @@
-import type { ReactNode } from 'react'
+import type { MouseEventHandler, ReactNode } from 'react'
 import { cn } from './cn'
 import { CHIP_TEXT_CLASSES } from './looks'
 
@@ -20,6 +20,14 @@ export interface ChipProps {
   label?: string
   leadingIcon?: ReactNode
   trailingIcon?: ReactNode
+  /**
+   * The chip is a link: a real anchor with the chip's own round shape, so the
+   * keyboard ring is round too. It sits above a row's covering `Link`, so the
+   * row opens one thing and the chip another (UIG-33, Katerina 28 September).
+   */
+  href?: string
+  /** With `href`: a router app takes the click here, like `Link`. */
+  onClick?: MouseEventHandler<HTMLAnchorElement>
   className?: string
 }
 
@@ -32,9 +40,10 @@ const typeStyles: Record<ChipType, string> = {
   error: 'bg-error-muted text-error-default signal:border signal:border-error-outline',
 }
 
-export function Chip({ type = 'neutral', label, leadingIcon, trailingIcon, className }: ChipProps) {
-  return (
-    <div className={cn('inline-flex min-w-0 items-center justify-center gap-1.5 rounded-full max-h-[20px] px-2 py-1', typeStyles[type], className)}>
+export function Chip({ type = 'neutral', label, leadingIcon, trailingIcon, href, onClick, className }: ChipProps) {
+  const classes = cn('inline-flex min-w-0 items-center justify-center gap-1.5 rounded-full max-h-[20px] px-2 py-1', typeStyles[type], className)
+  const inside = (
+    <>
       {leadingIcon && <span className="flex size-3 shrink-0 items-center justify-center">{leadingIcon}</span>}
       {label && (
         // A chip given a `max-w-*` cuts a long label with an ellipsis instead
@@ -48,6 +57,9 @@ export function Chip({ type = 'neutral', label, leadingIcon, trailingIcon, class
         <span className={cn('min-w-0 overflow-x-clip text-ellipsis whitespace-nowrap signal:tracking-wide', CHIP_TEXT_CLASSES)}>{label}</span>
       )}
       {trailingIcon && <span className="flex size-3 shrink-0 items-center justify-center">{trailingIcon}</span>}
-    </div>
+    </>
   )
+  // `relative` lifts a linked chip above a covering link that comes before it.
+  if (href) return <a href={href} onClick={onClick} className={cn('relative', classes)}>{inside}</a>
+  return <div className={classes}>{inside}</div>
 }

package/src/Link.mdx

@@ -24,6 +24,11 @@ the app decides how it navigates.
   what it wraps draws itself.
 - `external` — another site or app: it opens in a new tab, with
   `noopener noreferrer`.
+- **`cover`** — a row that opens one thing wherever you click it: an item in a
+  list, a row of a table. The link covers the row, and the keyboard ring goes
+  round the whole row.
+
+<Canvas of={LinkStories.Cover} />
 
 ## When not
 
@@ -33,6 +38,13 @@ the app decides how it navigates.
 - A link that looks like an icon button → **IconButton** with `href`.
 - A word standing for a person or a thing, drawn in a small box → **InlineChip**
   with `href`.
+- A box that is one link → **Card** with `href`. `cover` is for a row that has
+  no frame of its own.
+- `cover` on a row whose parts each open something different, or a row with
+  nothing to open. A row with only a second link inside it (a chip, say) is
+  fine: see How.
+- Stretching a link over its row by hand (`after:absolute`): the lint refuses
+  it. Use `cover`.
 
 ## How
 
@@ -59,6 +71,26 @@ import { Link } from '@estiva-app/ui'
 
 - `truncate` keeps a title that is a link on one line, cut with an ellipsis.
   Its size and colour still come from the text around it.
+
+- `cover` covers the nearest box that is `relative`: give the row `relative`.
+  The row keeps its own size, fill and hover; the link only adds the layer
+  and the ring. Pointing anywhere on the row counts as pointing at the link,
+  so `quiet` underlines the title while the row is hovered.
+- A second link inside the row comes **after** the covering link and is
+  `relative` itself, so it sits above the layer. A **Chip** with `href` already
+  is.
+
+```tsx
+<div className="relative flex h-9 items-center gap-3 px-3 hover:bg-bg-hover">
+  <Link href={itemUrl} variant="plain" cover onClick={navigate}>Item one</Link>
+  <Chip href={groupUrl} label="Group" onClick={navigate} />
+</div>
+
+<tr className="relative">
+  <td><Link href={itemUrl} variant="quiet" cover>Item one</Link></td>
+  <td>…</td>
+</tr>
+```
 - `quiet`, `underlined` and `plain` take their size and colour from where they
   sit, so put those on your own element around the link, not on the link —
   the lint refuses a look passed in `className`.

package/src/Link.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { Link } from './Link'
 import { Card } from './Card'
+import { Chip } from './Chip'
 
 const meta = {
   title: 'Navigation/Link',
@@ -70,6 +71,54 @@ export const External: Story = {
   ),
 }
 
+const ROWS = [
+  { key: 'A-1', title: 'Item one', group: 'Group', time: '2h' },
+  { key: 'A-2', title: 'Item two', group: 'Group', time: '1d' },
+  { key: 'A-3', title: 'Item three', time: '3d' },
+]
+
+/**
+ * A row that is one link: click anywhere on it, or Tab to it and the ring goes
+ * round the whole row. The chip is a second link, and opens something else.
+ */
+export const Cover: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex w-full max-w-xl flex-col">
+      {ROWS.map((row) => (
+        <div key={row.key} className="relative flex h-9 items-center gap-3 rounded-md px-3 transition-colors hover:bg-bg-hover">
+          <Link href="#" variant="plain" cover className="flex min-w-0 flex-1 items-center gap-3">
+            <span className="w-10 shrink-0 font-mono text-caption text-text-muted">{row.key}</span>
+            <span className="min-w-0 flex-1 truncate text-body-2 text-text-primary">{row.title}</span>
+          </Link>
+          {row.group && <Chip href="#" label={row.group} />}
+          <span className="w-8 shrink-0 text-right text-caption text-text-muted">{row.time}</span>
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/** The same in a table: the row is `relative`, the title a `quiet` link that covers it. */
+export const CoverInTable: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <table className="w-full max-w-xl text-body-2">
+      <tbody>
+        {ROWS.map((row) => (
+          <tr key={row.key} className="relative border-b border-border-subtle last:border-b-0 hover:bg-bg-hover">
+            <td className="w-14 px-3 py-2 font-mono text-caption text-text-muted">{row.key}</td>
+            <td className="px-3 py-2 text-text-primary">
+              <Link href="#" variant="quiet" cover>{row.title}</Link>
+            </td>
+            <td className="w-16 px-3 py-2 text-right text-caption text-text-muted">{row.time}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  ),
+}
+
 /** The four looks, each where it belongs. */
 export const AllVariants: Story = {
   parameters: { controls: { disable: true } },

package/src/Link.test.tsx

@@ -88,6 +88,21 @@ describe('Link', () => {
     expect(classesOf(screen.getByRole('link'))).toEqual([])
   })
 
+  it('cover lays a layer over the row and moves the ring onto it; without it, nothing of the kind', () => {
+    render(
+      <>
+        <Link href="#" variant="plain" cover>
+          Row
+        </Link>
+        <Link href="#" variant="plain">
+          Words
+        </Link>
+      </>,
+    )
+    expect(classesOf(screen.getByRole('link', { name: 'Row' }))).toEqual(['after:absolute', 'after:inset-0', 'after:rounded-md', 'focus-visible:outline-none', 'focus-visible:after:[outline-style:auto]'])
+    expect(classesOf(screen.getByRole('link', { name: 'Words' }))).toEqual([])
+  })
+
   it('a ref reaches the anchor', () => {
     const ref = createRef<HTMLAnchorElement>()
     render(

package/src/Link.tsx

@@ -18,6 +18,15 @@ import { cn } from './cn'
  *   and a solid version became this one, solid (her ruling, 13 September).
  * - `plain` — no look at all: a card or a row that is a link draws itself.
  *
+ * **`cover`: a row that is one link** (UIG-33, Katerina 28 September). The link
+ * stretches an invisible layer over the nearest box the app has given
+ * `relative` (a row, a table row), so a click anywhere on it opens the link, and
+ * the keyboard ring goes round that whole box rather than round the words. The
+ * row stays the app's own: its size, its fill, its hover. A second link inside
+ * the row stays clickable when it comes after the covering link and is
+ * `relative` itself, which a `Chip` with an `href` already is. Both apps
+ * stretched a link by hand before this, each under a written exception.
+ *
  * **Navigation is the app's.** The package cannot know a router, so like
  * `NavItem` it renders a real anchor and passes every anchor prop through: a
  * router app hands in `onClick`, prevents the default and navigates, and the
@@ -25,6 +34,13 @@ import { cn } from './cn'
  */
 export type LinkVariant = 'text' | 'quiet' | 'underlined' | 'plain'
 
+/**
+ * The covering layer, and the ring moved onto it: `outline-none` takes the ring
+ * off the words, and `outline-style: auto` draws the browser's own ring round the
+ * layer, the same ring every other control shows, only the size of the row.
+ */
+const COVER_CLASSES = 'after:absolute after:inset-0 after:rounded-md focus-visible:outline-none focus-visible:after:[outline-style:auto]'
+
 const VARIANT_CLASSES: Record<LinkVariant, string> = {
   text: 'text-info-default underline underline-offset-2 hover:opacity-80',
   quiet: 'hover:underline',
@@ -46,15 +62,20 @@ export interface LinkProps extends ComponentPropsWithRef<'a'> {
    * Its size and colour still come from the text around it (UIG-9, 17 September).
    */
   truncate?: boolean
+  /**
+   * The link covers the row it sits in: a click anywhere on the row opens it,
+   * and the keyboard ring goes round the whole row. Give the row `relative`.
+   */
+  cover?: boolean
   children: ReactNode
 }
 
-export function Link({ href, variant = 'text', external = false, truncate = false, className, children, ...props }: LinkProps) {
+export function Link({ href, variant = 'text', external = false, truncate = false, cover = false, className, children, ...props }: LinkProps) {
   return (
     <a
       href={href}
       {...(external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
-      className={cn(VARIANT_CLASSES[variant], truncate && 'truncate', className)}
+      className={cn(VARIANT_CLASSES[variant], truncate && 'truncate', cover && COVER_CLASSES, className)}
       {...props}
     >
       {children}

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.')] }],
+  },
+}