Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
96c3a63
test(ui): give the package a Jest harness
gohabereg Oct 9, 2026
1ab4201
feat(ui): add the block settings menu plugin
gohabereg Oct 9, 2026
e2325b8
feat(ui): open block settings from the toolbar
gohabereg Oct 9, 2026
41c200b
feat(default-block-settings-plugin): move, move and delete as a plugin
gohabereg Oct 9, 2026
fc7053f
feat(editorjs): ship the block settings menu in the bundle
gohabereg Oct 9, 2026
c326a8b
fix(ui): let block settings rows fill the menu
gohabereg Oct 9, 2026
6cc8510
test(editorjs): cover the block settings menu's accessibility
gohabereg Oct 9, 2026
82b69e1
fix(ui): make the block settings menu robust to its own providers
gohabereg Oct 9, 2026
14908df
test(editorjs): group the block settings e2e tests
gohabereg Oct 9, 2026
0d59297
refactor(ui)!: let the block settings plugin own its button
gohabereg Oct 9, 2026
0e3140a
refactor(ui): share the toolbar button styling
gohabereg Oct 9, 2026
053497c
docs: keep the block settings comments to two sentences
gohabereg Oct 9, 2026
aef43b1
fix(ci): build type-only workspace dependencies before linting and te…
gohabereg Oct 9, 2026
ddaf36f
fix(ui): make the block settings button reachable, dismissable and cheap
gohabereg Oct 10, 2026
8ef0305
docs(openspec): check off the block-settings-ui review follow-ups
gohabereg Oct 10, 2026
8eb68ff
fix(ui): stop one settings provider from taking the whole menu with it
gohabereg Oct 11, 2026
baaec46
fix(ui): keep the settings menu pointing at the block it was built for
gohabereg Oct 16, 2026
78e4615
docs(openspec): check off the third-round block-settings-ui follow-ups
gohabereg Oct 16, 2026
4d1950f
fix(ui): keep the block settings target with the button
gohabereg Nov 5, 2026
d64a75d
fix(ui): isolate a throwing isActive to the provider that shipped it
gohabereg Nov 5, 2026
b477577
docs(openspec): specify and check off the fourth-round block-settings…
gohabereg Nov 5, 2026
bb431a4
fix(ui): dismiss the block settings menu from a second Enter
gohabereg Nov 8, 2026
97c8c97
docs(openspec): specify and check off the fifth-round block-settings-…
gohabereg Nov 8, 2026
f7cc971
fix(ui): hold the block settings target by id, not by position
gohabereg Nov 16, 2026
4655437
fix(ui): recognise a repeated selection by block and position together
gohabereg Nov 16, 2026
479cc39
feat(ui): tell other plugins which block the UI treats as selected
gohabereg Nov 16, 2026
db49275
fix(ui): follow the selection again once nothing is holding the toolbar
gohabereg Nov 16, 2026
4f9b89b
fix(ui): stop a menu rebuild reporting itself as closed and reopened
gohabereg Nov 16, 2026
84af3cb
fix(ui): keep a throwing item handler out of the popover
gohabereg Nov 16, 2026
9d62a54
feat(ui)!: let a settings provider say how long it may take
gohabereg Nov 16, 2026
a1e68af
docs(ui): say that block settings must be registered after its host
gohabereg Nov 16, 2026
ac6508d
fix(ui)!: leave the tool out of the provider context when it is unknown
gohabereg Nov 16, 2026
e79eff9
docs(ui): say when unregistering a settings provider takes effect
gohabereg Nov 16, 2026
839dd52
refactor(default-block-settings-plugin): collect the item titles in o…
gohabereg Nov 16, 2026
7664c08
fix(ui): stop the toolbar's plus button submitting a form
gohabereg Nov 16, 2026
d886832
refactor(ui): walk the popover item union instead of a plain record
gohabereg Nov 16, 2026
09670a3
test(ui): reopen the settings menu from the keyboard after the caret …
gohabereg Nov 16, 2026
29139a7
ci(ui): limit the workflow's token permissions and run it in the merg…
gohabereg Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 16 additions & 4 deletions .github/actions/base-coverage/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,15 +22,27 @@ runs:
fetch-depth: 0
submodules: true

