bible-note 0.5.0 → 0.6.2

package/dist/chunks/{TreeViewPlugin-B0UnxNiM.mjs → TreeViewPlugin-Cd1KNBRW.mjs}

@@ -1,6 +1,6 @@
 import { $ as e, $n as t, A as n, Ar as r, B as i, Bn as a, C as o, Cr as s, Ct as c, D as l, Dn as u, Dr as d, E as f, En as p, Er as m, Et as h, F as g, Fr as _, Ft as v, Gn as y, Gr as b, Gt as x, H as S, Hn as C, Hr as w, Ht as T, I as E, It as D, J as ee, Jt as O, K as te, Kt as ne, Ln as k, M as re, Nr as ie, Nt as ae, O as oe, P as se, Pn as ce, Pt as le, Q as ue, Qn as de, Qr as fe, R as pe, Rr as me, Rt as he, S as ge, Sn as _e, Tn as ve, Tr as ye, Un as be, Ut as xe, V as Se, Vn as Ce, Vr as A, W as we, Wn as Te, Wt as Ee, X as De, Xn as Oe, Y as ke, Yn as Ae, Yr as je, Yt as Me, Z as Ne, Zn as Pe, Zr as Fe, Zt as Ie, _ as Le, _r as Re, _t as ze, a as Be, ar as Ve, b as He, bn as j, br as Ue, bt as We, cn as Ge, cr as Ke, dn as qe, dr as Je, en as Ye, et as Xe, f as Ze, fn as Qe, gn as $e, gr as et, h as tt, i as nt, ii as rt, jn as it, jt as at, kn as ot, kr as st, l as ct, ln as lt, lr as ut, m as dt, mr as ft, mt as pt, n as mt, ni as ht, o as gt, oi as _t, on as vt, or as yt, p as bt, pr as xt, q as St, qn as Ct, qr as wt, qt as M, ri as Tt, rn as Et, rr as Dt, s as Ot, sr as kt, t as At, ti as jt, tn as Mt, tr as Nt, tt as N, un as Pt, ur as Ft, vn as It, vr as Lt, vt as P, w as Rt, wn as zt, wr as Bt, wt as Vt, x as Ht, xn as Ut, xr as Wt, xt as Gt, yn as Kt, yt as qt, zn as Jt, zt as Yt } from "./Lexical.prod-DYDuARMX.mjs";
-import { C as Xt, I as Zt, N as Qt, T as $t, a as en, f as tn, g as nn, i as rn, k as an, n as on, o as sn, s as cn, t as ln } from "./LexicalUtils.prod-5zbJxaQa.mjs";
-import { B as un, H as dn, I as fn, K as pn, M as mn, R as hn, V as gn, c as _n, d as vn, f as yn, h as bn, j as xn, l as Sn, m as Cn, n as wn, s as Tn, u as En, v as Dn, x as On, y as kn } from "./ContentEditable-C_wyHFh1.mjs";
+import { C as Xt, F as Zt, M as Qt, O as $t, a as en, f as tn, g as nn, i as rn, n as an, o as on, s as sn, t as cn, w as ln } from "./LexicalUtils.prod-D2Igim2c.mjs";
+import { B as un, H as dn, I as fn, K as pn, M as mn, R as hn, V as gn, c as _n, d as vn, f as yn, h as bn, j as xn, l as Sn, m as Cn, n as wn, s as Tn, u as En, v as Dn, x as On, y as kn } from "./ContentEditable-BaXBKC3m.mjs";
 import { t as An } from "./useLexicalEditable.prod-CgMasHPY.mjs";
 import * as jn from "react";
 import { Suspense as Mn, createContext as Nn, forwardRef as Pn, startTransition as Fn, useCallback as F, useContext as In, useEffect as I, useLayoutEffect as Ln, useMemo as Rn, useRef as L, useState as R } from "react";
