bible-note 0.4.7 → 0.6.0

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

@@ -13,6 +13,7 @@ export { EDITOR_STATE_LOCAL_STORAGE_KEY } from './editorStateStorage';
 export { applyBibleNoteColorScheme, clearBibleNoteColorScheme, } from './params/colorScheme';
 export { BIBLE_NOTE_STORAGE_MANAGER_KEYS, createBrowserStorageManager, } from './storageManager';
 export { getLookupRecordValues, getMentionKjvName, LocationsLookupManager, NamesLookupManager, normalizeMentionNameType, parseMentionLocationMatch, parseMentionLocationMatches, parseMentionNameMatch, parseMentionNameMatches, } from './LookupManager';
+export type { BibleNoteFloatingActionButton, BibleNoteFloatingActionButtonClickEvent, BibleNoteFloatingActionButtons, BibleNoteSelectionPoint, BibleNoteTextSelection, } from './floatingActionButtons';
 export type { BibleNoteFooterActionButton, BibleNoteFooterActionButtonPlacement, BibleNoteFooterActionButtons, } from './footerActionButtons';
 export type { BibleNoteProps, BibleNoteRenderOptions, } from './bibleNoteHelpers';
 export type { LocationsLookupManagerDataMap, LocationsLookupManagerLangData, LookupManagerStyle, LookupPaginationOptions, LookupPaginationResult, LookupSearchOptions, MentionLocationCoordinates, MentionLocationLink, MentionLocationMatch, MentionLocationPreview, MentionNameLink, MentionNameMatch, MentionNamePreview, MentionNameType, MentionNameYearRange, NamesLookupManagerDataMap, NamesLookupManagerLangData, NamesLookupPaginationOptions, NamesLookupSearchOptions, NameTypeCount, VerseRecordIdsMap, } from './LookupManager';

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;

package/types/storageManager.d.ts

@@ -1,12 +1,32 @@
+/**
+ * Where the editor keeps its own state — settings, comments, read-only mode,
+ * zoom, panel state — as string values under the keys in
+ * `BIBLE_NOTE_STORAGE_MANAGER_KEYS`. The note itself goes through
+ * `loadData` / `saveData` instead. Every key is read once, before the editor
+ * first renders; writes are fire-and-forget.
+ */
 export type BibleNoteStorageManager = {
+    /** Stores `value` (a string, or a value to `JSON.stringify`) under `key`. */
     setSetting(key: string, value: unknown): Promise<void>;
+    /** The value stored under `key`, or `null` when there is none. */
     getSetting<T = unknown>(key: string): Promise<T | null>;
+    /** Removes `key`. */
     deleteSetting(key: string): Promise<void>;
 };
 type BibleNoteStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+/**
+ * Every key the editor reads from its storage manager before it renders. A
+ * host-side store that needs to know its keys up front (to prefetch or migrate
+ * them) can use this list.
+ */
 export declare const BIBLE_NOTE_STORAGE_MANAGER_KEYS: readonly ["lexical-playground-settings", "lexical-playground-editor-state", "lexical-playground-comments", "lexical-playground-comments-panel-open", "lexical-playground-block-text-links", "lexical-playground-read-only-mode", "lexical-playground-insert-character-picker", "lexical-playground-editor-zoom-percent"];
 export declare function configureBibleNoteStorageManager(storageManager?: BibleNoteStorageManager): void;
 export declare function hydrateBibleNoteStorageManager(keys: ReadonlyArray<string>): Promise<void>;
 export declare function getBibleNoteStorage(): BibleNoteStorage | null;
+/**
+ * A `BibleNoteStorageManager` backed by `window.localStorage`. Non-string
+ * values are stored as JSON; when `localStorage` is unavailable every call is
+ * a no-op.
+ */
 export declare function createBrowserStorageManager(): BibleNoteStorageManager;
 export {};

package/types/utils/filePathResolver.d.ts

@@ -1,8 +1,15 @@
+/** How a media file reached the editor: dropped/pasted, or picked in the media dialog. */
 export type FilePathSource = 'drop' | 'file-input';
+/** Context passed to a `FilePathResolver`. */
 export type FilePathResolverContext = Readonly<{
     source: FilePathSource;
 }>;
+/**
+ * Maps a media file to the path or URL the note should reference. Return
+ * `null` (or throw) to let the editor embed the file as a data URL instead.
+ */
 export type FilePathResolver = (file: File, context: FilePathResolverContext) => Promise<string | null> | string | null;
+/** Shows a local media file to the user, e.g. in the system file manager. */
 export type FileRevealer = (filePath: string) => Promise<void> | void;
 export declare function getFallbackFilePath(file: File): string;
 export declare function resolveMediaFilePath(resolver: FilePathResolver | undefined, file: File, source: FilePathSource): Promise<string | null>;

package/types/utils/fontFamilyOptions.d.ts

@@ -5,11 +5,17 @@
  * LICENSE file in the root directory of this source tree.
  *
  */
+/** A font in the toolbar's font menu: `[fontFamily, label, languageCode]`. */
 export type FontFamilyOption = readonly [
     fontFamily: string,
     label: string,
     language: string
 ];
+/**
+ * A host font added to the editor: `[fontFamily, languageCode]`, e.g.
+ * `['Battambang', 'km']`. The language code is what `getLangCode` returns
+ * for text that should use this font.
+ */
 export type ExtraFontFamilyOption = readonly [
     fontFamily: string,
     language: string