Skip to content

feat(ui): block settings menu as a plugin surface - #200

Open
gohabereg wants to merge 38 commits into
mainfrom
feat/block-settings-ui
Open

gohabereg wants to merge 38 commits into
mainfrom
feat/block-settings-ui

Conversation

@gohabereg

Copy link
Copy Markdown
Member

Implements the block-settings-ui change from #189, the last of the three that replace the Block Tune entity. Stacked on #193 — review that first; this diff is the UI and the plugin.

A "tune" is now just a plugin that puts an item in a menu. BlockSettingsUI renders the menu and owns no items of its own; everything in it comes from providers registered through api.plugins['block-settings'], the built-in Move up / Move down / Delete included. Nothing in the editor has a privileged path into that menu.

What's in it

  • BlockSettingsUI (@editorjs/ui) — the menu, plus register(provider, options?) returning an unregister function. Providers are asked again on every open, so item state is derived rather than cached; contributions are concatenated by ascending order with a separator between providers, and one that returns nothing adds no separator either.
  • @editorjs/default-block-settings-plugin — the built-in entries, registered at order: 1000 so they sit last. 100% mutation score.
  • packages/ui gets its first test suite — Jest with jsdom, CSS Modules mapped to their own class names.
  • Registered by the bundle, with an e2e suite driving the whole round trip in Chromium and WebKit.

Three things worth a reviewer's attention

The plugin owns its button, not the toolbar. ToolbarUI was naming it, tracking its aria-expanded and following block selection on its behalf — all state belonging to a plugin that may not be registered. The plugin now announces the button and the menu together through ui:block-settings:rendered, and the toolbar only places them. The button is announced separately from the menu rather than nested in it, because the toolbar's roving tabindex reads direct children of its actions container: wrapped, it would silently drop out of the single-tab-stop contract main already asserts in e2e.

Handlers resolve the block from blockId, never blockIndex. A menu can stay open while a collaborator inserts a block above the target, or while an undo runs. isDisabled is necessarily a build-time snapshot, so the built-in handlers carry their own bounds check rather than trusting it — a stale disabled state then only greys an item out, where a stale index would move the wrong block.

Providers are isolated. This is a public extension point whose whole job is running third-party code. One provider throwing used to take the entire menu down for every block, losing the entries of plugins that did nothing wrong; each is now wrapped, and a failure is reported the way BlockRenderer reports a tool that fails to render.

Naming

@editorjs/block-actions-plugin became @editorjs/default-block-settings-plugin. #187 ships "Block actions" as the toolbar container's accessible name, asserted in two e2e suites and carried in a requirement title; the plugin was still only spec text, so it was far the cheaper side to move. Rejected block-operations — collaboration-manager already owns that word.

Found and fixed while building it

  • Menu rows were shrink-wrapped to their labels, so the hover highlight covered a ragged part of each row — wrapperTag: 'button' is right for ui-kit's inline popover, wrong for a vertical menu. Guarded by an e2e test, since only a real layout engine sees it.
  • ToolboxUI's open event was constructed with an event name where a payload belongs; the empty payload type accepted the string, so every listener had been receiving detail: 'ui:toolbox:open'.
  • The shared base-coverage action would have failed on this very PR: it skipped a package missing from the base ref, but not one present there without a test suite — the case of any PR adding its first.

Deliberately out of scope

Three pre-existing issues found while reviewing this, each carded on the project board rather than folded in: UI components mounting in registration order, the editor never activating a @codexteam/ui theme (so var(--accent--*) is dead), and the e2e suites not yet grouped onto test.describe. None is introduced here and each touches files this change does not otherwise go near.

Notes for review

  • Task 5.3 is intentionally unchecked: the archive gate reads an all-checked task list as ready-to-archive, and its second half — filling the new capabilities' ## Purpose — can only happen after /archive.
  • Ported work from feat: implement Block Tunes #157 is credited to @bettysteger on the three commits that carry it.

Verified: yarn build and yarn lint clean, 1,111 unit tests, 100 e2e across Chromium and WebKit, openspec validate block-settings-ui --type change passes.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Unit Tests

