docs(react): add JSDoc to undocumented hooks and schema factory functions

Add JSDoc documentation with @param and @returns tags to 10 React hooks
(useActiveStyles, useEditorChange, useEditorSelectionBoundingBox,
useEditorSelectionChange, useFocusWithin, useOnUploadEnd, useOnUploadStart,
usePrefersColorScheme, useSelectedBlocks, useUploadLoading) and 2 schema
factory functions (createReactInlineContentSpec, createReactStyleSpec).

Nightshift-Task: docs-backfill
Nightshift-Ref: https://github.com/marcus/nightshift
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Nick the Sick

packages/react/src/hooks/useActiveStyles.ts

@@ -3,6 +3,15 @@ import { BlockNoteEditor, Styles, StyleSchema } from "@blocknote/core";
 import { useBlockNoteContext } from "../editor/BlockNoteContext.js";
 import { useEditorState } from "./useEditorState.js";
 
+/**
+ * Returns the currently active text styles (e.g., bold, italic) at the editor's
+ * current cursor position or selection. Re-renders automatically when the active
+ * styles change.
+ *
+ * @param editor - The BlockNote editor instance. If omitted, uses the editor
+ * from the nearest `BlockNoteContext`.
+ * @returns The set of active styles at the current cursor position or selection.
+ */
 export function useActiveStyles<T extends StyleSchema>(
   editor?: BlockNoteEditor<any, any, T>,
 ): Styles<T> {

packages/react/src/hooks/useEditorChange.ts

@@ -2,6 +2,15 @@ import type { BlockNoteEditor } from "@blocknote/core";
 import { useEffect } from "react";
 import { useBlockNoteContext } from "../editor/BlockNoteContext.js";
 
+/**
+ * Subscribes to editor content changes. The callback is invoked whenever the
+ * editor's document is modified, and the subscription is automatically cleaned
+ * up when the component unmounts.
+ *
+ * @param callback - Function called when the editor content changes.
+ * @param editor - The BlockNote editor instance. If omitted, uses the editor
+ * from the nearest `BlockNoteContext`.
+ */
 export function useEditorChange(
   callback: Parameters<BlockNoteEditor<any, any, any>["onChange"]>[0],
   editor?: BlockNoteEditor<any, any, any>,

packages/react/src/hooks/useEditorSelectionBoundingBox.ts

@@ -1,6 +1,18 @@
 import type { BlockNoteEditor } from "@blocknote/core";
 import { useEditorState } from "./useEditorState.js";
 
+/**
+ * Returns the bounding box (`DOMRect`) of the current editor selection.
+ * Re-renders automatically when the selection changes. Useful for positioning
+ * floating UI elements (e.g., toolbars, tooltips) relative to the selection.
+ *
+ * @param enabled - Whether to compute the bounding box. When `false`, returns
+ * `undefined` without measuring.
+ * @param editor - The BlockNote editor instance. If omitted, uses the editor
+ * from the nearest `BlockNoteContext`.
+ * @returns The `DOMRect` of the current selection, or `undefined` if disabled
+ * or no selection exists.
+ */
 export function useEditorSelectionBoundingBox(
   enabled?: boolean,
   editor?: BlockNoteEditor<any, any, any>,

packages/react/src/hooks/useEditorSelectionChange.ts

@@ -2,6 +2,17 @@ import type { BlockNoteEditor } from "@blocknote/core";
 import { useEffect } from "react";
 import { useBlockNoteContext } from "../editor/BlockNoteContext.js";
 
+/**
+ * Subscribes to editor selection changes. The callback is invoked whenever the
+ * user's cursor position or text selection changes, and the subscription is
+ * automatically cleaned up when the component unmounts.
+ *
+ * @param callback - Function called when the selection changes.
+ * @param editor - The BlockNote editor instance. If omitted, uses the editor
+ * from the nearest `BlockNoteContext`.
+ * @param includeSelectionChangedByRemote - Whether to also fire the callback
+ * when the selection is changed by a remote collaborator. Defaults to `false`.
+ */
 export function useEditorSelectionChange(
   callback: () => void,
   editor?: BlockNoteEditor<any, any, any>,

packages/react/src/hooks/useFocusWithin.ts

@@ -17,6 +17,18 @@ function containsRelatedTarget(event: FocusEvent) {
   return false;
 }
 
+/**
+ * Tracks whether focus is within a referenced DOM element. Returns a ref to
+ * attach to the target element and a `focused` boolean that is `true` whenever
+ * the element or any of its descendants has focus.
+ *
+ * Adapted from Mantine's `useFocusWithin` hook.
+ *
+ * @param options - Optional `onFocus` and `onBlur` callbacks fired when focus
+ * enters or leaves the element.
+ * @returns An object with a `ref` to attach to the target element and a
+ * `focused` boolean indicating current focus-within state.
+ */
 export function useFocusWithin<T extends HTMLElement = any>({
   onBlur,
   onFocus,

packages/react/src/hooks/useOnUploadEnd.ts

@@ -1,6 +1,14 @@
 import { useEffect } from "react";
 import { useBlockNoteEditor } from "./useBlockNoteEditor.js";
 
+/**
+ * Subscribes to file upload completion events. The callback is invoked whenever
+ * a file upload finishes within the editor, and the subscription is
+ * automatically cleaned up when the component unmounts.
+ *
+ * @param callback - Function called when an upload completes. Receives the
+ * `blockId` of the block whose upload finished, if available.
+ */
 export function useOnUploadEnd(callback: (blockId?: string) => void) {
   const editor = useBlockNoteEditor();
 

packages/react/src/hooks/useOnUploadStart.ts

@@ -1,6 +1,14 @@
 import { useEffect } from "react";
 import { useBlockNoteEditor } from "./useBlockNoteEditor.js";
 
+/**
+ * Subscribes to file upload start events. The callback is invoked whenever a
+ * file upload begins within the editor, and the subscription is automatically
+ * cleaned up when the component unmounts.
+ *
+ * @param callback - Function called when an upload starts. Receives the
+ * `blockId` of the block where the upload was initiated, if available.
+ */
 export function useOnUploadStart(callback: (blockId?: string) => void) {
   const editor = useBlockNoteEditor();
 

packages/react/src/hooks/usePrefersColorScheme.ts

@@ -4,6 +4,15 @@
 // issues when used in a NextJS project.
 import { useEffect, useMemo, useState } from "react";
 
+/**
+ * Returns the user's preferred color scheme (`"dark"`, `"light"`, or
+ * `"no-preference"`) based on the `prefers-color-scheme` media query.
+ * Automatically updates when the system preference changes.
+ *
+ * Adapted from the `use-prefers-color-scheme` package.
+ *
+ * @returns `"dark"`, `"light"`, or `"no-preference"`.
+ */
 export const usePrefersColorScheme = () => {
   const darkQuery = useMemo(
     () => window.matchMedia?.("(prefers-color-scheme: dark)"),

packages/react/src/hooks/useSelectedBlocks.ts

@@ -6,6 +6,16 @@ import {
 } from "@blocknote/core";
 import { useEditorState } from "./useEditorState.js";
 
+/**
+ * Returns the blocks that are currently selected in the editor. If no
+ * multi-block selection exists, returns an array containing the single block
+ * at the text cursor position. Re-renders automatically when the selection
+ * changes.
+ *
+ * @param editor - The BlockNote editor instance. If omitted, uses the editor
+ * from the nearest `BlockNoteContext`.
+ * @returns An array of the currently selected blocks.
+ */
 export function useSelectedBlocks<
   BSchema extends BlockSchema,
   ISchema extends InlineContentSchema,

packages/react/src/hooks/useUploadLoading.ts

@@ -2,6 +2,13 @@ import { useState } from "react";
 import { useOnUploadEnd } from "./useOnUploadEnd.js";
 import { useOnUploadStart } from "./useOnUploadStart.js";
 
+/**
+ * Tracks whether a file upload is in progress for a specific block. Returns
+ * `true` while the upload is active and `false` otherwise.
+ *
+ * @param blockId - The ID of the block to monitor for upload activity.
+ * @returns `true` if a file upload is currently in progress for the given block.
+ */
 export function useUploadLoading(blockId?: string) {
   const [showLoader, setShowLoader] = useState(false);