@@ -446,10 +446,10 @@ function fr(t, r = un(rr)) {
 	}, 0), t.registerCommand(ce, () => {
 		let e = st(), t = N();
 		return j(t) && (e.setFormat(t.format), e.setStyle(t.style)), we([e]), !0;
-	}, 0), t.registerCommand(vt, () => ln((e) => {
+	}, 0), t.registerCommand(vt, () => cn((e) => {
 		let t = e.getIndent();
 		e.setIndent(t + 1);
-	}), 0), t.registerCommand(xt, () => ln((e) => {
+	}), 0), t.registerCommand(xt, () => cn((e) => {
 		let t = e.getIndent();
 		t > 0 && e.setIndent(Math.max(0, t - 1));
 	}), 0), t.registerCommand(s, (e) => {
@@ -473,10 +473,10 @@ function fr(t, r = un(rr)) {
 		let t = N();
 		if (_(t)) {
 			let n = t.getNodes();
-			if (n.length > 0) return e.preventDefault(), ur(n[0], an(n[0]) ? "next" : "previous"), !0;
+			if (n.length > 0) return e.preventDefault(), ur(n[0], $t(n[0]) ? "next" : "previous"), !0;
 		}
 		if (!j(t)) return !1;
-		if (!e.shiftKey && ir(t, an(t.anchor.getNode()) ? "next" : "previous")) return e.preventDefault(), !0;
+		if (!e.shiftKey && ir(t, $t(t.anchor.getNode()) ? "next" : "previous")) return e.preventDefault(), !0;
 		if (e.shiftKey || nr(t, "arrow", "start", r.peek()), Zt(t, !0)) {
 			let n = e.shiftKey;
 			return e.preventDefault(), Qt(t, n, !0), !0;
@@ -486,10 +486,10 @@ function fr(t, r = un(rr)) {
 		let t = N();
 		if (_(t)) {
 			let n = t.getNodes();
-			if (n.length > 0) return e.preventDefault(), ur(n[0], an(n[0]) ? "previous" : "next"), !0;
+			if (n.length > 0) return e.preventDefault(), ur(n[0], $t(n[0]) ? "previous" : "next"), !0;
 		}
 		if (!j(t)) return !1;
-		if (!e.shiftKey && ir(t, an(t.anchor.getNode()) ? "previous" : "next")) return e.preventDefault(), !0;
+		if (!e.shiftKey && ir(t, $t(t.anchor.getNode()) ? "previous" : "next")) return e.preventDefault(), !0;
 		if (e.shiftKey || nr(t, "arrow", "end", r.peek()), Zt(t, !1)) {
 			let n = e.shiftKey;
 			return e.preventDefault(), Qt(t, n, !1), !0;
@@ -505,7 +505,7 @@ function fr(t, r = un(rr)) {
 				if (t.offset !== 0) return !1;
 				let n = t.getNode();
 				if (Tt(n)) return !1;
-				let r = sn(n);
+				let r = on(n);
 				return r.getIndent() > 0 && (r.is(n) || n.is(r.getFirstDescendant()));
 			}(n)) return e.preventDefault(), t.dispatchCommand(xt, void 0);
 			if (Oe && Wt) return !1;
@@ -557,8 +557,8 @@ function fr(t, r = un(rr)) {
 	}, 0), t.registerCommand(Ct, () => {
 		let e = N();
 		return Fe(j(e) && ye(e.anchor.getNode()) !== null ? e : null), !0;
-	}, 0), t.registerCommand(me, (e) => (_n(t, cn(e, ClipboardEvent) ? e : null), !0), 0), t.registerCommand(ae, (e) => (async function(e, t) {
-		await _n(t, cn(e, ClipboardEvent) ? e : null), t.update(() => {
+	}, 0), t.registerCommand(me, (e) => (_n(t, sn(e, ClipboardEvent) ? e : null), !0), 0), t.registerCommand(ae, (e) => (async function(e, t) {
+		await _n(t, sn(e, ClipboardEvent) ? e : null), t.update(() => {
 			let e = N();
 			j(e) ? e.removeText() : _(e) && e.getNodes().forEach((e) => e.remove());
 		}, { tag: "cut" });
@@ -566,7 +566,7 @@ function fr(t, r = un(rr)) {
 		let [, n, r] = rn(e);
 		return n.length > 0 && !r ? (t.dispatchCommand(Wn, n), !0) : k(e.target) && b(e.target) ? !1 : N() !== null && (function(e, t) {
 			e.preventDefault(), t.update(() => {
-				let n = N(), r = cn(e, InputEvent) || cn(e, KeyboardEvent) ? null : e.clipboardData;
+				let n = N(), r = sn(e, InputEvent) || sn(e, KeyboardEvent) ? null : e.clipboardData;
 				r != null && n !== null && bn(r, n, t);
 			}, { tag: "paste" });
 		}(e, t), !0);
@@ -1860,7 +1860,7 @@ function ui(e, t, r, a, o) {
 		let t = N();
 		if (t) {
 			if (!J(t) && !j(t)) return !1;
-			_n(r, cn(e, ClipboardEvent) ? e : null, En(t));
+			_n(r, sn(e, ClipboardEvent) ? e : null, En(t));
 			let n = p(e);
 			return j(t) ? (t.removeText(), !0) : n;
 		}
@@ -2634,10 +2634,10 @@ function Ki(e) {
 	G(e.getParent()) ? e.isEmpty() && e.append(r()) : e.remove();
 }
 function qi(e) {
-	Y(e.getParent()) ? $t(e, U) : e.remove();
+	Y(e.getParent()) ? ln(e, U) : e.remove();
 }
 function Ji(e) {
-	$t(e, G);
+	ln(e, G);
 	let [t] = Br(e, null, null), n = t.reduce((e, t) => Math.max(e, t.length), 0), i = e.getChildren();
 	for (let e = 0; e < t.length; ++e) {
 		let a = i[e];
@@ -2730,7 +2730,7 @@ function $i(e, t) {
 		let i = N() || ke();
 		if (!i || !j(i) || !r && ki(i.anchor.getNode())) return !1;
 		let a = xr(Number(e), Number(t), n);
-		on(a);
+		an(a);
 		let o = a.getFirstDescendant();
 		return O(o) && o.select(), !0;
 	}(e, n.peek()), 0), e.registerCommand(ue, (t, r) => e === r && function(e, t) {
@@ -3580,7 +3580,7 @@ function Za(e, t) {
 		let r = t.attributes.value;
 		return e.registerCommand(Te, (t) => {
 			let i = N();
-			if (!j(i) || i.isCollapsed() || !cn(t, ClipboardEvent) || t.clipboardData === null) return !1;
+			if (!j(i) || i.isCollapsed() || !sn(t, ClipboardEvent) || t.clipboardData === null) return !1;
 			let a = t.clipboardData.getData("text");
 			return n(a) ? !i.getNodes().some((e) => P(e) || O(e) && !e.isSimpleText()) && (e.dispatchCommand(Ka, {
 				...r,
@@ -4329,7 +4329,7 @@ function Os(e, t, n, r, i) {
 }
 //#endregion
 //#region src/nodes/MediaNode.tsx
-var ks = jn.lazy(() => import("./MediaComponent-BTaaADsV.mjs"));
+var ks = jn.lazy(() => import("./MediaComponent-D-AMKM9e.mjs"));
 function As(e) {
 	return e.parentElement != null && e.parentElement.tagName === "LI" && e.previousSibling === null && e.getAttribute("aria-roledescription") === "checkbox";
 }

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.2** 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                                         |
@@ -676,9 +716,9 @@ settings panel.
 | `AutocompletePlugin` | `src/plugins/AutocompletePlugin` | `isAutocomplete` |
 | `PageSizePreviewPlugin` | `src/plugins/PageSizePreviewPlugin` | always |
 | `PaperPageNavigationPlugin` | `src/plugins/PaperPageNavigationPlugin` | always |
-| `TableOfContentsPlugin` | `src/plugins/TableOfContentsPlugin` | `showTableOfContents` |
 | `ContextMenuPlugin` | `src/plugins/ContextMenuPlugin` | `shouldUseLexicalContextMenu` |
 | `SpecialTextPlugin` | `src/plugins/SpecialTextPlugin` | `shouldAllowHighlightingWithBrackets` |
+| `ScrollToTopPlugin` | `src/plugins/ScrollToTopPlugin` | always |
 | `ActionsPlugin` | `src/plugins/ActionsPlugin` | always |
 | `TreeViewPlugin` | `src/plugins/TreeViewPlugin` | `showTreeView` |
 
@@ -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>;
+}>;
+```