@bayonai/rich-text-editor 0.1.2 → 1.0.0

package/BEHAVIOR.md

@@ -0,0 +1,396 @@
+# Rich Text Editor Behavior
+
+This document describes the visible behavior and internal structure contracts for
+`@bayonai/rich-text-editor`. It is intended for maintainers changing editor
+behavior. Public package APIs and the persisted `RichTextBlock` shape should
+remain stable unless a migration is explicitly planned.
+
+## Core Model
+
+The saved document model is `RichTextBlock[]`.
+
+Top-level blocks can be paragraphs, headings, quotes, code, dividers, images,
+bullets, ordered rows, checkboxes, or toggles. Only tree rows are nestable:
+
+- `bullet`
+- `ordered`
+- `checkbox`
+- `toggle`
+
+Tree rows carry child blocks in `children`. Toggles also carry `collapsed`.
+Checkboxes also carry `checked`.
+
+Paragraphs, headings, and quotes currently stay flat. Do not introduce generic
+block nesting unless the editor model and persistence boundaries are planned
+for it.
+
+## Source Responsibilities
+
+- `src/core/types.ts` defines the persisted block shape.
+- `src/core/richText.ts` owns sanitization, Markdown conversion, clipboard
+  encode/decode, and public non-React helpers.
+- `src/react/editor/RichTextEditor.tsx` owns the editable DOM, semantic edit
+  handlers, DOM-to-block parsing, editor HTML serialization, selection
+  restoration, and keyboard behavior.
+- `src/react/editor/RichTextBody.tsx` is the `contentEditable` shell and should
+  stay thin.
+- `src/react/editor/blockActions.ts` owns pure block operations such as split,
+  delete, indent, outdent, reorder, and clipboard text for block actions.
+- `src/react/editor/RichTextRenderedBlock.tsx` owns read-only rendering and must
+  stay visually aligned with editor rendering.
+- `src/react/styles/RichTextStyles.tsx` owns package styles for both editable
+  and read-only surfaces.
+
+When possible, add behavior in pure helpers first, cover it with focused tests,
+then connect it to the editable DOM.
+
+## Component Behavior Inventory
+
+The React package surface is intentionally small. Keep these responsibilities
+stable so host apps can compose the editor without depending on private DOM
+details.
+
+- `RichTextEditor` is the full controlled editing experience. It composes the
+  title, document surface, editable body, selection toolbar, special block
+  insertion tool, block action handles, drag/drop state, stats, and optional
+  transcription. It must emit sanitized `RichTextBlock[]` updates through
+  `onContentBlocksChange` and title updates through `onTitleChange`.
+- `RichTextDocumentSurface` provides the shared editor/read-only document
+  frame. It owns only the transparent vs panel background shell and should not
+  learn editor state or block semantics.
+- `RichTextTitleInput` renders the editable auto-growing title textarea.
+  `Enter` and `ArrowDown` move focus to the start of the body. Validation text
+  is announced with `role="alert"` and the input exposes invalid/required ARIA
+  state.
+- `RichTextReadTitle` renders the read-only title with the same textarea
+  sizing and package title styles as the editable title. Use it for view/edit
+  parity instead of duplicating title chrome in host apps.
+- `RichTextBody` is the only `contentEditable` surface. It delegates semantic
+  Enter, Backspace, Delete, Tab, paste, toggle-collapse, and formatting shortcut
+  behavior to `RichTextEditor`; it should stay a thin event boundary.
+- `RichTextRenderer` renders sanitized blocks for read-only views and injects
+  the shared package styles. When `onContentBlocksChange` is supplied, rendered
+  toggles are interactive and persist collapsed-state changes through the same
+  block shape.
+- `RichTextRenderedBlocks` and `RichTextRenderedBlock` own read-only block
+  markup. They group adjacent tree rows into semantic `ul`/`ol` lists, render
+  nested children recursively, preserve checkbox checked state, and keep toggle
+  title/content structure aligned with the editor DOM.
+- `RichTextStyleScope` injects the package CSS needed by editor, renderer,
+  title, transcription, block tools, and unsaved-change dialog surfaces. New
+  visible package components should reuse these classes rather than shipping
+  app-specific styles.
+- `SelectionFormatToolbar` is the floating selection toolbar. It uses icon
+  buttons with labels/tooltips for bold, italic, link, title, quote, and code,
+  and it must keep mouse-down from stealing the active text selection.
+- `SpecialBlockTool` and `SpecialBlockOption` render the floating add-block
+  control for empty insertion targets. The action catalog is the single source
+  of truth for special block labels, icons, inserted HTML, and initial focus
+  behavior.
+- `BlockActionTool` renders each visible block handle and its copy, cut, delete,
+  and close icon controls. It owns pointer capture/suppressed-click behavior for
+  drag handles, but block movement and clipboard semantics stay in pure helpers.
+- `TranscriptionControl` owns browser `SpeechRecognition` integration. It must
+  remain browser-local, expose clear ready/recording/success/error/unavailable
+  states, stop recording on unmount, and report final transcript text through
+  `onTranscript` only. It must treat mobile Safari as unavailable even when
+  `webkitSpeechRecognition` exists, because those sessions can get stuck.
+- `EditorSessionProvider` owns the shared unsaved-change registry, beforeunload
+  guard, and pending-exit dialog. Use `useEditorSession` for a controlled
+  editor's dirty/save/reset state and `useEditorExitGuard` for route/navigation
+  guards.
+- `UnsavedChangesDialog` is the default pending-exit UI. It lets users stay,
+  discard and leave, or save and leave; backdrop clicks stay on the page unless
+  a save is in progress, and save errors are announced.
+- `RichTextIcons` are package-local presentational icons. They should stay
+  side-effect free and accessible labels should live on the buttons that render
+  them.
+
+## Baseline Patterns Intention
+
+- Treat every visible row as a block. Paragraphs, headings, quotes, code,
+  media placeholders, dividers, list rows, checkboxes, and toggles should all
+  feel independently selectable, movable, copyable, and deletable when that
+  action is supported.
+- Keep creation shortcuts lightweight and Markdown-like. A user should be able
+  to create common structure from the keyboard without opening menus: list
+  markers, checkbox syntax, numbered rows, headings, quotes, toggles, dividers,
+  and code blocks should remain discoverable through text shortcuts.
+- Prefer contextual chrome over persistent controls. Block handles, insertion
+  tools, drag affordances, and selection formatting should appear near the
+  active or hovered content and stay quiet when the user is simply reading or
+  typing.
+- Preserve keyboard-first editing. Enter creates the next natural row,
+  Shift+Enter creates an intentional soft break, Tab and Shift+Tab change list
+  hierarchy, Backspace exits or removes structure at the beginning of a block,
+  and common formatting shortcuts should not require the mouse.
+- Keep block transforms conceptually reversible. When a row changes from one
+  type to another, preserve its visible text and caret position where practical
+  instead of treating the action as delete plus recreate.
+- Make toggles manual and predictable. Toggle state changes only when the user
+  activates the toggle control or an explicit shortcut. Collapsing hides child
+  content visually but must not mutate, reorder, or discard those children.
+- Keep drag/drop scoped to obvious block movement. Moving a block should move
+  its subtree, show a precise destination indicator, and avoid accidental
+  structural changes when the pointer is released on an invalid or ambiguous
+  target.
+- Keep read-only output visually faithful to editing output. Users should not
+  need to learn a different document shape when switching between edit and
+  view modes.
+- Keep mobile editing uncluttered. Favor the document content and the current
+  action target; avoid always-visible heavy toolbars, wide controls, or
+  side-scrolling layouts.
+- Use icon buttons with accessible labels and tooltips for compact editor
+  controls. Text labels belong in menus, dialogs, validation, and ambiguous
+  destructive flows where the extra clarity is worth the space.
+
+## Current Baseline Discrepancies
+
+These are known places where the current editor does not fully meet the
+baseline patterns above. Treat this section as implementation guidance for
+future editor polish, not as permission to broaden unrelated bug fixes.
+
+- Block transforms are only partial. Text shortcuts create structure, Backspace
+  can convert supported tree rows back to paragraphs, and the selection toolbar
+  can format selected text as heading, quote, or code. There is not yet a
+  general row-level transform menu for changing an existing block between
+  paragraph, heading, quote, list row, checkbox, toggle, code, divider, or image
+  while preserving text, children, and caret placement.
+- The shortcut set is intentionally smaller than a full Notion-style shortcut
+  map. The editor supports common patterns such as `# `, `> `, `>> `, `- `,
+  `* `, `1. `, `[]`, `[x]`, divider markers, and fenced-code starts, but it
+  does not expose multiple heading levels, slash commands, or Notion-exact
+  toggle/list shortcuts.
+- The floating special-block insertion tool does not expose every basic block
+  type. It currently includes image, quote, title, bullet list, toggle, code
+  block, embedded HTML, and divider. Ordered rows and checkboxes are keyboard
+  shortcuts only unless a host builds additional chrome.
+- Keyboard behavior covers core editing but not full block navigation. There is
+  no dedicated block-selection mode, no keyboard command for opening the block
+  action menu, no shortcut to toggle a checkbox or collapse a toggle from
+  anywhere in the row, and no expand/collapse-all toggle command.
+- Read-only rendering is close to edit-mode structure, but it is not a perfect
+  mirror. Empty toggle content is omitted in read-only output, URL-backed image
+  blocks render their image, upload-progress placeholders stay editor-only, and
+  read-only block actions are not available.
+- Mobile simplicity is an intention rather than a fully verified contract. The
+  editor uses contextual controls, but viewport-level checks should verify that
+  block handles, selection toolbar, special-block tool, transcription control,
+  and nested toggle/list rows do not create horizontal scrolling or obscure the
+  active text target on small screens.
+
+## Tree Row Structure
+
+Bullets, ordered rows, checkboxes, and toggles are all tree rows. Shared tree
+row behavior should use shared helpers rather than type-specific branches.
+
+Shared concepts:
+
+- row detection: `getTreeRowEditorParts(...)`
+- label focus: `focusTreeRowLabelAtTextOffset(...)`
+- Enter splitting: `splitTreeRowMarkdownAtTextOffset(...)` and
+  `splitTreeRowBlock(...)`
+- Backspace paragraph exit:
+  `getTreeRowBackspaceParagraphMarkdown(...)` and
+  `getTreeRowBackspaceFocusPositionForParagraph(...)`
+- nesting: `indentBlock(...)`, `outdentBlock(...)`, `reorderBlock(...)`
+
+Type-specific behavior should be limited to actual type differences:
+
+- bullet marker vs ordered counter vs checkbox input
+- checkbox `checked` state
+- toggle `collapsed` state and content box
+- clipboard prefixes such as `- `, `1. `, `[ ] `, and `[x] `
+
+## Cursor Behavior Guidelines
+
+Prefer visually consistent behavior over a technically pure model
+interpretation.
+
+Selection and toolbar behavior:
+
+- Text selection shows the formatting toolbar above block handles and hover
+  zones.
+- While a selection toolbar is active, formatting controls take priority over
+  block drag controls.
+
+Backspace at the beginning of a tree-row label:
+
+- Empty bullet exits to a paragraph containing `*`, with the caret after `*`.
+- Empty ordered row exits to a paragraph containing `1.`, with the caret after
+  `1.`.
+- Empty checkbox exits to an empty paragraph, with the caret at the start.
+- Non-empty bullet, ordered row, or checkbox exits to a paragraph containing the
+  same text, with the caret at the start of that text. This keeps the caret
+  visually where it was before the marker/input was removed.
+- Empty toggle title removes the toggle only when its content is empty.
+- Toggle content must not backspace into the title. The title and content box
+  are a strict pair.
+- Backspace in an empty text block inside toggle content deletes that block
+  when there is a previous content sibling to focus. It does nothing at the top
+  of an otherwise empty content box.
+- Backspace immediately below a toggle must not pull the block into the toggle.
+  Toggle title and content are not allowed to merge with adjacent blocks.
+
+Delete in an empty editable block:
+
+- Forward Delete removes the empty current block and moves focus to the next
+  visible block when one exists.
+- If no next focus target exists, Delete does not remove the final editable
+  fallback block.
+
+Enter inside a tree-row label:
+
+- Splits at the browser-visible cursor offset.
+- Preserves intentional trailing spaces on the previous row.
+- Moves children to the new visual sibling when a parent row is split.
+- Empty tree rows become a default paragraph.
+- Paragraph-like blocks inside toggle content split inside the same toggle
+  content wrapper. Enter should not break them out of the toggle.
+- Shift+Enter stays inside the current row and inserts a visible soft break.
+
+Tab and Shift+Tab:
+
+- Use the shared block tree operations.
+- Preserve following child sequences when outdenting.
+- Keep focus at the same visible label offset when practical.
+
+Placeholders and empty hit targets:
+
+- Empty checkbox labels are visually empty and must not use a `Task`
+  placeholder.
+- Empty checkbox labels still need a stable same-line editable hit area beside
+  the checkbox input.
+- Empty list and toggle labels may show calm placeholders without selecting
+  placeholder text.
+- Empty toggle content shows the `Toggle content` placeholder inside its content
+  wrapper.
+
+## Toggle Guidelines
+
+A toggle is one strict structure:
+
+1. title row
+2. content wrapper
+
+The content wrapper should always exist while editing, including when empty.
+It is an independent nested document area and a drop target for dragged blocks.
+Collapsed toggles hide content visually but keep child blocks in document data.
+
+Backspace should not allow content rows to become title rows or adjacent root
+blocks to be absorbed into a toggle. Structural changes must preserve the
+title/content pairing.
+
+All direct toggle content blocks render inside one shared content wrapper. Do
+not render a separate bordered content box per child block.
+
+Creating a toggle focuses the beginning of the title for both the special block
+action and `>>` shortcut-created toggles.
+
+Drag and drop inside toggle content should use the same block movement helpers
+as the rest of the editor. Dropping onto the content wrapper places the dragged
+block inside the toggle; dropping among rows inside the wrapper targets those
+rows first.
+
+Toggling collapsed state should preserve scroll position and should never drop
+children.
+
+## Block Actions and Drag
+
+Every visible block row should have its own block handle when hovered or active,
+including paragraphs inside toggle content and individual checkbox items.
+Empty paragraphs are still visible block rows: they should expose a drag handle
+and, when they are also valid insertion targets, the special block plus control.
+Those controls should sit in separate gutter slots so neither hides the other.
+
+Handle visibility and placement:
+
+- Deeply nested rows keep their hover lane aligned with their visual row.
+- Checkbox handles use a small raised anchor to align with the checkbox input.
+- Toggle handles use the normal row anchor.
+- Block action menus include copy, cut, delete, and close icon controls.
+- Deleting from the block action menu preserves scroll position.
+
+Drag behavior:
+
+- Dragging a block moves the whole block subtree.
+- Before and after drops match the target sibling's visual indentation level.
+- Moving the pointer into a compatible indentation lane drops inside the target
+  row.
+- Moving the pointer to a shallower indentation lane drops beside the visual
+  ancestor.
+- The drop indicator should draw at the indentation level that the drop will
+  produce.
+- Toggle content boxes are valid drop targets, but row targets inside them take
+  priority.
+- Invalid drag targets show the drop indicator in red. Releasing onto the
+  dragged block itself, one of its descendants, or no meaningful target must not
+  mutate the document or trigger a content change.
+
+## Clipboard and Persistence
+
+Clipboard round trips should prefer the structured rich-text encoding when
+available. Plain-text clipboard export should remain readable and compatible
+with common Markdown-like input:
+
+- bullet: `- text`
+- ordered: `1. text`
+- unchecked checkbox: `[ ] text`
+- checked checkbox: `[x] text`
+- toggle: `> title`
+
+Persistence boundaries must preserve nested `children`, checkbox `checked`, and
+toggle `collapsed`. If the saved block shape changes, update package tests,
+application mappers, and Functions mappers together.
+
+Pasting behavior:
+
+- Rich-text clipboard payloads should decode back into the same block structure
+  when possible.
+- Pasting into an empty editable block replaces that block instead of creating
+  an extra blank row.
+- Pasting into an empty toggle content placeholder inserts the pasted blocks as
+  toggle children.
+- Plain-text shortcuts such as `[]`, `* `, `1. `, and `>>` should continue to
+  work inside toggle content.
+
+Typography and whitespace:
+
+- Interior repeated spaces and intentional trailing spaces should be preserved
+  through editor storage and rendering.
+- Spacer entities inserted by the browser should be dropped when they are only
+  editor artifacts.
+- Enter splitting should use browser-visible text offsets, including soft
+  breaks and emoji.
+- List-like rows should remain compact vertically.
+
+## Transcription
+
+Hosts may enable browser-native transcription with `transcriptionEnabled`.
+The editor inserts final transcript text into the current body selection with
+readable spacing. Mobile Safari should show the unavailable state instead of
+starting `webkitSpeechRecognition`, which can leave the browser in a stuck
+recording session.
+
+If a host needs the transcription control in external chrome, it should pass
+`transcriptionPortalContainer`. The control must stay React-owned through a
+portal; host components must not move `.bayon-rte-transcription` with direct DOM
+operations such as `appendChild`.
+
+## Testing and Build Expectations
+
+For behavior changes, add focused tests near the helper or component being
+changed. Prefer pure helper tests for tree operations before DOM integration.
+
+Common verification commands:
+
+```powershell
+pnpm --filter @bayonai/rich-text-editor test -- --run
+pnpm --filter @bayonai/rich-text-editor lint
+pnpm --filter @bayonai/rich-text-editor build
+pnpm exec tsc --noEmit -p tsconfig.json
+git diff --check
+```
+
+The repository tracks package build output. After changing rich-text package
+source, rebuild the package so tracked output stays aligned.

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+- Added nested bullet, ordered, checkbox, and toggle block support with
+  recursive sanitization and editable/read-only rendering built on recursive
+  `ul`/`ol` plus `li` list DOM.
+- Added Tab and Shift+Tab handling for indenting and outdenting nestable rows
+  while leaving paragraph, heading, quote, code, divider, and image blocks flat.
+- Added `* ` and `1. ` shortcuts for unordered and ordered rows.
+- Unified Enter behavior across bullet, ordered, checkbox, and toggle rows so
+  row splitting uses the caret position consistently.
+- Fixed Enter at the end of title blocks so the following row starts as default
+  paragraph text.
+- Fixed ArrowUp in body text so the browser moves to the previous visual line
+  instead of jumping focus to the title.
+- Removed top-level list indentation and nested list borders while keeping
+  indentation on child list containers.
+- Kept empty special-created list and toggle rows as placeholder rows instead
+  of selected placeholder text.
+- Added editable toggle collapse and expand controls that preserve child
+  content while storing collapsed state on the toggle block.
+- Aligned block action handles with indented nested rows.
+- Added an editor operation boundary with document and selection snapshots to
+  prepare semantic editor actions for future undo/redo support.
+
 ## 0.1.2 - 2026-06-24
 
 - Added block-level action handles for non-empty editor blocks.

