bible-note 0.4.4 → 0.5.0

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "bible-note",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "A Bible study tool for taking notes and organizing your thoughts.",
   "license": "MIT",
+  "author": "raksa <eng.raksa@gmail.com>",
+  "homepage": "https://github.com/raksa/bible-note-dist#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raksa/bible-note-dist.git"
+  },
+  "bugs": {
+    "url": "https://github.com/raksa/bible-note-dist/issues"
+  },
   "type": "module",
   "main": "./dist/bible-note.cjs",
   "module": "./dist/bible-note.mjs",
@@ -14,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"
   ],
@@ -41,4 +53,4 @@
     "react",
     "notes"
   ]
-}
+}

package/types/BibleNote.d.ts

@@ -2,9 +2,23 @@ import type { BibleNoteFooterActionButton } from './footerActionButtons';
 import type { BibleNoteColorScheme } from './params/colorScheme';
 import { type BibleNoteProps, type BibleNoteRenderOptions } from './bibleNoteHelpers';
 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;
@@ -18,17 +32,56 @@ declare class BibleNote {
     private readonly footerActionButtonControllerOwner;
     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;
@@ -44,7 +97,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 and footer 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/bibleNoteHelpers.d.ts

@@ -12,35 +12,140 @@ 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;

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/footerActionButtons.d.ts

@@ -1,11 +1,30 @@
 import type { ReactNode } from 'react';
+/** A host-supplied button in the editor's footer. */
 export type BibleNoteFooterActionButton = {
+    /** Unique per editor; adding a button with an existing id replaces it in place. */
     id: string;
+    /**
+     * What the button does. Used as the button's tooltip when the button element
+     * has no `title` of its own.
+     */
     description?: string;
+    /**
+     * A keyboard shortcut that clicks the button from anywhere in the page,
+     * written as modifiers plus one key joined by `+`: `"Ctrl+Shift+K"`,
+     * `"Cmd+Shift+K"`, `"Alt+Shift+K"` (`Ctrl`/`Control`, `Cmd`/`Command`/`Meta`,
+     * `Alt`/`Option`, `Shift`). It is appended to the tooltip and set as
+     * `aria-keyshortcuts`.
+     */
     shortcutKey?: string;
+    /**
+     * The button itself, normally a single `<button>`. When it is a single plain
+     * element, the editor adds the tooltip and `aria-keyshortcuts` to it.
+     */
     children: ReactNode;
 };
+/** Which side of the built-in footer buttons a host button sits on. */
 export type BibleNoteFooterActionButtonPlacement = 'before' | 'after';
+/** The host footer buttons on each side of the built-in ones, in order. */
 export type BibleNoteFooterActionButtons = Readonly<{
     before: ReadonlyArray<BibleNoteFooterActionButton>;
     after: ReadonlyArray<BibleNoteFooterActionButton>;

package/types/lookupTypes.d.ts

@@ -21,17 +21,28 @@ export type MentionNameType = 'person' | 'concept' | 'place' | 'group' | 'deity'
  * used for untyped name records.
  */
 export declare function normalizeMentionNameType(type: string | null | undefined): MentionNameType;
+/** A dated span in a person's life, e.g. a reign. */
 export type MentionNameYearRange = {
+    /** What the span is, e.g. `reign` or `coregency`. */
     type: string;
     start: number;
     end: number;
 };
+/** An external reference about a record. */
 export type MentionNameLink = {
+    /** The source, e.g. `wikipedia`, `easton`, `newadvent`. */
     type: string;
     url: string;
 };
+/**
+ * One person/name record — what `NamesLookupManager` searches and returns, and
+ * what an `@` mention shows. Fields holding other records (`parents`,
+ * `locations`, …) hold their ids; resolve them with `getRecordsByIds`.
+ */
 export type MentionNameMatch = {
+    /** Stable record id; mentions in saved notes refer to it. */
     id: string;
+    /** The name as printed in this dataset's Bible text. */
     name: string;
     /**
      * The KJV English name, carried only by translated datasets (the km-BFBS
@@ -43,53 +54,112 @@ export type MentionNameMatch = {
      * translated name the way a Bible book reads "លោកុប្បត្តិ (Genesis)".
      */
     kjvName: string | null;
+    /** A former name (e.g. Abram for Abraham), searchable like `name`; `null` when none. */
     oldName: string | null;
+    /**
+     * A one-line identification ("prophet who led Israel out of Egypt"). Like
+     * `description`, it may carry inline reference links:
+     * `[Egypt](location-id://…)`, `[Amram](name-id://…)`,
+     * `[Genesis 1:1](verse-key://GEN 1:1)`, `[Genesis](book-key://GEN)`,
+     * `[Genesis 14](chapter-key://GEN 14)`.
+     */
     title: string;
+    /** A paragraph about the person, with the same inline links as `title`. */
     description: string;
+    /** `male`, `female` or `unknown` in the generated datasets; `''` when absent. */
     gender: string;
+    /** Age as stated in the text (e.g. `120 years`); `''` when unknown. */
     age: string;
+    /** Dated spans such as a king's reign; usually empty. */
     years: Array<MentionNameYearRange>;
+    /** Ids of location records tied to the person. */
     locations: Array<string>;
+    /** Ids of name records. */
     spouses: Array<string>;
+    /** Ids of name records. */
     children: Array<string>;
+    /** Ids of name records. */
     parents: Array<string>;
+    /** Ids of name records. */
     siblings: Array<string>;
+    /** Ids of name records. */
     cousin: Array<string>;
+    /** The raw type; `normalizeMentionNameType` maps it to a {@link MentionNameType}. */
     type: string;
+    /**
+     * Short verse keys where the Bible prints the name, e.g. `GEN 1:1` or a
+     * collapsed range `1SA 17:1-4` (so the array length is not a verse count).
+     */
     verses: Array<string>;
+    /** External references (Wikipedia, Easton's, New Advent…). */
     links: Array<MentionNameLink>;
+    /** The record's Wikipedia URL, or `null`. */
     wikipedia: string | null;
+    /**
+     * How much the record matters, ascending: 0 is the most important on this
+     * dataset's scale. Orders every listing and breaks ties in search. Records
+     * without a rank get `Infinity` and sort to the very end.
+     */
     matterRange: number;
 };
+/**
+ * A name record as the mention UI displays it: the dataset record, or a
+ * fallback built from what a mention in the note carries when the dataset has
+ * no such record. `id` is `null` when the mention has no record id.
+ */
 export type MentionNamePreview = Omit<MentionNameMatch, 'id'> & {
     id: string | null;
 };
+/** WGS 84 decimal degrees. */
 export type MentionLocationCoordinates = {
     latitude: number;
     longitude: number;
 };
+/** An external reference about a location; same shape as {@link MentionNameLink}. */
 export type MentionLocationLink = {
     type: string;
     url: string;
 };
+/**
+ * One place/location record — what `LocationsLookupManager` searches and
+ * returns, and what a `#` mention shows.
+ */
 export type MentionLocationMatch = {
+    /** Stable record id; mentions in saved notes refer to it. */
     id: string;
+    /** The name as printed in this dataset's Bible text. */
     name: string;
     /** The KJV English name; see {@link MentionNameMatch.kjvName}. */
     kjvName: string | null;
+    /** A former name, searchable like `name`; `null` when none. */
     oldName: string | null;
+    /** A one-line identification, with inline reference links like {@link MentionNameMatch.title}. */
     title: string;
+    /** A paragraph about the place, with the same inline links. */
     description: string;
+    /** The kind of place, e.g. `city`, `region`, `mountain`. */
     type: string;
+    /** Ids of other location records. */
     relatedLocations: Array<string>;
+    /** The modern site or name, when known. */
     modernIdentification: string | null;
     coordinates: MentionLocationCoordinates | null;
+    /** Short verse keys where the Bible prints the name; ranges are collapsed. */
     verses: Array<string>;
+    /** External references (Wikipedia, Easton's, New Advent…). */
     links: Array<MentionLocationLink>;
+    /** The record's Wikipedia URL, or `null`. */
     wikipedia: string | null;
+    /** `true` when the identification or location is uncertain. */
     uncertainty: boolean;
+    /** Importance rank on the same scale as {@link MentionNameMatch.matterRange}. */
     matterRange: number;
 };
+/**
+ * A location record as the mention UI displays it: the dataset record, or a
+ * fallback built from what a mention in the note carries. `id` is `null` when
+ * the mention has no record id.
+ */
 export type MentionLocationPreview = Omit<MentionLocationMatch, 'id'> & {
     id: string | null;
 };
@@ -106,6 +176,10 @@ export declare function getMentionKjvName(record: {
 export declare function getTrimmedString(value: unknown): string;
 export declare function getNullableTrimmedString(value: unknown): string | null;
 export declare function getTrimmedStringArray(value: unknown): Array<string>;
+/**
+ * The records of a raw dataset collection, whether it is an id-keyed object or
+ * a plain array; `[]` for anything else.
+ */
 export declare function getLookupRecordValues(value: unknown): Array<unknown>;
 /**
  * Normalizes one raw dataset entry into a {@link MentionNameMatch}, or returns

package/types/params/BibleNoteSettings.d.ts

@@ -1,6 +1,16 @@
 import type { JSX } from 'react';
 import type { BibleNoteColorScheme } from './colorScheme';
+/** Props of `BibleNoteSettings`. */
 export type BibleNoteSettingsProps = {
+    /**
+     * Called when the Dark Mode switch flips. Pass
+     * `(mode) => bibleNote.setColorScheme(mode)` so the instance stays in step.
+     */
     setColorScheme: (mode: BibleNoteColorScheme) => void;
 };
+/**
+ * The editor's settings panel — a gear button that opens the switches (Dark
+ * Mode, Table Of Contents, …). Pass it to `render` as `options.settings`;
+ * settings persist through the storage manager.
+ */
 export default function BibleNoteSettings({ setColorScheme, }: BibleNoteSettingsProps): JSX.Element;

package/types/params/colorScheme.d.ts

@@ -1,3 +1,11 @@
+/** The editor's two colour schemes. */
 export type BibleNoteColorScheme = 'dark' | 'light';
+/**
+ * Applies a colour scheme to `body` (default `document.body`): toggles the
+ * `playground-theme-dark` / `playground-theme-light` classes and sets
+ * `data-bs-theme`, so Bootstrap's own components follow. Prefer
+ * `BibleNote#setColorScheme` on a mounted editor; this is the bare DOM step.
+ */
 export declare function applyBibleNoteColorScheme(mode: BibleNoteColorScheme, body?: HTMLElement): void;
+/** Removes the theme classes `applyBibleNoteColorScheme` added (leaves `data-bs-theme`). */
 export declare function clearBibleNoteColorScheme(body?: HTMLElement): void;