@estiva-app/ui 0.58.0 → 0.59.0

package/dist/looks.d.ts

@@ -33,6 +33,8 @@ export declare const FLOATING_SURFACE_CLASSES = "rounded-lg border border-border
 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,iGAAiG;AACjG,eAAO,MAAM,kBAAkB,wDAAwD,CAAA;AAEvF,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.58.0",
+  "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.58.0",
-    "exports": 131,
-    "typeExports": 135,
+    "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": [],

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/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/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} />

package/src/MembersDialog.stories.tsx

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { MembersDialog } from './MembersDialog'
+
+const people = [
+  { id: 'ana', label: 'Ana Duarte' },
+  { id: 'ravi', label: 'Ravi Mehta' },
+  { id: 'marta', label: 'Marta Silva' },
+  { id: 'jonas', label: 'Jonas Weber' },
+]
+
+const meta = {
+  title: 'Primitives/MembersDialog',
+  component: MembersDialog,
+  args: {
+    members: [
+      { id: 'me', name: 'You', caption: 'Product designer' },
+      { id: 'ana', name: 'Ana Duarte', caption: 'Assignee' },
+    ],
+    self: { action: 'leave', onToggle: () => {} },
+    candidates: people,
+    onAdd: () => {},
+    onClose: () => {},
+  },
+} satisfies Meta<typeof MembersDialog>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** A member: Leave and "Add members" on top. */
+export const Member: Story = {}
+
+/** Not a member yet: Join on top, and nothing to add until you are in. */
+export const NotAMember: Story = {
+  args: {
+    members: [{ id: 'ana', name: 'Ana Duarte', caption: 'Assignee' }],
+    self: { action: 'join', onToggle: () => {} },
+    onAdd: undefined,
+  },
+}
+
+/** Membership still being read: no row on top rather than a wrong one. */
+export const Unknown: Story = {
+  args: { self: undefined, onAdd: undefined },
+}
+
+/** Someone who left but still holds a role, and a line about what membership covers. */
+export const WithNote: Story = {
+  args: {
+    members: [
+      { id: 'me', name: 'You' },
+      { id: 'ravi', name: 'Ravi Mehta', caption: 'Assignee · not following' },
+    ],
+    count: 1,
+    note: 'Leaving covers this page only; the items inside it still tell you about their comments.',
+  },
+}
+
+/** More rows than fit: the roster scrolls inside the dialog. */
+export const Long: Story = {
+  args: {
+    members: Array.from({ length: 14 }, (_, i) => ({ id: String(i), name: `Person ${i + 1}`, caption: i % 3 === 0 ? 'Owner' : undefined })),
+  },
+}
+
+/** Opened straight on the add layer. */
+export const AddLayer: Story = {
+  args: { initialView: 'add' },
+}

package/src/MembersDialog.test.tsx

@@ -0,0 +1,69 @@
+// @vitest-environment jsdom
+/** What the MembersDialog page claims, pinned. */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { MembersDialog } from './MembersDialog'
+import { MembersPill } from './MembersPill'
+
+afterEach(cleanup)
+
+const members = [
+  { id: 'me', name: 'You' },
+  { id: 'ana', name: 'Ana Duarte', caption: 'Assignee' },
+]
+
+describe('MembersDialog', () => {
+  it('lists every member with their caption, and counts them in the title', async () => {
+    render(<MembersDialog members={members} onClose={() => {}} />)
+    const dialog = await screen.findByRole('dialog', { name: /Members/ })
+    expect(dialog.textContent).toContain('Ana Duarte')
+    expect(dialog.textContent).toContain('Assignee')
+    expect(dialog.textContent).toContain('2')
+  })
+
+  it('offers no Join, Leave or Add when none is given', async () => {
+    render(<MembersDialog members={members} onClose={() => {}} />)
+    await screen.findByRole('dialog')
+    expect(screen.queryByRole('button', { name: /^(Join|Leave|Add members)$/ })).toBeNull()
+  })
+
+  it('says Join to a non-member and Leave to a member, and calls onToggle once', async () => {
+    const user = userEvent.setup()
+    const onToggle = vi.fn()
+    const { rerender } = render(<MembersDialog members={members} self={{ action: 'join', onToggle }} onClose={() => {}} />)
+    await user.click(await screen.findByRole('button', { name: 'Join' }))
+    expect(onToggle).toHaveBeenCalledTimes(1)
+    rerender(<MembersDialog members={members} self={{ action: 'leave', onToggle }} onClose={() => {}} />)
+    expect(await screen.findByRole('button', { name: 'Leave' })).toBeTruthy()
+  })
+
+  it('goes to the add layer and back, and Invite waits for a choice', async () => {
+    const user = userEvent.setup()
+    render(<MembersDialog members={members} candidates={[{ id: 'ravi', label: 'Ravi Mehta' }]} onAdd={() => {}} onClose={() => {}} />)
+    await user.click(await screen.findByRole('button', { name: 'Add members' }))
+    expect((await screen.findByRole('button', { name: 'Invite' })).hasAttribute('disabled')).toBe(true)
+    await user.click(screen.getByRole('button', { name: 'Back to members' }))
+    expect(await screen.findByRole('button', { name: 'Add members' })).toBeTruthy()
+  })
+
+  it('stays on the add layer when onAdd returns false', async () => {
+    const user = userEvent.setup()
+    const onAdd = vi.fn(() => false)
+    render(<MembersDialog members={members} candidates={[{ id: 'ravi', label: 'Ravi Mehta' }]} onAdd={onAdd} initialView="add" onClose={() => {}} />)
+    await user.type(await screen.findByRole('combobox'), 'Ravi')
+    await user.click(await screen.findByRole('option', { name: /Ravi Mehta/ }))
+    await user.click(screen.getByRole('button', { name: 'Invite' }))
+    expect(onAdd).toHaveBeenCalledWith([{ id: 'ravi', label: 'Ravi Mehta' }])
+    expect(screen.getByRole('button', { name: 'Invite' })).toBeTruthy()
+  })
+})
+
+describe('MembersPill', () => {
+  it('names the total, and draws nothing for none', () => {
+    const { container, rerender } = render(<MembersPill members={[{ name: 'Ana Duarte' }]} count={4} onClick={() => {}} />)
+    expect(screen.getByRole('button', { name: '4 members' })).toBeTruthy()
+    rerender(<MembersPill members={[]} />)
+    expect(container.textContent).toBe('')
+  })
+})