Skip to content

docs: add a drag-and-drop concepts page - #3158

Draft
christianhg wants to merge 1 commit into
mainfrom
dnd-concepts-page
Draft

docs: add a drag-and-drop concepts page#3158
christianhg wants to merge 1 commit into
mainfrom
dnd-concepts-page

Conversation

@christianhg

@christianhg christianhg commented Aug 24, 2026

Copy link
Copy Markdown
Member

The dnd model had no home: the plugin README carries the mounting recipe, and the Rendering and Containers pages carry fragments. This page states the ownership story and unpacks it: the editor owns event translation, move semantics, destination fitting, self-drop cancellation, and the drag ghost; registrations own draggable markup; @portabletext/plugin-dnd owns optional indicator presentation.

Content is claim-verified against source: the seven drag.* events with their real public payloads (dragstart promises only position.selection; originEvent is a reduced object, not the browser DragEvent), the three outcomes of an entire-block internal drop (split, snap, no-op) with the mixed-fit result and its discarded-blocks consequence stated, drag handles on text blocks, and that dragging out of the editor writes the same clipboard formats copying does. The dragover observer example forwards the event it handles, because a behavior that doesn't forward kills the drag; the same ownership on drag.drop is the documented way to cancel a drop.

Sits at sidebar order 5, after Clipboard, whose structure it mirrors. Part of the v8 docs arc alongside the migration guide (#3146).

@vercel

vercel Bot commented Aug 24, 2026

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
portable-text-editor-documentation Ready Ready Preview Aug 25, 2026 11:14am
portable-text-example-basic Ready Ready Preview Aug 25, 2026 11:14am
1 Skipped Deployment
Project Deployment Actions Updated (UTC)
portable-text-playground Skipped Skipped Aug 25, 2026 11:14am

Request Review

@changeset-bot

changeset-bot Bot commented Aug 24, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 01cfc98

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@github-actions

github-actions Bot commented Aug 24, 2026

Copy link
Copy Markdown
Contributor

Bundle Stats

✅ No significant changes.

All scenario measurements (7)

🗺️ @portabletext/editor / @portabletext/editor · @portabletext/editor / @portabletext/editor/behaviors · @portabletext/editor / @portabletext/editor/plugins · @portabletext/editor / @portabletext/editor/selectors · @portabletext/editor / @portabletext/editor/traversal · @portabletext/editor / @portabletext/editor/utils · @portabletext/markdown / @portabletext/markdown · Artifacts

Scenario Kind Bundle (raw / gzip) Gzip change Import time Import change
⚪ @portabletext/editor / @portabletext/editor export 1.08 MB / 251.5 KB None 67 ms -1 ms, -1.1%
⚪ @portabletext/editor / @portabletext/editor/behaviors export 4.0 KB / 1.4 KB None 2 ms +0 ms, +1.9%
⚪ @portabletext/editor / @portabletext/editor/plugins export 5.1 KB / 1.8 KB None 7 ms -0 ms, -1.0%
⚪ @portabletext/editor / @portabletext/editor/selectors export 93.4 KB / 21.3 KB None 8 ms -0 ms, -1.5%
⚪ @portabletext/editor / @portabletext/editor/traversal export 41.4 KB / 10.7 KB None 6 ms +0 ms, +1.4%
⚪ @portabletext/editor / @portabletext/editor/utils export 32.8 KB / 8.6 KB None 6 ms +0 ms, +2.7%
⚪ @portabletext/markdown / @portabletext/markdown export 272.2 KB / 79.6 KB None 41 ms +1 ms, +2.8%

Significant means at least 1.0 KB and 1% gzip, or at least 5 ms and 10% import time.

The dnd model had no home: the plugin README carries the recipe, and
Rendering and Containers carry fragments. The page states the ownership
story, the editor owns event translation, move semantics, destination
fitting, self-drop cancellation, and the drag ghost; registrations own
draggable markup; `@portabletext/plugin-dnd` owns optional indicator
presentation, and unpacks it: the seven `drag.*` events and their
payloads, split versus snap versus no-op with the mixed-fit outcome
stated, internal versus external drags (dragging out writes the same
formats copying does), draggable markup for block objects and
text-block drag handles, and a `dragover` observer that forwards the
event it handles. Sidebar order 5, after Clipboard; one cross-link from
Rendering's drop-indicators bullet.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant