@wordpress/editor 14.44.0 → 14.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/editor",
-	"version": "14.44.0",
+	"version": "14.45.0",
 	"description": "Enhanced block editor for WordPress posts.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -60,50 +60,50 @@
 		"build-module/bindings/**"
 	],
 	"dependencies": {
-		"@floating-ui/react-dom": "2.0.8",
-		"@wordpress/a11y": "^4.44.0",
-		"@wordpress/api-fetch": "^7.44.0",
-		"@wordpress/base-styles": "^6.20.0",
-		"@wordpress/blob": "^4.44.0",
-		"@wordpress/block-editor": "^15.17.0",
-		"@wordpress/block-serialization-default-parser": "^5.44.0",
-		"@wordpress/blocks": "^15.17.0",
-		"@wordpress/commands": "^1.44.0",
-		"@wordpress/components": "^32.6.0",
-		"@wordpress/compose": "^7.44.0",
-		"@wordpress/core-data": "^7.44.0",
-		"@wordpress/data": "^10.44.0",
-		"@wordpress/dataviews": "^14.1.0",
-		"@wordpress/date": "^5.44.0",
-		"@wordpress/deprecated": "^4.44.0",
-		"@wordpress/dom": "^4.44.0",
-		"@wordpress/element": "^6.44.0",
-		"@wordpress/fields": "^0.36.0",
-		"@wordpress/global-styles-engine": "^1.11.0",
-		"@wordpress/global-styles-ui": "^1.11.0",
-		"@wordpress/hooks": "^4.44.0",
-		"@wordpress/html-entities": "^4.44.0",
-		"@wordpress/i18n": "^6.17.0",
-		"@wordpress/icons": "^12.2.0",
-		"@wordpress/interface": "^9.29.0",
-		"@wordpress/keyboard-shortcuts": "^5.44.0",
-		"@wordpress/keycodes": "^4.44.0",
-		"@wordpress/media-editor": "^0.7.0",
-		"@wordpress/media-fields": "^0.9.0",
-		"@wordpress/media-utils": "^5.44.0",
-		"@wordpress/notices": "^5.44.0",
-		"@wordpress/patterns": "^2.44.0",
-		"@wordpress/plugins": "^7.44.0",
-		"@wordpress/preferences": "^4.44.0",
-		"@wordpress/private-apis": "^1.44.0",
-		"@wordpress/reusable-blocks": "^5.44.0",
-		"@wordpress/rich-text": "^7.44.0",
-		"@wordpress/server-side-render": "^6.20.0",
-		"@wordpress/upload-media": "^0.29.0",
-		"@wordpress/url": "^4.44.0",
-		"@wordpress/views": "^1.11.0",
-		"@wordpress/warning": "^3.44.0",
-		"@wordpress/wordcount": "^4.44.0",
+		"@wordpress/a11y": "^4.45.0",
+		"@wordpress/api-fetch": "^7.45.0",
+		"@wordpress/base-styles": "^7.0.0",
+		"@wordpress/blob": "^4.45.0",
+		"@wordpress/block-editor": "^15.18.0",
+		"@wordpress/block-serialization-default-parser": "^5.45.0",
+		"@wordpress/blocks": "^15.18.0",
+		"@wordpress/commands": "^1.45.0",
+		"@wordpress/components": "^33.0.0",
+		"@wordpress/compose": "^7.45.0",
+		"@wordpress/core-data": "^7.45.0",
+		"@wordpress/data": "^10.45.0",
+		"@wordpress/dataviews": "^14.2.0",
+		"@wordpress/date": "^5.45.0",
+		"@wordpress/deprecated": "^4.45.0",
+		"@wordpress/dom": "^4.45.0",
+		"@wordpress/element": "^6.45.0",
+		"@wordpress/fields": "^0.37.0",
+		"@wordpress/global-styles-engine": "^1.12.0",
+		"@wordpress/global-styles-ui": "^1.12.0",
+		"@wordpress/hooks": "^4.45.0",
+		"@wordpress/html-entities": "^4.45.0",
+		"@wordpress/i18n": "^6.18.0",
+		"@wordpress/icons": "^13.0.0",
+		"@wordpress/interface": "^9.30.0",
+		"@wordpress/keyboard-shortcuts": "^5.45.0",
+		"@wordpress/keycodes": "^4.45.0",
+		"@wordpress/media-editor": "^0.8.0",
+		"@wordpress/media-fields": "^0.10.0",
+		"@wordpress/media-utils": "^5.45.0",
+		"@wordpress/notices": "^5.45.0",
+		"@wordpress/patterns": "^2.45.0",
+		"@wordpress/plugins": "^7.45.0",
+		"@wordpress/preferences": "^4.45.0",
+		"@wordpress/private-apis": "^1.45.0",
+		"@wordpress/reusable-blocks": "^5.45.0",
+		"@wordpress/rich-text": "^7.45.0",
+		"@wordpress/server-side-render": "^6.21.0",
+		"@wordpress/ui": "^0.12.0",
+		"@wordpress/upload-media": "^0.30.0",
+		"@wordpress/url": "^4.45.0",
+		"@wordpress/views": "^1.12.0",
+		"@wordpress/warning": "^3.45.0",
+		"@wordpress/wordcount": "^4.45.0",
 		"change-case": "^4.1.2",
 		"client-zip": "^2.4.5",
 		"clsx": "^2.1.1",
@@ -126,5 +126,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "b862d8c84121a47bbeff882f6c87e61681ce2e0d"
+	"gitHead": "8c229eaed0e88c9827e2da3d73a78f9ddd77714b"
 }

