docs(dashboards): document drag-to-place for dashboard widgets (CUB-3179)

[mngr]

What

Documents the new drag-to-place behavior for adding widgets to a dashboard, alongside the existing click-to-add. Adds a short Adding widgets section to the dashboard Widgets overview page describing the two placement modes:

• Click a toolbar item → widget drops into the first open spot (existing behavior).
• Drag a toolbar item onto the canvas → a full-size placeholder previews the footprint, surrounding widgets reflow, and the widget lands where you release. Useful on dense dashboards where auto-placement would drop it far down the page.

Why

Ships alongside the product change in cubedevinc/cubejs-enterprise#13820 (CUB-3179). One page touched: docs/explore-analyze/dashboards/widgets/index.mdx.

Note on rollout: drag-to-place is currently available on the new UI Kit Board dashboard engine (behind the useBoardDashboards flag) and is not yet GA for all tenants. Hold merge until the feature is generally available so the docs match what users see, or merge now if the engine is being rolled out broadly.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟢 Ready	View Preview	Aug 14, 2026, 1:27 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Claude finished @mngr's task in 56s —— View job

---

Docs review — looks good, 1 medium (availability gating), 1 low (verbosity)

Full review

• Read PR diff and changed file
• Check against docs-mintlify/CLAUDE.md conventions
• Check sibling widget pages for consistency
• Check existing review threads (none)
• Post findings

What's good

• Right site (/docs-mintlify, not the deprecated /docs) and right page — extends an existing page rather than creating a new one, as the docs guidelines ask.
• New section starts at H2, matching the "body sections start at H2" rule.
• No new page, so no docs.json navigation update is needed — correct as-is.
• Terminology matches the taxonomy and the sibling pages' UI labels (Charts picker, Add Text, Add AI Summary, Add Controls / Filter / Time Granularity).
• No images committed; no internal flag names leaked into the prose itself.

Findings

Medium — feature availability isn't gated (widgets/index.mdx:21-24)

Your own PR description says drag-to-place is only on the new UI Kit Board engine (behind useBoardDashboards) and not yet GA. The page presents it as unconditionally available, so anyone still on the old engine will hunt for behavior they don't have. docs-mintlify/CLAUDE.md requires a <Warning> preview callout for preview features (and no internal flag names in public docs). Either hold the merge until GA — your suggested option, and the cleaner one — or add the callout. Left an inline comment with detail.

Low — the drag bullet is longer than it needs to be (widgets/index.mdx:24)

Three sentences for one interaction. The placeholder/reflow detail is self-evident the instant you start dragging; the guidance is to say it once and not pad. Suggested a two-line trim in the inline comment.

Nit — no screenshot placeholder. Drag interactions are hard to convey in prose. Consider {/* TODO: screenshot — dragging a chart from the toolbar with the placeholder visible */}, per the docs convention for pending media.

Not applicable

Security, performance, testing, and error handling have no surface here — this is a 8-line prose change to a single .mdx file with no code, no build inputs, and no navigation changes.

· branch `gleb/cub-3179-docs-drag-to-place`

[claude]

Claude finished @mngr's task in 41s —— View job

---

Re-review after fd19018 — preview gating resolved, 1 low (duplication) remains

Full review

• Read new commit fd19018 and current file state
• Re-check against docs-mintlify/CLAUDE.md conventions
• Verify the support link target exists
• Check existing review threads for dedup / resolution
• Post findings

What changed

fd19018 adds a <Warning> preview callout after the Adding widgets section. That resolves the medium finding from the previous review:

• States the feature is in preview and the behavior may still change ✅
• Points at Cube support to activate for the account ✅ — target docs-mintlify/admin/account-billing/support.mdx exists, link path is correct
• No internal flag name (useBoardDashboards) leaked into public docs ✅

On placement: CLAUDE.md says the preview <Warning> goes right after the frontmatter, but that rule is written for a page that documents a preview feature end-to-end. Here only one bullet of a broader page is in preview, so scoping the callout to the section it applies to is the better read of the intent — putting it at the top would wrongly imply the whole Widgets page is preview. Fine as-is.

Remaining finding

Low — the drag bullet and the callout say the same thing twice (widgets/index.mdx:24,28)

Line 24 is still three sentences for one interaction, and the callout now re-describes the same behavior ("Dragging a toolbar item to place it exactly (drag-to-place)") plus a third restatement of click-to-add ("Clicking to add a widget is available to everyone"), which line 23 already covers. CLAUDE.md's "say it once — don't restate the same point in prose and again in a callout" applies directly. Suggested shape:

- **Click** it to drop the widget into the first open spot on the canvas.
- **Drag** it onto the canvas to place it exactly where you want — surrounding widgets reflow to open a slot as you drag. Useful on dense dashboards, where clicking would place the widget far down the page.

<Warning>

Drag-to-place is currently in preview, and the behavior may still change. Reach out to the [Cube support team](/admin/account-billing/support) to activate it for your account.