Package Coverage Delta
@editorjs/ui 71.15% N/A
@editorjs/editorjs 100% 0% ⚪️
@editorjs/collaboration-manager 87.58% 0% ⚪️
@editorjs/shortcuts-plugin 100% 0% ⚪️
@editorjs/default-block-settings-plugin 100% N/A
@editorjs/core 78.05% +0.28% 🟢
@editorjs/ot-server 20% 0% ⚪️
@editorjs/clipboard-plugin 66.66% 0% ⚪️
@editorjs/dom-adapters 86.95% 0% ⚪️
@editorjs/model 98.61% 0% ⚪️
@editorjs/model-types 67.85% 0% ⚪️

Mutation Tests

Package Mutation score Dashboard URL
@editorjs/dom-adapters No files to mutate found.
@editorjs/shortcuts-plugin No files to mutate found.
@editorjs/model No files to mutate found.
@editorjs/default-block-settings-plugin 100.00% 🟢 Dashboard
@editorjs/collaboration-manager No files to mutate found.
@editorjs/clipboard-plugin No files to mutate found.
@editorjs/core 88.57% 🟢 Dashboard

@gohabereg
gohabereg force-pushed the feat/remove-block-tunes branch from cafb423 to 46e05e9 Compare October 9, 2026 23:06
@gohabereg
gohabereg force-pushed the feat/block-settings-ui branch 2 times, most recently from 0eebcb2 to 63243e2 Compare October 10, 2026 01:16
@gohabereg
gohabereg force-pushed the feat/remove-block-tunes branch 2 times, most recently from 7cbecaf to 02eff13 Compare October 13, 2026 16:09
@gohabereg
gohabereg force-pushed the feat/block-settings-ui branch from 63243e2 to c115815 Compare October 13, 2026 16:09
@gohabereg
gohabereg requested a balanced review from Copilot October 16, 2026 20:59

Copilot AI 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.

🟡 Changes recommended

Unresolved selection and menu-state defects can expose actions for the wrong block or reopen dismissed menus.

5 open issues
What changed in this PR

Replaces Block Tune UI with a provider-based settings menu and an ordinary plugin for built-in block actions.

Changes:

  • Adds the settings menu, provider API, and default Move/Delete entries.
  • Integrates toolbar controls and keyboard-driven block selection.
  • Adds tests, CI workflows, build support, and documentation.
