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

[nperez0111]

Summary

• Added JSDoc documentation (@param, @returns, description) to 10 undocumented React hooks: useActiveStyles, useEditorChange, useEditorSelectionBoundingBox, useEditorSelectionChange, useFocusWithin, useOnUploadEnd, useOnUploadStart, usePrefersColorScheme, useSelectedBlocks, useUploadLoading
• Added JSDoc documentation to 2 schema factory functions: createReactInlineContentSpec, createReactStyleSpec
• Improves JSDoc coverage in @blocknote/react from 28.6% to 100% for hooks and schema specs

Test plan

• Changes are JSDoc comments only — no runtime behavior affected
• Verify build passes (CI)

🤖 Generated with Claude Code

Nightshift-Task: docs-backfill
Nightshift-Ref: https://github.com/marcus/nightshift

Summary by CodeRabbit

• Documentation
  • Added JSDoc documentation to React hooks for improved IDE support and developer experience
  • Enhanced documentation for schema creation utilities with detailed parameter descriptions and return type specifications

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
blocknote	Ready	Preview	Mar 21, 2026 10:14pm
blocknote-website	Ready	Preview	Mar 21, 2026 10:14pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a31d89cb-0cfc-413d-b1ce-de2df17560db

📥 Commits

Reviewing files that changed from the base of the PR and between 3f642c8 and 201b994.

📒 Files selected for processing (12)

• packages/react/src/hooks/useActiveStyles.ts
• packages/react/src/hooks/useEditorChange.ts
• packages/react/src/hooks/useEditorSelectionBoundingBox.ts
• packages/react/src/hooks/useEditorSelectionChange.ts
• packages/react/src/hooks/useFocusWithin.ts
• packages/react/src/hooks/useOnUploadEnd.ts
• packages/react/src/hooks/useOnUploadStart.ts
• packages/react/src/hooks/usePrefersColorScheme.ts
• packages/react/src/hooks/useSelectedBlocks.ts
• packages/react/src/hooks/useUploadLoading.ts
• packages/react/src/schema/ReactInlineContentSpec.tsx
• packages/react/src/schema/ReactStyleSpec.tsx

---

📝 Walkthrough

Walkthrough

This pull request adds comprehensive JSDoc documentation comments to 11 React hooks and schema utility functions in the packages/react/src directory. The additions describe hook purposes, parameters, return values, and behaviors without modifying any runtime logic, control flow, or exported API signatures.

Changes

Cohort / File(s)	Summary
Editor State Hooks packages/react/src/hooks/useActiveStyles.ts, useEditorChange.ts, useEditorSelectionBoundingBox.ts, useEditorSelectionChange.ts, useSelectedBlocks.ts	Added JSDoc blocks documenting hook purposes, parameter behavior (including optional editor fallback from BlockNoteContext), return values, and re-render triggers tied to editor state changes.
UI Interaction Hooks packages/react/src/hooks/useFocusWithin.ts	Added JSDoc documentation describing focus-within tracking behavior, ref attachment, boolean focused state, and optional onFocus/onBlur callbacks.
Upload Event Hooks packages/react/src/hooks/useOnUploadStart.ts, useOnUploadEnd.ts, useUploadLoading.ts	Added JSDoc blocks documenting subscription to file upload events, callback invocation semantics, automatic cleanup on unmount, and progress tracking for specific block IDs.
Theme Preference Hook packages/react/src/hooks/usePrefersColorScheme.ts	Added JSDoc documentation describing returned values ("dark", "light", "no-preference"), derivation from prefers-color-scheme media queries, and reactivity to system preference changes.
Schema Specification Functions packages/react/src/schema/ReactInlineContentSpec.tsx, ReactStyleSpec.tsx	Added comprehensive JSDoc blocks describing each function as React counterparts to vanilla spec creators, detailing expected configuration objects, implementation parameters, and return types suitable for editor schemas.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 With whiskers twitched and paws so keen,
I've penned the docs that were unseen,
Each hook now shines with clarity bright,
JSDoc blocks in organized might! ✨
The code speaks clear, no guessing game—
Context and purpose, now they're named!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description covers summary and test plan well, but lacks rationale, detailed changes, impact, and checklist sections required by the template.	Expand the description to include rationale explaining benefits, detailed list of major changes per file, potential impacts, and complete the checklist to align with the repository template.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding JSDoc documentation to React hooks and schema factory functions.
Docstring Coverage	✅ Passed	Docstring coverage is 92.31% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/react-hooks-jsdoc

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@blocknote/ariakit

npm i https://pkg.pr.new/@blocknote/ariakit@2582

@blocknote/code-block

npm i https://pkg.pr.new/@blocknote/code-block@2582

@blocknote/core

npm i https://pkg.pr.new/@blocknote/core@2582

@blocknote/mantine

npm i https://pkg.pr.new/@blocknote/mantine@2582

@blocknote/react

npm i https://pkg.pr.new/@blocknote/react@2582

@blocknote/server-util

npm i https://pkg.pr.new/@blocknote/server-util@2582

@blocknote/shadcn

npm i https://pkg.pr.new/@blocknote/shadcn@2582

@blocknote/xl-ai

npm i https://pkg.pr.new/@blocknote/xl-ai@2582

@blocknote/xl-docx-exporter

npm i https://pkg.pr.new/@blocknote/xl-docx-exporter@2582

@blocknote/xl-email-exporter

npm i https://pkg.pr.new/@blocknote/xl-email-exporter@2582

@blocknote/xl-multi-column

npm i https://pkg.pr.new/@blocknote/xl-multi-column@2582

@blocknote/xl-odt-exporter

npm i https://pkg.pr.new/@blocknote/xl-odt-exporter@2582

@blocknote/xl-pdf-exporter

npm i https://pkg.pr.new/@blocknote/xl-pdf-exporter@2582

commit: 201b994