@estiva-app/ui 0.51.0 → 0.53.0

package/dist/suggestionPopup.d.ts

@@ -22,6 +22,15 @@ export interface SuggestionPopupOptions<T> {
     sections?: (items: T[], query: string) => readonly SuggestionMenuSection<T>[];
     itemKey: (item: T) => string;
     row: (item: T) => SuggestionMenuRow;
+    /**
+     * With `refresh`: called with a listener while the list is open; the app
+     * calls it when its data has changed (a search landing), and the open list is
+     * drawn again for the same query. Returns the unsubscribe, run when the list
+     * closes however it closes.
+     */
+    subscribe?: (listener: () => void) => () => void;
+    /** The items for a query, as the plugin's `items` answers — asked again when `subscribe` fires. */
+    refresh?: (query: string) => T[];
 }
 /**
  * The `render` of a Tiptap suggestion plugin, drawn as a `SuggestionMenu` —

package/dist/suggestionPopup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"suggestionPopup.d.ts","sourceRoot":"","sources":["../src/suggestionPopup.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAA0B,iBAAiB,EAAmB,MAAM,oBAAoB,CAAA;AACpG,OAAO,EAA6C,KAAK,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAchI;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED,mFAAmF;AACnF,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAA;IACjB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAA;IACjB,yGAAyG;IACzG,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAA;IAC7E,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAA;IAC5B,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,iBAAiB,CAAA;CACpC;AA0BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAgClH"}
+{"version":3,"file":"suggestionPopup.d.ts","sourceRoot":"","sources":["../src/suggestionPopup.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAA0B,iBAAiB,EAAmB,MAAM,oBAAoB,CAAA;AACpG,OAAO,EAA6C,KAAK,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAchI;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED,mFAAmF;AACnF,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAA;IACjB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAA;IACjB,yGAAyG;IACzG,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAA;IAC7E,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAA;IAC5B,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,iBAAiB,CAAA;IACnC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAA;IAChD,mGAAmG;IACnG,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,EAAE,CAAA;CACjC;AA0BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAmDlH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",
@@ -88,6 +88,7 @@
     "eslint-plugin-better-tailwindcss": "^4.7.0",
     "typescript-eslint": "^8.0.0",
     "@tiptap/core": "^3.22.1",
+    "@tiptap/extension-mention": "^3.22.1",
     "@tiptap/pm": "^3.22.1",
     "@tiptap/react": "^3.22.1",
     "@tiptap/suggestion": "^3.22.1"
@@ -105,6 +106,9 @@
     "@tiptap/core": {
       "optional": true
     },
+    "@tiptap/extension-mention": {
+      "optional": true
+    },
     "@tiptap/pm": {
       "optional": true
     },
@@ -126,6 +130,7 @@
     "@testing-library/react": "^16.3.3",
     "@testing-library/user-event": "^14.6.7",
     "@tiptap/core": "^3.31.3",
+    "@tiptap/extension-mention": "^3.31.3",
     "@tiptap/pm": "^3.31.3",
     "@tiptap/react": "^3.31.3",
     "@tiptap/starter-kit": "^3.31.3",

package/registry.json

@@ -4,9 +4,9 @@
     "kind": "package",
     "repo": "estiva-ui",
     "package": "@estiva-app/ui",
-    "packageVersion": "0.51.0",
-    "exports": 105,
-    "typeExports": 116,
+    "packageVersion": "0.53.0",
+    "exports": 120,
+    "typeExports": 128,
     "files": null
   },
   "storybook": {
@@ -15,6 +15,25 @@
     "devUrl": "http://localhost:6008"
   },
   "entries": [
+    {
+      "name": "applyFormat",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposerTriggers.tsx",
+      "purpose": "Apply one format to the current block. `set*` wherever Tiptap has one: choosing Heading should make a heading, not turn one off.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composertriggers--docs",
+      "storyId": "primitives-composertriggers--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "AppShell",
       "repo": "estiva-ui",
@@ -583,6 +602,25 @@
         "signal:bg-transparent signal:border signal:border-border-default signal:text-text-primary signal:shadow-none signal:hover:bg-success-muted signal:hover:border-success-outline signal:hover:text-success-default signal:transition-colors"
       ]
     },
+    {
+      "name": "CaptionedReference",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposerTriggers.tsx",
+      "purpose": "A reference mid-sentence, drawn as `label: snippet` and written as its `uri` verbatim (SPEC §13.1).",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composertriggers--docs",
+      "storyId": "primitives-composertriggers--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Card",
       "repo": "estiva-ui",
@@ -2176,6 +2214,63 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "filterPeople",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposerTriggers.tsx",
+      "purpose": "The people whose name holds the query, the first {@link PEOPLE_LIMIT} of them.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composertriggers--docs",
+      "storyId": "primitives-composertriggers--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "filterReferences",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposerTriggers.tsx",
+      "purpose": "The references whose label or text holds the query — the last {@link REFERENCE_LIMIT}, in the order given: a thread is unbounded, and a list that grew with it would be a hundred rows of prose.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composertriggers--docs",
+      "storyId": "primitives-composertriggers--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "filterSlashSections",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposerTriggers.tsx",
+      "purpose": "The sections narrowed to a query — the text typed after the `/`.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composertriggers--docs",
+      "storyId": "primitives-composertriggers--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Form",
       "repo": "estiva-ui",
@@ -2239,6 +2334,44 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "FORMATS",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposerTriggers.tsx",
+      "purpose": "The formats `/` offers, in order. The hint is what you would type, not a key chord.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composertriggers--docs",
+      "storyId": "primitives-composertriggers--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "formatSection",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposerTriggers.tsx",
+      "purpose": "The Format section every app's `/` opens with.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composertriggers--docs",
+      "storyId": "primitives-composertriggers--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "hueFor",
       "repo": "estiva-ui",
@@ -3725,6 +3858,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "peopleMenu",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposerTriggers.tsx",
+      "purpose": "The people list `@` and `!@` open: the face, the name, the second line, and the Enter hint while highlighted — `MenuItem` at its tall size.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composertriggers--docs",
+      "storyId": "primitives-composertriggers--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "Person",
       "repo": "estiva-ui",
@@ -3775,6 +3927,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "PersonMention",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposerTriggers.tsx",
+      "purpose": "`@` — a person, as a chip that writes their key (SPEC §13.1).",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composertriggers--docs",
+      "storyId": "primitives-composertriggers--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "PersonTrigger",
       "repo": "estiva-ui",
@@ -4410,6 +4581,44 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "referenceMenu",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposerTriggers.tsx",
+      "purpose": "The list `[` opens: `label: snippet` rows, the same box as the people list.",
+      "purposeFrom": "comment",
+      "props": [
+        {
+          "name": "ariaLabel",
+          "takes": "text",
+          "required": true,
+          "note": "Names the list, e.g. what can be referenced."
+        },
+        {
+          "name": "sectionLabel",
+          "takes": "text",
+          "required": true,
+          "note": "The section's heading."
+        },
+        {
+          "name": "icon",
+          "takes": "anything",
+          "required": true,
+          "note": "At each row's start: a 16px icon."
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composertriggers--docs",
+      "storyId": "primitives-composertriggers--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "ReferenceNode",
       "repo": "estiva-ui",
@@ -4429,6 +4638,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "ReferenceTrigger",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposerTriggers.tsx",
+      "purpose": "`[` — reference something, inserted as a {@link CaptionedReference} chip.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composertriggers--docs",
+      "storyId": "primitives-composertriggers--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "RichText",
       "repo": "estiva-ui",
@@ -5168,6 +5396,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "SlashCommands",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposerTriggers.tsx",
+      "purpose": "`/` — format the line or insert something, at the caret, mid-sentence too.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composertriggers--docs",
+      "storyId": "primitives-composertriggers--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "SuggestionMenu",
       "repo": "estiva-ui",
@@ -5321,6 +5568,18 @@
           "takes": "a handler",
           "required": true,
           "note": null
+        },
+        {
+          "name": "subscribe",
+          "takes": "a handler",
+          "required": false,
+          "note": "With `refresh`: called with a listener while the list is open; the app calls it when its data has changed (a search landing), and the open list is drawn again for the same query."
+        },
+        {
+          "name": "refresh",
+          "takes": "a handler",
+          "required": false,
+          "note": "The items for a query, as the plugin's `items` answers — asked again when `subscribe` fires."
         }
       ],
       "variants": [],
@@ -6175,6 +6434,25 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "typeTrigger",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposerTriggers.tsx",
+      "purpose": "A row that types another trigger, so its own list opens — `@` from `/`.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composertriggers--docs",
+      "storyId": "primitives-composertriggers--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "UnknownBlock",
       "repo": "estiva-ui",
@@ -6194,6 +6472,51 @@
       "app": null,
       "looks": []
     },
+    {
+      "name": "UrgentPersonMention",
+      "repo": "estiva-ui",
+      "kind": "component",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposerTriggers.tsx",
+      "purpose": "`!@` — a person, urgently: the same chip in the urgent tone.",
+      "purposeFrom": "comment",
+      "props": [],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composertriggers--docs",
+      "storyId": "primitives-composertriggers--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
+    {
+      "name": "urgentPubkeys",
+      "repo": "estiva-ui",
+      "kind": "helper",
+      "importPath": "@estiva-app/ui/editor",
+      "sourceFile": "src/ComposerTriggers.tsx",
+      "purpose": "The keys the document's urgent mentions name — what the write turns into `[\"urgent\", <pubkey>]` tags.",
+      "purposeFrom": "comment",
+      "props": [
+        {
+          "name": "state",
+          "takes": "{ doc: Doc }",
+          "required": true,
+          "note": null
+        }
+      ],
+      "variants": [],
+      "ownsBehaviours": [],
+      "status": "stable",
+      "migrationStage": null,
+      "docsId": "primitives-composertriggers--docs",
+      "storyId": "primitives-composertriggers--default",
+      "docPage": null,
+      "app": null,
+      "looks": []
+    },
     {
       "name": "useToast",
       "repo": "estiva-ui",

package/src/ComposerTriggers.mdx

@@ -0,0 +1,115 @@
+import { Meta, Canvas } from '@storybook/addon-docs/blocks'
+import * as ComposerTriggersStories from './ComposerTriggers.stories'
+
+<Meta of={ComposerTriggersStories} />
+
+# ComposerTriggers
+
+The four keys a composer shares across apps: `@` and `!@` to mention a person,
+`[` to reference something, `/` to format the line or insert something. Each
+opens a `SuggestionMenu` at the caret; a pick inserts a chip.
+
+<Canvas of={ComposerTriggersStories.Default} />
+
+## When
+
+- **`PersonMention` and `UrgentPersonMention`** — any editor whose text names
+  people. The urgent one is the same chip in the urgent tone.
+- **`CaptionedReference` and `ReferenceTrigger`** — referencing something the
+  app can list, drawn as who wrote it and its opening words.
+- **`SlashCommands`** — `formatSection()` first, then only the rows the app can
+  perform. `formatSection('block')` makes Code a block, for an editor of a
+  block document.
+
+## When not
+
+- Formatting text already written → **SelectionToolbar**. Bold, italic and
+  underline are not in `/` for that reason.
+- A list that is not opened by a key typed in an editor → **CommandPalette** or
+  **Menu**.
+- Drawing a sent body → **RichText**. These are for editing only.
+
+## How
+
+```tsx
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { IconSquareRounded } from '@tabler/icons-react'
+import {
+  CaptionedReference,
+  PersonMention,
+  ReferenceTrigger,
+  SlashCommands,
+  UrgentPersonMention,
+  formatSection,
+  typeTrigger,
+  urgentPubkeys,
+  type CaptionedItem,
+  type MentionPerson,
+} from '@estiva-app/ui/editor'
+
+const people = (): MentionPerson[] => [{ id: 'one', name: 'Person one', pubkey: null }]
+const items = (): CaptionedItem[] => [{ id: 'one', label: 'Person one', snippet: 'Item one', uri: 'nostr:item' }]
+
+const editor = useEditor({
+  extensions: [
+    StarterKit,
+    PersonMention.configure({ people }),
+    UrgentPersonMention.configure({ people }),
+    CaptionedReference.configure({ icon: <IconSquareRounded size={14} stroke={1.5} /> }),
+    ReferenceTrigger.configure({ items, ariaLabel: 'Items', sectionLabel: 'Items', icon: <IconSquareRounded size={16} stroke={1.5} /> }),
+    SlashCommands.configure({
+      sections: [formatSection(), { label: 'Insert', commands: [{ key: 'insert-@', row: { label: 'Mention', shortcut: '@' }, run: typeTrigger('@') }] }],
+    }),
+  ],
+})
+
+const urgent = editor ? urgentPubkeys(editor) : undefined
+
+<EditorContent editor={editor} />
+```
+
+- **The body is written by `@estiva-app/conversation`, not here.** A mention
+  chip carries `pubkey` and `label` for its `mentionText`; a reference chip
+  carries the `uri` the app built with that package, written back verbatim. The
+  urgency is not in the text: hand `urgentPubkeys(editor)` to `urgentTagsFor`.
+- **The lists ask each time the query changes.** `people` and `items` are
+  functions, so they read the app's current data. `@` shows the first six
+  names holding the query; `[` the last six whose label or `search` (default:
+  `snippet`) holds it.
+- **`[` in sections, filled in as answers land:** pass `sections(query)` in
+  place of `items` — labelled groups the app has already narrowed and ordered;
+  an empty group is not drawn — and `subscribe(listener)`, which the app calls
+  when a slower answer (a search) has landed. The open list is drawn again for
+  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.
+- **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`).
+- **A row that opens another list** runs `typeTrigger('@')`: it types the key
+  once the `/query` is gone.
+- An open list is reported by `isSuggestionActive()`, so an editor that sends
+  on Enter does not send on the Enter that picked a row.
+
+<Canvas of={ComposerTriggersStories.CodeAsABlock} />
+
+## What it owns
+
+Nothing. It only draws. Clicks and keys are yours.
+
+## Keys
+
+The lists are `SuggestionMenu`s, and their keys are its own. What the body
+says, the tags it earns and sending stay the app's.
+
+
+| Key | Does |
+| --- | --- |
+| `@` after a space or at the line's start | Opens the people list |
+| `!@` | Opens the urgent list |
+| `[` | Opens the reference list |
+| `/` after a space or at the line's start | Opens Format and the app's sections |
+| ↑ ↓ | Move the highlight, wrapping at the ends |
+| Enter | Inserts the highlighted row, or runs it |
+| Escape | Closes the list |

package/src/ComposerTriggers.stories.tsx

@@ -0,0 +1,99 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconSquareRounded } from '@tabler/icons-react'
+import { EditorContent, useEditor } from '@tiptap/react'
+import StarterKit from '@tiptap/starter-kit'
+import { richTextClassName } from './RichText'
+import {
+  CaptionedReference,
+  PersonMention,
+  ReferenceTrigger,
+  SlashCommands,
+  UrgentPersonMention,
+  formatSection,
+  typeTrigger,
+  type CaptionedItem,
+  type MentionPerson,
+  type ReferenceSection,
+  type SlashSection,
+} from './ComposerTriggers'
+
+/**
+ * The four composer triggers: `@` and `!@` offer a person, `[` offers
+ * something to reference, and `/` formats the line or inserts something.
+ * Type one of them in the box.
+ */
+const meta = {
+  title: 'Primitives/ComposerTriggers',
+  parameters: { layout: 'padded' },
+} satisfies Meta
+
+export default meta
+type Story = StoryObj
+
+const PEOPLE: MentionPerson[] = ['one', 'two', 'three', 'four', 'five', 'six', 'seven'].map((n, i) => ({
+  id: `person-${n}`,
+  name: `Person ${n}`,
+  description: i % 2 === 0 ? 'Label' : undefined,
+  pubkey: null,
+}))
+
+const ITEMS: CaptionedItem[] = ['one', 'two', 'three'].map((n) => ({
+  id: `item-${n}`,
+  label: 'Person one',
+  snippet: `Item ${n}`,
+  uri: `nostr:item-${n}`,
+}))
+
+const DESCRIBED: CaptionedItem[] = ['four', 'five'].map((n) => ({
+  id: `item-${n}`,
+  label: 'Label',
+  snippet: `Item ${n}`,
+  uri: `nostr:item-${n}`,
+  description: 'Label',
+}))
+
+const matching = (items: CaptionedItem[], query: string) => items.filter((item) => item.snippet.toLowerCase().includes(query.toLowerCase()))
+
+const SECTIONS = (query: string): ReferenceSection[] => [
+  { label: 'Group one', items: matching(ITEMS, query) },
+  { label: 'Group two', items: matching(DESCRIBED, query) },
+]
+
+const INSERT: SlashSection = {
+  label: 'Insert',
+  commands: [
+    { key: 'insert-@', row: { label: 'Mention', shortcut: '@' }, keywords: ['@'], run: typeTrigger('@') },
+    { key: 'insert-[', row: { label: 'Reference', shortcut: '[' }, keywords: ['['], run: typeTrigger('[') },
+  ],
+}
+
+function Composer({ code, sections }: { code: 'inline' | 'block'; sections?: typeof SECTIONS }) {
+  const editor = useEditor({
+    extensions: [
+      StarterKit,
+      PersonMention.configure({ people: () => PEOPLE }),
+      UrgentPersonMention.configure({ people: () => PEOPLE }),
+      CaptionedReference.configure({ icon: <IconSquareRounded size={14} stroke={1.5} /> }),
+      ReferenceTrigger.configure({
+        items: () => ITEMS,
+        sections,
+        ariaLabel: 'Items',
+        sectionLabel: 'Items',
+        icon: <IconSquareRounded size={16} stroke={1.5} className="text-text-secondary" />,
+      }),
+      SlashCommands.configure({ sections: [formatSection(code), INSERT] }),
+    ],
+    content: '<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} />
+}
+
+/** Code as a mark inside the line. */
+export const Default: Story = { render: () => <Composer code="inline" /> }
+
+/** Code as a block of its own, for an editor of a block document. */
+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} /> }