File Description
yarn.lock Locks new plugin and testing dependencies.
packages/​ui/​vite.config.ts Excludes tests from declaration output.
packages/​ui/​test/​styleMock.cjs Mocks CSS Modules.
packages/​ui/​test/​emptyModule.cjs Mocks stylesheet side effects.
packages/​ui/​src/​Toolbar/​Toolbar.ts Mounts settings controls and tracks menu state.
packages/​ui/​src/​Toolbar/​Toolbar.spec.ts Tests toolbar integration and cleanup.
packages/​ui/​src/​Toolbar/​Toolbar.module.pcss Arranges toolbar controls horizontally.
packages/​ui/​src/​Toolbar/​Toolbar.const.ts Removes obsolete button class mapping.
packages/​ui/​src/​messages.ts Adds settings accessibility labels.
packages/​ui/​src/​index.ts Exports settings functionality.
packages/​ui/​src/​controls.module.pcss Shares toolbar button styling.
packages/​ui/​src/​BlockSettings/​events/​index.ts Exports settings events.
packages/​ui/​src/​BlockSettings/​events/​BlockSettingsRenderedUIEvent.ts Announces button and menu elements.
packages/​ui/​src/​BlockSettings/​events/​BlockSettingsOpenUIEvent.ts Defines programmatic open requests.
packages/​ui/​src/​BlockSettings/​events/​BlockSettingsOpenedUIEvent.ts Defines opened notifications.
packages/​ui/​src/​BlockSettings/​events/​BlockSettingsClosedUIEvent.ts Defines closed notifications.
packages/​ui/​src/​BlockSettings/​events/​BlockSettingsBaseEvent.ts Namespaces settings events.
packages/​ui/​src/​BlockSettings/​BlockSettings.ts Implements provider-based settings UI.
packages/​ui/​src/​BlockSettings/​BlockSettings.spec.ts Tests providers and menu lifecycle.
packages/​ui/​src/​Blocks/​Blocks.ts Reports caret-based block selection.
packages/​ui/​src/​Blocks/​Blocks.spec.ts Tests selection notifications.
packages/​ui/​package.json Adds UI testing and build dependencies.
packages/​ui/​jest.config.ts Configures browser-like unit tests.
packages/​ui/​eslint.config.mjs Allows test imports.
packages/​sdk/​src/​entities/​EntityType.ts Adds settings UI component type.
packages/​sdk/​src/​api/​BlocksAPI.ts Declares tool-name lookup.
packages/​plugins/​default-block-settings-plugin/​tsconfig.json Configures plugin compilation.
packages/​plugins/​default-block-settings-plugin/​tsconfig.eslint.json Configures lint type checking.
packages/​plugins/​default-block-settings-plugin/​tsconfig.build.json Excludes tests from builds.
packages/​plugins/​default-block-settings-plugin/​stryker.conf.mjs Configures mutation testing.
packages/​plugins/​default-block-settings-plugin/​src/​index.ts Supplies built-in Move/Delete entries.
packages/​plugins/​default-block-settings-plugin/​src/​index.spec.ts Tests registration and guarded actions.
packages/​plugins/​default-block-settings-plugin/​README.md Documents plugin behavior and usage.
packages/​plugins/​default-block-settings-plugin/​package.json Defines plugin package and scripts.
packages/​plugins/​default-block-settings-plugin/​jest.config.ts Configures plugin unit tests.
packages/​plugins/​default-block-settings-plugin/​eslint.config.mjs Configures plugin linting.
packages/​plugins/​default-block-settings-plugin/​.gitignore Excludes generated artifacts.
packages/​playground/​package.json Orders builds by development dependencies.
packages/​editorjs/​src/​index.ts Registers settings UI and default plugin.
packages/​editorjs/​src/​index.spec.ts Tests bundle registration.
packages/​editorjs/​package.json Adds plugin dependency and build ordering.
packages/​editorjs/​e2e/​tests/​block-settings.spec.ts Tests settings interactions and layout.
packages/​editorjs/​e2e/​tests/​axe.spec.ts Audits settings menu accessibility.
packages/​core/​src/​components/​BlockManager.ts Implements tool-name lookup.
packages/​core/​src/​api/​BlocksAPI.ts Exposes tool-name lookup.
packages/​core/​src/​api/​BlocksAPI.integration.spec.ts Tests lookup behavior.
package.json Updates workspace build ordering.
openspec/​changes/​block-settings-ui/​tasks.md Records implementation progress.
docs/​plugins.md Documents settings providers and APIs.
docs/​events.md Documents settings and selection events.
.github/​workflows/​ui.yml Adds UI package checks.
.github/​workflows/​default-block-settings-plugin.yml Adds plugin checks and mutation testing.
.github/​actions/​base-coverage/​action.yml Skips unavailable baseline coverage scripts.

Review effort: Balanced

return;
}

this.#selectedBlockIndex = event.detail.index;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Fixed. A build now remembers which block it is for, and #handleBlockSelected abandons it when the selection moves elsewhere — the same invalidation a close uses.

Regression test registers a slow provider, dispatches an open for block 0, reports block 1 as selected while it is still running, and asserts nothing opens. It fails without the invalidation.

Comment on lines +246 to +248
this.#button = make('button', ControlStyle['toolbar-button'], {
innerHTML: IconMenuSmall,
}) as HTMLButtonElement;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Fixed — the button is created with type="button".

return;
}

this.#isOpen = false;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Fixed. Both close paths abandon a build in flight now, through one helper that destroy() also calls. Putting the token bump only in #close() was the mistake: that is the programmatic path, and Escape and outside clicks — the ones users actually take — arrive at #handleClosed straight from the popover.

Regression test opens a menu for block 0, requests one for block 1 whose provider is still running, dismisses with Escape, and asserts the replacement never opens.

Comment thread packages/ui/src/Blocks/Blocks.ts Outdated
const block = event.target as HTMLElement;
const index = this.#blocks.indexOf(block);

this.#selectBlock(block, this.#blocks.indexOf(block));

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Fixed, and this one was a regression from the deduplication added in an earlier review round, so thank you for catching it. Pointer entry is announced unconditionally again; caret moves keep the deduplication, which is what it was for — selectionchange fires on every keystroke and most stay inside one block.

mouseenter only fires on actually crossing into a block, so there was never any repetition there to suppress. Two cases in Blocks.spec.ts: alternating hovers report every entry, and a hover still reports a block the caret just reported.