</Warning>

Fix this →

This is style, not correctness — merge-blocking only if you want it tight.

Threads

Re-affirmed 1 prior thread on widgets/index.mdx:24 — the availability half is now addressed by the callout, but the trim half still applies, so I left it unresolved rather than opening a duplicate.

Nit (unchanged)

Still no screenshot placeholder for a drag interaction: {/* TODO: screenshot — dragging a chart from the toolbar with the placeholder visible */}.

Not applicable

Security, performance, testing, and error handling have no surface here — prose-only change to a single .mdx, no code, no build inputs, no docs.json changes needed.

· · branch gleb/cub-3179-docs-drag-to-place

[claude]

Claude finished @mngr's task in 58s —— View job

---

Re-review after force-push (4ae2cad) — preview gating in place, 1 low (say-it-once) remains

Full review

• Read current branch state (4ae2cad — squashed/amended, now carries both the section and the callout)
• Re-check against docs-mintlify/CLAUDE.md conventions
• Verify the support link target and sibling preview-callout wording
• Check existing review threads (1 prior thread, already resolved by the author)
• Post findings

State of the branch

The branch was force-pushed, so git log origin/master..HEAD now shows a single commit 4ae2cad containing the whole change — the Adding widgets section plus the preview <Warning>. Reviewing against that as the current state.

What's good

• Right site (/docs-mintlify), right page — extends an existing page rather than adding one, so no docs.json change is needed.
• Section starts at H2; terminology matches the sibling pages (Charts picker, Add Widgets, Add Controls / Filter / Time Granularity).
• Preview gating resolves the medium finding from the first review: it says the feature is in preview, points at Cube support (target docs-mintlify/admin/account-billing/support.mdx exists, path correct), and leaks no internal flag name.
• Callout wording matches the established pattern — same phrasing as widgets/layout.mdx:8 and the Arranging widgets callout further down this page.
• On placement: CLAUDE.md:304 puts the preview <Warning> right after the frontmatter, but that rule is written for a page documenting a preview feature end-to-end. Here only one bullet is in preview, and CLAUDE.md:67 ("place the callout immediately after the section heading it applies to") is the better fit. Scoping it to the section is correct — a top-of-page callout would wrongly imply the whole Widgets page is preview.
• No images committed.

Finding

Low — the drag behavior is stated twice, click-to-add three times (widgets/index.mdx:24,28)

Line 24 is three sentences for one interaction, and the new callout re-describes the same behavior ("Dragging a toolbar item to place it exactly (drag-to-place)") and then restates click-to-add ("Clicking to add a widget is available to everyone"), which line 23 already says. CLAUDE.md:265 — "Say it once. Don't restate the same point in prose and again in a callout." The callout only needs the availability fact. Left an inline suggestion with the trimmed shape.

Fix this →

Threads

The one prior thread on widgets/index.mdx:25 is now resolved (author addressed the availability half). Since the duplication is a new consequence of the added callout — different root cause, different fix — I posted a fresh inline comment rather than reopening. I resolved nothing; the thread was already closed by the author.

Nit (unchanged)

Still no screenshot placeholder for a drag interaction, which is hard to convey in prose: {/* TODO: screenshot — dragging a chart from the toolbar with the placeholder visible */} (CLAUDE.md:329).

Not applicable

Security, performance, testing, and error handling have no surface here — prose-only change to a single .mdx, no code, no build inputs, no navigation changes. No lint or test suite was run; there is nothing executable in the diff.

· branch `gleb/cub-3179-docs-drag-to-place`

[claude]

The preview gating is right — this matches the sibling convention on layout.mdx:8 and in the Arranging widgets section below, and it keeps the internal flag name out of public docs. One leftover: with the callout added, the drag behavior is now described twice and click-to-add three times.

• Line 24 spends three sentences on the interaction; the placeholder-and-reflow detail is visible the instant you start dragging.
• Line 28 re-explains what dragging does ("Dragging a toolbar item to place it exactly") and then restates click-to-add ("Clicking to add a widget is available to everyone"), which line 23 already covers.

docs-mintlify/CLAUDE.md:265 — "Say it once. Don't restate the same point in prose and again in a callout." The callout only needs the availability fact; the behavior belongs in the bullet.

Suggested change

	- **Click** it to drop the widget into the first open spot on the canvas.
	- **Drag** it from the toolbar onto the canvas to place it exactly where you want. As you drag, a full-size placeholder previews the widget's footprint and the surrounding widgets reflow to open a slot; release to drop it there. Dragging is especially handy on dense dashboards, where clicking would otherwise place the new widget far down the page.
	<Warning>
	- **Drag** it onto the canvas to place it exactly where you want — surrounding widgets reflow to open a slot as you drag. Useful on dense dashboards, where clicking would place the widget far down the page.
	<Warning>
	Drag-to-place is currently in preview, and the behavior may still change. Reach out to the [Cube support team](/admin/account-billing/support) to activate it for your account.

Style, not correctness.