@estiva-app/ui 0.66.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
@@ -125,7 +132,8 @@ const RICH_TEXT_CLASSES = {
   syntax: '[&_:is(.hljs-keyword,.hljs-doctag,.hljs-type,.hljs-template-tag,.hljs-template-variable)]:text-syntax-keyword [&_.hljs-title]:text-syntax-function [&_:is(.hljs-number,.hljs-literal,.hljs-attr,.hljs-attribute,.hljs-meta,.hljs-variable,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-id)]:text-syntax-constant [&_:is(.hljs-string,.hljs-regexp)]:text-syntax-string [&_:is(.hljs-built_in,.hljs-symbol)]:text-syntax-variable [&_.hljs-comment]:text-syntax-comment [&_:is(.hljs-name,.hljs-quote,.hljs-selector-tag,.hljs-selector-pseudo)]:text-syntax-tag',
   /* A divider splits the text in two: 16px either side (Katerina, 9 October; 4 before). */
   divider: '[&_hr]:my-2 [&_hr]:border-border-default',
-  table: '[&_:is(th,td)>p]:m-0 [&_:is(th,td)]:border [&_:is(th,td)]:border-border-default [&_:is(th,td)]:px-2 [&_:is(th,td)]:py-1 [&_:is(th,td)]:text-left [&_:is(th,td)]:align-top [&_table]:w-full [&_table]:border-collapse [&_th]:bg-bg-code [&_th]:font-medium [&_th]:text-text-primary',
+  /* A table 16px above and below, as a divider (Katerina, 14 October; 8 before): the editor's row ➕ sits in that room, not over the next line. */
+  table: '[&_:is(th,td)>p]:m-0 [&_:is(th,td)]:border [&_:is(th,td)]:border-border-default [&_:is(th,td)]:px-2 [&_:is(th,td)]:py-1 [&_:is(th,td)]:text-left [&_:is(th,td)]:align-top [&_table]:my-2 [&_table]:w-full [&_table]:border-collapse [&_th]:bg-bg-code [&_th]:font-medium [&_th]:text-text-primary',
   /* Bold in the heading colour, not only heavier. An underlined word draws a faint line, so it does not read as a link (Katerina, 9 October). */
   marks: '[&_em]:italic [&_strong]:font-semibold [&_strong]:text-text-primary [&_u]:underline [&_u]:decoration-text-muted [&_u]:underline-offset-2',
   /* Lines 1.5 apart (Katerina, 9 October; 1.4 before). */
@@ -185,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
 }
 
@@ -244,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>
       )
     })
@@ -280,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>
     )
@@ -298,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>
@@ -332,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': {
@@ -400,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

@@ -12,6 +12,7 @@ export { PastedImages, pastedImages, pastedImageName, type PastedImagesOptions,
 export { CodeBlockColours } from './CodeBlockColours'
 export { suggestionPopup, isSuggestionActive, isSuggestionOpen, type SuggestionPopupOptions } from './suggestionPopup'
 export { EditorBlockHandle, blockDropCursor, deleteBlock, moveBlock, duplicateBlock, startBlockDrag, type EditorBlockHandleProps, type BlockTurnInto } from './EditorBlockHandle'
+export { EditorTableControls, appendTableRow, appendTableColumn, deleteTableRow, deleteTableColumn, type EditorTableControlsProps } from './EditorTableControls'
 export {
   PersonMention,
   UrgentPersonMention,
@@ -54,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 144 names over 76 files: 109 components, 34 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)', () => {
+  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: 109, helper: 34, hook: 1 })
-    expect(new Set(registry.entries.map((one) => one.sourceFile)).size).toBe(76)
+    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(72)
-    expect(registry.entries.filter((one) => one.purposeFrom === 'comment').length).toBe(72)
+    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', () => {
@@ -299,7 +299,7 @@ describe('the ids point at something', () => {
 describe('a second parser agrees', async () => {
   const docgen = await import('react-docgen').catch(() => null)
 
-  it.skipIf(!docgen)('finds the same props on all 79 components', async () => {
+  it.skipIf(!docgen)('finds the same props on all 80 components', async () => {
     if (!docgen) return
     const resolver = new docgen.builtinResolvers.FindExportedDefinitionsResolver({ limit: 0 })
     const byName = new Map(registry.entries.map((one) => [one.name, one]))

package/src/registry/siblings.test.ts

@@ -26,7 +26,7 @@ function appAt(folder: string, name: string, deps: Record<string, string> = UI,
   put(`${folder}/src/${part}.tsx`, `/** The ${part.toLowerCase()} of ${name}. */\nexport function ${part}() {\n  return <i />\n}\n`)
 }
 // A repository is a folder with `.git`: a directory, or a worktree's file.
-appAt('alpha', 'alpha-app', UI, 'Tabletop')
+appAt('alpha', 'alpha-app', UI, 'Sundial')
 put('alpha/.git/HEAD', 'ref: refs/heads/main\n')
 put('beta/package.json', JSON.stringify({ name: 'beta' }))
 put('beta/.git/HEAD', 'ref: refs/heads/main\n')
@@ -75,7 +75,7 @@ describe.skipIf(!existsSync(cli))('estiva-ui find, with nothing else typed', ()
   })
 
   it('answers the same from the folder that holds them', () => {
-    expect(find(workspace, 'tabletop')).toMatch(/^Tabletop {2}· .* · {2}alpha/m)
+    expect(find(workspace, 'sundial')).toMatch(/^Sundial {2}· .* · {2}alpha/m)
     expect(find(workspace, 'zzqqx')).toContain('Nothing in estiva-ui, alpha, beta matches')
   })
 

package/stories/Choosing.mdx

@@ -73,6 +73,7 @@ fork freely, owe nothing back, mention it on the package's ticket.
 | A composer's `@`, `!@`, `[` and `/` — mention a person, reference something, format or insert | **ComposerTriggers** — `PersonMention`, `UrgentPersonMention`, `CaptionedReference`, `ReferenceTrigger` and `SlashCommands` from `@estiva-app/ui/editor`; the app passes its people, its items and its own `/` rows |
 | An editor that saves a block document and must keep its block ids | **BlockNodes** — `BlockId`, `UnknownBlock`, `ReferenceNode` and `AttachmentNode` from `@estiva-app/ui/editor`, beside StarterKit and TableKit |
 | Move, turn, duplicate or delete one block of a document being edited | **EditorBlockHandle**, from `@estiva-app/ui/editor`, with your rows after its own |
+| Add or delete a table's rows and columns in a document being edited | **EditorTableControls**, from `@estiva-app/ui/editor`, inside the EditorBlockHandle |
 | Offer a link or a comment on one block of a document being read | **BlockHandle** — your rows only, and no Tiptap loaded |
 | Anything with a title, body and footer | **DialogShell** |
 | "Are you sure?" | **ConfirmDialog** |
@@ -97,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 |