Repository navigation
docs(openspec): propose replacing Block Tunes with plugins #189
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
a6eb135
docs(openspec): propose replacing Block Tunes with plugins
gohabereg e4521ac
docs(openspec): spell out plugin-data key handling in tasks
gohabereg ba1f365
Merge branch 'main' into spec/tunes-as-plugins
gohabereg 9cf08ab
docs(openspec): reconcile block-settings-ui with the merged ARIA work
gohabereg e6d5f32
docs(openspec): fold the implementation branches' spec edits back in
gohabereg bd54a53
docs(openspec): specify the review follow-ups for the tunes-as-plugin…
gohabereg 23c1c31
Merge branch 'main' into spec/tunes-as-plugins
gohabereg 4942c30
docs(openspec): specify the second round of review follow-ups
gohabereg 2beea89
docs(openspec): specify the third round of review follow-ups
gohabereg b657798
docs(openspec): finish the sweep the last two review rounds started
gohabereg cec3580
Merge branch 'main' into spec/tunes-as-plugins
gohabereg File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| schema: spec-driven | ||
| created: 2026-09-21 |
Large diffs are not rendered by default.
Oops, something went wrong.
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| ## Why | ||
|
|
||
| A v2 Block Tune did two things in the UI: it added an entry to the block's settings menu, and optionally it changed how the block looks. In v3 neither needs a dedicated entity. Plugins can already expose and consume public APIs (`api.plugins`, see `plugin-public-api`), so a UI plugin can expose the settings menu as an API and any plugin (a "tune") can add items to it. "Tune" then becomes a UI term only. | ||
|
|
||
| This change covers the settings menu only. Changing a block's appearance from a plugin — classes on the block wrapper, and per-block DOM kept out of the editable region — is a separate change, because the two are different concerns with different hazards (see the deferred section in `design.md`). | ||
|
|
||
| This is the second of three changes that replace the Block Tune entity with plugins (see the review on [PR #157](https://github.com/editor-js/document-model/pull/157)): | ||
| 1. `plugin-block-data`: the data layer. | ||
| 2. **`block-settings-ui`** (this change): the UI surfaces. | ||
| 3. `remove-block-tunes`: deleting the old entity. | ||
|
|
||
| This change doesn't depend on `plugin-block-data`: the built-in block settings items need no per-block data. Plugins that do store data combine the two. | ||
|
|
||
| It **does** assume `test/editorjs-e2e-and-aria-openspec` has merged, since it builds on that branch's `messages.ts`, toolbar ARIA/keyboard behavior, Playwright harness and `@editorjs/ui-kit` 2.x. | ||
|
|
||
| ## What Changes | ||
|
|
||
| - **Block settings plugin.** The new `BlockSettingsUI` (`name: 'block-settings'`) renders a per-block settings popover. Its `publicApi` lets any plugin register a settings provider: a function called with the target block's context each time the menu opens, returning a `BlockSettingsMenuConfig` with `onActivate`/`confirmation` declared inside it (the same model as `InlineTool#getToolbarConfig`). | ||
| - **Toolbar settings button.** `BlockSettingsUI` renders the button that opens its menu and announces it together with the menu; `ToolbarUI` mounts both next to the plus button, treats the button as a control of its roving tabindex, and doesn't reposition while settings are open. The button's own name and state belong to the plugin, because `aria-expanded` has to track a menu whose open state only the plugin knows. | ||
| - **Built-in block settings items as a plugin.** The new package `@editorjs/default-block-settings-plugin` (`name: 'default-block-settings'`) provides Move up, Move down, and Delete with a confirmation state (as in v2) through the block-settings API and `BlocksAPI.move`/`delete`. | ||
| - **Bundle.** `@editorjs/editorjs` registers `BlockSettingsUI` and `DefaultBlockSettingsPlugin` by default. | ||
| - **Types.** `@editorjs/ui` exports the settings API types and augments `EditorjsPluginApiMap`; `sdk` gains only a `UiComponentType.BlockSettings` member for the new plugin's static `type`. | ||
| - **Accessibility.** The settings button takes an accessible name from `messages.ts`, reports `aria-haspopup`/`aria-expanded`, is focused before the popover opens, and participates in the toolbar's roving tabindex; the popover itself is named. | ||
| - **Test infrastructure.** `packages/ui` gets a Jest (jsdom) setup and a CI workflow, since it has neither today. | ||
|
|
||
| ## Capabilities | ||
|
|
||
| ### New Capabilities | ||
|
|
||
| - `block-settings`: the per-block settings popover and the plugin-facing registration API for its items. | ||
| - *Intended Purpose (paste into the folded spec, since archive writes a `TBD` placeholder):* "The block settings menu (the \"tunes\" menu in v2) is a UI surface that any plugin can add items to; it is not tied to a special entity type. This capability owns the `BlockSettingsUI` plugin, the button that opens it for the selected block, and the `publicApi` through which plugins register settings providers that return `BlockSettingsMenuConfig` items for a given block. The toolbar that hosts the button and the block rendering it builds on live in [[ui]], and cross-plugin access in [[plugin-public-api]]." | ||
| - `default-block-settings-plugin`: the built-in Move up / Move down / Delete settings, implemented as a plugin. | ||
| - *Intended Purpose:* "`@editorjs/default-block-settings-plugin` supplies the default block settings entries — moving a block up or down and deleting it after confirmation — by registering a provider with [[block-settings]] and calling `BlocksAPI.move`/`delete` from [[core]]. It is the reference example of a \"tune\" built as a plain plugin, and is registered by the [[editorjs-bundle]]." | ||
|
|
||
| ### Modified Capabilities | ||
|
|
||
| - `ui`: `ToolbarUI` mounts the settings button and the menu that `BlockSettingsUI` announces, keeps that button in its roving tabindex, and reassigns its single tab stop once the button joins. `BlocksUI` also reports the selected block for a caret move, not only for pointer entry. | ||
| - `editorjs-bundle`: the default composition includes `BlockSettingsUI` and `DefaultBlockSettingsPlugin`. | ||
|
|
||
| ## Impact | ||
|
|
||
| - **Packages:** `ui`, `editorjs`, the new `packages/plugins/default-block-settings-plugin`, and one enum member in `sdk`. `core` is untouched: the target block's id comes from `api.blocks.getIdByIndex`. | ||
| - **CI:** new workflows for `packages/ui` and the new plugin package; `include-e2e` enabled for the bundle. | ||
| - **Not breaking:** everything here is new API surface. | ||
| - **From PR #157:** its toolbar settings button, styles, popover wiring and `BlockTunes*UIEvent` classes are ported (renamed to `BlockSettings*`), along with the behavior and tests of its internal delete/move-up/move-down tunes. Its `BlockTunesManager` and `BlockTuneAdapter` are not ported. | ||
| - **Docs to update:** `docs/plugins.md` (the block settings API and default-block-settings as the reference "tune"), and `docs/events.md` (the `ui:block-settings:*` events). |
139 changes: 139 additions & 0 deletions
139
openspec/changes/block-settings-ui/specs/block-settings/spec.md
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,139 @@ | ||
| ## ADDED Requirements | ||
|
|
||
| ### Requirement: Block settings plugin | ||
| The system SHALL provide `BlockSettingsUI`, an `EditorjsPlugin` with static `name` `block-settings`, that renders a per-block settings popover **and the button that opens it**. Both SHALL be announced together via `ui:block-settings:rendered` for a host to mount; the plugin SHALL NOT place them itself. The popover SHALL open when that button is activated, or on a `ui:block-settings:open` event targeting a block, and SHALL dispatch `ui:block-settings:opened` and `ui:block-settings:closed` when its open state changes. | ||
|
|
||
| #### Scenario: Opening settings for a block | ||
| - **GIVEN** at least one settings provider is registered | ||
| - **WHEN** a `ui:block-settings:open` event targeting block index 2 is dispatched | ||
| - **THEN** the popover opens populated with the items the providers return for block 2, and `ui:block-settings:opened` is dispatched | ||
|
|
||
| #### Scenario: Closing settings | ||
| - **GIVEN** the settings popover is open | ||
| - **WHEN** it is closed by the user, by an item with default close-on-activate, or by `api.plugins['block-settings'].close()` | ||
| - **THEN** `ui:block-settings:closed` is dispatched | ||
|
|
||
| #### Scenario: No items for a block | ||
| - **GIVEN** every registered provider returns nothing for the target block | ||
| - **WHEN** settings are requested for that block | ||
| - **THEN** the popover is not opened | ||
|
|
||
| #### Scenario: No target block | ||
| - **GIVEN** no block has been selected, so the requested index resolves to no block id | ||
| - **WHEN** block settings are requested | ||
| - **THEN** no provider is invoked, the popover is not opened, and no error is thrown | ||
|
|
||
| ### Requirement: Block settings button | ||
| The button `BlockSettingsUI` announces SHALL carry the whole menu-button contract, because the state it reports is the plugin's own: an accessible name from the UI package's message catalogue, `aria-haspopup="menu"`, and an `aria-expanded` kept in sync with whether the menu is open. Activating it SHALL focus it before opening the menu, so the popover has a control to return focus to when it closes. Activating it while the menu is already open SHALL close the menu instead of rebuilding it, as the menu button pattern requires: the control that opens a menu is also the control that dismisses it. This SHALL hold however the button is activated, pointer or keyboard, which means the state it reads cannot be captured from pointer events alone. The button SHALL also declare itself a non-submitting control, so that an editor mounted inside a form does not post it when the menu is opened. The plugin SHALL follow block selection to know which block the button acts on, and SHALL stop following it while the menu is open, so the open menu and the button cannot come to mean different blocks. | ||
|
|
||
| #### Scenario: The button is announced with the menu | ||
| - **WHEN** `BlockSettingsUI` is constructed | ||
| - **THEN** `ui:block-settings:rendered` carries both the button and the element the menu renders into | ||
|
|
||
| #### Scenario: The button names the menu it controls | ||
| - **WHEN** the button is inspected | ||
| - **THEN** it has an accessible name from the message catalogue, `aria-haspopup="menu"`, and `aria-expanded="false"` | ||
|
|
||
| #### Scenario: The button reports the menu state | ||
| - **GIVEN** the button has opened the menu | ||
| - **THEN** its `aria-expanded` is `"true"`, and it holds focus | ||
| - **WHEN** the menu closes, by any route | ||
| - **THEN** its `aria-expanded` returns to `"false"` | ||
|
|
||
| #### Scenario: The button closes the menu it opened | ||
| - **GIVEN** the button has opened the menu | ||
| - **WHEN** the button is activated again | ||
| - **THEN** the menu closes, `aria-expanded` returns to `"false"`, and no second menu is built | ||
|
|
||
| #### Scenario: The menu is dismissed while a replacement is being built | ||
| - **GIVEN** the menu is open and another block's menu has been requested, whose providers have not returned | ||
| - **WHEN** the open menu is dismissed, by Escape or by a click outside | ||
| - **THEN** the requested menu does not open when its providers return, because a dismissal abandons a build in flight exactly as a programmatic close does | ||
|
|
||
| #### Scenario: Selection moves while a menu is being built | ||
| - **GIVEN** a menu is being built for one block and its providers have not returned | ||
| - **WHEN** another block is reported as selected | ||
| - **THEN** that build is abandoned, rather than opening one block's actions beside another | ||
|
|
||
| #### Scenario: The target does not move under an open menu | ||
| - **GIVEN** the menu is open for the block at index 0 | ||
| - **WHEN** another block is reported as selected and the menu is then closed and opened again | ||
| - **THEN** the menu built the second time is for the block selected after it closed, not one chosen while it was open | ||
|
|
||
| ### Requirement: Block settings menu is accessible | ||
| The settings popover SHALL carry an accessible name drawn from the UI package's message catalogue, in the same way the toolbox menu is named. Items removed from the menu SHALL leave the accessibility tree rather than remaining hidden but present. | ||
|
|
||
| #### Scenario: Menu is named | ||
| - **WHEN** the block settings popover opens | ||
| - **THEN** it exposes an accessible name from the message catalogue, so a screen reader announces what the menu is | ||
|
|
||
| #### Scenario: Removed items leave the tree | ||
| - **GIVEN** the menu is rebuilt for a different block with fewer items | ||
| - **WHEN** the previous items are removed | ||
| - **THEN** they are no longer reachable in the accessibility tree | ||
|
|
||
| ### Requirement: Settings provider registration | ||
| `BlockSettingsUI` SHALL expose a `publicApi` with `register(provider, options?)` that returns an unregister function. A provider SHALL be a function receiving `{ blockId, blockIndex, tool }` for the target block and returning a `BlockSettingsMenuConfig`, a promise of one, or `undefined`. In that context `blockId` identifies the block for as long as it exists, while `blockIndex` is only its position at the moment the menu was built, so an item's handler SHALL resolve the block's current position from `blockId` rather than reusing `blockIndex`. Providers SHALL be invoked each time the popover opens, and their results SHALL be concatenated in ascending `options.order` (default `0`, ties broken by registration order), with a separator between the contributions of different providers. Item behavior SHALL be taken entirely from the returned `BlockSettingsMenuConfig` (`onActivate`, `isActive`, `isDisabled`, `closeOnActivate`, `children`, or a `confirmation` object whose own handler runs on the second activation — a confirmation item carries no top-level `onActivate`). | ||
|
|
||
| #### Scenario: Plugin contributes an item | ||
| - **GIVEN** a plugin calls `api.plugins['block-settings'].register(ctx => ({ title: 'Anchor', icon, onActivate: () => ... }))` | ||
| - **WHEN** block settings open for any block | ||
| - **THEN** an "Anchor" item is shown, and activating it calls the provider's `onActivate` | ||
|
|
||
| #### Scenario: Provider opts out for a tool | ||
| - **GIVEN** a provider returns `undefined` when `ctx.tool` is `"image"` | ||
| - **WHEN** block settings open for an image block | ||
| - **THEN** that provider contributes no items and no separator | ||
|
|
||
| #### Scenario: Item acts on the block it was built for | ||
| - **GIVEN** a provider returns an item whose `onActivate` resolves the block's position from `ctx.blockId` | ||
| - **WHEN** the document changes while the menu is open and the item is then activated | ||
| - **THEN** the action applies to that same block, because positions are resolved at activation rather than taken from `ctx.blockIndex` | ||
|
|
||
| #### Scenario: Items reflect current state | ||
| - **GIVEN** a provider derives an item's `isActive` from state it reads when called (e.g. the block's data via `EditorAPI`) | ||
| - **WHEN** that state changes and settings are opened again | ||
| - **THEN** the item's active state reflects the new data | ||
|
|
||
| #### Scenario: Ordering providers | ||
| - **GIVEN** provider A is registered with `order: 1000` before provider B with default order | ||
| - **WHEN** settings open | ||
| - **THEN** B's items are shown before A's | ||
|
|
||
| #### Scenario: Unregistering a provider | ||
| - **GIVEN** a provider was registered and its returned unregister function is called | ||
| - **WHEN** settings open afterwards | ||
| - **THEN** that provider is not invoked | ||
|
|
||
| #### Scenario: Item with confirmation | ||
| - **GIVEN** a provider returns an item with a `confirmation` config and no top-level `onActivate` | ||
| - **WHEN** the user activates the item | ||
| - **THEN** the item switches to its confirmation state, and only activating the confirmation runs the handler declared inside `confirmation` | ||
|
|
||
| ### Requirement: A failing provider costs only its own items | ||
| Providers are third-party code, and the open menu is the one place all of it runs, so no single provider SHALL be able to stop the menu from opening. A provider that throws, whose promise rejects, or that has not settled within a fixed timeout SHALL contribute nothing, SHALL be reported to the console so the plugin behind it can be identified, and SHALL leave no separator behind; every other provider's contribution is still built and shown. A contribution SHALL be discarded rather than rendered when a newer open request has started since it was asked for, or when the menu it was being built for has been closed in the meantime. | ||
|
|
||
| #### Scenario: A provider throws | ||
| - **GIVEN** two providers are registered and the first throws when invoked | ||
| - **WHEN** block settings open | ||
| - **THEN** the menu opens with the second provider's items alone, with no separator for the first, and the failure is reported to the console | ||
|
|
||
| #### Scenario: A provider's promise rejects | ||
| - **GIVEN** a provider returns a promise that rejects | ||
| - **WHEN** block settings open | ||
| - **THEN** it is skipped on the same terms as one that threw synchronously | ||
|
|
||
| #### Scenario: A provider never settles | ||
| - **GIVEN** a provider returns a promise that never settles | ||
| - **WHEN** block settings open and the timeout elapses | ||
| - **THEN** the menu opens without that provider's items rather than never opening, and the timeout is reported to the console | ||
|
|
||
| #### Scenario: A result arrives after a newer request | ||
| - **GIVEN** a provider is still working on the menu for one block when settings are requested for another | ||
| - **WHEN** the first request's providers finally return | ||
| - **THEN** their items are discarded, because the newer request owns the menu | ||
|
|
||
| #### Scenario: The menu is closed while it is being built | ||
| - **GIVEN** settings were requested and a provider has not yet returned | ||
| - **WHEN** `api.plugins['block-settings'].close()` is called before it does | ||
| - **THEN** the menu does not open when the provider finally returns, because a close abandons a build in flight as well as an open menu | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| ## MODIFIED Requirements | ||
|
|
||
| ### Requirement: EditorAPI surface | ||
| The system SHALL expose an `EditorAPI` aggregating `BlocksAPI` (insert/insertMany/delete/move/render/clear/getBlocksCount/getPluginData/updatePluginData/getToolByIndex), `SelectionAPI` (applyInlineTool, selectedBlocks), `DocumentAPI` (serialized data, onUpdate, insertData/removeData/modifyData, undo/redo), and `TextAPI` (insert/remove/format/unformat/getFragments/get) to tools, plugins, and adapters. | ||
|
|
||
| `BlocksAPI` SHALL offer a reader for a single block's tool name, so that a caller needing one scalar about one block does not reach for `DocumentAPI.data` — which serializes every block, every text node and every inline fragment tree in the document, and would do so on each open of a menu. | ||
|
|
||
| #### Scenario: Deleting with no block selected | ||
| - **GIVEN** no block is currently selected/no caret is set | ||
| - **WHEN** `BlocksAPI.delete()` or `move()` is called without an explicit index | ||
| - **THEN** it throws an error ("No block selected to delete" / "No block selected to move") | ||
|
|
||
| #### Scenario: Splitting or converting with an unknown tool | ||
| - **GIVEN** a `splitBlock`/`convertBlock` call references a `dataKey` that doesn't exist, or a source/target tool that isn't registered | ||
| - **WHEN** the operation is attempted | ||
| - **THEN** it throws an error identifying the missing key or tool | ||
|
|
||
| #### Scenario: Inserting a block with plugin data | ||
| - **GIVEN** `BlocksAPI.insert` is called with both `data` and `plugins: { anchors: { id: 'intro' } }` | ||
| - **WHEN** the block is added to the model | ||
| - **THEN** the serialized block carries both its tool data and that plugin data, each under its own key | ||
|
|
||
| #### Scenario: Reading a block's tool name | ||
| - **GIVEN** a document whose block at index 1 was inserted with tool `header` | ||
| - **WHEN** `BlocksAPI.getToolByIndex(1)` is called | ||
| - **THEN** it returns `"header"` | ||
|
|
||
| #### Scenario: Reading the tool name of a block that is not there | ||
| - **GIVEN** an index outside the document, or a negative one | ||
| - **WHEN** `BlocksAPI.getToolByIndex` is called with it | ||
| - **THEN** it returns `undefined` rather than throwing, matching `getIdByIndex` | ||
|
|
||
| Implemented in `src/api/index.ts`, `src/api/BlocksAPI.ts`, `src/api/SelectionAPI.ts`, `src/api/DocumentAPI/DocumentAPI.ts`, `src/api/TextAPI.ts`, `src/components/BlockManager.ts`, validated by co-located `.spec.ts`/`.integration.spec.ts` files. |
Oops, something went wrong.
Oops, something went wrong.
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.
Uh oh!
There was an error while loading. Please reload this page.