@wordpress/editor

# Notes Sidebar The Notes sidebar (a.k.a. collab sidebar) lets users attach threaded notes to individual blocks. It renders in two modes: - **All notes** - a full sidebar (opened from the editor's More menu) listing every note thread on the current post. - **Floating notes** - on larger viewports, unresolved notes also float next to their associated blocks in the canvas, positioned to track scroll and avoid overlap. Notes are stored as WordPress comments (`type: 'note'`) attached to the post. A block references its thread via `metadata.noteId` on block attributes. Each thread has a top-level note plus replies; threads can be resolved (stored as status `approved`) or reopened. ## File structure ``` collab-sidebar/ ├── README.md this file ├── index.js NotesSidebarContainer → NotesSidebar (entry, toolbar slot fills) ├── notes.js Notes - coordinator (outer Stack, actions, keyboard nav) ├── note-thread.js NoteThread - per-thread (selection, floating registration, reply form) ├── note.js Note - per-card state (edit/delete mode, menu, dialog) ├── note-card.js NoteCard - presentational shell (byline + actions slot + children) ├── note-byline.js NoteByline - avatar + name + relative date ├── note-form.js NoteForm - autosizing textarea + submit/cancel ├── add-note.js AddNote - new-note surface (floating + template-locked cases) ├── add-note-menu-item.js AddNoteMenuItem - block-toolbar "Add note" trigger ├── note-indicator-toolbar.js NoteAvatarIndicator - toolbar participants avatars ├── floating-container.js FloatingContainer - stack wrapper that applies `top` in floating mode │ ├── hooks.js useNoteThreads, useNoteActions, useFloatingBoard, useEnableFloatingSidebar ├── utils.js focusNoteThread, getNoteExcerpt, sanitizeNoteContent, calculateNotePositions, getAvatarBorderColor ├── board-store.js createBoardStore - ResizeObserver + ref registry for floating layout ├── constants.js sidebar identifier strings ├── style.scss └── test/ └── utils.js ``` ## Component hierarchy ``` NotesSidebarContainer (index.js) - gates on post type support └── NotesSidebar (index.js) - owns sidebarRef + useNoteThreads + sidebar registration ├── AddNoteMenuItem - slot fill in the block toolbar ├── NoteAvatarIndicator - slot fill in the block toolbar (per-thread avatars) ├── PluginSidebar (all-notes) - full sidebar │ └── Notes (notes.js) - owns outer Stack + aria-label + useNoteActions + keyboard nav │ ├── AddNote - rendered when no threads (template-locked) or selectedNote === 'new' │ └── NoteThread[] - per thread │ └── <FloatingContainer> │ ├── Note - top-level note (own state: edit/delete/dialog) │ │ └── NoteCard │ │ └── NoteByline + actions slot + body children │ ├── Note[] - replies (when selected) │ └── NoteCard + NoteForm - inline reply form (when selected) └── PluginSidebar (floating) - floating sidebar (large viewport, unresolved notes) └── Notes (same) - isFloating ``` `Notes` is reused for both sidebar surfaces. The only visual difference is driven by `isFloating` (whether to layer threads over the canvas or stack them in a panel). ## Floating board Goal: in the floating sidebar, each unresolved note appears beside its associated block, tracks canvas scroll, and shifts up/down to avoid overlapping with neighbors - all without re-rendering threads as the canvas scrolls. Three layers cooperate: ### 1. `board-store.js` - imperative DOM registry A plain JS module returning a store created via `createBoardStore()` (one per mounted `Notes`). Holds: - `blockRefs: Map<noteId, HTMLElement>` - each note's associated block element. - `floatingRefs: Map<noteId, HTMLElement>` - each note's floating DOM node. - `idByElement: WeakMap<HTMLElement, noteId>` - reverse lookup for the `ResizeObserver`. - `heights: { [noteId]: number }` - observed heights of floating elements. - `snapshot: { ... }` - frozen shallow copy of `heights` (for `useSyncExternalStore`). A single shared `ResizeObserver` watches every registered floating element; when a floating note changes height, it updates `heights`, snapshots, and calls every `listener` in the store's `Set`. API: - `subscribe(listener)` / `getSnapshot()` - wired to React via `useSyncExternalStore`. Disconnects the observer when the last subscriber leaves. - `registerThread(id, blockEl, floatingEl)` - called by each `NoteThread` once mounted. Adds the block ref, swaps the floating ref (unobserving the previous one), starts observing the new one, emits. - `unregisterThread(id)` - inverse; called on unmount. - `getBlockRects()` - returns a batched snapshot of block `getBoundingClientRect()` values. Batches reads so subsequent CSS writes don't trigger layout thrash. - `getFirstBlockElement()` - the first registered block, used to locate the canvas scroll container. The store owns DOM references directly, not through React - floating note height changes must update layout without re-rendering the thread list. ### 2. `useFloatingBoard` - the React bridge (in `hooks.js`) Lives inside `Notes`. Holds one store instance (`useState(createBoardStore)`) and: 1. Subscribes to `heights` via `useSyncExternalStore(store.subscribe, store.getSnapshot)`. 2. In a `useEffect` keyed on `threads + heights + selectedNoteId + isFloating + sidebarRef`: - Resolves the canvas scroll container by climbing from the first registered block to `.is-root-container` and calling `getScrollContainer()` on it. - Schedules a single `requestAnimationFrame` that calls `calculateNotePositions({ threads, selectedNoteId, blockRects: store.getBlockRects(), heights, scrollTop })` (pure function in `utils.js`) and stores the result in React state (`notePositions`). - Attaches a capture-phase `scroll` listener on the canvas's `defaultView` that writes a CSS variable `--canvas-scroll` to the sidebar panel. (`window` capture catches scrolls on the document root, which don't bubble.) 3. Returns `{ notePositions, registerThread, unregisterThread }` - the positions flow down as props; the two register callbacks flow to each `NoteThread`. ### 3. `calculateNotePositions` - pure layout math (in `utils.js`) Given the list of threads, the currently selected note id, the block rects, the floating heights, and the canvas scroll offset, returns `{ positions: { [noteId]: top } }` where `top` is the final canvas-space y-coordinate for each floating thread. Algorithm, keyed on the selected note as an **anchor**: 1. Anchor the selected note at `blockRect.top + THREAD_ALIGN_OFFSET` (−16). If no selected note, anchor the first thread. 2. Walk forward from the anchor: each subsequent thread starts at its block's top; if it would overlap the previous thread's bottom (plus `THREAD_GAP` of 16), push it further down by `OVERLAP_MARGIN` (20). 3. Walk backward from the anchor: mirror - push upward into any overlap. 4. Convert each final offset into content-space by adding `blockRect.top + scrollTop`. ### 4. `FloatingContainer` - the render shell Renders a `Stack` with `top: floating.y` when in floating mode. CSS uses the `--canvas-scroll` custom property to translate the whole panel in sync with the canvas, so per-thread `top` values stay stable while scrolling. ### Why this shape - `ResizeObserver` is canonical for height changes that must drive layout without polling. - `useSyncExternalStore` is the right React 18 primitive for "external mutable source with snapshot" - gives concurrent-mode-safe subscriptions without a provider. - The scroll listener updates a CSS variable rather than React state, so scrolling doesn't re-render. Per-note `top` only recomputes when threads, heights, selection, or structural inputs change. - Batching `getBoundingClientRect` reads inside the `rAF` and separating them from style writes avoids forced layout.