@estiva-app/ui 0.57.4 → 0.59.0

package/dist/looks.d.ts

@@ -29,8 +29,12 @@ export declare const FIELD_SIZE_CLASSES: {
 export declare const FIELD_SHELL_CLASSES = "bg-bg-field border border-border-field shadow-field hover:border-border-strong group-hover/field:border-border-strong rounded-lg transition-colors";
 /** A panel that floats over the page: Menu's panel and Tooltip. */
 export declare const FLOATING_SURFACE_CLASSES = "rounded-lg border border-border-default bg-bg-elevated shadow-lg";
+/** A count beside a label, in the muted colour: NavItem's number and SectionHeader's `count`. */
+export declare const COUNT_TEXT_CLASSES = "font-mono text-caption tabular-nums text-text-muted";
 /** A chip's words: Chip's label and Reaction's count. */
 export declare const CHIP_TEXT_CLASSES = "text-chip signal:font-mono signal:text-small signal:font-semibold signal:tabular-nums";
+/** Small secondary words that turn mono under signal: Kbd's key, CommandPalette's footer and MembersPill's count. */
+export declare const MONO_CAPTION_CLASSES = "text-caption text-text-secondary signal:font-mono signal:text-small";
 /** Words typed straight into an input with no box of its own: SearchInput and ChipInput. */
 export declare const BARE_INPUT_CLASSES = "bg-transparent text-text-primary placeholder:text-text-muted outline-none";
 /** A sidebar row's shape and its words at rest, brightening under the pointer: NavItem, and SectionHeader's `row` (a folder among rows). */

package/dist/looks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"looks.d.ts","sourceRoot":"","sources":["../src/looks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,2MAA2M,CAAA;AAEzO,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,kDAAkD,CAAA;AAEjF,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,iKAAiK,CAAA;AAEpM,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,4DAA4D,CAAA;AAEjG,kJAAkJ;AAClJ,eAAO,MAAM,kBAAkB;;;CAGrB,CAAA;AAEV,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,uJAAuJ,CAAA;AAEvL,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,qEAAqE,CAAA;AAE1G,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,0FAA0F,CAAA;AAExH,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,8EAA8E,CAAA;AAE7G,4IAA4I;AAE5I,eAAO,MAAM,mBAAmB,iCAAiC,CAAA;AACjE,eAAO,MAAM,wBAAwB,gDAAgD,CAAA;AAErF,2FAA2F;AAC3F,eAAO,MAAM,qBAAqB,kEAAkE,CAAA;AAEpG,2IAA2I;AAC3I,eAAO,MAAM,oBAAoB,gGAAgG,CAAA;AAEjI;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,kLAAkL,CAAA"}
+{"version":3,"file":"looks.d.ts","sourceRoot":"","sources":["../src/looks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,2MAA2M,CAAA;AAEzO,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,kDAAkD,CAAA;AAEjF,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,iKAAiK,CAAA;AAEpM,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,4DAA4D,CAAA;AAEjG,kJAAkJ;AAClJ,eAAO,MAAM,kBAAkB;;;CAGrB,CAAA;AAEV,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,uJAAuJ,CAAA;AAEvL,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,qEAAqE,CAAA;AAE1G,iGAAiG;AACjG,eAAO,MAAM,kBAAkB,wDAAwD,CAAA;AAEvF,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,0FAA0F,CAAA;AAExH,qHAAqH;AACrH,eAAO,MAAM,oBAAoB,wEAAwE,CAAA;AAEzG,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,8EAA8E,CAAA;AAE7G,4IAA4I;AAE5I,eAAO,MAAM,mBAAmB,iCAAiC,CAAA;AACjE,eAAO,MAAM,wBAAwB,gDAAgD,CAAA;AAErF,2FAA2F;AAC3F,eAAO,MAAM,qBAAqB,kEAAkE,CAAA;AAEpG,2IAA2I;AAC3I,eAAO,MAAM,oBAAoB,gGAAgG,CAAA;AAEjI;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,kLAAkL,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.57.4",
+  "version": "0.59.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.57.4",
-    "exports": 130,
-    "typeExports": 134,
+    "packageVersion": "0.59.0",
+    "exports": 133,
+    "typeExports": 140,
     "files": null
   },
   "storybook": {
@@ -3152,10 +3152,9 @@
       "docPage": "src/Kbd.mdx",
       "app": null,
       "looks": [
-        "whitespace-nowrap rounded-sm border border-border-strong bg-bg-inset font-sans text-caption text-text-secondary signal:border-b-2 signal:bg-bg-wash signal:font-mono signal:text-small ship:border-b-2 ship:bg-bg-wash ship:font-mono ship:text-small leaf:font-mono leaf:text-small",
-        "whitespace-nowrap rounded-sm border border-border-strong bg-bg-inset font-sans text-caption text-text-secondary signal:border-b-2 signal:bg-bg-wash signal:font-mono signal:text-small ship:border-b-2 ship:bg-bg-wash ship:font-mono ship:text-small leaf:font-mono leaf:text-small border-border-tooltip-key bg-bg-tooltip-key text-text-tooltip-key signal:bg-bg-tooltip-key ship:bg-bg-tooltip-key",
-        "whitespace-nowrap rounded-sm border border-border-strong bg-bg-inset font-sans text-caption text-text-secondary",
-        "signal:border-b-2 signal:bg-bg-wash signal:font-mono signal:text-small",
+        "whitespace-nowrap rounded-sm border border-border-strong bg-bg-inset font-sans text-caption text-text-secondary signal:font-mono signal:text-small signal:border-b-2 signal:bg-bg-wash ship:border-b-2 ship:bg-bg-wash ship:font-mono ship:text-small leaf:font-mono leaf:text-small",
+        "whitespace-nowrap rounded-sm border border-border-strong bg-bg-inset font-sans text-caption text-text-secondary signal:font-mono signal:text-small signal:border-b-2 signal:bg-bg-wash ship:border-b-2 ship:bg-bg-wash ship:font-mono ship:text-small leaf:font-mono leaf:text-small border-border-tooltip-key bg-bg-tooltip-key text-text-tooltip-key signal:bg-bg-tooltip-key ship:bg-bg-tooltip-key",
+        "whitespace-nowrap rounded-sm border border-border-strong bg-bg-inset font-sans",
         "ship:border-b-2 ship:bg-bg-wash ship:font-mono ship:text-small",
         "border-border-tooltip-key bg-bg-tooltip-key text-text-tooltip-key signal:bg-bg-tooltip-key ship:bg-bg-tooltip-key"
       ]
@@ -3406,6 +3405,149 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "MembersDialog",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/MembersDialog.tsx",
+      "purpose": "Who is in this, with joining, leaving and adding people — the list a MembersPill opens.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "members",
+          "takes": "MembersDialogMember[]",
+          "required": true,
+          "note": "The roster, in the order to draw it. The viewer's own row is the caller's to name (\"You\")."
+        },
+        {
+          "name": "count",
+          "takes": "number",
+          "required": false,
+          "note": "The number in the title's chip. Defaults to how many rows there are."
+        },
+        {
+          "name": "self",
+          "takes": "a handler",
+          "required": false,
+          "note": "The viewer's own row on top: \"Join\" when they are not in, \"Leave\" when they are."
+        },
+        {
+          "name": "candidates",
+          "takes": "MembersDialogCandidate[]",
+          "required": false,
+          "note": "Who \"Add members\" may offer. Members are left out by id."
+        },
+        {
+          "name": "onAdd",
+          "takes": "a handler",
+          "required": false,
+          "note": "Adds the people chosen. With it, the \"Add members\" row shows and opens the add layer."
+        },
+        {
+          "name": "note",
+          "takes": "anything",
+          "required": false,
+          "note": "One line under the roster — what membership does and does not cover."
+        },
+        {
+          "name": "initialView",
+          "takes": "list | add",
+          "required": false,
+          "note": "`add` opens straight on the add layer."
+        },
+        {
+          "name": "onClose",
+          "takes": "a handler",
+          "required": true,
+          "note": null
+        }
+      ],
+      "variants": [
+        {
+          "prop": "initialView",
+          "values": [
+            "list",
+            "add"
+          ]
+        }
+      ],
+      "ownsBehaviours": [
+        {
+          "id": "portal",
+          "behaviour": "Floats on top of the page"
+        },
+        {
+          "id": "press-outside",
+          "behaviour": "Closes on a press outside"
+        },
+        {
+          "id": "page-keys",
+          "behaviour": "Takes its keys by itself"
+        },
+        {
+          "id": "focus",
+          "behaviour": "Holds focus inside while open, and gives it back"
+        },
+        {
+          "id": "scroll-lock",
+          "behaviour": "Stops the page behind it scrolling"
+        }
+      ],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-membersdialog--docs",
+      "storyId": "primitives-membersdialog--member",
+      "docPage": "src/MembersDialog.mdx",
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "MembersPill",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/MembersPill.tsx",
+      "purpose": "Who is in this: up to three faces and the total, in a small outlined pill that opens the full list.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "members",
+          "takes": "AvatarGroupMember[]",
+          "required": true,
+          "note": "Who is in it, in order. Up to three faces are drawn."
+        },
+        {
+          "name": "count",
+          "takes": "number",
+          "required": false,
+          "note": "The number beside the faces. Defaults to how many members there are."
+        },
+        {
+          "name": "onClick",
+          "takes": "a handler",
+          "required": false,
+          "note": "Opens the list — usually a `MembersDialog`."
+        },
+        {
+          "name": "className",
+          "takes": "text",
+          "required": false,
+          "note": null
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-memberspill--docs",
+      "storyId": "primitives-memberspill--two-members",
+      "docPage": "src/MembersPill.mdx",
+      "app": null,
+      "looks": [
+        "text-caption text-text-secondary signal:font-mono signal:text-small signal:tabular-nums"
+      ]
+    },
     {
       "name": "Menu",
       "repo": "estiva-ui",
@@ -4969,7 +5111,7 @@
           "name": "icon",
           "takes": "anything",
           "required": true,
-          "note": "At each row's start: a 16px icon."
+          "note": "At each row's start: a 16px icon — unless the row brings its own (`CaptionedItem.icon`)."
         }
       ],
       "variants": [],
