@estiva-app/ui 0.63.0 → 0.65.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.63.0",
+  "version": "0.65.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",
@@ -91,7 +91,8 @@
     "@tiptap/extension-mention": "^3.22.1",
     "@tiptap/pm": "^3.22.1",
     "@tiptap/react": "^3.22.1",
-    "@tiptap/suggestion": "^3.22.1"
+    "@tiptap/suggestion": "^3.22.1",
+    "@tiptap/extension-code-block-lowlight": "^3.22.1"
   },
   "peerDependenciesMeta": {
     "eslint": {
@@ -117,6 +118,9 @@
     },
     "@tiptap/suggestion": {
       "optional": true
+    },
+    "@tiptap/extension-code-block-lowlight": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -130,6 +134,7 @@
     "@testing-library/react": "^16.3.3",
     "@testing-library/user-event": "^14.6.7",
     "@tiptap/core": "^3.31.3",
+    "@tiptap/extension-code-block-lowlight": "^3.31.3",
     "@tiptap/extension-mention": "^3.31.3",
     "@tiptap/pm": "^3.31.3",
     "@tiptap/react": "^3.31.3",
@@ -162,6 +167,7 @@
   "dependencies": {
     "@base-ui/react": "^1.8.0",
     "clsx": "^2.1.1",
+    "lowlight": "^3.3.0",
     "tailwind-merge": "^3.5.0"
   },
   "main": "./dist/index.js",

package/registry.json

@@ -4,8 +4,8 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.63.0",
-    "exports": 139,
+    "packageVersion": "0.65.0",
+    "exports": 140,
     "typeExports": 145,
     "files": null
   },
@@ -1196,6 +1196,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "CodeBlockColours",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/CodeBlockColours.ts",
+      "purpose": "A code block in an editor, coloured by its language as you type.",
+      "purposeFrom": "page",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-codeblockcolours--docs",
+      "storyId": "primitives-codeblockcolours--in-an-editor",
+      "docPage": "src/CodeBlockColours.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "CollapsibleSection",
       "repo": "estiva-ui",
@@ -3439,10 +3458,10 @@
       "docPage": "src/Link.mdx",
       "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",
-        "text-info-default underline underline-offset-2 hover:opacity-80 truncate after:rounded-md focus-visible:outline-none",
+        "text-text-interactive underline underline-offset-2 hover:opacity-80",
+        "text-text-interactive underline underline-offset-2 hover:opacity-80 after:rounded-md focus-visible:outline-none",
+        "text-text-interactive underline underline-offset-2 hover:opacity-80 truncate",
+        "text-text-interactive 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",
@@ -5394,15 +5413,15 @@
       "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(ul,ol)]:pl-5 [&_li>p]:m-0 [&_li]:break-words [&_li]:marker:text-text-secondary [&_ol]:list-decimal [&_ul]:list-disc",
+        "[&_blockquote>p]:m-0 [&_blockquote]:border-l-[3px] [&_blockquote]:border-text-muted [&_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 [&_:not(pre)>code]:border [&_:not(pre)>code]:border-border-default [&_code]:font-mono [&_code]:text-[0.85em] [&_code]:text-text-primary",
+        "[&_pre>code]:text-[1em] [&_pre]:whitespace-pre-wrap [&_pre]:break-words [&_pre]:rounded-md [&_pre]:bg-bg-code [&_pre]:px-3 [&_pre]:py-2.5 [&_pre]:font-mono [&_pre]:text-[0.85em] [&_pre]:leading-relaxed [&_pre]:text-text-primary",
+        "[&_:is(.hljs-keyword,.hljs-doctag,.hljs-type,.hljs-template-tag,.hljs-template-variable)]:text-syntax-keyword [&_.hljs-title]:text-syntax-function [&_:is(.hljs-number,.hljs-literal,.hljs-attr,.hljs-attribute,.hljs-meta,.hljs-variable,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-id)]:text-syntax-constant [&_:is(.hljs-string,.hljs-regexp)]:text-syntax-string [&_:is(.hljs-built_in,.hljs-symbol)]:text-syntax-variable [&_.hljs-comment]:text-syntax-comment [&_:is(.hljs-name,.hljs-quote,.hljs-selector-tag,.hljs-selector-pseudo)]:text-syntax-tag",
         "[&_: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"