- name: Check package exists on base ref
# A base-ref comparison only means something when the base ref can actually produce
# a coverage report. Two cases cannot: the package may not exist there yet, or it may
# exist without a test suite, which is the case for the PR that first adds one. The
# second needs its own check -- package.json is present, so the file test passes, and
# `yarn workspace ... test:coverage` then fails with "couldn't find a script".
- name: Check base ref can report coverage
id: check
shell: bash
run: |
if [ -f "${{ inputs.working-directory }}/package.json" ]; then
echo "exists=true" >> "$GITHUB_OUTPUT"
else
if [ ! -f "${{ inputs.working-directory }}/package.json" ]; then
echo "Package not present on base ref (new package), skipping base coverage"
echo "exists=false" >> "$GITHUB_OUTPUT"
elif ! node -e "
const fs = require('fs');
const pkg = JSON.parse(fs.readFileSync(process.argv[1] + '/package.json', 'utf8'));
process.exit(pkg.scripts && pkg.scripts['test:coverage'] ? 0 : 1);
" "${{ inputs.working-directory }}"; then
echo "Package has no test:coverage script on base ref (suite added in this PR), skipping base coverage"
echo "exists=false" >> "$GITHUB_OUTPUT"
else
echo "exists=true" >> "$GITHUB_OUTPUT"
fi

- name: Setup Node
Expand Down
20 changes: 20 additions & 0 deletions .github/workflows/default-block-settings-plugin.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
name: Default block settings plugin check
on:
pull_request:
merge_group:

permissions:
contents: read
pull-requests: write
issues: write
actions: read

jobs:
package-check:
uses: ./.github/workflows/package-check.yml
with:
package-name: '@editorjs/default-block-settings-plugin'
working-directory: './packages/plugins/default-block-settings-plugin'
include-mutations: true
secrets:
stryker_dashboard_api_key: ${{ secrets.STRYKER_DASHBOARD_API_KEY }}
17 changes: 17 additions & 0 deletions .github/workflows/ui.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
name: UI check
on:
pull_request:
merge_group:

permissions:
contents: read
pull-requests: write
issues: write
actions: read

jobs:
package-check:
uses: ./.github/workflows/package-check.yml
with:
package-name: '@editorjs/ui'
working-directory: './packages/ui'
Comment thread
github-advanced-security[bot] marked this conversation as resolved.
Fixed
15 changes: 15 additions & 0 deletions docs/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,24 @@ Dispatched on the IoC-managed `EventBus` (one instance per editor) with prefixed
| `UndoCoreEvent` | `core:undo` | — | `DocumentAPI.undo()` or `BlocksUI` (Cmd/Ctrl+Z) |
| `RedoCoreEvent` | `core:redo` | — | `DocumentAPI.redo()` or `BlocksUI` (Cmd/Ctrl+Shift+Z) |
| `BeforeInputUIEvent` | `ui:before-input` | `{ data, inputType, targetRanges, isCrossInputSelection, isComposing }` | `BlocksUI` |
| `BlockSelectedUIEvent` | `ui:blocks:block-selected` | `{ block: HTMLElement, index }` | `BlocksUI`, on pointer enter and on the caret moving into another block |
| `BlockSettingsOpenUIEvent` | `ui:block-settings:open` | `{ index }` | anyone opening the menu programmatically |
| `BlockSettingsRenderedUIEvent` | `ui:block-settings:rendered` | `{ button: HTMLElement, blockSettings: HTMLElement }` | `BlockSettingsUI` |
| `BlockSettingsOpenedUIEvent` | `ui:block-settings:opened` | — | `BlockSettingsUI` |
| `BlockSettingsClosedUIEvent` | `ui:block-settings:closed` | — | `BlockSettingsUI` |

`BlockAddedCoreEvent` carries the rendered `HTMLElement` in `detail.ui`, while the model-level `BlockAddedEvent` carries serialised data — they are complementary.

