@estiva-app/ui 0.51.0 → 0.52.0

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.52.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: one section of `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",
@@ -6175,6 +6422,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 +6460,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,108 @@
+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.
+- **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,79 @@
+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 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 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 }: { code: 'inline' | 'block' }) {
+  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,
+        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" /> }