@estiva-app/ui 0.67.0 → 0.68.0

package/src/RichText.tsx

@@ -1,4 +1,4 @@
-import type { MouseEvent, ReactNode } from 'react'
+import { Fragment, type MouseEvent, type ReactNode } from 'react'
 import { Checkbox } from './Checkbox'
 import { cn } from './cn'
 import { Link } from './Link'
@@ -84,6 +84,13 @@ export interface RichTextProps {
    * `undefined` to leave it to the part, which draws its words.
    */
   renderBlock?: (block: RichTextBlock) => ReactNode | undefined
+  /**
+   * Draws something after a line of text: after a paragraph, a heading or a
+   * quote, and inside a list item or a table cell after its words — where a
+   * document's chip asks for its card (SPEC §13.3). Asked of every such line;
+   * return nothing for most.
+   */
+  renderAfter?: (block: RichTextBlock) => ReactNode
   /**
    * Ticks or unticks a checklist item, by its block id: its box is then a
    * control, one click where the text is read. Without it the box is a picture
@@ -186,6 +193,7 @@ interface Draw {
   renderText: (text: string) => ReactNode
   renderReference: (reference: string, run: RichTextRun) => ReactNode
   renderBlock?: (block: RichTextBlock) => ReactNode | undefined
+  renderAfter?: (block: RichTextBlock) => ReactNode
   onTick?: (blockId: string, checked: boolean) => void
 }
 
@@ -245,8 +253,14 @@ function Table({ block, draw }: { block: RichTextBlock; draw: Draw }) {
           colSpan={colspan && colspan > 1 ? colspan : undefined}
           rowSpan={rowspan && rowspan > 1 ? rowspan : undefined}
         >
-          {(cell.children ?? []).map((child, j) => <Runs key={j} runs={child.inline} draw={draw} />)}
+          {(cell.children ?? []).map((child, j) => (
+            <Fragment key={j}>
+              <Runs runs={child.inline} draw={draw} />
+              {draw.renderAfter?.(child)}
+            </Fragment>
+          ))}
           <Runs runs={cell.inline} draw={draw} />
+          {draw.renderAfter?.(cell)}
         </Cell>
       )
     })
@@ -281,6 +295,7 @@ function ListItem({ item, draw, below }: { item: RichTextBlock; draw: Draw; belo
     return (
       <li data-block-id={item.id}>
         <Runs runs={item.inline} draw={draw} />
+        {draw.renderAfter?.(item)}
         {below}
       </li>
     )
@@ -299,6 +314,7 @@ function ListItem({ item, draw, below }: { item: RichTextBlock; draw: Draw; belo
         <p>
           <Runs runs={item.inline} draw={draw} />
         </p>
+        {draw.renderAfter?.(item)}
         {below}
       </div>
     </li>
@@ -333,6 +349,20 @@ function nestItems(items: readonly RichTextBlock[]): NestedItem[] {
 function Block({ block, draw }: { block: RichTextBlock; draw: Draw }): ReactNode {
   const own = draw.renderBlock?.(block)
   if (own !== undefined) return own
+  const drawn = Drawn({ block, draw })
+  // After a line of its own words; a list and a table ask each item and cell.
+  const lineOfWords = block.type === 'paragraph' || block.type === 'heading' || block.type === 'blockquote'
+  const after = lineOfWords ? draw.renderAfter?.(block) : undefined
+  if (after === undefined || after === null || after === false) return drawn
+  return (
+    <>
+      {drawn}
+      {after}
+    </>
+  )
+}
+
+function Drawn({ block, draw }: { block: RichTextBlock; draw: Draw }): ReactNode {
   const runs = <Runs runs={block.inline} draw={draw} />
   switch (block.type) {
     case 'heading': {
@@ -401,10 +431,11 @@ export function RichText({
   renderText = (text) => text,
   renderReference = (_reference, run) => run.text,
   renderBlock,
+  renderAfter,
   onTick,
 }: RichTextProps) {
   if (blocks.length === 0) return null
-  const draw: Draw = { renderText, renderReference, renderBlock, onTick }
+  const draw: Draw = { renderText, renderReference, renderBlock, renderAfter, onTick }
   return (
     <div data-rich-text className={richTextClassName(size)}>
       {blocks.map((block, i) => <Block key={block.id ?? i} block={block} draw={draw} />)}

package/src/SelectionToolbar.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react'
 import type { Editor } from '@tiptap/react'
 import { Extension } from '@tiptap/core'
 import { Plugin, PluginKey } from '@tiptap/pm/state'
@@ -221,9 +221,16 @@ export interface SelectionToolbarProps {
   marks?: readonly MarkId[]
   /** The Link button and its address field. Needs a link mark in the editor and `KeptSelection`. Default off. */
   link?: boolean
+  /**
+   * More of the strip, after the marks: the app's own `ToolbarButton`s for what
+   * is selected — a chip's card, say. Each keeps the selection by preventing
+   * its press's default, as the marks do. Nothing is added when it renders
+   * nothing.
+   */
+  children?: ReactNode
 }
 