package/src/components/collab-sidebar/README.md

@@ -0,0 +1,117 @@
+# 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.

package/src/components/collab-sidebar/{comment-menu-item.js → add-note-menu-item.js}

@@ -16,9 +16,9 @@ import { store as keyboardShortcutsStore } from '@wordpress/keyboard-shortcuts';
  */
 import { unlock } from '../../lock-unlock';
 
-const { CommentIconSlotFill } = unlock( blockEditorPrivateApis );
+const { NoteIconSlotFill } = unlock( blockEditorPrivateApis );
 
-const AddCommentMenuItem = ( { clientId, onClick, isDistractionFree } ) => {
+function NoteMenuItem( { clientId, onClick, isDistractionFree } ) {
 	const block = useSelect(
 		( select ) => {
 			return select( blockEditorStore ).getBlock( clientId );
@@ -61,13 +61,13 @@ const AddCommentMenuItem = ( { clientId, onClick, isDistractionFree } ) => {
 			{ __( 'Add note' ) }
 		</MenuItem>
 	);
-};
+}
 
-const AddCommentMenuItemFill = ( { onClick, isDistractionFree } ) => {
+export function AddNoteMenuItem( { onClick, isDistractionFree } ) {
 	return (
-		<CommentIconSlotFill.Fill>
+		<NoteIconSlotFill.Fill>
 			{ ( { clientId, onClose } ) => (
-				<AddCommentMenuItem
+				<NoteMenuItem
 					clientId={ clientId }
 					isDistractionFree={ isDistractionFree }
 					onClick={ () => {
@@ -76,8 +76,6 @@ const AddCommentMenuItemFill = ( { onClick, isDistractionFree } ) => {
 					} }
 				/>
 			) }
-		</CommentIconSlotFill.Fill>
+		</NoteIconSlotFill.Fill>
 	);
-};
-
-export default AddCommentMenuItemFill;
+}

package/src/components/collab-sidebar/{add-comment.js → add-note.js}

@@ -1,16 +1,8 @@
-/**
- * External dependencies
- */
-import clsx from 'clsx';
 /**
  * WordPress dependencies
  */
 import { __ } from '@wordpress/i18n';
 import { useSelect, useDispatch } from '@wordpress/data';
-import {
-	__experimentalHStack as HStack,
-	__experimentalVStack as VStack,
-} from '@wordpress/components';
 import {
 	store as blockEditorStore,
 	privateApis as blockEditorPrivateApis,
@@ -19,22 +11,16 @@ import {
 /**
  * Internal dependencies
  */
-import { unlock } from '../../lock-unlock';
-import CommentAuthorInfo from './comment-author-info';
-import CommentForm from './comment-form';
-import { focusCommentThread, noop } from './utils';
+import { NoteCard } from './note-card';
+import { NoteForm } from './note-form';
+import { FloatingContainer } from './floating-container';
+import { focusNoteThread } from './utils';
 import { store as editorStore } from '../../store';
+import { unlock } from '../../lock-unlock';
 
 const { useBlockElement } = unlock( blockEditorPrivateApis );
 
-export function AddComment( {
-	onSubmit,
-	commentSidebarRef,
-	reflowComments = noop,
-	isFloating = false,
-	y,
-	refs,
-} ) {
+export function AddNote( { onSubmit, sidebarRef, floating } ) {
 	const { clientId } = useSelect( ( select ) => {
 		const { getSelectedBlockClientId } = select( blockEditorStore );
 		return {
@@ -49,7 +35,7 @@ export function AddComment( {
 	const { toggleBlockSpotlight } = unlock( useDispatch( blockEditorStore ) );
 	const { selectNote } = unlock( useDispatch( editorStore ) );
 
-	const unselectThread = () => {
+	const unselectNote = () => {
 		selectNote( undefined );
 		blockElement?.focus();
 		toggleBlockSpotlight( clientId, false );
@@ -60,23 +46,15 @@ export function AddComment( {
 	}
 
 	return (
-		<VStack
-			className={ clsx(
-				'editor-collab-sidebar-panel__thread is-selected',
-				{
-					'is-floating': isFloating,
-				}
-			) }
-			spacing="3"
+		<FloatingContainer
+			floating={ floating }
+			className="editor-collab-sidebar-panel__thread is-selected"
+			gap="md"
 			tabIndex={ 0 }
 			aria-label={ __( 'New note' ) }
 			role="treeitem"
-			ref={ isFloating ? refs.setFloating : undefined }
 			style={
-				isFloating
-					? // Delay showing the floating note box until a Y position is known to prevent blink.
-					  { top: y, opacity: ! y ? 0 : undefined }
-					: undefined
+				floating ? { opacity: ! floating.y ? 0 : undefined } : undefined
 			}
 			onBlur={ ( event ) => {
 				// Don't deselect notes when the browser window/tab loses focus.
@@ -90,20 +68,19 @@ export function AddComment( {
 				selectNote( undefined );
 			} }
 		>
-			<HStack alignment="left" spacing="3">
-				<CommentAuthorInfo />
-			</HStack>
-			<CommentForm
-				onSubmit={ async ( inputComment ) => {
-					const { id } = await onSubmit( { content: inputComment } );
-					selectNote( id );
-					focusCommentThread( id, commentSidebarRef.current );
-				} }
-				onCancel={ unselectThread }
-				reflowComments={ reflowComments }
-				submitButtonText={ __( 'Add note' ) }
-				labelText={ __( 'New note' ) }
-			/>
-		</VStack>
+			<NoteCard>
+				<NoteForm
+					onSubmit={ async ( inputComment ) => {
+						const { id } = await onSubmit( {
+							content: inputComment,
+						} );
+						selectNote( id );
+						focusNoteThread( id, sidebarRef.current );
+					} }
+					onCancel={ unselectNote }
+					labels={ { input: __( 'New note' ) } }
+				/>
+			</NoteCard>
+		</FloatingContainer>
 	);
 }

package/src/components/collab-sidebar/board-store.js

@@ -0,0 +1,85 @@
+export function createBoardStore() {
+	const listeners = new Set();
+	const blockRefs = new Map();
+	const floatingRefs = new Map();
+	const idByElement = new WeakMap();
+	const heights = {};
+	let snapshot = {};
+
+	function emit() {
+		snapshot = { ...heights };
+		for ( const listener of listeners ) {
+			listener();
+		}
+	}
+
+	const observer = new window.ResizeObserver( ( entries ) => {
+		let changed = false;
+		for ( const entry of entries ) {
+			const id = idByElement.get( entry.target );
+			const newHeight = entry.borderBoxSize[ 0 ].blockSize;
+			if ( heights[ id ] !== newHeight ) {
+				heights[ id ] = newHeight;
+				changed = true;
+			}
+		}
+		if ( changed ) {
+			emit();
+		}
+	} );
+
+	return {
+		subscribe( listener ) {
+			listeners.add( listener );
+			return () => {
+				listeners.delete( listener );
+				if ( listeners.size === 0 ) {
+					observer.disconnect();
+				}
+			};
+		},
+
+		getSnapshot() {
+			return snapshot;
+		},
+
+		registerThread( id, blockEl, floatingEl ) {
+			blockRefs.set( id, blockEl );
+			const prev = floatingRefs.get( id );
+			if ( prev && prev !== floatingEl ) {
+				observer.unobserve( prev );
+				idByElement.delete( prev );
+			}
+			if ( floatingEl ) {
+				floatingRefs.set( id, floatingEl );
+				idByElement.set( floatingEl, id );
+				observer.observe( floatingEl );
+			}
+			emit();
+		},
+
+		unregisterThread( id ) {
+			blockRefs.delete( id );
+			const prev = floatingRefs.get( id );
+			if ( prev ) {
+				observer.unobserve( prev );
+				idByElement.delete( prev );
+				floatingRefs.delete( id );
+			}
+			delete heights[ id ];
+		},
+
+		getBlockRects() {
+			// Batch all rect reads before any writes to avoid layout thrashing.
+			return Object.fromEntries(
+				Array.from( blockRefs ).flatMap( ( [ id, el ] ) =>
+					el ? [ [ id, el.getBoundingClientRect() ] ] : []
+				)
+			);
+		},
+
+		getFirstBlockElement() {
+			return blockRefs.values().next().value ?? null;
+		},
+	};
+}

package/src/components/collab-sidebar/floating-container.js

@@ -0,0 +1,30 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+
+/**
+ * WordPress dependencies
+ */
+import { Stack } from '@wordpress/ui';
+
+export function FloatingContainer( {
+	floating,
+	className,
+	style,
+	children,
+	...props
+} ) {
+	const isFloating = !! floating;
+	return (
+		<Stack
+			direction="column"
+			className={ clsx( className, { 'is-floating': isFloating } ) }
+			ref={ isFloating ? floating.ref : undefined }
+			style={ isFloating ? { top: floating.y, ...style } : style }
+			{ ...props }
+		>
+			{ children }
+		</Stack>
+	);
+}