+        "[&_em]:italic [&_strong]:font-semibold [&_strong]:text-text-primary [&_u]:underline [&_u]:decoration-text-muted [&_u]:underline-offset-2",
+        "text-body-2 leading-normal [&>:is(h2,h3)]:text-body-2 [&>:is(h2,h3)]:font-semibold [&>h1]:text-h4",
+        "text-caption leading-snug [&>:is(h1,h2,h3)]:mb-0.5 [&>:is(h1,h2,h3)]:mt-1.5 [&>:is(h1,h2,h3)+:is(h1,h2,h3)]:mt-1 [&>:is(h1,h2,h3):last-child]:mb-0 [&>:is(h2,h3)]:text-caption [&>:is(h2,h3)]:font-semibold [&>h1]:text-body-2 [&>h1]:font-semibold"
       ]
     },
     {

package/src/CodeBlockColours.mdx

@@ -0,0 +1,49 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as CodeBlockColoursStories from './CodeBlockColours.stories'
+
+<Meta of={CodeBlockColoursStories} />
+
+# CodeBlockColours
+
+A code block in an editor, coloured by its language as you type. The colours
+are the ones RichText reads it in, so writing looks the same as reading.
+
+<Canvas of={CodeBlockColoursStories.InAnEditor} />
+
+## When
+
+- **Any editor that writes RichText**: a message box, an edit box, a
+  description. Use it in place of the starter kit's code block.
+
+## When not
+
+- Drawing text that is already written → **RichText**, which colours its code
+  blocks itself.
+- Code in a sentence → the code mark. It takes no colours.
+
+## How
+
+```tsx
+import StarterKit from '@tiptap/starter-kit'
+import { CodeBlockColours } from '@estiva-app/ui/editor'
+import { richTextClassName } from '@estiva-app/ui'
+
+useEditor({
+  extensions: [StarterKit.configure({ codeBlock: false }), CodeBlockColours],
+  editorProps: { attributes: { class: richTextClassName() } },
+})
+```
+
+- **The editor's root must wear `richTextClassName`.** The colours live in its
+  class list; without it the words are named but drawn in one colour.
+- The block keeps the name `codeBlock` and its `language`, so text written
+  before it was added reads the same.
+- It colours highlight.js's 37 everyday languages, only by the language the
+  block names (```` ```ts ```` then Enter). A block in any other language, or
+  in none, stays one colour: it never guesses, so it looks the same once read.
+- The app installs `@tiptap/extension-code-block-lowlight`, as it installs the
+  other Tiptap parts.
+
+## What it owns
+
+Nothing. It names each word of a code block; the RichText class list colours them.

package/src/CodeBlockColours.stories.tsx

@@ -0,0 +1,37 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { Card } from './Card'
+import { CodeBlockColours } from './CodeBlockColours'
+import { richTextClassName } from './RichText'
+
+/**
+ * Type in the code block: each word takes its colour as you write, the same
+ * colours RichText reads it in. Change the theme to see each set.
+ */
+const meta = {
+  title: 'Primitives/CodeBlockColours',
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+function Box() {
+  const editor = useEditor({
+    extensions: [StarterKit.configure({ codeBlock: false }), CodeBlockColours],
+    content: [
+      '<p>A code block in a language takes its colours:</p>',
+      '<pre><code class="language-ts">// Count the items that are done\nexport function countDone(items: Item[]): number {\n  const done = items.filter((item) =&gt; item.state === \'done\')\n  return done.length + 0\n}</code></pre>',
+    ].join(''),
+    editorProps: { attributes: { class: richTextClassName('default', 'outline-none'), 'aria-label': 'Text' } },
+  })
+  return (
+    <Card fill="surface" className="w-full max-w-lg p-3">
+      <EditorContent editor={editor} />
+    </Card>
+  )
+}
+
+/** An editor with a code block in TypeScript. Type in it. */
+export const InAnEditor: Story = { render: () => <Box /> }

package/src/CodeBlockColours.test.ts

@@ -0,0 +1,36 @@
+// @vitest-environment jsdom
+/**
+ * CodeBlockColours colours a block only by the language it names, as RichText
+ * does when the text is read (Katerina, 9 October: never guess).
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { Editor } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import { CodeBlockColours } from './CodeBlockColours'
+
+let editor: Editor | undefined
+afterEach(() => editor?.destroy())
+
+const coloured = (content: string) => {
+  editor = new Editor({ element: document.createElement('div'), extensions: [StarterKit.configure({ codeBlock: false }), CodeBlockColours], content })
+  return editor.view.dom.querySelectorAll('pre [class*="hljs-"]').length
+}
+
+describe('CodeBlockColours', () => {
+  it('colours a block that names its language', () => {
+    expect(coloured('<pre><code class="language-ts">const done = items.length</code></pre>')).toBeGreaterThan(0)
+  })
+
+  it('leaves a block that names no language in one colour, as RichText reads it', () => {
+    expect(coloured('<pre><code>const done = items.length</code></pre>')).toBe(0)
+  })
+
+  it('leaves a block in a language it does not know in one colour', () => {
+    expect(coloured('<pre><code class="language-nothing">const done = items.length</code></pre>')).toBe(0)
+  })
+
+  it('keeps the block a code block, with its language', () => {
+    coloured('<pre><code class="language-ts">const done = 1</code></pre>')
+    expect(editor!.getJSON().content?.[0]).toMatchObject({ type: 'codeBlock', attrs: { language: 'ts' } })
+  })
+})

package/src/CodeBlockColours.ts

@@ -0,0 +1,28 @@
+/** The editor's code block, coloured by language like RichText's (`@estiva-app/ui/editor`). */
+import { CodeBlockLowlight } from '@tiptap/extension-code-block-lowlight'
+import { lowlight } from './codeColours'
+
+/*
+  The editor library guesses a language for a block that names none, or names
+  one it does not know, and colours it by the guess. RichText never guesses, so
+  that block was coloured while written and plain once read. A block is
+  coloured only by the language it names, while written and when read
+  (Katerina, 9 October: never guess).
+*/
+const namedOnly = {
+  highlight: (language: string, value: string) => lowlight().highlight(language, value),
+  highlightAuto: (value: string) => ({ type: 'root' as const, children: [{ type: 'text' as const, value }], data: { language: undefined, relevance: 0 } }),
+  listLanguages: () => lowlight().listLanguages(),
+  registered: (language: string) => lowlight().registered(language),
+}
+
+/**
+ * A code block in the editor, with the colours RichText reads it in (Katerina,
+ * 9 October): the same highlight.js languages, the same classes, and the
+ * editor's root wears `richTextClassName`, which colours them.
+ *
+ * It replaces the starter kit's code block: `StarterKit.configure({ codeBlock: false })`,
+ * then add `CodeBlockColours`. The block keeps its name, `codeBlock`, and its
+ * `language` attribute, so nothing already written changes.
+ */
+export const CodeBlockColours = CodeBlockLowlight.configure({ lowlight: namedOnly })

package/src/Link.mdx

@@ -14,7 +14,7 @@ the app decides how it navigates.
 
 - **It takes the size and colour of the text around it**: put it inside that
   text.
-- **`text`** — a link written inside text: the info colour, always
+- **`text`** — a link written inside text: the theme's link colour, always
   underlined, dimming on hover.
 - **`quiet`** — a title or a time that is also a link. It takes the colour and
   size of the text it sits in, and underlines on hover.

package/src/Link.stories.tsx

@@ -15,7 +15,7 @@ const meta = {
 export default meta
 type Story = StoryObj<typeof meta>
 
-/** Inside written text: the info colour, always underlined. Hover dims it. */
+/** Inside written text: the theme's link colour, always underlined. Hover dims it. */
 export const Text: Story = {
   render: (args) => (
     <p className="max-w-[480px] text-body-2 text-text-primary">

package/src/Link.test.tsx

@@ -53,10 +53,10 @@ describe('Link', () => {
     expect(screen.getByRole('link', { name: 'Documents' }).getAttribute('href')).toBe('/documents')
   })
 
-  it('text is the info colour, always underlined, and is the default', () => {
+  it('text is the link colour, always underlined, and is the default', () => {
     render(<Link href="#">Label</Link>)
     const classes = classesOf(screen.getByRole('link'))
-    expect(classes).toContain('text-info-default')
+    expect(classes).toContain('text-text-interactive')
     expect(classes).toContain('underline')
     expect(classes).toContain('underline-offset-2')
   })

package/src/Link.tsx

@@ -9,7 +9,7 @@ import { cn } from './cn'
  * on 13 September 2026, in three jobs (UIG-27). The looks are the ones those
  * links already had, reduced by Katerina's ruling:
  *
- * - `text` — a link inside written text: the info colour, always underlined,
+ * - `text` — a link inside written text: the theme's link colour, always underlined,
  *   dimming on hover. The look a link in a body of text already had.
  * - `quiet` — a title or a timestamp that is also a link. It takes the colour
  *   and size of the text it sits in and underlines on hover. Two looks that
@@ -43,7 +43,7 @@ export type LinkVariant = 'text' | 'quiet' | 'underlined' | 'plain'
 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',
+  text: 'text-text-interactive underline underline-offset-2 hover:opacity-80',
   quiet: 'hover:underline',
   underlined: 'underline underline-offset-2 hover:text-text-primary',
   plain: '',

package/src/RichText.stories.tsx

@@ -57,6 +57,7 @@ export const Links: Story = {
     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')),
+      p(t('An '), t('underlined', 'underline'), t(' word beside [a link](https://example.com), and '), t('item.count', 'code'), t(' in a sentence.')),
     ],
   },
 }
@@ -89,3 +90,26 @@ export const UnknownBlock: Story = {
     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.')] }],
   },
 }
+
+/** A code block in a named language. */
+export const CodeInALanguage: Story = {
+  args: {
+    blocks: [
+      {
+        type: 'codeBlock',
+        language: 'ts',
+        inline: [
+          t(
+            [
+              '// Count the items that are done',
+              'export function countDone(items: Item[]): number {',
+              "  const done = items.filter((item) => item.state === 'done')",
+              '  return done.length + 0',
+              '}',
+            ].join('\n'),
+          ),
+        ],
+      },
+    ],
+  },
+}

package/src/RichText.tsx

@@ -1,6 +1,7 @@
 import type { MouseEvent, ReactNode } from 'react'
 import { cn } from './cn'
 import { Link } from './Link'
+import { codeColours } from './codeColours'
 
 /**
  * Formatted text, drawn: headings, paragraphs, lists, a quote, code, a divider,
@@ -11,7 +12,8 @@ import { Link } from './Link'
  * 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.
+ * 28 September, one per difference, most of them Peek's, with the room and
+ * colours she changed on 9 October.
  *
  * **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
@@ -84,21 +86,32 @@ export interface RichTextProps {
  * 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',
+  /* Blocks 8px apart (Katerina, 9 October; 4 before). A list's own items stay together. */
+  base: 'flex flex-col gap-2 break-words text-text-secondary',
+  /* A heading binds to what follows it: 12px above (4 and the 8px gap), 8px below (the gap); two headings in a row, 12px apart. The same as before the gap grew (Katerina, 9 October: headings do not change). Level 3 keeps the text's colour, one step lower: at the same size as level 2, colour is what tells them apart (Katerina, 9 October). */
+  headings: '[&>:is(h1,h2,h3)]:mt-1 [&>:is(h1,h2,h3):first-child]:mt-0 [&>:is(h1,h2)]:text-text-primary',
+  /* Bullets and numbers in the text's own colour, so a number can be read (Katerina, 9 October; they were the muted grey, 2.4 : 1 in Leaf). */
+  lists: '[&_:is(ul,ol)]:pl-5 [&_li>p]:m-0 [&_li]:break-words [&_li]:marker:text-text-secondary [&_ol]:list-decimal [&_ul]:list-disc',
+  /* The line in the muted text grey, not the border grey: a border grey was 1.3 : 1 in Leaf (Katerina, 9 October). */
   // 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',
+  quote: '[&_blockquote>p]:m-0 [&_blockquote]:border-l-[3px] [&_blockquote]:border-text-muted [&_blockquote]:pl-2.5',
+  /* Code in a sentence: the code fill and a thin border, in the heading colour (Katerina, 9 October: option B; the amber of 0.64.0 was too much). */
+  // eslint-disable-next-line token-values/no-restricted-classes -- @estiva-escape: code is 0.85 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 [&_:not(pre)>code]:border [&_:not(pre)>code]:border-border-default [&_code]:font-mono [&_code]:text-[0.85em] [&_code]:text-text-primary',
+  /* 12px either side, 10px above and below, looser lines than the text (Katerina, 9 October; 8px all round before). */
+  // eslint-disable-next-line token-values/no-restricted-classes -- @estiva-escape: code is 0.85 of the text around it; the code inside the block is the block's own size, not 0.85 of it again
+  codeBlock: '[&_pre>code]:text-[1em] [&_pre]:whitespace-pre-wrap [&_pre]:break-words [&_pre]:rounded-md [&_pre]:bg-bg-code [&_pre]:px-3 [&_pre]:py-2.5 [&_pre]:font-mono [&_pre]:text-[0.85em] [&_pre]:leading-relaxed [&_pre]:text-text-primary',
+  /* Colours inside a code block, by language: the classes `codeColours` gives each word, after highlight.js's own GitHub theme (Katerina, 9 October). */
+  syntax: '[&_:is(.hljs-keyword,.hljs-doctag,.hljs-type,.hljs-template-tag,.hljs-template-variable)]:text-syntax-keyword [&_.hljs-title]:text-syntax-function [&_:is(.hljs-number,.hljs-literal,.hljs-attr,.hljs-attribute,.hljs-meta,.hljs-variable,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-id)]:text-syntax-constant [&_:is(.hljs-string,.hljs-regexp)]:text-syntax-string [&_:is(.hljs-built_in,.hljs-symbol)]:text-syntax-variable [&_.hljs-comment]:text-syntax-comment [&_:is(.hljs-name,.hljs-quote,.hljs-selector-tag,.hljs-selector-pseudo)]:text-syntax-tag',
+  /* A divider splits the text in two: 16px either side (Katerina, 9 October; 4 before). */
+  divider: '[&_hr]:my-2 [&_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',
+  /* Bold in the heading colour, not only heavier. An underlined word draws a faint line, so it does not read as a link (Katerina, 9 October). */
+  marks: '[&_em]:italic [&_strong]:font-semibold [&_strong]:text-text-primary [&_u]:underline [&_u]:decoration-text-muted [&_u]:underline-offset-2',
+  /* Lines 1.5 apart (Katerina, 9 October; 1.4 before). */
+  default: 'text-body-2 leading-normal [&>:is(h2,h3)]:text-body-2 [&>:is(h2,h3)]:font-semibold [&>h1]:text-h4',
+  /* Blocks 6px apart; a heading keeps its 12px above and 8px below. */
+  small: 'gap-1.5 text-caption leading-snug [&>:is(h1,h2,h3)]:mb-0.5 [&>:is(h1,h2,h3)]:mt-1.5 [&>:is(h1,h2,h3)+:is(h1,h2,h3)]:mt-1 [&>:is(h1,h2,h3):last-child]:mb-0 [&>:is(h2,h3)]:text-caption [&>:is(h2,h3)]:font-semibold [&>h1]:text-body-2 [&>h1]:font-semibold',
 }
 
 /**
@@ -106,8 +119,8 @@ const RICH_TEXT_CLASSES = {
  * 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)
+  const { base, headings, lists, quote, code, codeBlock, syntax, divider, table, marks } = RICH_TEXT_CLASSES
+  return cn(base, headings, lists, quote, code, codeBlock, syntax, divider, table, marks, RICH_TEXT_CLASSES[size], className)
 }
 
 /**
@@ -251,9 +264,10 @@ function Block({ block, draw }: { block: RichTextBlock; draw: Draw }): ReactNode
       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.
+      // In a language highlight.js knows, each word takes its colour; in any other, the text as it is.
       return (
         <pre data-block-id={block.id} data-language={block.language}>
-          <code>{(block.inline ?? []).map((run) => run.text).join('')}</code>
+          <code>{codeColours((block.inline ?? []).map((run) => run.text).join(''), block.language)}</code>
         </pre>
       )
     case 'horizontalRule':

package/src/codeColours.ts

@@ -0,0 +1,41 @@
+import { createElement, type ReactNode } from 'react'
+import { common, createLowlight } from 'lowlight'
+
+/**
+ * Colours inside a code block, by language (Katerina, 9 October).
+ *
+ * highlight.js reads the code and names each word (a keyword, a string, a
+ * comment); RichText's class list gives each name its colour from the theme's
+ * `syntax-*` tokens. The same instance colours the editor's code block
+ * (`CodeBlockColours`), so what is written looks the same as what is read.
+ *
+ * `common` is highlight.js's 37 everyday languages. A language outside them, or
+ * none, leaves the code in one colour.
+ *
+ * Made the first time code is coloured, not when the package loads: a call at
+ * the top of the file is kept by every app's bundler, so an app that never draws
+ * code carried highlight.js too (measured: an app importing only `Link` was
+ * 55 KB gzipped).
+ */
+let instance: ReturnType<typeof createLowlight> | undefined
+export function lowlight() {
+  return (instance ??= createLowlight(common))
+}
+
+interface HastNode {
+  type: string
+  value?: string
+  properties?: { className?: string[] }
+  children?: HastNode[]
+}
+
+function draw(node: HastNode, key: number): ReactNode {
+  if (node.type === 'text') return node.value
+  return createElement('span', { key, className: node.properties?.className?.join(' ') }, (node.children ?? []).map(draw))
+}
+
+/** The code, its words wrapped in highlight.js's classes; the text as it is when the language is unknown. */
+export function codeColours(text: string, language?: string): ReactNode {
+  if (!language || !lowlight().registered(language)) return text
+  return (lowlight().highlight(language, text).children as HastNode[]).map(draw)
+}

package/src/editor.ts

@@ -9,6 +9,7 @@
  */
 export { KeptSelection, SelectionToolbar, normalizeHref, type MarkId, type SelectionToolbarProps } from './SelectionToolbar'
 export { PastedImages, pastedImages, pastedImageName, type PastedImagesOptions, type ClipboardSource } from './PastedImages'
+export { CodeBlockColours } from './CodeBlockColours'
 export { suggestionPopup, isSuggestionActive, isSuggestionOpen, type SuggestionPopupOptions } from './suggestionPopup'
 export { EditorBlockHandle, blockDropCursor, deleteBlock, moveBlock, duplicateBlock, startBlockDrag, type EditorBlockHandleProps, type BlockTurnInto } from './EditorBlockHandle'
 export {

package/src/pages.test.ts

@@ -41,6 +41,7 @@ const NOTHING = 'Nothing. It only draws. Clicks and keys are yours.'
 const HOLDS_ONLY: Record<string, string> = {
   AppProvider: 'Nothing. It draws nothing; it holds two answers for the parts below it.',
   PastedImages: 'Nothing. It draws nothing; it hands a pasted picture to the app, named.',
+  CodeBlockColours: 'Nothing. It names each word of a code block; the RichText class list colours them.',
 }
 
 const dir = new URL('.', import.meta.url)

package/src/registry/registry.test.ts

@@ -26,7 +26,7 @@ import { SCHEMA_VERSION, validateRegistry, type Registry, type RegistryEntry } f
 const root = process.cwd()
 const registry = buildRegistry({ root })
 /** Editor extensions: named like components by the catalogue, and not React components. */
-const EDITOR_EXTENSIONS = ['KeptSelection', 'BlockId', 'UnknownBlock', 'ReferenceNode', 'AttachmentNode', 'PersonMention', 'UrgentPersonMention', 'CaptionedReference', 'ReferenceTrigger', 'SlashCommands', 'PastedImages']
+const EDITOR_EXTENSIONS = ['KeptSelection', 'BlockId', 'UnknownBlock', 'ReferenceNode', 'AttachmentNode', 'PersonMention', 'UrgentPersonMention', 'CaptionedReference', 'ReferenceTrigger', 'SlashCommands', 'PastedImages', 'CodeBlockColours']
 const entry = (name: string): RegistryEntry => {
   const found = registry.entries.find((candidate) => candidate.name === name)
   if (!found) throw new Error(`no entry for ${name}`)
@@ -48,19 +48,19 @@ describe('the registry builds', () => {
     expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
   })
 
-  it('counts 139 names over 75 files: 106 components, 32 helpers and 1 hook (NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October)', () => {
+  it('counts 140 names over 76 files: 107 components, 32 helpers and 1 hook (NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October; CodeBlockColours, the coloured code block of the editor, on 9 October)', () => {
     // The reconciliation GATES.md §24 explains. If this changes, that changes.
-    // The ten `EDITOR_EXTENSIONS` count as components by their names; they are
+    // The `EDITOR_EXTENSIONS` count as components by their names; they are
     // editor extensions, documented on SelectionToolbar's, BlockNodes' and
     // ComposerTriggers' pages.
     const kinds = registry.entries.reduce<Record<string, number>>((all, one) => ({ ...all, [one.kind]: (all[one.kind] ?? 0) + 1 }), {})
-    expect(kinds).toEqual({ component: 106, helper: 32, hook: 1 })
-    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(75)
+    expect(kinds).toEqual({ component: 107, helper: 32, hook: 1 })
+    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(76)
   })
 
   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(71)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(72)
     expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(68)
   })
 

package/stories/Choosing.mdx

@@ -97,6 +97,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 picture pasted into an editor, attached rather than pasted | **PastedImages** — from `@estiva-app/ui/editor`; the app hands it its upload |
+| A code block in an editor, coloured by its language as you type | **CodeBlockColours** — from `@estiva-app/ui/editor`, in place of the starter kit's code block |
 | A person or a thing named inside a sentence | **InlineChip** — one line high, level with the words; `href` makes it a link |
 | What kind of thing a name stands for — a topic, a project, an issue, a file, a message | **KindIcon** — before the name in a row, or inside an **InlineChip**; `thingKindOf` turns an event kind into one |
 | Formatted text: headings, lists, a quote, code, a table, links | **RichText** — pass the parsed tree; `small` inside a card |

package/tailwind-preset.js

@@ -155,6 +155,13 @@ export default {
         'bg-tooltip-key': 'var(--bg-tooltip-key)',
         'bg-field':     'var(--bg-field)',
         'bg-code':      'var(--bg-code)',
+        'syntax-keyword': 'var(--syntax-keyword)',
+        'syntax-function': 'var(--syntax-function)',
+        'syntax-constant': 'var(--syntax-constant)',
+        'syntax-string': 'var(--syntax-string)',
+        'syntax-variable': 'var(--syntax-variable)',
+        'syntax-comment': 'var(--syntax-comment)',
+        'syntax-tag': 'var(--syntax-tag)',
         // text
         'text-primary':   'var(--text-primary)',
         'text-secondary': 'var(--text-secondary)',