`BlockSettingsUI` owns both its menu and the button that opens it, and announces the two
together so a host can place them: `ToolbarUI` puts the button among its own controls and the
menu beside the toolbox popover. `ui:block-settings:open` is therefore not how the button works
— it is the way anything *else* opens the menu, naming the target block by index.

`BlockSelectedUIEvent` is what "the selected block" means to the toolbar and to anything
mounted in it. It is dispatched for the pointer entering a block *and* for the caret moving
into one, so a control acting on the selected block still works for someone who never touches
a mouse. Repeats for the same block are not dispatched.

Use core/UI events for UI workflows and extension coordination.

## Adapter internals
Expand Down
66 changes: 65 additions & 1 deletion docs/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,8 @@ Tools are registered via `core.use(ToolConstructor, options)` during setup. The
| Inline Tool | `InlineTool` (from config `tools`) | Selection formatting actions |

There is no Block Tune tool kind. What v2 called a tune is a UI plugin: it puts an item in the
block settings menu and stores its state as [per-block plugin data](#per-block-plugin-data).
[block settings menu](#block-settings) and stores its state as
[per-block plugin data](#per-block-plugin-data).

## Initialization sequence

Expand Down Expand Up @@ -116,6 +117,66 @@ Merging is shallow **at the plugin-id level**: a slice supplied through `use()`
const { shortcut } = toolFacade.pluginOptions('shortcuts') ?? {};
```

## Block settings

The per-block settings menu — the thing v2 called "block tunes" — is no longer a kind of entity.
`BlockSettingsUI` renders the popover and the button that opens it, announcing both through
`ui:block-settings:rendered` for the toolbar to place, and owns no items of its own; a plugin
contributes to it by registering a *provider*:

```ts
const unregister = api.plugins['block-settings']?.register(ctx => ({
title: 'Anchor',
icon: IconLink,
isActive: Boolean(api.blocks.getPluginData({ block: ctx.blockId, plugin: 'anchors' })),
onActivate: () => setAnchor(ctx.blockId),
}));
```

A provider is asked again every time the menu opens, so an item's `isActive`, `isDisabled` and
`title` can be derived from current state rather than cached. Return `undefined` (or an empty
array) to contribute nothing for a given block — a provider that opts out adds no separator
either. Item behaviour comes entirely from the returned config — a `BlockSettingsMenuConfig`, which is
ui-kit's popover-item shape: `onActivate`, `closeOnActivate`, `children` for a submenu, or a
`confirmation` whose own handler runs on the second activation. It is deliberately not
`@editorjs/sdk`'s `MenuConfig`, which is the narrower shape inline tools return from
`getToolbarConfig`.

The button that opens the menu is a toggle: activating it while the menu is open dismisses it.
It acts on the block the pointer is over, or — with no pointer involved — the one the caret is
in, so the menu is reachable from the keyboard alone.

Contributions are concatenated in ascending `order` (default `0`, ties broken by registration
order), separated from one another. `@editorjs/default-block-settings-plugin` registers at
`order: 1000` so the built-in Move up / Move down / Delete sit last; it is the reference example
of a former "tune" written as a plain plugin, with no privileged path into the menu.

### Resolve positions from `blockId`, not `blockIndex`

The provider context carries both, but only `blockId` is durable:

```ts
onActivate: () => {
const index = api.blocks.getIndexById(ctx.blockId);

// The block may be gone — removed by a collaborator, or by an undo — while the menu was open.
if (index === -1) {
return;
}

api.blocks.move({ fromIndex: index, toIndex: index - 1 });
}
```

`ctx.blockIndex` is only true at the moment the menu was built. A menu can stay open while a
collaborator inserts a block above the target, or while an undo runs, and a handler acting on the
stale index then moves the wrong block. Deriving a *disabled state* from the index is fine, since
going stale only greys an item out — deriving an *action* from it is not.

The menu is absent in a headless setup, which is why the lookup above is optional: a plugin
registered on a `Core` without `BlockSettingsUI` finds nothing under `api.plugins['block-settings']`
and should simply contribute nothing rather than fail.

## Per-block plugin data

A plugin stores its own data on a block through `api.blocks`, under a key that is by convention the
Expand Down Expand Up @@ -310,6 +371,9 @@ Programmatic block management — delegates to `BlocksManager`.
| `render(document)` | Re-initialize the document from serialised data |
| `clear()` | Remove all blocks |
| `getBlocksCount()` | Return the total number of blocks |
| `getIdByIndex(index)` | Id of the block at that index, or `undefined` |
| `getIndexById(id)` | Position of the block with that id, or `-1` |
| `getToolByIndex(index)` | Tool name of the block at that index, or `undefined` |
| `getPluginData({ block, plugin })` | Read a plugin's per-block data, or `undefined` |
| `updatePluginData({ block, plugin, data, userId? })` | Merge keys into a plugin's per-block data |

Expand Down
10 changes: 7 additions & 3 deletions openspec/changes/block-settings-ui/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,12 +44,16 @@ type BlockSettingsProvider = (ctx: { blockId: BlockId; blockIndex: number; tool:

Wiring follows the Toolbox pattern, with one departure from it:
1. `BlockSettingsUI` renders both the popover **and the button that opens it**, and announces the two together via `ui:block-settings:rendered`. `ToolbarUI` mounts them in its actions area and reassigns its single tab stop once the button joins.
2. The plugin follows `ui:blocks:block-selected` itself to know which block the button acts on, and stops following it while the menu is open. It also opens on a `ui:block-settings:open` event, so a host can request the menu for a block without the button.
3. `ToolbarUI` doesn't reposition while settings are open.
2. The plugin follows `ui:blocks:block-selected` itself to know which block the button acts on, and stops following it for as long as the toolbar is holding its position -- while the menu is open, and while the toolbox is open. It also opens on a `ui:block-settings:open` event, so a host can request the menu for a block without the button.
3. `ToolbarUI` doesn't reposition while settings or the toolbox are open.

The two halves of 2 and 3 have to agree, which is why the plugin tracks `ui:toolbox:opened`/`closed` as well. `ToolbarUI` owns where the button sits and this plugin owns what it acts on, so whenever one freezes the other must: a button left beside one block whose menu was built for another acts on the wrong block, and `Delete` is one of the items.

*Why the button belongs to the plugin rather than the toolbar:* a menu button's `aria-expanded` has to track the menu, and the menu's open state is the plugin's. Split across the two, every open and close would need a round trip through the event bus to keep an attribute honest, and the button would report a block the menu was not built for. `ToolbarUI` treats it as a control of the container like its own plus button -- named, stated and operated by its owner, positioned and tab-managed by the toolbar.

`BlockSettingsUI` resolves the target block's id with `api.blocks.getIdByIndex(index)` from the index it last saw selected, so this change needs no new event or payload field from `core`.
`BlockSettingsUI` resolves the target block's id with `api.blocks.getIdByIndex(index)` as each selection is reported, and keeps that id as the target, resolving the position back with `getIndexById` when the menu opens. So this change needs no new event or payload field from `core`. Keeping the position instead would go stale: a block inserted or removed above the target shifts every position below it, and none of the ways that happens -- a collaborator, an undo, a move -- reports a selection, so the button would quietly come to act on a different block.

*Alternative considered:* give `ToolbarUI` the target index and pass it in `ui:block-settings:open`, so there is one owner rather than two components agreeing. Rejected for now because it moves the block the menu acts on back out of the plugin that owns the button, against the reasoning above; the duplicated flag is the smaller cost, and `ui:block-settings:open` stays available as the seam if that trade changes.

The provider context carries both `blockId` and `blockIndex`, but only `blockId` is durable: a menu can stay open while a collaborator inserts or removes blocks above the target, or while an undo does. Item handlers therefore resolve the position from `blockId` at activation time. This is how the tunes in PR #157 behave (`getIndexById` inside `activate()`), and it is worth keeping.

Expand Down
Loading
Loading