-export function SelectionToolbar({ editor, marks = ['bold', 'italic', 'underline'], link = false }: SelectionToolbarProps) {
+export function SelectionToolbar({ editor, marks = ['bold', 'italic', 'underline'], link = false, children }: SelectionToolbarProps) {
   /** The selection's top edge and horizontal centre; the face decides the rest. */
   const [anchor, setAnchor] = useState<{ top: number; centre: number } | null>(null)
   const [mode, setMode] = useState<Mode>('marks')
@@ -480,6 +487,7 @@ export function SelectionToolbar({ editor, marks = ['bold', 'italic', 'underline
               <IconLink size={16} stroke={1.5} />
             </ToolbarButton>
           )}
+          {children}
         </Toolbar>
       )}
     </Popover>

package/src/editor.ts

@@ -55,3 +55,16 @@ export {
   type AttachmentNodeOptions,
   type AttachmentViewProps,
 } from './BlockNodes'
+export {
+  ReferenceCards,
+  useReferenceCards,
+  referenceAtSelection,
+  referenceCardPlacements,
+  setReferenceCard,
+  setReferenceCardAt,
+  type ReferenceCard,
+  type ReferenceCardLayout,
+  type ReferenceCardSlot,
+} from './ReferenceCards'
+export { LinkChips, findLinkChips, refreshLinkChips, type LinkChipsOptions, type PastedRange } from './LinkChips'
+export { ReferenceMenu, ReferenceMenuView, isReferenceMenuOpen, referenceMenuClick, type ReferenceMenuViewProps } from './ReferenceMenu'

package/src/pages.test.ts

@@ -42,6 +42,9 @@ const HOLDS_ONLY: Record<string, string> = {
   AppProvider: 'Nothing. It draws nothing; it holds two answers for the parts below it.',
   PastedImages: 'Nothing. It draws nothing; it hands a pasted picture to the app, named.',
   CodeBlockColours: 'Nothing. It names each word of a code block; the RichText class list colours them.',
+  LinkChips: 'Nothing. It draws nothing; it turns the URLs the app recognises into chips.',
+  // Its box is the Popover's, which owns what a box does; it holds which chip the menu is on.
+  ReferenceMenu: 'Nothing. Its box is the Popover; it holds which chip the menu is open on, and its keys.',
 }
 
 const dir = new URL('.', import.meta.url)

package/src/registry/registry.test.ts

@@ -26,7 +26,7 @@ import { SCHEMA_VERSION, validateRegistry, type Registry, type RegistryEntry } f
 const root = process.cwd()
 const registry = buildRegistry({ root })
 /** Editor extensions: named like components by the catalogue, and not React components. */
-const EDITOR_EXTENSIONS = ['KeptSelection', 'BlockId', 'UnknownBlock', 'ReferenceNode', 'AttachmentNode', 'PersonMention', 'UrgentPersonMention', 'CaptionedReference', 'ReferenceTrigger', 'SlashCommands', 'PastedImages', 'CodeBlockColours', 'Checklist', 'Callout']
+const EDITOR_EXTENSIONS = ['KeptSelection', 'BlockId', 'UnknownBlock', 'ReferenceNode', 'AttachmentNode', 'PersonMention', 'UrgentPersonMention', 'CaptionedReference', 'ReferenceTrigger', 'SlashCommands', 'PastedImages', 'CodeBlockColours', 'Checklist', 'Callout', 'ReferenceCards', 'LinkChips', 'ReferenceMenu']
 const entry = (name: string): RegistryEntry => {
   const found = registry.entries.find((candidate) => candidate.name === name)
   if (!found) throw new Error(`no entry for ${name}`)
@@ -48,20 +48,20 @@ describe('the registry builds', () => {
     expect(registry.entries.map((one) => one.name).sort()).toEqual(values.map((one) => one.name).sort())
   })
 
-  it('counts 149 names over 77 files: 110 components, 38 helpers and 1 hook (NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October; CodeBlockColours, the coloured code block of the editor, on 9 October; Checklist, Callout, isChecklistTick and calloutLook (RIC-19) on 13 October; EditorTableControls and its four actions (RIC-21) on 13 October)', () => {
+  it('counts 162 names over 80 files: 114 components, 46 helpers and 2 hooks (NavTree, NavTreeSection, the composer triggers and UnreadDot joined on 2 October; BlockHandle and EditorBlockHandle (RIC-18) on 2 October, moveBlock and blockDropCursor, the drop in the gutter, on 5 October, MembersPill and MembersDialog, moved from Peek (SHI-31), on 6 October, ShowMore on 7 October, AppProvider on 8 October, and KindIcon, thingKindOf and PastedImages with its two helpers, moved from Peek, on 8 October; CodeBlockColours, the coloured code block of the editor, on 9 October; Checklist, Callout, isChecklistTick and calloutLook (RIC-19) on 13 October; EditorTableControls and its four actions (RIC-21) on 13 October; ReferenceCards, useReferenceCards and its three helpers, the card a chip in a document asks for, on 14 October; LinkChips and its two helpers, a URL in a document read as its chip, on 14 October; ReferenceMenu, ReferenceMenuView and three helpers, the menu of a chip while writing, on 14 October)', () => {
     // The reconciliation GATES.md §24 explains. If this changes, that changes.
     // The `EDITOR_EXTENSIONS` count as components by their names; they are
     // editor extensions, documented on SelectionToolbar's, BlockNodes' and
     // ComposerTriggers' pages.
     const kinds = registry.entries.reduce<Record<string, number>>((all, one) => ({ ...all, [one.kind]: (all[one.kind] ?? 0) + 1 }), {})
-    expect(kinds).toEqual({ component: 110, helper: 38, hook: 1 })
-    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(77)
+    expect(kinds).toEqual({ component: 114, helper: 46, hook: 2 })
+    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(80)
   })
 
   it('gives every entry a purpose, from its own page or from the comment above it', () => {
     expect(registry.entries.filter((one) => one.purpose.trim() === '')).toEqual([])
-    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(73)
-    expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(76)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'page').length).toBe(76)
+    expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(86)
   })
 
   it('takes a name with a page of its own from the page, and a name without one from the code', () => {

package/stories/Choosing.mdx

@@ -98,6 +98,9 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | A link — in text, on a title, beside a note, or a whole box | **Link** — `text`, `quiet`, `underlined`, `plain`; `external` for a new tab |
 | A document or an image attached to something, posted or waiting to be sent | **AttachmentCard** — the file decides the shape; `pending` in a composer |
 | A picture pasted into an editor, attached rather than pasted | **PastedImages** — from `@estiva-app/ui/editor`; the app hands it its upload |
+| A card a chip in a document asks for, drawn after its line | **ReferenceCards** — from `@estiva-app/ui/editor`, beside `ReferenceNode`; the app draws its card into each slot |
+| A URL in a document that reads as the chip of what it points at | **LinkChips** — from `@estiva-app/ui/editor`, beside `ReferenceNode`; the app says what each URL names |
+| Open a chip in a document, or choose its card, while writing | **ReferenceMenu** — from `@estiva-app/ui/editor`, beside `ReferenceCards`; a click on the chip, or putting one in, opens it |
 | A code block in an editor, coloured by its language as you type | **CodeBlockColours** — from `@estiva-app/ui/editor`, in place of the starter kit's code block |
 | A person or a thing named inside a sentence | **InlineChip** — one line high, level with the words; `href` makes it a link |
 | What kind of thing a name stands for — a topic, a project, an issue, a file, a message | **KindIcon** — before the name in a row, or inside an **InlineChip**; `thingKindOf` turns an event kind into one |