package/README.md

@@ -14,10 +14,17 @@ The package has no Next.js, Firebase, or application-domain dependencies.
 Hosts provide controlled document values, optional metadata, persistence
 callbacks, and navigation adapters.
 
+## Maintainer Notes
+
+Internal structure and behavior contracts are documented in
+[`BEHAVIOR.md`](./BEHAVIOR.md). Read that file before changing tree-row,
+toggle, cursor, clipboard, or persistence behavior.
+
 ## Editor Capabilities
 
 - Native rich-text body editing with headings, quotes, code, dividers,
-  checkboxes, image placeholders, and Markdown-compatible text storage.
+  bullets, ordered bullets, checkboxes, toggles, image placeholders, and
+  Markdown-compatible text storage.
 - Empty, undesignated blocks expose the special block insertion tool.
 - Non-empty top-level blocks expose a compact gutter handle for block actions.
 - Dragging a block handle reorders blocks with a visible drop indicator.
@@ -26,12 +33,24 @@ callbacks, and navigation adapters.
   block only after the clipboard write succeeds.
 - Deleting the last block preserves one empty paragraph so the editor remains
   writable.
-- Checkbox rows can be reordered individually; copy, cut, and delete actions
-  still apply to consecutive checkbox rows as one action group. Pressing Enter
-  from a checkbox creates the next checkbox, and Backspace at the start of a
-  checkbox row converts that row back to a paragraph.
+- Checkbox rows can be created with the `[]` shortcut, reordered individually,
+  copied, cut, and deleted. Pressing Enter from a checkbox creates the next
+  checkbox, and Backspace at the start of a checkbox row converts that row back
+  to a paragraph.
+- Bullet rows can be created with the `* ` shortcut, and ordered rows can be
+  created with the `1. ` shortcut. Empty list-like rows show placeholders
+  instead of selecting placeholder text.
+- Bullet, ordered, checkbox, and toggle rows can hold nested children. Pressing
+  Tab indents a nestable row under the previous compatible row, and Shift+Tab
+  promotes it one level. Paragraph, heading, quote, code, divider, and image
+  blocks remain flat. Editable and read-only nested rows render as recursive
+  `ul`/`ol` plus `li` trees so list-like content keeps semantic list structure.
+- Toggle rows render as collapsible sections in read-only output and preserve
+  their collapsed state in the stored block. Editable toggles can also be
+  collapsed and expanded without dropping child content.
 - Browser-native transcription can be enabled by hosts with the editor's
   `transcriptionEnabled` option. It defaults to enabled, uses the browser
   `SpeechRecognition` or `webkitSpeechRecognition` API when available, inserts
   final transcript text into the current editor body, and never uploads or
