@estiva-app/ui 0.39.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.39.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.39.0",
-    "exports": 88,
-    "typeExports": 97,
+    "packageVersion": "0.40.0",
+    "exports": 90,
+    "typeExports": 101,
     "files": null
   },
   "storybook": {
@@ -4079,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",

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

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