From 201b9946ffef2ec7c68c8a31e09425243e77fe19 Mon Sep 17 00:00:00 2001 From: Nick the Sick Date: Sat, 21 Mar 2026 23:10:55 +0100 Subject: [PATCH] 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) --- packages/react/src/hooks/useActiveStyles.ts | 9 +++++++++ packages/react/src/hooks/useEditorChange.ts | 9 +++++++++ .../src/hooks/useEditorSelectionBoundingBox.ts | 12 ++++++++++++ .../react/src/hooks/useEditorSelectionChange.ts | 11 +++++++++++ packages/react/src/hooks/useFocusWithin.ts | 12 ++++++++++++ packages/react/src/hooks/useOnUploadEnd.ts | 8 ++++++++ packages/react/src/hooks/useOnUploadStart.ts | 8 ++++++++ packages/react/src/hooks/usePrefersColorScheme.ts | 9 +++++++++ packages/react/src/hooks/useSelectedBlocks.ts | 10 ++++++++++ packages/react/src/hooks/useUploadLoading.ts | 7 +++++++ .../react/src/schema/ReactInlineContentSpec.tsx | 15 +++++++++++++-- packages/react/src/schema/ReactStyleSpec.tsx | 13 +++++++++++-- 12 files changed, 119 insertions(+), 4 deletions(-) diff --git a/packages/react/src/hooks/useActiveStyles.ts b/packages/react/src/hooks/useActiveStyles.ts index a539d50f71..93ad08d3a1 100644 --- a/packages/react/src/hooks/useActiveStyles.ts +++ b/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( editor?: BlockNoteEditor, ): Styles { diff --git a/packages/react/src/hooks/useEditorChange.ts b/packages/react/src/hooks/useEditorChange.ts index 70e455a1f9..ade26292eb 100644 --- a/packages/react/src/hooks/useEditorChange.ts +++ b/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["onChange"]>[0], editor?: BlockNoteEditor, diff --git a/packages/react/src/hooks/useEditorSelectionBoundingBox.ts b/packages/react/src/hooks/useEditorSelectionBoundingBox.ts index 12200e0b2a..bb097a09f7 100644 --- a/packages/react/src/hooks/useEditorSelectionBoundingBox.ts +++ b/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, diff --git a/packages/react/src/hooks/useEditorSelectionChange.ts b/packages/react/src/hooks/useEditorSelectionChange.ts index 9260f38552..08225fc88f 100644 --- a/packages/react/src/hooks/useEditorSelectionChange.ts +++ b/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, diff --git a/packages/react/src/hooks/useFocusWithin.ts b/packages/react/src/hooks/useFocusWithin.ts index 992bcc60cd..d4fff7d03c 100644 --- a/packages/react/src/hooks/useFocusWithin.ts +++ b/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({ onBlur, onFocus, diff --git a/packages/react/src/hooks/useOnUploadEnd.ts b/packages/react/src/hooks/useOnUploadEnd.ts index b5d346e287..3757fdd203 100644 --- a/packages/react/src/hooks/useOnUploadEnd.ts +++ b/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(); diff --git a/packages/react/src/hooks/useOnUploadStart.ts b/packages/react/src/hooks/useOnUploadStart.ts index 0a31b66cb9..e042681f61 100644 --- a/packages/react/src/hooks/useOnUploadStart.ts +++ b/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(); diff --git a/packages/react/src/hooks/usePrefersColorScheme.ts b/packages/react/src/hooks/usePrefersColorScheme.ts index 9dc982c000..60872ebc0d 100644 --- a/packages/react/src/hooks/usePrefersColorScheme.ts +++ b/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)"), diff --git a/packages/react/src/hooks/useSelectedBlocks.ts b/packages/react/src/hooks/useSelectedBlocks.ts index 2f5612aae9..79058d74f2 100644 --- a/packages/react/src/hooks/useSelectedBlocks.ts +++ b/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, diff --git a/packages/react/src/hooks/useUploadLoading.ts b/packages/react/src/hooks/useUploadLoading.ts index af55cb9c36..df4f8c572a 100644 --- a/packages/react/src/hooks/useUploadLoading.ts +++ b/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); diff --git a/packages/react/src/schema/ReactInlineContentSpec.tsx b/packages/react/src/schema/ReactInlineContentSpec.tsx index 341c8981e5..84df6cefb7 100644 --- a/packages/react/src/schema/ReactInlineContentSpec.tsx +++ b/packages/react/src/schema/ReactInlineContentSpec.tsx @@ -94,8 +94,19 @@ export function InlineContentWrapper< ); } -// A function to create custom block for API consumers -// we want to hide the tiptap node from API consumers and provide a simpler API surface instead +/** + * Creates a custom inline content specification for use with React. This is the + * React counterpart to the vanilla `createInlineContentSpec` and lets you define + * custom inline content types (e.g., mentions, tags) using React components for + * rendering. + * + * @param inlineContentConfig - The inline content type configuration, including + * its `type` name, `propSchema`, and `content` mode (`"styled"` or `"none"`). + * @param inlineContentImplementation - The React implementation, including a + * `render` component and optionally a `toExternalHTML` component and `parse` + * rules. + * @returns An `InlineContentSpec` that can be passed to the editor's schema. + */ export function createReactInlineContentSpec< const T extends CustomInlineContentConfig, // I extends InlineContentSchema, diff --git a/packages/react/src/schema/ReactStyleSpec.tsx b/packages/react/src/schema/ReactStyleSpec.tsx index 27ecbed323..1b6825e0b5 100644 --- a/packages/react/src/schema/ReactStyleSpec.tsx +++ b/packages/react/src/schema/ReactStyleSpec.tsx @@ -26,8 +26,17 @@ export type ReactCustomStyleImplementation = { runsBefore?: string[]; }; -// A function to create custom block for API consumers -// we want to hide the tiptap node from API consumers and provide a simpler API surface instead +/** + * Creates a custom style specification for use with React. This is the React + * counterpart to the vanilla `createStyleSpec` and lets you define custom text + * styles (e.g., font color, highlight) using React components for rendering. + * + * @param styleConfig - The style configuration, including its `type` name and + * `propSchema` (`"boolean"` or `"string"`). + * @param styleImplementation - The React implementation, including a `render` + * component that receives the style value, a `contentRef`, and the editor. + * @returns A style spec that can be passed to the editor's schema. + */ export function createReactStyleSpec( styleConfig: T, styleImplementation: ReactCustomStyleImplementation,