-  stores audio.
+  stores audio. Mobile Safari is treated as unavailable because its prefixed
+  recognition sessions can get stuck and leave the editor unusable.

package/dist/core/blockTree.d.ts

@@ -0,0 +1,14 @@
+import { type NestableRichTextBlock } from "./blockTypes";
+import type { RichTextBlock, RichTextBlockPath } from "./types";
+export declare function findBlockPath(blocks: RichTextBlock[], blockId: string): RichTextBlockPath | null;
+export declare function getBlockAtPath(blocks: RichTextBlock[], path: RichTextBlockPath): RichTextBlock | null;
+export declare function getBlocksAtPath(blocks: RichTextBlock[], path: RichTextBlockPath): RichTextBlock[] | null;
+export declare function removeBlockAtPath(blocks: RichTextBlock[], path: RichTextBlockPath): {
+    block: RichTextBlock;
+    blocks: RichTextBlock[];
+} | null;
+export declare function updateBlockAtPath(blocks: RichTextBlock[], path: RichTextBlockPath, updater: (block: RichTextBlock) => RichTextBlock): RichTextBlock[];
+export declare function insertBlockAtPath(blocks: RichTextBlock[], parentPath: RichTextBlockPath, index: number, insertedBlocks: RichTextBlock[]): RichTextBlock[];
+export declare function pathContains(parentPath: RichTextBlockPath, childPath: RichTextBlockPath): boolean;
+export declare function withNestableBlockChildren(block: NestableRichTextBlock, children: RichTextBlock[]): NestableRichTextBlock;
+export declare function withBlockChildren(block: RichTextBlock, children: RichTextBlock[]): RichTextBlock;

