bible-note 0.5.0 → 0.6.0

package/knowledge/development.md

@@ -1,6 +1,6 @@
 # BibleNote — development guide
 
-> Generated by `npm run pack` for **bible-note@0.5.0** from the hand-written topics in `knowledge/development/` and the package's own type declarations. Do not edit this file — edit the sources and re-run the pack. End-user help for the editor UI lives in `ui-rag.md` next to it.
+> Generated by `npm run pack` for **bible-note@0.6.0** from the hand-written topics in `knowledge/development/` and the package's own type declarations. Do not edit this file — edit the sources and re-run the pack. End-user help for the editor UI lives in `ui-rag.md` next to it.
 
 ## Contents
 
@@ -233,11 +233,48 @@ tooltip when the element has no `title`; `shortcutKey` clicks the button from
 anywhere in the page and is shown in the tooltip. Give the button the
 `action-button` class to match the built-in ones.
 
+### Host buttons on the selected-text toolbar
+
+The toolbar that pops up over selected text (Bold, Italic, …, Insert comment)
+takes host buttons too. Here the editor renders the `<button>`, and `onClick`
+receives the selection it was clicked on:
+
+```tsx
+bibleNote.appendFloatingActionButton({
+  id: 'copy-selected-text',
+  description: 'Copy selected text', // tooltip and accessible name
+  children: <i className="bi bi-clipboard format" />,
+  onClick: async ({ selection }) => {
+    await navigator.clipboard.writeText(selection.text);
+  },
+});
+bibleNote.appendFloatingActionButton({
+  id: 'uppercase-selected-text',
+  description: 'Make selected text uppercase',
+  isHiddenWhenReadOnly: true,
+  children: <i className="bi bi-alphabet-uppercase format" />,
+  onClick: ({ selection, replaceText }) => {
+    replaceText(selection.text.toUpperCase());
+  },
+});
+bibleNote.removeFloatingActionButton('copy-selected-text');
+```
+
+`selection` holds the plain `text`, the `html` Copy would produce, the `start`
+and `end` points in document order, `isBackward`, and a copy of the DOM
+`domRange`. `replaceText(text)` writes back into that captured range the way
+`addText` inserts text, even after an `await`; it returns `false` and changes
+nothing when the note is read-only or the range no longer holds
+`selection.text`. `prepend…` places a button before Bold, `append…` after
+Insert comment; re-adding an `id` replaces that button in place. The buttons
+show in read-only mode unless `isHiddenWhenReadOnly` is set.
+
 ### Mounting without auto-mount
 
 `render` can be called any time after construction and again later — each call
 unmounts the previous root first. Call `unmount()` when the host view goes away;
-the instance keeps its props and footer buttons for the next `render`.
+the instance keeps its props, footer buttons and selected-text toolbar
+buttons for the next `render`.
 
 <a id="dev-datasets-and-lookup-managers"></a>
 
@@ -541,7 +578,10 @@ instance's `colorScheme` follows the Dark Mode switch.
   selected page size and opens the print dialog).
 
 Host buttons go before or after the built-in ones with
-`prependFooterActionButton` / `appendFooterActionButton`.
+`prependFooterActionButton` / `appendFooterActionButton`. Buttons for the
+toolbar over selected text use `prependFloatingActionButton` /
+`appendFloatingActionButton`; their `onClick` receives the selection and a
+`replaceText` that writes back into it.
 
 ### Electron: native file dialogs
 
@@ -596,7 +636,7 @@ This topic is for changing the editor itself, in its source repository.
 | -------------------------------------------- | -------------------------------------------------------------------------------------- |
 | `src/lib.ts`                                 | the package's public entry — only re-exports; everything it reaches is library code    |
 | `src/index.tsx`                              | the demo host (fetches datasets, wires every prop, mounts) — not part of the package   |
-| `src/BibleNote.ts`                           | the `BibleNote` class: queued editor actions, footer buttons, colour scheme            |
+| `src/BibleNote.ts`                           | the `BibleNote` class: queued editor actions, host buttons, colour scheme              |
 | `src/bibleNoteHelpers.tsx`                   | `BibleNoteProps`, the storage split, `renderEditor`                                    |
 | `src/AppComp.tsx`                            | providers, storage hydration, the editor controller behind `BibleNote`'s methods       |
 | `src/Editor.tsx`                             | the plugin tree, zoom and the full-view layout                                         |
