bible-note 0.4.7 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bible-note",
-  "version": "0.4.7",
+  "version": "0.6.0",
   "description": "A Bible study tool for taking notes and organizing your thoughts.",
   "license": "MIT",
   "author": "raksa <eng.raksa@gmail.com>",
@@ -23,11 +23,14 @@
       "require": "./dist/bible-note.cjs"
     },
     "./styles.css": "./dist/bible-note.css",
+    "./knowledge/development.md": "./knowledge/development.md",
+    "./knowledge/ui-rag.md": "./knowledge/ui-rag.md",
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "types",
+    "knowledge",
     "README.md",
     "LICENSE"
   ],

package/types/AppComp.d.ts

@@ -7,6 +7,7 @@
  */
 import type { LibraryItems } from './excalidrawTypes';
 import { type JSX, type ReactNode } from 'react';
+import { type BibleNoteFloatingActionButtonControllerOwner } from './floatingActionButtons';
 import { type BibleNoteFooterActionButtonControllerOwner } from './footerActionButtons';
 import type { LocationsLookupManager, NamesLookupManager } from './LookupManager';
 import type { ExtraFontFamilyOption } from './utils/fontFamilyOptions';
@@ -23,6 +24,7 @@ type PlaygroundAppProps = {
     excalidrawLibraryItems?: LibraryItems;
     excalidrawLoadLibrariesFileList?: () => string[];
     excalidrawSaveLibrariesFile?: (librariesFile: string) => void;
+    floatingActionButtonController?: BibleNoteFloatingActionButtonControllerOwner;
     footerActionButtonController?: BibleNoteFooterActionButtonControllerOwner;
     isMinimize: boolean;
     isOnApp: boolean;
@@ -63,6 +65,6 @@ type BibleNoteEditorController = {
 export type BibleNoteEditorControllerOwner = {
     connectEditorController: (controller: BibleNoteEditorController) => () => void;
 };
-export declare function BibleNoteApp({ detectTextLanguage, editorController, editorExtraFontFamilies, excalidrawClearLibrariesFileList, excalidrawLibraryItems, excalidrawLoadLibrariesFileList, excalidrawSaveLibrariesFile, footerActionButtonController, isMinimize, isOnApp, print, resolveFilePath, revealFile, settings, settingsContainerElement, settingsController, stickyNoteExtraFontFamilies, shortToVerseData, verseFullTextToListShorts, changeBibleKey, }: PlaygroundAppProps): JSX.Element;
-export declare function AppComp({ detectTextLanguage, namesLookupManager, locationsLookupManager, editorController, editorExtraFontFamilies, excalidrawClearLibrariesFileList, excalidrawLibraryItems, excalidrawLoadLibrariesFileList, excalidrawSaveLibrariesFile, footerActionButtonController, print, resolveFilePath, revealFile, settings, settingsContainerElement, settingsController, stickyNoteExtraFontFamilies, storageManager, isMinimize, isOnApp, shortToVerseData, verseFullTextToListShorts, changeBibleKey, }: PlaygroundAppProps): JSX.Element;
+export declare function BibleNoteApp({ detectTextLanguage, editorController, editorExtraFontFamilies, excalidrawClearLibrariesFileList, excalidrawLibraryItems, excalidrawLoadLibrariesFileList, excalidrawSaveLibrariesFile, floatingActionButtonController, footerActionButtonController, isMinimize, isOnApp, print, resolveFilePath, revealFile, settings, settingsContainerElement, settingsController, stickyNoteExtraFontFamilies, shortToVerseData, verseFullTextToListShorts, changeBibleKey, }: PlaygroundAppProps): JSX.Element;
+export declare function AppComp({ detectTextLanguage, namesLookupManager, locationsLookupManager, editorController, editorExtraFontFamilies, excalidrawClearLibrariesFileList, excalidrawLibraryItems, excalidrawLoadLibrariesFileList, excalidrawSaveLibrariesFile, floatingActionButtonController, footerActionButtonController, print, resolveFilePath, revealFile, settings, settingsContainerElement, settingsController, stickyNoteExtraFontFamilies, storageManager, isMinimize, isOnApp, shortToVerseData, verseFullTextToListShorts, changeBibleKey, }: PlaygroundAppProps): JSX.Element;
 export {};

package/types/BibleNote.d.ts

@@ -1,42 +1,121 @@
+import type { BibleNoteFloatingActionButton } from './floatingActionButtons';
 import type { BibleNoteFooterActionButton } from './footerActionButtons';
 import type { BibleNoteColorScheme } from './params/colorScheme';
 import { type BibleNoteProps, type BibleNoteRenderOptions } from './bibleNoteHelpers';
+export type { BibleNoteFloatingActionButton, BibleNoteFloatingActionButtonClickEvent, BibleNoteFloatingActionButtons, BibleNoteSelectionPoint, BibleNoteTextSelection, } from './floatingActionButtons';
 export type { BibleNoteFooterActionButton, BibleNoteFooterActionButtons, } from './footerActionButtons';
+/**
+ * The BibleNote editor. Construct it with the host's datasets and storage
+ * callbacks, then {@link BibleNote.render | render} it into an element.
+ *
+ * Every editor-backed method (`content`, `addText`, `searchText`, …) can be
+ * called before `render`: writes are queued and applied once the editor has
+ * mounted, and reads return an empty value until then.
+ */
 declare class BibleNote {
+    /** The package version this bundle was built from. */
     static VERSION: string;
+    /** The props the instance was constructed with. */
     props: Readonly<BibleNoteProps>;
+    /**
+     * The colour scheme last applied — by {@link BibleNote.setColorScheme} or the
+     * settings panel's Dark Mode switch. Read it; change it with `setColorScheme`.
+     */
     colorScheme: BibleNoteColorScheme;
     private editorController;
     private pendingEditorActions;
     private pendingColorScheme;
     private readOnlyOverride;
     private footerActionButtonController;
-    private footerActionButtons;
+    private readonly footerActionButtons;
+    private floatingActionButtonController;
+    private readonly floatingActionButtons;
     private root;
     private settingsController;
     private readonly editorControllerOwner;
     private readonly footerActionButtonControllerOwner;
+    private readonly floatingActionButtonControllerOwner;
     private readonly storageManager;
     private readonly settingsControllerOwner;
+    /** Creates the editor; nothing is rendered until `render` is called. */
     constructor(props: BibleNoteProps);
+    /**
+     * The note as a serialized Lexical editor state (a JSON string) — the same
+     * string `saveData` receives. Reads `''` until the editor has mounted.
+     * Assigning replaces the whole document; assigning `''` clears it.
+     */
     get content(): string;
     set content(value: string);
+    /**
+     * Whether the note is locked against editing. Assigning `true` forces
+     * read-only mode: the footer's lock turns into **Read-Only Mode Locked** and
+     * the user cannot unlock it. Assigning `false` releases that lock and makes
+     * the note editable.
+     */
     get isReadOnly(): boolean;
     set isReadOnly(value: boolean);
+    /**
+     * Whether the caret is in the editor right now: the window has focus, the
+     * editor is the active element, and the selection is a collapsed caret inside
+     * it. A host can use this to decide whether to send text to `addText`.
+     */
     getIsFocusing(): boolean;
+    /**
+     * Switches the editor between light and dark. Applies the body classes at
+     * once (see `applyBibleNoteColorScheme`) and keeps the settings panel's Dark
+     * Mode switch in step.
+     */
     setColorScheme(mode: BibleNoteColorScheme): void;
+    /**
+     * Inserts text at the caret, or at the end of the note when there is no
+     * selection, exactly as if the user had pasted it as plain text — so the
+     * paste rules apply: Bible text pasted right after a `^` becomes a verse
+     * mention. Ignored while the note is read-only or when `text` is empty.
+     */
     addText(text: string): void;
+    /**
+     * Adds a host button after the footer's built-in buttons. A button whose `id`
+     * is already present is replaced in place, keeping its position.
+     */
     appendFooterActionButton(actionButton: BibleNoteFooterActionButton): void;
+    /**
+     * Adds a host button before the footer's built-in buttons, ahead of any
+     * prepended earlier. A button whose `id` is already present is replaced in
+     * place, keeping its position.
+     */
     prependFooterActionButton(actionButton: BibleNoteFooterActionButton): void;
+    /** The host footer button with this `id`, or `null`. */
     getFooterActionButton(id: string): BibleNoteFooterActionButton | null;
+    /** Removes the host footer button with this `id`; `false` when there was none. */
     removeFooterActionButton(id: string): boolean;
-    private setFooterActionButton;
-    private getFooterActionButtonsSnapshot;
+    /**
+     * 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.
+     */
+    appendFloatingActionButton(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.
+     */
+    prependFloatingActionButton(actionButton: BibleNoteFloatingActionButton): void;
+    /** The host floating toolbar button with this `id`, or `null`. */
+    getFloatingActionButton(id: string): BibleNoteFloatingActionButton | null;
+    /**
+     * Removes the host floating toolbar button with this `id`; `false` when there
+     * was none.
+     */
+    removeFloatingActionButton(id: string): boolean;
     private syncFooterActionButtons;
+    private syncFloatingActionButtons;
     private runOrQueueEditorAction;
     private connectEditorController;
     private connectSettingsController;
     private connectFooterActionButtonController;
+    private connectFloatingActionButtonController;
     private syncColorSchemeFromSettings;
     /**
      * Drives the editor's find bar. A string opens the bar (or updates the query
@@ -44,7 +123,16 @@ declare class BibleNote {
      * like the other editor-backed methods.
      */
     searchText(query: string | null): void;
+    /**
+     * Mounts the editor into `containerElement` with its own React root.
+     * Rendering again unmounts the previous root first, so an instance is only
+     * ever mounted once.
+     */
     render(containerElement: HTMLElement, options?: BibleNoteRenderOptions): void;
+    /**
+     * Unmounts the editor. The instance keeps its props, footer buttons and
+     * floating toolbar buttons and can be rendered again.
+     */
     unmount(): void;
     /**
      * Every short verse reference (`GEN 1:1`) the given note content mentions, in

package/types/LookupManager.d.ts

@@ -16,47 +16,72 @@ export { getLookupRecordValues, getMentionKjvName, normalizeMentionNameType, par
  * font does not cover; anything a `style` attribute accepts works.
  */
 export type LookupManagerStyle = CSSProperties;
+/** Options for `searchNames` / `searchLocations`. */
 export type LookupSearchOptions = {
+    /** Language to search; falls back to `defaultLang` when absent or unknown. */
     lang?: string;
+    /** Maximum number of results; all matches when omitted. */
     limit?: number;
 };
+/** Options for the `…Pagination` searches. */
 export type LookupPaginationOptions = {
+    /** Search text; empty or omitted lists every record in importance order. */
     query?: string;
+    /** Language to search; falls back to `defaultLang` when absent or unknown. */
     lang?: string;
+    /** 1-based page number, clamped to the available pages. Defaults to 1. */
     page?: number;
+    /** Records per page (at least 1). Defaults to 20. */
     pageSize?: number;
 };
+/** One page of search results. */
 export type LookupPaginationResult<TRecord> = {
+    /** The language actually searched. */
     lang: string;
+    /** Matches across all pages. */
     totalRecords: number;
+    /** The page returned, after clamping. */
     page: number;
+    /** Number of pages; at least 1, even with no matches. */
     totalPages: number;
     pageSize: number;
+    /** This page's records. */
     records: Array<TRecord>;
 };
+/** `LookupSearchOptions` plus a name-type filter. */
 export type NamesLookupSearchOptions = LookupSearchOptions & {
+    /** Only records of this type; applied before `limit`. */
     type?: MentionNameType;
 };
+/** `LookupPaginationOptions` plus a name-type filter. */
 export type NamesLookupPaginationOptions = LookupPaginationOptions & {
+    /** Only records of this type. */
     type?: MentionNameType;
 };
+/** How many records of one name type a dataset holds. */
 export type NameTypeCount = {
     type: MentionNameType;
     count: number;
 };
+/** One language's name dataset, as `NamesLookupManager`'s constructor takes it. */
 export type NamesLookupManagerLangData = {
+    /** The normalized records (see `parseMentionNameMatches`). */
     records: ReadonlyArray<MentionNameMatch>;
     /** Short verse key (e.g. `"EXO 6:23"`) to the ids of the names it mentions. */
     versePersonsMap?: VerseRecordIdsMap;
 };
+/** Name datasets keyed by language code, e.g. `{ en: …, km: … }`. */
 export type NamesLookupManagerDataMap = {
     [langCode: string]: NamesLookupManagerLangData;
 };
+/** One language's location dataset, as `LocationsLookupManager`'s constructor takes it. */
 export type LocationsLookupManagerLangData = {
+    /** The normalized records (see `parseMentionLocationMatches`). */
     records: ReadonlyArray<MentionLocationMatch>;
     /** Short verse key (e.g. `"EXO 6:23"`) to the ids of the locations it mentions. */
     verseLocationsMap?: VerseRecordIdsMap;
 };
+/** Location datasets keyed by language code, e.g. `{ en: …, km: … }`. */
 export type LocationsLookupManagerDataMap = {
     [langCode: string]: LocationsLookupManagerLangData;
 };
@@ -103,14 +128,24 @@ declare abstract class LookupManager<TRecord extends LookupRecordLike, TLangData
      */
     get style(): LookupManagerStyle | undefined;
     set style(style: LookupManagerStyle | undefined);
+    /**
+     * The language used when a call names none (or names one this manager does
+     * not hold). Assigning a language the data map lacks throws.
+     */
     get defaultLang(): string;
     set defaultLang(lang: string);
+    /** The language codes this manager holds data for. */
     get langs(): ReadonlyArray<string>;
     /** Total number of records in a language, ignoring any query. */
     getRecordCount(lang?: string): number;
     /** Every record in a language, in importance order. */
     getAllRecords(lang?: string): Array<TRecord>;
+    /** The record with this id (whitespace-trimmed), or `null`. */
     getRecordById(id: string, lang?: string): TRecord | null;
+    /**
+     * The records for these ids, in the order given; unknown and repeated ids
+     * are skipped.
+     */
     getRecordsByIds(ids: ReadonlyArray<string>, lang?: string): Array<TRecord>;
     /**
      * Every record carrying exactly this name. Names are not unique in the
@@ -135,8 +170,18 @@ declare abstract class LookupManager<TRecord extends LookupRecordLike, TLangData
     protected abstract getVerseRecordIds(langData: TLangData): VerseRecordIdsMap;
     private getRankedMatches;
 }
+/**
+ * Owns the person/name dataset(s): ranked search, id and name lookup,
+ * pagination, name-type counts and verse → names lookup. Has no editor
+ * dependency, so a host can use it to build its own UI. Indexes are built
+ * lazily per language on first use.
+ */
 export declare class NamesLookupManager extends LookupManager<MentionNameMatch, NamesLookupManagerLangData> {
     private readonly nameTypeCounts;
+    /**
+     * Takes already-normalized records; prefer `fromRawDataset` for the generated
+     * dataset files. Throws when `dataMap` has no `defaultLang` entry.
+     */
     constructor(dataMap: NamesLookupManagerDataMap, defaultLang: string, style?: LookupManagerStyle);
     /**
      * Builds a manager straight from the generated dataset files, i.e. whatever
@@ -155,13 +200,31 @@ export declare class NamesLookupManager extends LookupManager<MentionNameMatch,
     getNameTypes(lang?: string): ReadonlyArray<NameTypeCount>;
     /** The name types present in the default language. */
     get nameTypes(): ReadonlyArray<NameTypeCount>;
+    /**
+     * Names matching `query`. Case-insensitive substring match against the name, the KJV English
+     * name (translated datasets) and the former name. Ranked exact, then prefix,
+     * then substring — the better of the two names counts — and by importance
+     * (`matterRange`, then alphabetical) within a tier. An empty query returns
+     * every record in importance order.
+     */
     searchNames(query: string, options?: NamesLookupSearchOptions): Array<MentionNameMatch>;
+    /** `searchNames`, one page at a time (20 records per page by default). */
     searchNamesPagination(options?: NamesLookupPaginationOptions): LookupPaginationResult<MentionNameMatch>;
     /** The names a short verse key (e.g. `"EXO 6:23"`) mentions. */
     searchByShortVerse(shortVerse: string, lang?: string): Array<MentionNameMatch>;
     protected getVerseRecordIds(langData: NamesLookupManagerLangData): VerseRecordIdsMap;
 }
+/**
+ * Owns the place/location dataset(s): ranked search, id and name lookup,
+ * pagination and verse → locations lookup. Has no editor dependency, so a host
+ * can use it to build its own UI. Indexes are built lazily per language on
+ * first use.
+ */
 export declare class LocationsLookupManager extends LookupManager<MentionLocationMatch, LocationsLookupManagerLangData> {
+    /**
+     * Takes already-normalized records; prefer `fromRawDataset` for the generated
+     * dataset files. Throws when `dataMap` has no `defaultLang` entry.
+     */
     constructor(dataMap: LocationsLookupManagerDataMap, defaultLang: string, style?: LookupManagerStyle);
     /**
      * Builds a manager straight from the generated dataset files, i.e. whatever
@@ -174,7 +237,15 @@ export declare class LocationsLookupManager extends LookupManager<MentionLocatio
     }, defaultLang: string, style?: LookupManagerStyle): LocationsLookupManager;
     /** An empty manager, used wherever a host has not supplied a dataset yet. */
     static createEmpty(): LocationsLookupManager;
+    /**
+     * Locations matching `query`. Case-insensitive substring match against the name, the KJV English
+     * name (translated datasets) and the former name. Ranked exact, then prefix,
+     * then substring — the better of the two names counts — and by importance
+     * (`matterRange`, then alphabetical) within a tier. An empty query returns
+     * every record in importance order.
+     */
     searchLocations(query: string, options?: LookupSearchOptions): Array<MentionLocationMatch>;
+    /** `searchLocations`, one page at a time (20 records per page by default). */
     searchLocationsPagination(options?: LookupPaginationOptions): LookupPaginationResult<MentionLocationMatch>;
     /** The locations a short verse key (e.g. `"EXO 6:23"`) mentions. */
     searchByShortVerse(shortVerse: string, lang?: string): Array<MentionLocationMatch>;

package/types/actionButtonList.d.ts

@@ -0,0 +1,23 @@
+/** Which side of an editor's built-in buttons a host button sits on. */
+export type ActionButtonPlacement = 'before' | 'after';
+/** Host buttons on each side of an editor's built-in buttons, in order. */
+export type PlacedActionButtons<T> = Readonly<{
+    before: ReadonlyArray<T>;
+    after: ReadonlyArray<T>;
+}>;
+/**
+ * The host buttons of one button bar, split around its built-in buttons. Ids are
+ * unique across both sides: adding a button whose id is already present
+ * replaces that button in place, whatever placement is asked for.
+ */
+export declare class ActionButtonList<T extends {
+    readonly id: string;
+}> {
+    private before;
+    private after;
+    get(id: string): T | null;
+    set(actionButton: T, placement: ActionButtonPlacement): void;
+    /** Removes the button with this id; `false` when there was none. */
+    remove(id: string): boolean;
+    snapshot(): PlacedActionButtons<T>;
+}

package/types/bibleNoteHelpers.d.ts

@@ -2,6 +2,7 @@ import type { CSSProperties, ReactNode } from 'react';
 import type { LibraryItems } from './excalidrawTypes';
 import type { Root } from 'react-dom/client';
 import type { BibleNoteEditorControllerOwner, BibleNoteSettingsControllerOwner } from './AppComp';
+import type { BibleNoteFloatingActionButtonControllerOwner } from './floatingActionButtons';
 import type { BibleNoteFooterActionButtonControllerOwner } from './footerActionButtons';
 import type { BibleNoteColorScheme } from './params/colorScheme';
 import type { BibleNoteStorageManager } from './storageManager';
@@ -12,42 +13,148 @@ export type BibleNoteSettingsController = {
     setColorScheme: (mode: BibleNoteColorScheme) => void;
 };
 export type BibleNoteEditorController = Parameters<BibleNoteEditorControllerOwner['connectEditorController']>[0];
+/** A Bible verse as the host renders it: a title line plus the full text. */
 type MentionedBibleDataType = {
+    /** The verse reference as displayed, e.g. `(KJV) Genesis 1:1`. */
     title: string;
+    /**
+     * 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…`.
+     */
     fullText: string;
+    /** Extra CSS for this verse's text, e.g. a font for a non-Latin version. */
     style?: CSSProperties;
 };
+/** Everything `new BibleNote(props)` needs from the host application. */
 export type BibleNoteProps = {
+    /**
+     * The person dataset behind `@` mentions, hover cards, the advanced panel
+     * and the lookup panel. Build it with `NamesLookupManager.fromRawDataset`.
+     */
     namesLookupManager: NamesLookupManager;
+    /**
+     * The place dataset behind `#` mentions, hover cards, the advanced panel and
+     * the lookup panel. Build it with `LocationsLookupManager.fromRawDataset`.
+     */
     locationsLookupManager: LocationsLookupManager;
+    /**
+     * Returns the language code of a piece of text (`'en'` for English). Used to
+     * pick a font for pasted Bible text and Excalidraw text: when it returns a
+     * code other than `'en'`, the editor switches to the first font in
+     * `editorExtraFontFamilies` registered for that language.
+     */
     getLangCode: (text: string) => string;
+    /**
+     * Fonts added to the toolbar's font menu and to Excalidraw, as
+     * `[fontFamily, languageCode]` pairs. The host must load the font faces
+     * itself; pass `[]` for the built-in fonts only.
+     */
     editorExtraFontFamilies: ReadonlyArray<ExtraFontFamilyOption>;
+    /** Extra Excalidraw library items, offered next to the bundled Christian library. */
     excalidrawLibraryItems?: LibraryItems;
+    /** Forgets every Excalidraw library file `excalidrawSaveLibrariesFile` stored. */
     excalidrawClearLibrariesFileList?: () => void;
+    /**
+     * Returns the Excalidraw library files saved earlier (each a serialized
+     * library JSON string); read each time the Excalidraw editor opens.
+     */
     excalidrawLoadLibrariesFileList?: () => string[];
+    /**
+     * Persists a library the user imported in Excalidraw (a serialized library
+     * JSON string) so `excalidrawLoadLibrariesFileList` can return it next time.
+     */
     excalidrawSaveLibrariesFile?: (librariesFile: string) => void;
+    /**
+     * Extra CSS font-family values offered in the sticky-note font picker, e.g.
+     * `'"Fasthand"'`. Pass `[]` for none.
+     */
     stickyNoteExtraFontFamilies: ReadonlyArray<string>;
+    /**
+     * Stores every piece of editor state except the note itself: settings,
+     * comments, read-only mode, zoom, panel state. `createBrowserStorageManager()`
+     * keeps them in `localStorage`. The keys it receives are listed in
+     * `BIBLE_NOTE_STORAGE_MANAGER_KEYS`.
+     */
     storageManager: BibleNoteStorageManager;
+    /**
+     * Saves the note: called with the serialized editor state (a JSON string) on
+     * every change to the document — the same string `BibleNote#content`
+     * returns. Called with `''` when the stored note could not be parsed and is
+     * discarded.
+     */
     saveData: (data: string) => Promise<void> | void;
+    /**
+     * Loads the note saved by `saveData`. Return `null` or `''` for an empty
+     * editor.
+     */
     loadData: () => Promise<string | null> | string | null;
+    /**
+     * Maps a media file the user dropped or picked to a path or URL to store in
+     * the note instead of embedding it as a data URL. Return `null` to fall back
+     * to embedding. In a browser there is usually no path to give; in Electron
+     * this is where a file's location on disk comes from.
+     */
     resolveFilePath?: FilePathResolver;
+    /**
+     * Shows a media file's location to the user (e.g. Electron's
+     * `shell.showItemInFolder`). When provided, a selected image, video, audio or
+     * PDF whose source is a local file path gets a reveal button.
+     */
     revealFile?: FileRevealer;
+    /**
+     * Replaces the footer Print button's built-in printing, which prints the note
+     * laid out at the selected page size.
+     */
     print?: () => void;
+    /**
+     * The editor is embedded in an app rather than a web page: hides the footer's
+     * **Share as Link** and **Convert From Markdown** buttons. Defaults to `false`.
+     */
     isOnApp?: boolean;
+    /**
+     * Compact footer: folds Import, Export and Editor Information into a
+     * **More actions** menu. Defaults to `false`.
+     */
     isMinimize?: boolean;
+    /**
+     * Resolves a short verse key (`GEN 1:1`) to its displayed title and text.
+     * Used for verse lists in mention panels and in the Word export's References
+     * appendix. Without it, those lists show the bare key.
+     */
     shortToVerseData?: (shortText: string) => Promise<MentionedBibleDataType | null>;
+    /**
+     * Lists the short verse keys a verse mention covers, given its full text.
+     * Enables the people and places mentioned in a verse, shown in that verse's
+     * advanced panel and in the Word export.
+     */
     verseFullTextToListShorts?: (fullText: string) => Promise<string[] | null>;
+    /**
+     * Offers the same verse in another Bible version. When provided, the version
+     * label in a verse's advanced panel becomes a button; resolve to the verse in
+     * the chosen version to open it in a new panel, or `null` to do nothing.
+     */
     changeBibleKey?: (event: React.MouseEvent<HTMLButtonElement>, verseFullText: string) => Promise<MentionedBibleDataType | null>;
 };
+/** Options for `BibleNote#render`. */
 export type BibleNoteRenderOptions = {
+    /**
+     * The settings panel to mount, normally `<BibleNoteSettings />`. Omit it and
+     * the editor has no settings panel.
+     */
     settings?: ReactNode;
+    /**
+     * Where to portal the `settings` panel. Without it the panel renders inside
+     * the editor's own layout.
+     */
     settingsContainerElement?: Element | DocumentFragment;
 };
 export declare function createBibleNoteStorageManager({ loadData, saveData, storageManager, }: BibleNoteProps): BibleNoteStorageManager;
-export declare function renderEditor({ props, containerElement, editorControllerOwner, footerActionButtonControllerOwner, settingsControllerOwner, storageManager, }: {
+export declare function renderEditor({ props, containerElement, editorControllerOwner, floatingActionButtonControllerOwner, footerActionButtonControllerOwner, settingsControllerOwner, storageManager, }: {
     props: BibleNoteProps;
     containerElement: HTMLElement;
     editorControllerOwner: BibleNoteEditorControllerOwner;
+    floatingActionButtonControllerOwner: BibleNoteFloatingActionButtonControllerOwner;
     footerActionButtonControllerOwner: BibleNoteFooterActionButtonControllerOwner;
     settingsControllerOwner: BibleNoteSettingsControllerOwner;
     storageManager: BibleNoteStorageManager;

package/types/editorStateStorage.d.ts

@@ -1,3 +1,8 @@
+/**
+ * The storage key of the note itself. The editor never hands this key to the
+ * host's `storageManager`: reads and writes of it go to `loadData` / `saveData`
+ * instead.
+ */
 export declare const EDITOR_STATE_LOCAL_STORAGE_KEY = "lexical-playground-editor-state";
 export declare const SHARED_EDITOR_STATE_QUERY_PARAM = "editor-state";
 export declare const SHARED_EDITOR_STATE_PASSWORD_PREFIX = "pwdecrypted:";

package/types/floatingActionButtons.d.ts

@@ -0,0 +1,118 @@
+import type { MouseEvent as ReactMouseEvent, ReactNode } from 'react';
+import type { PlacedActionButtons } from './actionButtonList';
+/**
+ * A position in the open note, addressed the way the editor addresses it: a
+ * node, and an offset inside that node.
+ */
+export 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';
+}>;
+/**
+ * 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.
+ */
+export 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;
+}>;
+/** What a floating action button's `onClick` receives. */
+export 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 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.
+ */
+export type BibleNoteFloatingActionButton = {
+    /** Unique per editor; adding a button with an existing id replaces it in place. */
+    id: string;
+    /** What the button does: its tooltip and its accessible name. */
+    description: string;
+    /**
+     * 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" />`.
+     */
+    children: ReactNode;
+    /**
+     * 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.
+     */
+    onClick: (event: BibleNoteFloatingActionButtonClickEvent) => void;
+    /**
+     * `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.
+     */
+    isHiddenWhenReadOnly?: boolean;
+};
+/** The host floating toolbar buttons on each side of the built-in ones, in order. */
+export type BibleNoteFloatingActionButtons = PlacedActionButtons<BibleNoteFloatingActionButton>;
+export type BibleNoteFloatingActionButtonController = {
+    setFloatingActionButtons: (actionButtons: BibleNoteFloatingActionButtons) => void;
+};
+export type BibleNoteFloatingActionButtonControllerOwner = {
+    connectFloatingActionButtonController: (controller: BibleNoteFloatingActionButtonController) => () => void;
+};
+export declare const EMPTY_BIBLE_NOTE_FLOATING_ACTION_BUTTONS: BibleNoteFloatingActionButtons;