@gohabereg
gohabereg force-pushed the feat/block-settings-ui branch from c115815 to c0480f4 Compare October 16, 2026 23:01
@gohabereg
gohabereg force-pushed the feat/remove-block-tunes branch from 02eff13 to 5f852d7 Compare October 16, 2026 23:01
@gohabereg
gohabereg force-pushed the feat/block-settings-ui branch from c0480f4 to b38bb29 Compare October 17, 2026 16:30
@gohabereg
gohabereg force-pushed the feat/remove-block-tunes branch 2 times, most recently from 119c8bf to 36fa683 Compare October 17, 2026 18:52
@gohabereg
gohabereg force-pushed the feat/block-settings-ui branch from b38bb29 to 17d624b Compare October 17, 2026 18:52
@gohabereg
gohabereg force-pushed the feat/remove-block-tunes branch from 36fa683 to 973d1c7 Compare November 5, 2026 01:55
@gohabereg
gohabereg force-pushed the feat/block-settings-ui branch from 17d624b to f31e3a4 Compare November 5, 2026 01:55
@gohabereg
gohabereg force-pushed the feat/remove-block-tunes branch from 973d1c7 to e163fa1 Compare November 5, 2026 02:02
@gohabereg
gohabereg force-pushed the feat/block-settings-ui branch from f31e3a4 to 4dc8b23 Compare November 5, 2026 02:02
@gohabereg
gohabereg requested a review from Reversean November 5, 2026 02:03
@gohabereg
gohabereg force-pushed the feat/remove-block-tunes branch from e163fa1 to e2760fa Compare November 8, 2026 13:47
@gohabereg
gohabereg force-pushed the feat/block-settings-ui branch from 4dc8b23 to 4c9013d Compare November 8, 2026 13:47
@gohabereg
gohabereg requested a review from Reversean November 8, 2026 14:01
Base automatically changed from feat/remove-block-tunes to main November 8, 2026 16:30

@neSpecc neSpecc 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.

Since #193 is merged, this needs a rebase onto main (the diff still includes #193) and a CI rerun afterwards. Overall it looks good to me, no blockers, just a few points inline. Missing tests worth adding: stale target after a block is inserted/removed above the selected one, clicking into another block while the menu is open and then opening it from the keyboard, a provider whose onActivate throws, and the closed/opened events when the menu is rebuilt while already open.

* Frozen while the menu is open: the menu belongs to one block, and re-targeting under it
* would leave the button and the open menu pointing at different blocks
*/
#selectedBlockIndex = -1;

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.

The target is stored as an index and only updated by block-selected, so after a block is inserted/removed above it (collaborator, undo, move) the button opens the menu for a different block until the next selection event. Consider keeping the block id (or its element) from the selection event and resolving the index at open time, or at least adjusting/resetting on core:BlockAdded/BlockRemoved.

