Improve docs based on AI assistant chat analysis#2016
Merged
Conversation
Analyzed ~10K user interactions with the docs AI assistant to identify the most common pain points. Key changes: - Add API mapping table to React migration guide (DndContext → DragDropProvider, arrayMove → move, active/over → operation.source/target, etc.) - Add packages overview note to React quickstart - Add kanban/trello/multi-column keywords to multiple sortable lists guide - Add external state integration section (React Query, duplicate items fix) - New React Modifiers guide with ref-based examples - New React Feedback plugin guide with troubleshooting - Document event object structure on DragDropProvider - Add touch/mobile section to pointer sensor docs - Update docs.json navigation with new guide pages Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
@dnd-kit/abstract
@dnd-kit/collision
@dnd-kit/dom
@dnd-kit/geometry
@dnd-kit/helpers
@dnd-kit/react
@dnd-kit/solid
@dnd-kit/state
@dnd-kit/svelte
@dnd-kit/vue
commit: |
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
dnd-kit | 605cf1e | Commit Preview URL Branch Preview URL |
May 05 2026, 11:53 PM |
- Move the API mapping table to the bottom of the guide so it serves as a reference after users work through the step-by-step migration - Split the single large table into grouped AccordionGroup sections (Context & Provider, Events, Sensors, Collision detection, Modifiers, Sortable) — much more scannable and less visually dense - Add a few additional mappings verified against source: - PointerSensor / KeyboardSensor from @dnd-kit/dom/sensors - closestCorners from @dnd-kit/collision - restrictToWindowEdges → RestrictToWindow - restrictToHorizontalAxis → RestrictToHorizontalAxis - createSnapModifier → SnapModifier - rectSortingStrategy → handled automatically Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Tables nested inside <Accordion> components aren't parsed by MDX in this Astro/Mintlify setup, leaving raw pipe characters visible to users. Switch to flat H3 subheadings with tables — cleaner, reliable, and each category now appears in the right-sidebar TOC for quick navigation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Users frequently ask what happened to SortableContext during migration. - Remove it from the "Context & Provider" table (it's a sortable concept, not a generic context) - Add a Note callout at the top of the Sortable section explaining it is no longer needed — useSortable auto-coordinates with DragDropProvider, and type/accept on useSortable replace the old container-level grouping - Surface SortableContext as the first row of the Sortable table so migrators see it immediately when scanning Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Verified against packages/dom/src/core/sensors/pointer/PointerSensor.ts:
- PointerSensor handles mouse, touch, AND pen via the native Pointer
Events API — the legacy MouseSensor and TouchSensor are consolidated
into this one class
- Per-input-type behavior is configured via a function passed to
activationConstraints that branches on event.pointerType
('mouse' | 'touch' | 'pen') — there is no "inputType" option
- PointerActivationConstraints.Delay and .Distance are the correct
static accessors for constraint classes
Changes:
- Add Note callout in Sensors migration section explaining the merge
and showing a working activationConstraints function example
- Add MouseSensor and TouchSensor → PointerSensor mappings to the table
- Fix incorrect import path "@dnd-kit/dom/sensors" → "@dnd-kit/dom"
(the dom package exports sensors from root; only ./modifiers,
./plugins/*, ./sortable, and ./utilities are subpath exports per
packages/dom/package.json)
- Fix the same import-path typo in extend/sensors/keyboard-sensor.mdx
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New guide at /react/guides/collision-detection documenting all 7 built-in collision detectors with when-to-use-each guidance, plus configuration, priority, custom detectors, and a migration mapping. All detector descriptions verified against source in packages/collision/src/algorithms/: - defaultCollisionDetection: pointerIntersection → shapeIntersection fallback - pointerIntersection: requires pointer inside droppable rect - shapeIntersection: greatest intersection area, tie-broken by pointer distance - closestCenter: 1/distance between centers - closestCorners: 1/(average corner-to-corner distance) - pointerDistance: 1/distance between pointer and droppable center - directionBiased: only detects collisions in drag movement direction Also verified: - collisionDetector is per-droppable option on useDroppable/useSortable (packages/react/src/core/droppable/useDroppable.ts) - CollisionPriority enum values Lowest/Low/Normal/High/Highest (packages/abstract/src/core/collision/types.ts) - @dnd-kit/collision is a transitive dep via @dnd-kit/dom so no explicit install needed Add the guide to React Guides navigation in docs.json. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add diagrams from the existing image library under each algorithm: - shape-intersection.svg for shapeIntersection - closest-center.svg for closestCenter - legacy/closest-corners.png for closestCorners (these are the same diagrams used in concepts/droppable.mdx) - Remove the inline migration section — migration lives in the migration guide, the collision-detection guide just links to it - Replace the section with a brief one-liner pointing migrators to the existing migration guide Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Match the icon used on the core /extend/modifiers page for consistency across the docs. Updates both the guide's frontmatter and the Next steps card in the migration guide. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The sliders icon is used on /extend/modifiers and was previously also on /react/guides/sortable-state-management, which meant both cards in the migration guide's Next steps showed the same glyph. Move sortable state management to list-ol to keep sliders unambiguously modifier-ish. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…docs
Verified all option signatures and defaults against
packages/dom/src/core/sensors/{pointer,keyboard}/*.ts.
PointerSensor docs (extend/sensors/pointer-sensor.mdx):
- Document the missing activatorElements option (designate alternative
pointerdown targets via array or function-of-source)
- Document the missing preventActivation option (skip a pointerdown
for a given event/source) — including the actual default which
prevents activation on interactive descendants of the draggable
KeyboardSensor docs (extend/sensors/keyboard-sensor.mdx):
- Fix incorrect default for keyboardCodes.end — source includes
'Tab' alongside 'Space' and 'Enter'
- Document the missing offset option (per-key-press pixel movement,
number or per-axis object, default 10)
- Document the missing preventActivation option (default only allows
activation when the focused target is the handle/element)
- Clarify the Shift modifier is a 5x multiplier, not a literal 50px
New React guide (react/guides/sensors.mdx, "Configuring sensors"):
- Where to configure (provider / per-draggable / per-instance)
- Customizing PointerSensor: activationConstraints, per-pointer-type
branching on event.pointerType, activatorElements, preventActivation
- Customizing KeyboardSensor: keyboardCodes, offset, preventActivation
- Per-draggable sensors via useDraggable/useSortable
- Replacing vs. extending defaults — with a warning about preserving
KeyboardSensor for accessibility
- Brief link out to migration guide for legacy MouseSensor/TouchSensor
Action-oriented guide titles:
- /react/guides/collision-detection: "Collision detection" → "Detecting collisions"
- /react/guides/modifiers: "Modifiers" → "Using modifiers"
- Both keep their original metaTitle for SEO; sidebarTitle matches the
new title for sidebar/H1 consistency
Migration guide:
- Update Modifiers card title to "Using modifiers" to match the
renamed page
- Add a link to the new Configuring sensors guide from the Sensors
Note callout
Add the new sensors guide to docs.json navigation between
collision-detection and modifiers.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Audit against packages/abstract/src/core/entities/{draggable,droppable}.ts,
packages/dom/src/{core,sortable}/...ts, and packages/react/src/...ts.
API NAME FIXES (would break user code if copied verbatim):
- The droppable option is `accept` (singular), not `accepts`. Source
destructures `accept` from input — passing `accepts` is silently
ignored. Renamed in:
- apps/docs/docs/react/hooks/use-droppable.mdx
- apps/docs/docs/react/hooks/use-sortable.mdx
- apps/docs/docs/concepts/droppable.mdx
- apps/docs/docs/concepts/sortable.mdx
The instance method `accepts(draggable)` (verb form) is unchanged
and remains correctly named.
- Tighten `accept` type signature to match source:
`Type | Type[] | ((source: Draggable) => boolean)` — the function
variant receives the Draggable, not just its type.
MISSING OPTIONS:
- Document `type` on useDroppable, useSortable, and concepts/droppable
(used to identify the droppable for `accept` rules on others).
- Document `group` on useSortable (groups items for multi-list sorting,
used by useSortable in packages/react/src/sortable/useSortable.ts).
- Document `alignment` on useDraggable and concepts/draggable (passed
through to the Draggable constructor; type Alignment from
@dnd-kit/geometry: `{x: 'start' | 'center' | 'end'; y: same}`,
consumed by the Feedback plugin).
NEW HOOK DOCS:
- apps/docs/docs/react/hooks/use-drag-operation.mdx — documents the
publicly-exported useDragOperation hook (returns reactive {source,
target}). Sourced from packages/react/src/core/hooks/useDragOperation.ts
and packages/react/src/core/index.ts (export).
- apps/docs/docs/react/hooks/use-drag-drop-manager.mdx — documents
useDragDropManager (returns the manager from context, or null).
Both new hooks added to docs.json under React → Hooks navigation.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sidebar: - Move useDragDropMonitor, useDragOperation, and useDragDropManager into a "Utilities" sub-group under React → Hooks. The three hooks are observation/escape-hatch utilities, distinct from the primary useDraggable / useDroppable / useSortable trio. - Add support for a `defaultOpen: true` flag on nav groups in docs.json. SidebarGroupItem reads it and starts the group expanded even when the active page is not inside it. Plugins/Sensors keep their existing collapse-by-default behavior. - Use icon `wrench` on the Utilities sub-group as a section marker. - Drop the per-page icons from useDragDropMonitor, useDragOperation, and useDragDropManager — the indent under Utilities is enough visual hierarchy. Guide titles (action-oriented, matching Detecting collisions / Using modifiers / Configuring sensors): - Feedback → Customizing feedback (frontmatter title + sidebarTitle, plus the Next steps card on the migration guide). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The custom ParamField component (used as both ParamField and ResponseField via the alias in mintlify-components.tsx) only read the `path` prop. Mintlify's <ResponseField> uses `name` instead, so all 80 occurrences across React/Vue/Svelte/Solid hook/composable/ primitive Output sections rendered as headerless description-only fields — missing the property name and type entirely. Accept either prop and prefer `path` when both are present, matching Mintlify's convention of distinct components for inputs vs outputs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Analyzed ~10K user interactions with the Mintlify AI assistant (Apr 7–14) to identify documentation gaps. The most common pain points were:
@dnd-kit/helpersexistsonDragEndevent objectsChanges
/react/guides/modifiers) with ref-based examples/react/guides/feedback) with troubleshootingdocs.jsonnavigation with new guide pagesAll import paths, API names, option types, and default values were cross-referenced against the actual package source code.
Test plan
🤖 Generated with Claude Code