@estiva-app/ui 0.62.1 → 0.64.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.62.1",
+  "version": "0.64.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,9 +4,9 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.62.1",
-    "exports": 134,
-    "typeExports": 141,
+    "packageVersion": "0.64.0",
+    "exports": 140,
+    "typeExports": 145,
     "files": null
   },
   "storybook": {
@@ -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",
@@ -3228,6 +3247,68 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "KindIcon",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/KindIcon.tsx",
+      "purpose": "The icon before a thing's name that says what kind of thing it is: a topic, a project, an issue, another app's file, or a message.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "kind",
+          "takes": "topic | project | issue | file | message",
+          "required": true,
+          "note": null
+        },
+        {
+          "name": "size",
+          "takes": "14 | 16",
+          "required": false,
+          "note": "16 in a row or a list; 14 inside a chip."
+        },
+        {
+          "name": "tone",
+          "takes": "secondary | inherit",
+          "required": false,
+          "note": "`secondary`: the quieter grey a list row's icon wears."
+        },
+        {
+          "name": "className",
+          "takes": "text",
+          "required": false,
+          "note": "Space and position only."
+        }
+      ],
+      "variants": [
+        {
+          "prop": "kind",
+          "values": [
+            "topic",
+            "project",
+            "issue",
+            "file",
+            "message"
+          ]
+        },
+        {
+          "prop": "tone",
+          "values": [
+            "secondary",
+            "inherit"
+          ]
+        }
+      ],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-kindicon--docs",
+      "storyId": "primitives-kindicon--default",
+      "docPage": "src/KindIcon.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Lightbox",
       "repo": "estiva-ui",
@@ -3377,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",
@@ -4413,6 +4494,63 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "pastedImageName",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/PastedImages.ts",
+      "purpose": "`'Screenshot 2026-09-07 14-32-05.png'`: sortable, and readable on a file card.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-pastedimages--docs",
+      "storyId": "primitives-pastedimages--in-an-editor",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "pastedImages",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/PastedImages.ts",
+      "purpose": "The pictures on the clipboard, named — `[]` when there is nothing to attach.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-pastedimages--docs",
+      "storyId": "primitives-pastedimages--in-an-editor",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "PastedImages",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/PastedImages.ts",
+      "purpose": "Pasting a picture into an editor attaches it.",
+      "purposeFrom": "page",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-pastedimages--docs",
+      "storyId": "primitives-pastedimages--in-an-editor",
+      "docPage": "src/PastedImages.mdx",
+      "app": null,
+      "looks": []
+    },
     {
       "name": "peopleMenu",
       "repo": "estiva-ui",
@@ -5161,7 +5299,13 @@
           "name": "icon",
           "takes": "anything",
           "required": true,
-          "note": "At each row's start: a 16px icon — unless the row brings its own (`CaptionedItem.icon`)."
+          "note": "At each row's start: a 16px icon — unless the row brings its own (`CaptionedItem.icon`), or `iconFor` answers."
+        },
+        {
+          "name": "iconFor",
+          "takes": "a handler",
+          "required": false,
+          "note": "A row's 16px icon from what it points at — its `uri` — when the list holds several kinds of thing; `undefined` from it draws `icon`."
         }
       ],
       "variants": [],
@@ -5269,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]:text-text-code [&_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"
       ]
     },
     {
@@ -6410,6 +6554,25 @@
         "bg-bg-field border border-border-field shadow-field hover:border-border-strong focus:border-border-focus rounded-lg text-caption text-text-primary placeholder:text-text-muted outline-none transition-colors disabled:pointer-events-none disabled:bg-bg-disabled disabled:text-text-disabled disabled:border-border-field signal:transition-shadow signal:focus:shadow-focus-ring"
       ]
     },
+    {
+      "name": "thingKindOf",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/KindIcon.tsx",
+      "purpose": "The kind of thing behind an event kind: a message is a message, a channel or a bare file is a topic, a project and an issue are themselves, and anything else is another app's file.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-kindicon--docs",
+      "storyId": "primitives-kindicon--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Toast",
       "repo": "estiva-ui",

package/src/CodeBlockColours.mdx

@@ -0,0 +1,48 @@
+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 is amber and takes no other 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. A block in any other
+  language, or in none, stays one colour.
+- 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.ts

@@ -0,0 +1,14 @@
+/** 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'
+
+/**
+ * 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 })

package/src/ComposerTriggers.mdx

@@ -92,10 +92,12 @@ const urgent = editor ? urgentPubkeys(editor) : undefined
   the same query; nothing waits for it. A row's `description` is its second
   line, which the chip does not wear. A row the person has arrowed to stays
   highlighted when the list is drawn again.
-- **Several kinds of thing in one `[` list:** a row's `icon` is drawn in
-  place of the list's, and the chip's `iconFor(uri)` picks the chip's from
-  what it points at, so the chip wears what its row wore. A row with no `icon`,
-  or a `uri` `iconFor` answers `undefined` for, keeps the one icon.
+- **Several kinds of thing in one `[` list:** give `ReferenceTrigger` and
+  `CaptionedReference` the same `iconFor(uri)` — at 16px for the rows, 14px
+  for the chip — and every row and the chip it inserts wear what they point
+  at. **KindIcon** is the answer for Estiva's own kinds. A row's own `icon`
+  wins over `iconFor`; a row with neither, or a `uri` `iconFor` answers
+  `undefined` for, keeps the list's one icon.
 
 <Canvas of={ComposerTriggersStories.ReferencesOfSeveralKinds} />
 

package/src/ComposerTriggers.test.tsx

@@ -145,6 +145,36 @@ describe('[', () => {
     expect(editor!.getHTML()).toContain('data-message-mention="true"')
   })
 
+  it('gives each row the icon `iconFor` answers for its uri; a row’s own icon wins, and no answer keeps the list’s', async () => {
+    const rows = [
+      { ...ITEMS[0], uri: 'nostr:a' },
+      { ...ITEMS[1], uri: 'nostr:b', icon: <i data-icon="own" /> },
+      { ...ITEMS[2], uri: 'nostr:c' },
+    ]
+    function Iconed() {
+      const made = useEditor({
+        extensions: [
+          StarterKit,
+          Chip,
+          ReferenceTrigger.configure({
+            items: () => rows,
+            nodeName: 'messageMention',
+            ariaLabel: 'Things',
+            sectionLabel: 'Things',
+            icon: <i data-icon="list" />,
+            iconFor: (uri) => (uri === 'nostr:a' ? <i data-icon="kind-a" /> : undefined),
+          }),
+        ],
+      })
+      editor = made
+      return <EditorContent editor={made} />
+    }
+    render(<Iconed />)
+    await type('[')
+    const icons = within(screen.getByRole('listbox')).getAllByRole('option').map((row) => row.querySelector('[data-icon]')?.getAttribute('data-icon'))
+    expect(icons).toEqual(['kind-a', 'own', 'list'])
+  })
+
   it('draws the app’s sections in order, skips an empty one, and redraws the open list when told', async () => {
     const listeners = new Set<() => void>()
     let late: CaptionedItem[] = []

package/src/ComposerTriggers.tsx

@@ -321,8 +321,14 @@ export interface ReferenceMenuOptions {
   ariaLabel: string
   /** The section's heading. */
   sectionLabel: string
-  /** At each row's start: a 16px icon — unless the row brings its own (`CaptionedItem.icon`). */
+  /** At each row's start: a 16px icon — unless the row brings its own (`CaptionedItem.icon`), or `iconFor` answers. */
   icon: ReactNode
+  /**
+   * A row's 16px icon from what it points at — its `uri` — when the list holds
+   * several kinds of thing; `undefined` from it draws `icon`. Give the chip the
+   * same answer at 14px (`CaptionedReference`'s `iconFor`), so a pick keeps it.
+   */
+  iconFor?: (uri: string) => ReactNode | undefined
 }
 
 /** A row as the list holds it: which section it is drawn under, when the list has several. */
@@ -333,7 +339,7 @@ type ListedItem = CaptionedItem & { section?: string }
  * One section headed `sectionLabel`, or — when the rows say which section they
  * are in — a heading for each, in the order the rows arrive.
  */