Comment thread packages/ui/src/Blocks/Blocks.ts Outdated
* `selectionchange` fires for every caret move, most of which stay inside one block, so
* announcing each one would be noise. Pointer entry is announced unconditionally instead
*/
if (index === this.#selectedBlockIndex) {

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.

Dedup is by index, and #selectedBlockIndex isn't adjusted in #addBlock/#removeBlock. E.g. after deleting block 2 the caret lands in the new block 2 and nothing is announced. Deduping by the wrapper element (or resetting on add/remove) would avoid that.

* re-targeting here would leave the button and this target on different blocks
* @param event - the selection event
*/
#handleBlockSelected = (event: BlockSelectedUIEvent): void => {

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.

Selections reported while the menu is open are ignored here (and in ToolbarUI), but BlocksUI has already recorded them, so they're never re-announced. If you click into another block while the menu is open, the caret moves on mousedown before the popover closes on click, and the toolbar/target stay on the old block. Maybe re-announce the caret block on block-settings:closed/toolbox:closed, or reset the BlocksUI dedup then?

* @param items - items the menu should consist of
*/
#renderPopover(items: PopoverItemParams[]): void {
this.#popover?.destroy();

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.

In ui-kit 2.0.1, PopoverDesktop.destroy() calls hide(), which emits Closed. The old popover is still subscribed to #handleClosed, so rebuilding while the menu is open sends a spurious closed + opened pair and briefly flips aria-expanded. Unsubscribe (off(PopoverEvent.Closed, ...)) before destroying.

* Inside the `try` on purpose: an `isActive` that throws is this provider failing, so it costs this
* provider's items rather than the whole menu
*/
return items.map(withResolvedActiveState);

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.

Building and isActive are isolated, but a throwing onActivate (or confirmation handler) still blows up inside ui-kit's click handler, and closeOnActivate doesn't run. Could wrap onActivate (nested and confirmation too) in the same try/catch + log while resolving items.

const items = await this.#collectItems({
blockId,
blockIndex: index,
tool: this.#api.blocks.getToolByIndex(index) ?? '',

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.

nit: once blockId resolved, an undefined tool means things are out of sync, and '' hides that. I'd treat it as "no block" and not open, or make tool optional in the context.

* @param provider - called with the target block each time the menu opens
* @param options - registration options
*/
#register(provider: BlockSettingsProvider, options?: BlockSettingsRegisterOptions): () => void {

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.

nit: unregistering doesn't touch an already open menu, so the provider's items stay until the next open. Fine, but worth a line in the register JSDoc.

return [
{
name: 'move-up',
title: 'Move up',

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.

nit: titles here ('Move up', 'Move down', 'Delete', 'Click to delete') are hardcoded English, while ui has a messages catalogue. I'd move them there or into plugin config so they can be localized later.

holder: make('div', Style[css.toolbar]) as HTMLDivElement,
actions: make('div', Style[css.actions]) as HTMLDivElement,
plusButton: make('button', Style[css.plusButton], {
plusButton: make('button', ControlStyle['toolbar-button'], {

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.

nit: the settings button got type: 'button' to avoid submitting an enclosing form, but the plus button still defaults to submit. Same fix here?

* long after the provider's own `try` has returned, and a throw there aborts the popover and every provider's items
* @param item - item as the provider returned it
*/
function withResolvedActiveState(item: PopoverItemParams): PopoverItemParams {

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.

nit: going through Record<string, unknown> and as drops the types. Narrowing the PopoverItemParams union and spreading would keep it type-safe (behaviour is fine, since ui-kit only reads isActive at render).

`@editorjs/ui` is the first package here that renders DOM, so it is also the
first to need `jest-environment-jsdom` as an explicit dependency. Two
module mappings make its sources loadable under Jest: `@codexteam/ui`'s
side-effect theme imports become an empty module, and CSS Modules resolve to a
proxy that answers each property with its own name, so an assertion on rendered
markup names the class the source asked for. `@codexteam/*` joins `@editorjs/*`
in `transformIgnorePatterns` because ui-kit ships as ESM.

Declaration emit moves to `tsconfig.build.json`, the config that excludes
`*.spec.ts`, so `dist` does not grow typings for the tests.

The shared `base-coverage` action skipped a package missing from the base ref
but not one present there without a test suite -- the case of any PR adding a
first suite, this one included. It would have run `test:coverage` on the base
ref and failed with "couldn't find a script", so its guard now also checks that
the script exists.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
gohabereg and others added 12 commits November 16, 2026 18:44
Eleven comments added by this change ran to three or four. Same content,
tightened: the plugin and provider docs, the rebuild-per-open and item-wrapper
notes, the toolbar's mounting contract, the shared button stylesheet, the CSS
Modules mock and the row-width regression test.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…sting

Two packages here depend on another workspace for its *types* only, and neither
the build order nor the CI jobs accounted for it.

`@editorjs/default-block-settings-plugin` takes `@editorjs/ui` as a
devDependency and imports from it with `import type`, so that
`api.plugins['block-settings']` typechecks without a runtime coupling. The
build scripts order by `--topological`, which sees dependencies but not
devDependencies, and run in parallel -- so the plugin was free to build before
`@editorjs/ui` had emitted anything. They now order by `--topological-dev`.

`@editorjs/ui` had no way to build its workspace dependencies at all: its build
is `vite build`, with none of the project references that make the tsc-built
packages pull `@editorjs/sdk` along, and its `build:declaration` was empty. The
new `ui.yml` workflow is what exposed this -- its lint and test jobs ran against
an unbuilt `@editorjs/sdk`. It gets the `build:dependencies` script
`@editorjs/editorjs` and the playground already use.

Reproduced each failure locally by clearing every `dist` *and* `tsbuildinfo` --
with the latter left behind, `tsc --build` believes its output is current and
emits nothing, which looks like a different bug entirely. From genuinely cold:
build, lint and test all clean, 1111 tests.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Three findings from reviewing this branch, plus the housekeeping around them.

The button did nothing at all for a keyboard-only user. `BlockSelectedUIEvent`
was dispatched on `mouseenter` and nowhere else, so with no pointer the
plugin's target index stayed `-1` and activating a control that is reachable,
named and `aria-haspopup`-annotated silently opened nothing. `BlocksUI` now
also reports the block the caret moves into. Reading the editor's own caret
state instead would not work: it is cleared the moment focus leaves the
editable, which is exactly what reaching for a toolbar does.

The button did not toggle. ui-kit closes the popover from a listener that
runs before the button's own handler, so the handler saw a closed menu and
re-opened it, and the menu could not be dismissed from the control that
advertises it. The open state is now read on `mousedown` — the last moment
the answer is still true — and tracked by the plugin rather than read back
off the popover, whose shown state does not survive that click.

Reading one block's tool name went through `api.document.data`, which
serializes every block, every text node and every inline fragment tree, on
every open of the menu. `BlocksAPI.getToolByIndex` replaces it, and the
default plugin's two `document.data.blocks.length` reads become
`getBlocksCount()`.

Alongside: the UI package's `MenuConfig` becomes `BlockSettingsMenuConfig`,
since `@editorjs/sdk` already exports a different type by that name and the
two are not interchangeable; `BlockSettingsUI`, `DefaultBlockSettingsPlugin`
and `ToolbarUI` drop their event bus listeners on `destroy`, the bus having
outlived them; and `build:declaration` emits declarations again rather than
only building dependencies.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
its own: a provider that never settles meant the menu never opened, and
never opened again either, because every later attempt waited on the same
provider. Each one now races a timeout, and the expiry lands in the same
skip-and-log path as a provider that threw.

A close arriving while the menu is still being built was also ignored,
because #isOpen is only set once the providers have returned -- so the
menu appeared a moment after the caller asked for it to be gone. #close()
abandons the request in flight before looking at the open state. destroy()
had the same hole: dropping the bus listeners stops the next request, not
the one already waiting on a holder that is about to be removed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Four ways the menu and the block it acts on could come apart.

A build in flight was only abandoned by #close(). Escape and a click
outside reach #handleClosed straight from the popover, so a menu
dismissed while a replacement was being built came back as soon as that
replacement's provider returned. Both close paths now abandon it, through
one helper that destroy() uses too.

Selection was still followed while a build was in flight, because #isOpen
is only set once the providers return. The build for the block the user
asked about would then finish and put its actions beside whichever block
the pointer had moved to. A build remembers which block it is for and is
abandoned when the selection leaves it.

The toggle read a state captured on mousedown, which a keyboard
activation never sets: Enter and Space send a click with no pointer
events at all. Their keydown is where that activation starts, so it is
recorded there as well, and the click reads the live state too so the
toggle no longer depends on which of the popover's dismissal and this
handler runs first.

The button carried no type, so an editor mounted inside a form submitted
it on every click of this control.

BlocksUI deduplicated pointer entry along with caret moves. `mouseenter`
only fires on actually crossing into a block, so there was no repetition
to suppress -- and suppressing it stranded the toolbar and the settings
menu, both of which ignore selection while the menu is open: after
dismissing a menu opened on another block, returning to this one told
them nothing and they kept acting on the old one. Caret moves are still
deduplicated, since selectionchange fires for every one of them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`ToolbarUI` holds its position while the toolbox is open, because that popover renders inside
it, but nothing told `BlockSettingsUI`. Hovering another block moved the target while the button
stayed where it was, so the menu opened for a block it was not beside -- and `Delete` is one of
the items it offers.

The plugin now follows the toolbox's own events and stops tracking the selection for as long as
the toolbar is holding its position, as it already did for its own open menu.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
ui-kit calls `isActive` while it renders an item, which happens in `#renderPopover` -- long
after the per-provider `try` in `#collectItems` has returned. One throwing callback aborted the
whole popover, so every other provider's items went with it and no menu opened at all.

Those callbacks are now called inside the provider's own error handling and ui-kit is handed the
values they return, at any depth of nested items and on an item's confirmation state. A throw
costs that provider's items, as returning nothing does. Nothing is lost by resolving early:
ui-kit reads the value once per render, and the popover is rebuilt on every open.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…-ui follow-ups

The spec change for the stack is merged, so this round's delta specs land here, with the code
that implements them, rather than in a spec PR of their own. `design.md` gains the reasoning for
the plugin tracking the toolbox itself, and the single-owner alternative that was rejected.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
ui-kit's flipper claims Enter for the menu it owns and prevents the default before the event
reaches the button, so the browser produces no `click` and the toggle that lives on it never
runs. The menu could not be dismissed from the button that opened it at all.

The keydown handler already received that key and only recorded the open state. It now closes
the menu when the default has been prevented, which is exactly the activation that will produce
no click. The click stays the primary path, so pointer activation and opening from the keyboard
behave as before, and the unit helper that dispatches a keydown and a click together keeps
meaning what it did.

Confirmed in Chromium and WebKit: focus stays on the button, the keydown arrives with the default
already prevented in the capture phase, and no click follows. The e2e case dropped when this was
first found -- on the view that the remaining half belonged upstream -- comes back with it, and
fails in both engines without the fix.

A second case covers a claimed key arriving while the menu is closed: it must open nothing, since
a dismissal is all that keydown stands in for.

The suppression itself is still ui-kit's, and is on the board as "Flipper claims Enter aimed at
the button that owns the popover". If that changes, this compensation becomes dead code and
should go with its tests.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ui follow-ups

The button requirement already promised the toggle holds however the button is activated. This
says what that takes when the open menu's own keyboard handling claims the key.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@gohabereg
gohabereg force-pushed the feat/block-settings-ui branch from 3a4d81a to 97c8c97 Compare November 16, 2026 18:51
Comment thread .github/workflows/ui.yml Fixed
gohabereg and others added 15 commits November 16, 2026 22:18
The target was a position, updated only by `ui:blocks:block-selected`. A block inserted or
removed above it shifts every position below, and none of the ways that happens -- a
collaborator, an undo, a move -- reports a selection, so the button quietly came to act on
whichever block slid into that position, with `Delete` among the items it offers.

The selection is recorded as a block id now, and the position resolved again when the menu
opens. `getIndexById` returns -1 for a block that is gone, which lands in the existing "no
block, do not open" path rather than needing one of its own.

`#buildingFor` becomes an id for the same reason: comparing a position recorded when the build
started against one reported now says nothing once the document has shifted underneath.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`#addBlock`/`#removeBlock` splice the block list without touching the position last announced,
so a position recorded earlier came to name a different block: after a removal, the next block
to take that number read as already reported, and the caret arriving there was announced to
nobody -- leaving the toolbar and the settings menu acting on a block the caret had left.

A repeat now means the same block at the same position. Both halves carry weight. Comparing
positions alone is the bug above. Comparing blocks alone hides that a block moved on the page:
the toolbar takes its vertical position from this event and from nothing else, so a block pushed
down by an insert above it has to be re-announced even though the selection never moved.

The block is compared as the element rather than by id, because within `BlocksUI` the element is
the block -- it holds the wrappers already, and the event carries them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Selection reaches other plugins as a one-shot `ui:blocks:block-selected` event, with nothing to
ask afterwards. A plugin that ignores an announcement on purpose -- as the toolbar and the
settings menu both do while a popover holds them -- had no way to find out what it missed.

`BlocksUI` gains a `publicApi`, reachable as `api.plugins.blocksUI`, answering with the selected
block's wrapper element and its id. The id is read through the position the block holds when
asked, not the one it held when it was reported, so a block inserted above it cannot leave the
answer naming whoever took its old slot. Nothing is answered once that block has been removed,
so a caller is never handed a wrapper that has left the document -- which is also why removal
needs no bookkeeping of its own.

Named `blocksUI` rather than `blocks` to keep it apart from `api.blocks`, which is the core's
block API and a different thing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Both the toolbar and the settings menu stop following selection while a popover holds them, and
the announcements they ignore are never repeated. Clicking into another block moves the caret on
mousedown while the popover only closes on the click, so both were left on the block the caret
had left -- the toolbar drawn beside it, and the button acting on it with `Delete` among the
items it offers.

Each now asks `api.plugins.blocksUI` which block is selected once nothing is holding it. Reading
a shared answer rather than each remembering what it skipped means they cannot come to disagree,
and the frozen window stays each one's own rule: the toolbar waits for both popovers, the menu
for both its own and the toolbox.

The cases that expected a skipped selection to be dropped are updated. The invariant they were
written for -- the button and the block it acts on naming the same block -- still holds, since
both now read the same answer.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`PopoverDesktop.destroy()` hides before it tears down, and hiding emits `Closed`. The popover
being replaced was still subscribed, so showing another block's items reported the menu as
closed and open again, flipping `aria-expanded` with it, though the menu never stopped being
open. Since the toolbar started catching up with the selection on a `closed`, a spurious one
could also have moved it mid-rebuild.

The subscription is dropped before the popover is destroyed. `destroy()` on the plugin itself is
left as it was: there the menu really is closing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`onActivate` runs inside ui-kit's own click handler, which honours `closeOnActivate` only after
the handler returns -- `e.handleClick(), ..., e.closeOnActivate === !0 && (this.hide(), ...)` --
so a throw escaping there abandoned the rest of the activation along with the close.

The handler is wrapped where `isActive` was already resolved, at every depth of nested items and
on an item's confirmation state. Wrapped rather than resolved, since unlike `isActive` it cannot
be called early.

Only the report is asserted: jsdom swallows a listener's exception, so neither the escape nor the
abandoned close can be observed there. That `closeOnActivate` resumes follows from the handler no
longer being able to throw out, not from a test.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The timeout containing a slow provider was a module constant, so every provider shared one
budget and a plugin needing longer had no way to ask. It is per registration now, through
`options.timeout`, and the default drops from 2000ms to 500ms.

A backstop rather than a budget: the menu shows nothing until every provider has answered, so a
provider approaching half a second is one worth noticing, and the provider type now says so. The
budget belongs with the provider it contains rather than with the editor, since a slow provider
is a property of that provider.

BREAKING CHANGE: a provider taking between 500ms and 2000ms is now left out of the menu unless it
registers with a longer `timeout`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`ui:block-settings:rendered` is dispatched once from the constructor and never replayed, so a
host registered after this plugin never hears it and the button and the menu stay off the page
with nothing reported.

Documented rather than fixed. `publicApi` is registered right after each plugin's constructor, so
a getter for late mounting would work, but this is one instance of the general problem tracked on
the board as "UI component registered before its parent never mounts", and solving it here for
this one pair would leave the rest of it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`tool` fell back to `''`, which matched no provider while looking like an answer. The id and the
tool are read from the same position, so an undefined tool means the editor's view of the block
disagrees with the Model's -- worth showing in the type rather than papering over.

Refusing to open was the other option: rejected, since the block does exist, and a menu that
will not open turns a disagreement the user cannot see into one they cannot work around.

BREAKING CHANGE: `BlockSettingsContext.tool` is optional, so a provider reading it as a string
has to handle it being absent.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Providers are asked as the menu is built, so a menu already on screen keeps the items it was
built with until it closes. The existing behaviour, said out loud on `register` and in the spec.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ne module

The titles were written inline where the items are built, while `@editorjs/ui` keeps its own
user-facing strings in a catalogue. They live in a `messages.ts` of this package's own now, so
localising them is a change to one module rather than to every item.

Plugin config was the other suggestion and is left open: a catalogue is where localisation would
read from either way, and it needs no options plumbing to be worth having now.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The settings button declares itself non-submitting; the plus button beside it still defaulted to
`submit`, so an editor mounted inside a form was posted when the toolbox was opened.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The item walk went through `Record<string, unknown>`, which dropped the types: the wrapper's
parameters were `unknown[]`, a misspelled key would have compiled, and the variants that forbid
`onActivate` were written through a string key regardless.

It narrows the union now. Half again as long -- five branches, two helpers and a named patch
type, the last because the lint config rejects an inline object return type -- and one cast is
left on the confirmation state, since the walk returns the wide union while that field holds the
base variant.

The `typeof` guard on `onActivate` matters: ui-kit optional-chains it, so an item without one at
runtime is legal, and without the guard it would be given a wrapper that throws on click.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…moved

The last of the cases the review asked for: the caret leaves the block the open menu belongs to,
and the menu is reopened without a pointer ever being used. The other three arrived with the
fixes for the stale target, the rebuilt menu and the throwing handler.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…e queue

CodeQL flagged the workflow this change adds for not restricting `GITHUB_TOKEN`, so the job
inherited the repository default rather than the four scopes a package check needs
(code-scanning alert 52).

It now declares the same block as `default-block-settings-plugin.yml`, the sibling added by this
same change, and gains the `merge_group` trigger it was also missing, so the UI package is
checked in the merge queue as well as on a pull request. No `include-mutations`: `packages/ui`
has no Stryker config.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@gohabereg
gohabereg requested a review from neSpecc November 16, 2026 22:39
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.

5 participants