@@ -960,6 +1000,45 @@ removeFooterActionButton(id: string): boolean;
 
 Removes the host footer button with this `id`; `false` when there was none.
 
+##### `appendFloatingActionButton()`
+
+```ts
+appendFloatingActionButton(actionButton: BibleNoteFloatingActionButton): void;
+```
+
+Adds a host button to the floating toolbar that appears over selected
+text, after its built-in buttons (after Insert comment). Its `onClick`
+receives the selection — text, HTML and range — and can replace the
+selected text. A button whose `id` is already present is replaced in
+place, keeping its position.
+
+##### `prependFloatingActionButton()`
+
+```ts
+prependFloatingActionButton(actionButton: BibleNoteFloatingActionButton): void;
+```
+
+Adds a host button to the floating toolbar before its built-in buttons
+(before Bold), ahead of any prepended earlier. A button whose `id` is
+already present is replaced in place, keeping its position.
+
+##### `getFloatingActionButton()`
+
+```ts
+getFloatingActionButton(id: string): BibleNoteFloatingActionButton | null;
+```
+
+The host floating toolbar button with this `id`, or `null`.
+
+##### `removeFloatingActionButton()`
+
+```ts
+removeFloatingActionButton(id: string): boolean;
+```
+
+Removes the host floating toolbar button with this `id`; `false` when there
+was none.
+
 ##### `searchText()`
 
 ```ts
@@ -986,8 +1065,8 @@ ever mounted once.
 unmount(): void;
 ```
 
-Unmounts the editor. The instance keeps its props and footer buttons and
-can be rendered again.
+Unmounts the editor. The instance keeps its props, footer buttons and
+floating toolbar buttons and can be rendered again.
 
 <a id="api-locationslookupmanager"></a>
 
@@ -1444,6 +1523,64 @@ The editor's two colour schemes.
 type BibleNoteColorScheme = 'dark' | 'light';
 ```
 
+<a id="api-biblenotefloatingactionbutton"></a>
+
+#### `BibleNoteFloatingActionButton`
+
+A host-supplied button in the floating toolbar that appears over selected
+text — the bar with Bold, Italic, Underline, … and Insert comment.
+
+Unlike a footer button, the editor renders the `<button>` itself, so it
+matches the built-in ones; `children` is only what goes inside it.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | yes | Unique per editor; adding a button with an existing id replaces it in place. |
+| `description` | `string` | yes | What the button does: its tooltip and its accessible name. |
+| `children` | `ReactNode` | yes | The content of the button, normally a Bootstrap icon given the `format` class so it is sized and tinted like the built-in icons: `<i className="bi bi-clipboard format" />`. |
+| `onClick` | `(event: BibleNoteFloatingActionButtonClickEvent) => void` | yes | Called on click with the selection the toolbar is showing for. Not called when the selection has collapsed to a caret by the time of the click. |
+| `isHiddenWhenReadOnly` | `boolean` | no | `true` shows the button only while the note can be edited, like the built-in formatting buttons. By default it shows in read-only mode too, like Insert comment — right for actions that only read the selection. |
+
+<a id="api-biblenotefloatingactionbuttonclickevent"></a>
+
+#### `BibleNoteFloatingActionButtonClickEvent`
+
+What a floating action button's `onClick` receives.
+
+```ts
+type BibleNoteFloatingActionButtonClickEvent = Readonly<{
+    /** The `id` of the button that was clicked. */
+    id: string;
+    /** The selection the button was clicked on. */
+    selection: BibleNoteTextSelection;
+    /**
+     * Replaces the text of the captured selection with `text`, inserted the way
+     * `BibleNote.addText` inserts it: as plain text, as if pasted, so the paste
+     * rules apply and `\n` starts a new paragraph. An empty string deletes the
+     * selected text. The selection is restored from `selection.start` and
+     * `selection.end` first, so this still works after the user has clicked
+     * elsewhere or after an `await`.
+     *
+     * Returns `false`, and changes nothing, when the note is read-only or when
+     * that range no longer holds `selection.text` — because the note was edited
+     * since the click, or the text was already replaced.
+     */
+    replaceText: (text: string) => boolean;
+    /** The React click event of the button. */
+    mouseEvent: ReactMouseEvent<HTMLButtonElement>;
+}>;
+```
+
+<a id="api-biblenotefloatingactionbuttons"></a>
+
+#### `BibleNoteFloatingActionButtons`
+
+The host floating toolbar buttons on each side of the built-in ones, in order.
+
+```ts
+type BibleNoteFloatingActionButtons = PlacedActionButtons<BibleNoteFloatingActionButton>;
+```
+
 <a id="api-biblenotefooteractionbutton"></a>
 
 #### `BibleNoteFooterActionButton`
@@ -1520,6 +1657,34 @@ Options for `BibleNote#render`.
 | `settings` | `ReactNode` | no | The settings panel to mount, normally `<BibleNoteSettings />`. Omit it and the editor has no settings panel. |
 | `settingsContainerElement` | `Element \| DocumentFragment` | no | Where to portal the `settings` panel. Without it the panel renders inside the editor's own layout. |
 