-export function referenceMenu({ ariaLabel, sectionLabel, icon }: ReferenceMenuOptions): SuggestionPopupOptions<CaptionedItem> {
+export function referenceMenu({ ariaLabel, sectionLabel, icon, iconFor }: ReferenceMenuOptions): SuggestionPopupOptions<CaptionedItem> {
   return {
     ariaLabel,
     width: 'w-[658px]',
@@ -349,7 +355,7 @@ export function referenceMenu({ ariaLabel, sectionLabel, icon }: ReferenceMenuOp
       return groups
     },
     itemKey: (item) => `reference-${item.id}`,
-    row: (item) => ({ leading: item.icon ?? icon, label: captionOf(item.label, item.snippet), description: item.description, hint: <EnterHint /> }),
+    row: (item) => ({ leading: item.icon ?? iconFor?.(item.uri) ?? icon, label: captionOf(item.label, item.snippet), description: item.description, hint: <EnterHint /> }),
   }
 }
 

package/src/KindIcon.mdx

@@ -0,0 +1,58 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as KindIconStories from './KindIcon.stories'
+
+<Meta of={KindIconStories} />
+
+# KindIcon
+
+The icon before a thing's name that says what kind of thing it is: a topic, a
+project, an issue, another app's file, or a message. One table for every app,
+so the same thing wears the same icon wherever it is named.
+
+<Canvas of={KindIconStories.EveryKind} />
+
+## When
+
+- **Before a thing's name in a list row**, at 16px: a `[` list row, a recent
+  file, a search result.
+- **Inside a chip**, at 14px: `InlineChip`'s `icon` when a sentence names a
+  thing.
+- **As `iconFor` of the `[` list and its chip** (`ReferenceTrigger`,
+  `CaptionedReference`), so every row and every chip it inserts wears its own
+  kind.
+
+<Canvas of={KindIconStories.InAChip} />
+
+## When not
+
+- A person → **Avatar** or **Person**. A person is a face, not a kind.
+- A status (open, resolved) → **Chip**, or the app's own status mark.
+- An icon for an action → **IconButton** with the icon you need.
+
+## How
+
+```tsx
+import { KindIcon, thingKindOf } from '@estiva-app/ui'
+
+<KindIcon kind="issue" />                          // 16px, in a row
+<KindIcon kind={thingKindOf(event.kind)} size={14} tone="inherit" /> // inside a chip
+```
+
+- `thingKindOf(eventKind)` turns an event kind into a kind of thing. A pointer
+  written as `nostr:naddr…` carries its kind once decoded; a `nostr:nevent…`
+  is a message.
+- The icon is `aria-hidden`: the name beside it says what it is.
+- **Which icon is which kind is this part's.** An app never picks its own icon
+  for these. Its stroke is 1.5; it comes in two sizes and two tones: the
+  quieter grey of a list row, or `inherit`, the ink of the chip or row that
+  holds it.
+
+<Canvas of={KindIconStories.InAList} />
+
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
+## Props
+
+<Controls of={KindIconStories.Default} />

package/src/KindIcon.stories.tsx

@@ -0,0 +1,64 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { InlineChip } from './InlineChip'
+import { KindIcon, type ThingKind } from './KindIcon'
+import { MenuItem, MenuPanel, MenuSection } from './Menu'
+
+const meta = {
+  title: 'Primitives/KindIcon',
+  component: KindIcon,
+  args: { kind: 'topic' },
+  argTypes: { kind: { control: 'select', options: ['topic', 'project', 'issue', 'file', 'message'] } },
+} satisfies Meta<typeof KindIcon>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const KINDS: { kind: ThingKind; name: string }[] = [
+  { kind: 'topic', name: 'Topic' },
+  { kind: 'project', name: 'Project' },
+  { kind: 'issue', name: 'Issue' },
+  { kind: 'file', name: 'Another app’s file' },
+  { kind: 'message', name: 'Message' },
+]
+
+export const Default: Story = {}
+
+/** Every kind, at 16px, beside its name. */
+export const EveryKind: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-2 text-body-2 text-text-primary">
+      {KINDS.map(({ kind, name }) => (
+        <div key={kind} className="flex items-center gap-2">
+          <KindIcon kind={kind} />
+          {name}
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/** At 14px inside a chip, the way a sentence names a thing. */
+export const InAChip: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <p className="text-body-2 text-text-primary">
+      Tracked in <InlineChip icon={<KindIcon kind="issue" size={14} tone="inherit" />}>Ship the block model</InlineChip> and{' '}
+      <InlineChip icon={<KindIcon kind="topic" size={14} tone="inherit" />}>Planning</InlineChip> for now.
+    </p>
+  ),
+}
+
+/** At the start of list rows, each saying what it points at. */
+export const InAList: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <MenuPanel className="w-72">
+      <MenuSection label="Files">
+        {KINDS.map(({ kind, name }) => (
+          <MenuItem key={kind} label={name} leading={<KindIcon kind={kind} />} onClick={() => {}} />
+        ))}
+      </MenuSection>
+    </MenuPanel>
+  ),
+}