@@ -5278,6 +5420,12 @@
           "required": false,
           "note": "Beside the title and always visible, before the actions — a count."
         },
+        {
+          "name": "count",
+          "takes": "number",
+          "required": false,
+          "note": "How many there are, 8px after the title — not at the row's end, where `trailing` goes (Katerina, 7 October: a heading over a list says its count beside its name, as a tab does)."
+        },
         {
           "name": "actions",
           "takes": "SectionAction[]",
@@ -5362,6 +5510,7 @@
         "opacity-0 transition-[opacity,transform] duration-150 group-hover:opacity-100",
         "opacity-0 transition-[opacity,transform] duration-150 group-hover:opacity-100 rotate-90",
         "transition-transform duration-150 text-text-secondary rotate-90",
+        "font-mono text-caption tabular-nums text-text-muted",
         "rounded-lg transition-colors text-text-secondary hover:text-text-primary",
         "rounded-lg transition-colors text-text-secondary hover:text-text-primary hover:bg-bg-hover",
         "opacity-0 transition-opacity group-hover:opacity-100 [@media(hover:none)]:opacity-100"
@@ -5646,6 +5795,61 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "ShowMore",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui",
+      "sourceFile": "src/ShowMore.tsx",
+      "purpose": "Long content cut at a height behind a fade, with \"Show more\" under it.",
+      "purposeFrom": "page",
+      "props": [
+        {
+          "name": "children",
+          "takes": "anything",
+          "required": true,
+          "note": null
+        },
+        {
+          "name": "maxHeight",
+          "takes": "number",
+          "required": false,
+          "note": "The height to cut at, in px. Default 96: about seven lines of caption text."
+        },
+        {
+          "name": "surface",
+          "takes": "surface | inset",
+          "required": false,
+          "note": "What the content sits on, for the fade to end in: a panel's `surface` (default), or an inset card's `inset`."
+        },
+        {
+          "name": "className",
+          "takes": "text",
+          "required": false,
+          "note": null
+        }
+      ],
+      "variants": [
+        {
+          "prop": "surface",
+          "values": [
+            "surface",
+            "inset"
+          ]
+        }
+      ],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "layout-showmore--docs",
+      "storyId": "layout-showmore--long",
+      "docPage": "src/ShowMore.mdx",
+      "app": null,
+      "looks": [
+        "pointer-events-none bg-gradient-to-t to-transparent from-bg-surface",
+        "pointer-events-none bg-gradient-to-t to-transparent from-bg-inset"
+      ]
+    },
     {
       "name": "Sidebar",
       "repo": "estiva-ui",

package/src/CommandPalette.tsx

@@ -15,6 +15,7 @@ import { Autocomplete } from '@base-ui/react/autocomplete'
 import type { BaseUIEvent } from '@base-ui/react/types'
 import { IconLoader2, IconSearch } from '@tabler/icons-react'
 import { cn } from './cn'
+import { MONO_CAPTION_CLASSES } from './looks'
 import { Button } from './Button'
 import { Card } from './Card'
 import { InputChip } from './ChipInput'
@@ -176,7 +177,7 @@ type Key = [key: string, word: string]
 function Footer({ keys }: { keys: Key[] }) {
   const { where } = usePalette('The footer')
   return (
-    <div className="flex h-9 shrink-0 items-center gap-4 border-t border-border-subtle px-5 text-caption text-text-secondary signal:font-mono signal:text-small signal:text-text-muted leaf:font-mono leaf:text-small">
+    <div className={cn('flex h-9 shrink-0 items-center gap-4 border-t border-border-subtle px-5', MONO_CAPTION_CLASSES, 'signal:text-text-muted leaf:font-mono leaf:text-small')}>
       <span className="min-w-0 flex-1 truncate">{where}</span>
       {keys.map(([key, word]) => (
         <span key={key} className="flex shrink-0 items-center gap-1.5">

package/src/ComposerTriggers.mdx

@@ -92,6 +92,13 @@ 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.
+
+<Canvas of={ComposerTriggersStories.ReferencesOfSeveralKinds} />
+
 - **An app's own node name:** `CaptionedReference.extend({ name: 'yourName' })`
   and `ReferenceTrigger.configure({ nodeName: 'yourName' })`. The chip's HTML
   attribute follows the name (`data-your-name`).

package/src/ComposerTriggers.stories.tsx

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
-import { IconSquareRounded } from '@tabler/icons-react'
+import { IconCircle, IconSquareRounded, IconTriangle } from '@tabler/icons-react'
 import { EditorContent, useEditor } from '@tiptap/react'
 import StarterKit from '@tiptap/starter-kit'
 import { richTextClassName } from './RichText'
@@ -59,6 +59,35 @@ const SECTIONS = (query: string): ReferenceSection[] => [
   { label: 'Group two', items: matching(DESCRIBED, query) },
 ]
 
+/* Three kinds of thing in one list, each row with its own icon, and the chip it inserts wearing the same. */
+const KIND_ICONS = { circle: IconCircle, triangle: IconTriangle, square: IconSquareRounded } as const
+type Kind = keyof typeof KIND_ICONS
+const kindOf = (uri: string | null): Kind | undefined => (Object.keys(KIND_ICONS) as Kind[]).find((kind) => uri?.includes(kind))
+const KINDS = (query: string): ReferenceSection[] => [
+  {
+    label: 'Items',
+    items: matching(
+      (['circle', 'triangle', 'square'] as const).map((kind, i) => {
+        const Icon = KIND_ICONS[kind]
+        return {
+          id: `kind-${kind}`,
+          label: `Item ${['one', 'two', 'three'][i]}`,
+          snippet: '',
+          uri: `nostr:${kind}`,
+          icon: <Icon size={16} stroke={1.5} className="text-text-secondary" />,
+        }
+      }),
+      query,
+    ),
+  },
+]
+const kindIcon = (uri: string | null) => {
+  const kind = kindOf(uri)
+  if (!kind) return undefined
+  const Icon = KIND_ICONS[kind]
+  return <Icon size={14} stroke={1.5} />
+}
+
 const INSERT: SlashSection = {
   label: 'Insert',
   commands: [
@@ -67,13 +96,13 @@ const INSERT: SlashSection = {
   ],
 }
 
-function Composer({ code, sections }: { code: 'inline' | 'block'; sections?: typeof SECTIONS }) {
+function Composer({ code, sections, kinds = false }: { code: 'inline' | 'block'; sections?: typeof SECTIONS; kinds?: boolean }) {
   const editor = useEditor({
     extensions: [
       StarterKit,
       PersonMention.configure({ people: () => PEOPLE }),
       UrgentPersonMention.configure({ people: () => PEOPLE }),
-      CaptionedReference.configure({ icon: <IconSquareRounded size={14} stroke={1.5} /> }),
+      CaptionedReference.configure({ icon: <IconSquareRounded size={14} stroke={1.5} />, iconFor: kinds ? kindIcon : undefined }),
       ReferenceTrigger.configure({
         items: () => ITEMS,
         sections,
@@ -83,7 +112,9 @@ function Composer({ code, sections }: { code: 'inline' | 'block'; sections?: typ
       }),
       SlashCommands.configure({ sections: [formatSection(code), INSERT] }),
     ],
-    content: '<p>Type @, !@, [ or / after a space: </p>',
+    content: kinds
+      ? '<p>Picked from [: <span data-captioned-reference="true" data-id="kind-circle" data-label="Item one" data-snippet="" data-uri="nostr:circle"></span> and <span data-captioned-reference="true" data-id="kind-triangle" data-label="Item two" data-snippet="" data-uri="nostr:triangle"></span>. Type [ for more: </p>'
+      : '<p>Type @, !@, [ or / after a space: </p>',
     editorProps: { attributes: { class: richTextClassName('default', 'min-h-[80px] w-[480px] rounded-md border border-border-default p-3 outline-none') } },
   })
   return <EditorContent editor={editor} />
@@ -97,3 +128,11 @@ export const CodeAsABlock: Story = { render: () => <Composer code="block" /> }
 
 /** `[` with the app's own groups, each headed, a row with a second line. */
 export const ReferencesInSections: Story = { render: () => <Composer code="inline" sections={SECTIONS} /> }
+
+/**
+ * `[` offering several kinds of thing: each row brings its own icon
+ * (`CaptionedItem.icon`), and the chip it inserts wears the same one, from its
+ * `uri` (`iconFor`). A row with no icon, or a chip `iconFor` cannot name, keeps
+ * the list's and the chip's one icon.
+ */
+export const ReferencesOfSeveralKinds: Story = { render: () => <Composer code="inline" sections={KINDS} kinds /> }

package/src/ComposerTriggers.test.tsx

@@ -206,6 +206,39 @@ describe('[', () => {
     expect(listeners.size).toBe(0)
   })
 
+  it('draws a row’s own icon in place of the list’s, and the chip its `iconFor` answer (7 October)', async () => {
+    const own = [
+      { id: 'a'.repeat(64), label: 'Plan', snippet: '', uri: 'nostr:naddr1plan', icon: <svg data-icon="row-own" /> },
+      { id: 'b'.repeat(64), label: 'Note', snippet: '', uri: 'nostr:naddr1note' },
+    ]
+    function Kinds() {
+      const made = useEditor({
+        extensions: [
+          StarterKit,
+          CaptionedReference.extend({ name: 'messageMention' }).configure({
+            icon: <svg data-icon="chip-default" />,
+            iconFor: (uri) => (uri === 'nostr:naddr1plan' ? <svg data-icon="chip-own" /> : undefined),
+          }),
+          ReferenceTrigger.configure({ items: () => own, nodeName: 'messageMention', ariaLabel: 'Things', sectionLabel: 'Things', icon: <svg data-icon="list" /> }),
+        ],
+      })
+      editor = made
+      return <EditorContent editor={made} />
+    }
+    render(<Kinds />)
+    await type('[')
+    const rows = within(screen.getByRole('listbox')).getAllByRole('option')
+    expect(rows[0].querySelector('[data-icon="row-own"]')).not.toBeNull()
+    expect(rows[1].querySelector('[data-icon="list"]')).not.toBeNull()
+    await press('Enter')
+    await type('[')
+    await press('ArrowDown')
+    await press('Enter')
+    const chips = document.querySelectorAll('[data-node-view-wrapper]')
+    expect(chips[0].querySelector('[data-icon="chip-own"]')).not.toBeNull()
+    expect(chips[1].querySelector('[data-icon="chip-default"]')).not.toBeNull()
+  })
+
   it('matches who said it, or the text it searches', () => {
     expect(filterReferences(ITEMS, 'bea').map((item) => item.id)).toEqual([ITEMS[7].id])
     expect(filterReferences(ITEMS, '**line** 3').map((item) => item.id)).toEqual([ITEMS[3].id])

package/src/ComposerTriggers.tsx

@@ -229,6 +229,12 @@ export interface CaptionedItem {
   search?: string
   /** The row's second line, e.g. where the thing sits. The chip does not wear it. */
   description?: string
+  /**
+   * This row's own 16px icon, in place of the list's `icon`: what the thing is,
+   * when the list holds several kinds — a topic, a project, a message
+   * (Katerina, 7 October). Absent, the list's icon.
+   */
+  icon?: ReactNode
 }
 
 /** One labelled group of `[`'s rows, in the order the list draws them. */
@@ -256,6 +262,12 @@ const captionOf = (label: string, snippet: string) => (snippet ? `${label}: ${sn
 export interface CaptionedReferenceOptions {
   /** Drawn before the caption: a 14px icon. */
   icon: ReactNode
+  /**
+   * The chip's 14px icon from what it points at — its `uri` — when chips name
+   * several kinds of thing; `undefined` from it, or no `iconFor`, draws `icon`.
+   * The same answer the list's row gave (Katerina, 7 October).
+   */
+  iconFor?: (uri: string | null) => ReactNode | undefined
 }
 
 /**
@@ -270,7 +282,7 @@ export const CaptionedReference = Mention.extend<MentionOptions & CaptionedRefer
   inline: true,
   atom: true,
   addOptions() {
-    return { ...this.parent!(), HTMLAttributes: {}, icon: null, suggestion: { char: '\0', items: () => [] } }
+    return { ...this.parent!(), HTMLAttributes: {}, icon: null, iconFor: undefined, suggestion: { char: '\0', items: () => [] } }
   },
   addAttributes() {
     return {
@@ -291,11 +303,11 @@ export const CaptionedReference = Mention.extend<MentionOptions & CaptionedRefer
     return [{ tag: `span[data-${this.name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}]` }]
   },
   addNodeView() {
-    const icon = this.options.icon
+    const { icon, iconFor } = this.options
     return ReactNodeViewRenderer(
       ({ node }: ReactNodeViewProps) => (
         <NodeViewWrapper as="span" className={inlineChipClassName('neutral', 'max-w-[24ch] cursor-default')}>
-          <span className="flex items-center justify-center w-4 h-4 shrink-0 text-text-secondary">{icon}</span>
+          <span className="flex items-center justify-center w-4 h-4 shrink-0 text-text-secondary">{iconFor?.(node.attrs.uri ?? null) ?? icon}</span>
           <span className="truncate">{captionOf(node.attrs.label, node.attrs.snippet)}</span>
         </NodeViewWrapper>
       ),
@@ -309,7 +321,7 @@ export interface ReferenceMenuOptions {
   ariaLabel: string
   /** The section's heading. */
   sectionLabel: string
-  /** At each row's start: a 16px icon. */
+  /** At each row's start: a 16px icon — unless the row brings its own (`CaptionedItem.icon`). */
   icon: ReactNode
 }
 
@@ -337,7 +349,7 @@ export function referenceMenu({ ariaLabel, sectionLabel, icon }: ReferenceMenuOp
       return groups
     },
     itemKey: (item) => `reference-${item.id}`,
-    row: (item) => ({ leading: icon, label: captionOf(item.label, item.snippet), description: item.description, hint: <EnterHint /> }),
+    row: (item) => ({ leading: item.icon ?? icon, label: captionOf(item.label, item.snippet), description: item.description, hint: <EnterHint /> }),
   }
 }
 

package/src/ContainerHeader.mdx

@@ -66,7 +66,7 @@ It does these by itself. Write none of them around it.
 
 | It does | So you never write | Refused when written by hand |
 |---|---|---|
-| Draws the column's bar: 48px tall, the title 20px in at 14px medium, the actions 16px from the right, a hairline under it | a row of your own with padding and a border |  |
+| Draws the column's bar: 48px tall, the title 16px in at 14px medium, the actions 16px from the right, a hairline under it | a row of your own with padding and a border |  |
 | Keeps its 48px in a scrolling column | `shrink-0` |  |
 
 ## Props

package/src/ContainerHeader.tsx

@@ -43,11 +43,12 @@ export function ContainerHeader({ title, chevron = false, titleMenu, actions, cl
     </div>
   )
   return (
+    // The title 16px in, where the column's content starts (Katerina, 7 October; it was 20px).
     // With a title menu the bar gives the button 6px of its left padding
-    // (pl-3.5 + the button's px-1.5 = pl-5): the words stay where a title's
+    // (pl-2.5 + the button's px-1.5 = pl-4): the words stay where a title's
     // are, and the fill is inside the bar — a negative margin had it clipped
     // (Katerina, 5 October).
-    <div className={cn('flex h-12 shrink-0 items-center justify-between overflow-hidden border-b border-border-subtle py-2 pr-4', titleMenu != null ? 'pl-3.5' : 'pl-5', className)}>
+    <div className={cn('flex h-12 shrink-0 items-center justify-between overflow-hidden border-b border-border-subtle py-2 pr-4', titleMenu != null ? 'pl-2.5' : 'pl-4', className)}>
       <div className={cn('flex items-center gap-2 overflow-hidden', text ? 'shrink-0' : 'min-w-0 flex-1')}>
         {titleMenu != null ? (
           <Menu

package/src/DialogShell.tsx

@@ -118,7 +118,9 @@ export function DialogShell({ title, onClose, headerContent, footer, children, b
             {/* Header: the package's one header bar, with the dialog's own title in it (UIG-22).
                 The title keeps to its one line and ends in "…": a long name wrapped to
                 two lines in the 48px bar and lost its top (Katerina, 1 October). */}
+            {/* `pl-5`: a dialog's title stays 20px in, over its body and footer, which are. */}
             <ContainerHeader
+              className="pl-5"
               title={
                 headerContent ?? (
                   <Parts.Title className="block truncate text-h4 text-text-primary" render={<span />}>

package/src/Kbd.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react'
 import { cn } from './cn'
+import { MONO_CAPTION_CLASSES } from './looks'
 
 /**
  * A keyboard hint — the small chip that names the key which does the same thing.
@@ -36,8 +37,9 @@ export function Kbd({ children, className, tone = 'default' }: KbdProps) {
   return (
     <kbd
       className={cn(
-        'inline-flex shrink-0 items-center justify-center whitespace-nowrap rounded-sm border border-border-strong bg-bg-inset px-1 py-px font-sans text-caption text-text-secondary',
-        'signal:border-b-2 signal:pt-[2px] signal:pb-px signal:bg-bg-wash signal:font-mono signal:text-small',
+        'inline-flex shrink-0 items-center justify-center whitespace-nowrap rounded-sm border border-border-strong bg-bg-inset px-1 py-px font-sans',
+        MONO_CAPTION_CLASSES,
+        'signal:border-b-2 signal:pt-[2px] signal:pb-px signal:bg-bg-wash',
         'ship:border-b-2 ship:pt-[2px] ship:pb-px ship:bg-bg-wash ship:font-mono ship:text-small',
         // Leaf sets its keys in mono, as Signal does (Katerina, 28 September): the type, not the key's shape.
         'leaf:font-mono leaf:text-small',

package/src/ListColumn.mdx

@@ -60,7 +60,7 @@ import { ListColumn, Toolbar, ToolbarButton } from '@estiva-app/ui'
 - It sits beside the page's main area, inside AppShell's card: put both in a
   flex row, the main area `flex-1`.
 - The numbers: 290px wide, a 1px line on the right. The header is
-  ContainerHeader's: 48px, the title 20px in. The list starts 16px under the
+  ContainerHeader's: 48px, the title 16px in. The list starts 16px under the
   header and ends 12px above the bottom, and its rows sit 12px in from each
   side.
 - The rows are yours. It scrolls them, so a list that grows with its data is

package/src/MembersDialog.mdx

@@ -0,0 +1,69 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as MembersDialogStories from './MembersDialog.stories'
+
+<Meta of={MembersDialogStories} />
+
+# MembersDialog
+
+Who is in this, with joining, leaving and adding people — the list a
+**MembersPill** opens.
+
+<Canvas of={MembersDialogStories.Member} />
+
+## When
+
+- The full roster behind a **MembersPill**: everyone in it, the viewer's own
+  Join or Leave, and "Add members" to bring somebody in.
+
+## When not
+
+- A glance at who is in it → **MembersPill** or **AvatarGroup**.
+- Picking people for something that is not membership → **ChipInput** in your own **DialogShell**.
+
+## How
+
+```tsx
+import { MembersDialog } from '@estiva-app/ui'
+
+const roster: { id: string; name: string; picture?: string; caption?: string }[] = []
+const directory: { id: string; label: string; picture?: string }[] = []
+const [open, setOpen] = useState(false)
+
+{open && (
+  <MembersDialog
+    members={roster}
+    self={{ action: 'join', onToggle: () => {} }}
+    candidates={directory}
+    onAdd={(chosen) => {}}
+    onClose={() => setOpen(false)}
+  />
+)}
+```
+
+- A row is `{ id, name, picture?, caption? }`. The caption is the second
+  line: a role, a relation such as "Assignee", or a state. Name the viewer's
+  own row "You".
+- `self` puts **Join** or **Leave** on top. Leave it out while membership is
+  still being read: no row is better than a wrong one. The row waits while
+  `onToggle`'s promise runs.
+- `onAdd` shows **Add members**, which opens the add layer: an "Invite people"
+  **ChipInput** over `candidates`, leaving out anyone already a member by id.
+  Return `false` to stay on the layer; otherwise it returns to the roster.
+- `count` is the number in the title when it differs from the rows — a row
+  for somebody who left but still holds a role, say.
+- `note` is one line under the roster, for what membership does not cover.
+
+## What it owns
+
+It does these by itself, on top of what **DialogShell** and **ChipInput** own.
+What a join, a leave or an add does is yours.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Goes between the roster and the add layer, and back after an add | a view state, or a second dialog |  |
+| Waits on the Join or Leave row while `onToggle` runs, so one press is one change | a busy flag around it |  |
+| Leaves current members out of the picker | a filter over your directory |  |
+
+## Props
+
+<Controls of={MembersDialogStories.Member} />