+<a id="api-biblenoteselectionpoint"></a>
+
+#### `BibleNoteSelectionPoint`
+
+A position in the open note, addressed the way the editor addresses it: a
+node, and an offset inside that node.
+
+```ts
+type BibleNoteSelectionPoint = Readonly<{
+    /**
+     * The editor's key for the node the point sits in. Keys identify nodes of
+     * the note as it is open right now: they are not saved with `content`, and
+     * they change when the note is loaded again.
+     */
+    key: string;
+    /**
+     * For a `'text'` point, the character offset inside that text node. For an
+     * `'element'` point, the index of the child the point sits before.
+     */
+    offset: number;
+    /**
+     * `'text'` when `key` names a text node; `'element'` when it names an element
+     * node such as a paragraph or a list item.
+     */
+    type: 'text' | 'element';
+}>;
+```
+
 <a id="api-biblenotesettingsprops"></a>
 
 #### `BibleNoteSettingsProps`
@@ -1546,6 +1711,45 @@ first renders; writes are fire-and-forget.
 | `getSetting` | `getSetting<T = unknown>(key: string): Promise<T \| null>` | yes | The value stored under `key`, or `null` when there is none. |
 | `deleteSetting` | `deleteSetting(key: string): Promise<void>` | yes | Removes `key`. |
 
+<a id="api-biblenotetextselection"></a>
+
+#### `BibleNoteTextSelection`
+
+The text selection a floating action button was clicked on. It is a snapshot
+taken at the click: it does not follow later edits or selection changes.
+
+```ts
+type BibleNoteTextSelection = Readonly<{
+    /**
+     * The selected text as plain text — what Copy puts on the clipboard as
+     * `text/plain`. Paragraphs are separated by `\n`. Never empty: the toolbar
+     * only appears over a selection that contains text.
+     */
+    text: string;
+    /**
+     * The selected content as HTML, formatting included — what Copy puts on the
+     * clipboard as `text/html`.
+     */
+    html: string;
+    /** Where the selection begins, in document order. */
+    start: BibleNoteSelectionPoint;
+    /** Where the selection ends, in document order. */
+    end: BibleNoteSelectionPoint;
+    /**
+     * `true` when the user selected from the end back toward the start, so the
+     * caret sits at `start`; `false` when the caret sits at `end`.
+     */
+    isBackward: boolean;
+    /**
+     * A copy of the browser's DOM `Range` for the selection, or `null` when the
+     * browser had no selection inside the editor at the click. Use it to measure
+     * the text on screen (`domRange.getBoundingClientRect()`); it stops matching
+     * the page once the note changes.
+     */
+    domRange: Range | null;
+}>;
+```
+
 <a id="api-extrafontfamilyoption"></a>
 
 #### `ExtraFontFamilyOption`
@@ -1925,3 +2129,14 @@ A Bible verse as the host renders it: a title line plus the full text.
 | `title` | `string` | yes | The verse reference as displayed, e.g. `(KJV) Genesis 1:1`. |
 | `fullText` | `string` | yes | The title line followed by the verse lines, in the same shape the editor accepts when Bible text is pasted after `^`: `(KJV) Genesis 1:1\n(1): In the beginning…`. |
 | `style` | `CSSProperties` | no | Extra CSS for this verse's text, e.g. a font for a non-Latin version. |
+
+#### `PlacedActionButtons`
+
+Host buttons on each side of an editor's built-in buttons, in order.
+
+```ts
+type PlacedActionButtons<T> = Readonly<{
+    before: ReadonlyArray<T>;
+    after: ReadonlyArray<T>;
+}>;
+```