Skip to content

fix(block-editor): preserve step text when switching types - #1606

Merged
moxious merged 2 commits into
grafana:mainfrom
hugosmoreira:agent/preserve-step-descriptions
Aug 17, 2026
Merged

moxious merged 2 commits into
grafana:mainfrom
hugosmoreira:agent/preserve-step-descriptions

Conversation

@hugosmoreira

@hugosmoreira hugosmoreira commented Aug 12, 2026 •

Copy link
Copy Markdown
Contributor

What does this PR do?

Preserves step text when switching between multistep and guided blocks from the type dropdown.

The dropdown previously used the generic block converter, which copied steps without translating the type-specific text field. As a result, multistep tooltip values were not moved to guided description values, and the reverse conversion had the same problem.

This change routes that pair through the existing field-aware conversion owner while preserving:

  • the existing confirmation dialog for target-incompatible fields;
  • shared block metadata such as id and authorNote;
  • root, section-nested, and conditional-branch editing behavior;
  • the generic fallback when no field-aware handler is available.

Multistep/guided dropdown conversion closes the modal after writing the converted block, while other target-type switches continue in place. Keeping this field-aware path open would render stale initial form data.

Linked issue(s)

Fixes #804

Verification

  • Focused block-form and conversion-handler tests: 14 passed
  • Applicable frontend suite with coverage: 422 suites, 6,606 tests passed
  • TypeScript typecheck
  • ESLint (0 errors; existing deprecation warnings only)
  • Prettier
  • Production webpack build
  • Documentation synchronization check
  • Negative controls confirmed the regression tests fail against the pre-fix implementation

Checklist

  • This PR addresses a single concern (one bug fix or feature, or a set of closely-related changes). Unrelated changes belong in separate PRs; see CONTRIBUTING.md.
  • All commits are signed (required, or the checks will not pass). See CONTRIBUTING.md.
  • I've added or updated tests for the change.
  • npm run check passes locally (typecheck, lint, prettier, Go lint/tests, frontend tests).
  • UI text and docs use sentence case.

@cla-assistant

cla-assistant Bot commented Aug 12, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@moxious

moxious commented Aug 13, 2026

Copy link
Copy Markdown
Collaborator

@hugosmoreira thank you for the contribution! If you could please sign the community CLA for licensing purposes, we'll take a look at the PR. Appreciate your efforts.

@hugosmoreira

Copy link
Copy Markdown
Contributor Author

@moxious Thanks! I’ve signed the community CLA, and the CLA Assistant now confirms that all committers have signed. Please let me know if anything else is needed.

@moxious
moxious marked this pull request as ready for review August 14, 2026 19:55

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 72f9663. Configure here.

@moxious moxious left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the contribution! This is a real bug and the fix is in the right place — routing the dropdown through the field-aware converter rather than duplicating the mapping. I confirmed the new tests genuinely pin it: reverting just the two source files makes 5 of the 14 fail.

A few things I'd like changed before merge.

1. handleConvertType needs the try/catch its sibling has — src/components/block-editor/hooks/useBlockConversionHandlers.ts:170

convertBlockType ends in JsonBlockSchema.safeParse and throws on failure. handleSwitchBlockType wraps that call in a try/catch that publishes a "Conversion failed" toast; handleConvertType doesn't. Before this PR that was fine, because handleConvertType hand-built the block and couldn't throw — now it can, and this PR routes the dropdown into it.

The reachable case comes through the conditional-branch support you added: BranchBlocksEditor.createDefaultBlock returns { type: 'multistep', content: '', steps: [] } and commits it to the branch with no schema check. convertBlockType copies those empty values in step 3, which makes step 4's REQUIRED_DEFAULTS skip them (!(key in converted)), so safeParse fails on content.min(1) / steps.min(1) and throws. Because the throw escapes a React click handler, error boundaries don't catch it — updateBlock and closeBlockForm never run, so the user gets no conversion, no modal close, and no message. A guided formfill step with validateInput: true and no targetvalue fails the same way.

Please wrap the conversion in the same try/catch + alert-error as handleSwitchBlockType (:246-252), or pull that handling into a small shared helper so the two entry points can't drift apart again, and add a test for the failing case.

2. The root and section-nested paths aren't directly covered — useBlockConversionHandlers.test.ts:11,65

Both new hook cases set editingConditionalBranchBlock, with editingBlock and editingNestedBlock null. The modal tests assert routing only (expect(onConvertType).toHaveBeenCalledWith('guided')). There were no pre-existing tests for handleConvertType, so the reported symptom — a root-level multistep with steps[].tooltip converting to guided steps[].description — is only covered compositionally across two files, and the updateBlock / updateNestedBlock arms are never exercised.

Two more cases mirroring the ones you wrote would close it: one with editingBlock asserting updateBlock(id, { type: 'guided', steps: [{ description: '…' }] }), one with editingNestedBlock. While you're there, asserting JsonBlockSchema.safeParse(arg).success on the captured block is one extra line and pins something the current shape leaves open — convertBlockType validates, and then the spread replaces steps afterwards, so what actually gets written was never parsed. That's harmless today since both block types share one step schema, but the as JsonMultistepBlock | JsonGuidedBlock assertion means the compiler isn't checking it either.

3. Trim the restating comments in the function you rewrote — useBlockConversionHandlers.ts:161,186,189,193

// Update nested block, // Update root-level block, // Close the modal. Our convention (AGENTS.md, "trim on touch") is to drop comments that restate the code when you're editing the surrounding function. Your new updateConditionalBranchBlock branch already has none, which is right. Leave // Update block type - triggers form remount via key prop change at :237 — that one names a non-obvious mechanism.

4. Worth a line in the PR description

Picking guided from the dropdown now closes the modal, while every other target keeps it open. That's correct as implemented — handleConvertType doesn't re-seed the editing state, so keeping the modal open would render stale initialData — but it's a user-visible change and shouldn't be discovered from the diff.

One thing you don't need to chase: compare and publish-report are failing with Resource not accessible by integration, which is the bundle-size action being unable to comment from a fork. Everything substantive is green.

@hugosmoreira

Copy link
Copy Markdown
Contributor Author

Thanks @moxious — I addressed all four requests in fb4343f.

  • Added shared conversion-failure handling used by both conversion entry points. The field-aware path now logs and publishes the existing alert-error event without updating state or closing the form when validation fails.
  • Added direct root and section-nested hook tests, including the mapped step field, the correct persistence callback, and JsonBlockSchema validation of the exact written block.
  • Added the reachable invalid conditional-branch regression test covering no throw, no update, no close, and error notification.
  • Removed the four restating comments while retaining the non-obvious form-remount comment.
  • Updated the PR description to document the intentional modal close after multistep/guided dropdown conversion.

Verification:

  • focused hook tests: 5 passed
  • hook + BlockFormModal tests: 17 passed
  • TypeScript typecheck, changed-file ESLint/Prettier, production webpack build, and diff check: passed
  • negative control: bypassing the new catch makes the regression test fail with the original validation exception; restoring it returns 5 passed

The complete local Windows Jest run also exposed unrelated POSIX path-separator assumptions; after isolating the child-Git trust issue, three unrelated Windows-only suites remain. No claim that the full local suite passed. GitHub CI is rerunning on the signed commit.

@moxious moxious left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the contribution and for addressing those comments!

@moxious
moxious merged commit 52b1fe5 into grafana:main Aug 17, 2026
32 of 34 checks passed
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.

Block editor: multistep ↔ guided type switch via dropdown silently loses step description data

2 participants