package/dist/core/blockTree.js

@@ -0,0 +1,126 @@
+import { isNestableRichTextBlock } from "./blockTypes.js";
+export function findBlockPath(blocks, blockId) {
+    for (let index = 0; index < blocks.length; index += 1) {
+        const block = blocks[index];
+        if (!block) {
+            continue;
+        }
+        if (block.id === blockId) {
+            return [index];
+        }
+        if (isNestableRichTextBlock(block) && block.children?.length) {
+            const childPath = findBlockPath(block.children, blockId);
+            if (childPath) {
+                return [index, ...childPath];
+            }
+        }
+    }
+    return null;
+}
+export function getBlockAtPath(blocks, path) {
+    let currentBlocks = blocks;
+    let currentBlock;
+    for (const index of path) {
+        currentBlock = currentBlocks[index];
+        if (!currentBlock) {
+            return null;
+        }
+        currentBlocks = isNestableRichTextBlock(currentBlock)
+            ? currentBlock.children ?? []
+            : [];
+    }
+    return currentBlock ?? null;
+}
+export function getBlocksAtPath(blocks, path) {
+    if (path.length === 0) {
+        return blocks;
+    }
+    const parent = getBlockAtPath(blocks, path);
+    return isNestableRichTextBlock(parent) ? parent.children ?? [] : null;
+}
+export function removeBlockAtPath(blocks, path) {
+    const [index, ...rest] = path;
+    if (index === undefined) {
+        return null;
+    }
+    if (rest.length === 0) {
+        const block = blocks[index];
+        if (!block) {
+            return null;
+        }
+        return {
+            block,
+            blocks: [...blocks.slice(0, index), ...blocks.slice(index + 1)],
+        };
+    }
+    const parent = blocks[index];
+    if (!isNestableRichTextBlock(parent)) {
+        return null;
+    }
+    const removed = removeBlockAtPath(parent.children ?? [], rest);
+    if (!removed) {
+        return null;
+    }
+    const updatedParent = withNestableBlockChildren(parent, removed.blocks);
+    return {
+        block: removed.block,
+        blocks: [
+            ...blocks.slice(0, index),
+            updatedParent,
+            ...blocks.slice(index + 1),
+        ],
+    };
+}
+export function updateBlockAtPath(blocks, path, updater) {
+    const [index, ...rest] = path;
+    if (index === undefined) {
+        return blocks;
+    }
+    const block = blocks[index];
+    if (!block) {
+        return blocks;
+    }
+    const updatedBlock = rest.length === 0
+        ? updater(block)
+        : isNestableRichTextBlock(block)
+            ? withNestableBlockChildren(block, updateBlockAtPath(block.children ?? [], rest, updater))
+            : block;
+    return [...blocks.slice(0, index), updatedBlock, ...blocks.slice(index + 1)];
+}
+export function insertBlockAtPath(blocks, parentPath, index, insertedBlocks) {
+    if (parentPath.length === 0) {
+        return [
+            ...blocks.slice(0, index),
+            ...insertedBlocks,
+            ...blocks.slice(index),
+        ];
+    }
+    return updateBlockAtPath(blocks, parentPath, (parent) => {
+        if (!isNestableRichTextBlock(parent)) {
+            return parent;
+        }
+        return withNestableBlockChildren(parent, [
+            ...(parent.children ?? []).slice(0, index),
+            ...insertedBlocks,
+            ...(parent.children ?? []).slice(index),
+        ]);
+    });
+}
+export function pathContains(parentPath, childPath) {
+    return parentPath.every((index, pathIndex) => childPath[pathIndex] === index);
+}
+export function withNestableBlockChildren(block, children) {
+    if (block.type === "toggle") {
+        return { ...block, children };
+    }
+    if (children.length > 0) {
+        return { ...block, children };
+    }
+    const { children: _children, ...rest } = block;
+    return rest;
+}
+export function withBlockChildren(block, children) {
+    return isNestableRichTextBlock(block)
+        ? withNestableBlockChildren(block, children)
+        : block;
+}

package/dist/core/blockTypes.d.ts

@@ -0,0 +1,6 @@
+import type { RichTextBlock } from "./types";
+export type NestableRichTextBlock = Extract<RichTextBlock, {
+    type: "bullet" | "ordered" | "checkbox" | "toggle";
+}>;
+export declare const NESTABLE_RICH_TEXT_BLOCK_TYPES: Set<"toggle" | "checkbox" | "ordered" | "bullet">;
+export declare function isNestableRichTextBlock(block: RichTextBlock | null | undefined): block is NestableRichTextBlock;

package/dist/core/blockTypes.js

@@ -0,0 +1,5 @@
+export const NESTABLE_RICH_TEXT_BLOCK_TYPES = new Set(["bullet", "ordered", "checkbox", "toggle"]);
+export function isNestableRichTextBlock(block) {
+    return (!!block &&
+        NESTABLE_RICH_TEXT_BLOCK_TYPES.has(block.type));
+}