diff --git a/.github/actions/base-coverage/action.yml b/.github/actions/base-coverage/action.yml index 3dc3b6de..a0499958 100644 --- a/.github/actions/base-coverage/action.yml +++ b/.github/actions/base-coverage/action.yml @@ -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 diff --git a/.github/workflows/default-block-settings-plugin.yml b/.github/workflows/default-block-settings-plugin.yml new file mode 100644 index 00000000..eb927d49 --- /dev/null +++ b/.github/workflows/default-block-settings-plugin.yml @@ -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 }} diff --git a/.github/workflows/ui.yml b/.github/workflows/ui.yml new file mode 100644 index 00000000..4f9bc02b --- /dev/null +++ b/.github/workflows/ui.yml @@ -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' diff --git a/docs/events.md b/docs/events.md index 635923e2..40282acc 100644 --- a/docs/events.md +++ b/docs/events.md @@ -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 diff --git a/docs/plugins.md b/docs/plugins.md index cce3fb35..f8d5f4e0 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -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 @@ -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 @@ -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 | diff --git a/openspec/changes/block-settings-ui/design.md b/openspec/changes/block-settings-ui/design.md index ef8018c7..ddc16861 100644 --- a/openspec/changes/block-settings-ui/design.md +++ b/openspec/changes/block-settings-ui/design.md @@ -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. diff --git a/openspec/changes/block-settings-ui/specs/block-settings/spec.md b/openspec/changes/block-settings-ui/specs/block-settings/spec.md index 249254d0..05eab212 100644 --- a/openspec/changes/block-settings-ui/specs/block-settings/spec.md +++ b/openspec/changes/block-settings-ui/specs/block-settings/spec.md @@ -1,13 +1,18 @@ ## 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. +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. That announcement is made once and is not replayed, so the plugin SHALL be registered after whatever mounts it: a host registered later never hears it, and the button and the menu stay off the page with nothing reported. This ordering requirement SHALL be documented on the plugin. 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. Those SHALL be dispatched only when the state really changes: replacing the popover to show another block's items keeps the menu open throughout, so a rebuild SHALL report neither, and `aria-expanded` SHALL stay `"true"` across it. #### 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: Rebuilding the menu for another block +- **GIVEN** the menu is open for one block +- **WHEN** it is asked to open for another, which replaces the popover under it +- **THEN** the items become that block's, and neither `closed` nor `opened` is dispatched and `aria-expanded` stays `"true"`, because the menu never stopped being open + #### 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()` @@ -24,7 +29,7 @@ The system SHALL provide `BlockSettingsUI`, an `EditorjsPlugin` with static `nam - **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. +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. Where the open menu's own keyboard handling claims the key and suppresses the click the activation would otherwise produce, the dismissal SHALL happen on the keydown itself: no click arrives to carry it, and without that the menu cannot be dismissed from the button at all. 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 remember the block it acts on by identity rather than by position, because a block inserted or removed above it shifts every position below without any selection being reported, and resolve the position again when the menu opens. Once nothing is holding the target, the plugin SHALL take up whichever block the blocks plugin then reports as selected, rather than waiting for the next selection to be announced: the ones ignored while frozen are not announced again, so the button would go on acting on a block the caret has left -- which is what clicking into another block does, since the caret moves on mousedown while the popover only closes on the click. The plugin SHALL follow block selection to know which block the button acts on, and SHALL stop following it whenever the toolbar is holding its position — while the menu is open, and while the toolbox is open, since that popover renders inside the toolbar and moving it would carry the popover along. The button therefore stays beside one block for as long as either is open, and the block it acts on SHALL stay with it: a menu built for a block the button is not next to acts on the wrong one, and `Delete` is among its items. #### Scenario: The button is announced with the menu - **WHEN** `BlockSettingsUI` is constructed @@ -45,6 +50,31 @@ The button `BlockSettingsUI` announces SHALL carry the whole menu-button contrac - **WHEN** the button is activated again - **THEN** the menu closes, `aria-expanded` returns to `"false"`, and no second menu is built +#### Scenario: Clicking into another block while the menu is open +- **GIVEN** the menu is open for one block, and the caret is then placed in another, which is reported while the target is frozen +- **WHEN** the menu closes +- **THEN** the button acts on the block the caret reached, and the toolbar has moved to it, so the two still name the same block + +#### Scenario: A block is inserted above the target +- **GIVEN** the block at index 1 is the reported selection, and a block is then inserted above it by a collaborator, an undo or a move +- **WHEN** the button is activated +- **THEN** the menu is built for the block that was selected, at the position it now holds, rather than for whatever moved into index 1 + +#### Scenario: The target block is removed +- **GIVEN** the reported selection is a block that is then removed from the document +- **WHEN** the button is activated +- **THEN** no provider is asked and no menu opens, as for any position naming no block + +#### Scenario: The button is activated again from the keyboard +- **GIVEN** the menu was opened from the button, and the button holds focus +- **WHEN** Enter is pressed again, and the open menu's keyboard handling has already prevented the default so that no click follows +- **THEN** the menu closes and `aria-expanded` returns to `"false"`, rather than staying open with nothing left to dismiss it + +#### Scenario: A claimed key arrives with the menu closed +- **GIVEN** the menu is closed +- **WHEN** a key whose default was prevented elsewhere reaches the button +- **THEN** no provider is asked and no menu opens, because a dismissal is all that keydown stands in for + #### 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 @@ -55,6 +85,16 @@ The button `BlockSettingsUI` announces SHALL carry the whole menu-button contrac - **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 while the toolbox is open +- **GIVEN** the block at index 0 is selected and the toolbox is open, so the toolbar is holding its position beside that block +- **WHEN** another block is reported as selected, the toolbox closes, and the button is activated +- **THEN** the menu is built for the block the button is beside, not the one hovered while the toolbox was open + +#### Scenario: The target follows the selection again once the toolbox closes +- **GIVEN** the toolbox was open and has closed +- **WHEN** another block is reported as selected and the button is activated +- **THEN** the menu is built for that block, because the toolbar is following the selection again + #### 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 @@ -73,7 +113,7 @@ The settings popover SHALL carry an accessible name drawn from the UI package's - **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`). +`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, with `tool` absent when it could not be determined -- which means the editor's view of the block disagrees with the Model's, since the id and the tool are read from the same position -- so that a provider matching on a tool does not match, rather than being handed an empty name that matches nothing while looking like an answer 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`. Unregistering SHALL take effect from the next open, since providers are asked as the menu is built, so a menu already on screen keeps the items it was built with until it closes. 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: () => ... }))` @@ -111,18 +151,43 @@ The settings popover SHALL carry an accessible name drawn from the UI package's - **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. +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 its 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. The menu shows nothing until every provider has answered, so providers are expected to answer from what they already have: the timeout SHALL default to half a second, as a backstop rather than a budget, and a provider that genuinely needs longer SHALL say so at registration through `options.timeout` rather than every menu waiting on its account. This SHALL cover the callbacks a contributed item carries that the popover calls itself, at any depth of nested items and on an item's confirmation state, since they run after the provider has returned and outside anything it could be held to otherwise. `isActive`, which the popover reads as it renders, SHALL be resolved while the provider's items are collected, so a throw costs that provider's items as returning nothing does, rather than aborting the popover and with it every other provider's items. `onActivate`, which the popover calls on a click, SHALL instead be reported and go no further, because the popover honours `closeOnActivate` only after the handler returns and a throw escaping would abandon that along with the rest of the activation. 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: An item's isActive callback throws +- **GIVEN** two providers are registered and the first contributes an item whose `isActive` throws +- **WHEN** block settings open +- **THEN** the menu opens with the second provider's items alone and the failure is reported to the console, rather than no menu opening at all + +#### Scenario: An item's onActivate throws +- **GIVEN** an item whose `onActivate` throws, contributed by a provider +- **WHEN** it is activated +- **THEN** the failure is reported to the console and does not reach the popover, so the activation it would have abandoned, `closeOnActivate` among it, still runs + +#### Scenario: A nested item's isActive callback throws +- **GIVEN** a provider contributes an item whose nested child's `isActive` throws +- **WHEN** block settings open +- **THEN** that provider is skipped on the same terms, because nested items are rendered with their parent + +#### Scenario: An isActive callback that works +- **GIVEN** a provider contributes one item whose `isActive` returns `true` and one whose returns `false` +- **WHEN** block settings open +- **THEN** the first is shown as active and the second is not + #### 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 asks to be waited for +- **GIVEN** a provider registered with a `timeout` longer than the default, which answers within it +- **WHEN** block settings open +- **THEN** its items are shown, and nothing is reported -- while a provider that asked for less than it takes is skipped at the budget it asked for + #### Scenario: A provider never settles - **GIVEN** a provider returns a promise that never settles - **WHEN** block settings open and the timeout elapses diff --git a/openspec/changes/block-settings-ui/specs/default-block-settings-plugin/spec.md b/openspec/changes/block-settings-ui/specs/default-block-settings-plugin/spec.md index 65d96ca1..200b27ce 100644 --- a/openspec/changes/block-settings-ui/specs/default-block-settings-plugin/spec.md +++ b/openspec/changes/block-settings-ui/specs/default-block-settings-plugin/spec.md @@ -1,7 +1,7 @@ ## ADDED Requirements ### Requirement: Default block settings plugin -The system SHALL provide `@editorjs/default-block-settings-plugin`, an `EditorjsPlugin` with static `name` `default-block-settings` whose only runtime dependencies are `@editorjs/sdk` and `@codexteam/icons` (it takes `@editorjs/ui` as a devDependency, for `import type` alone, so that `api.plugins['block-settings']` typechecks without a runtime coupling). Once the editor is ready, it SHALL register a settings provider with `block-settings` at `order: 1000`, contributing "Move up", "Move down" and "Delete" items for every block. When no `block-settings` plugin is registered, it SHALL do nothing and SHALL NOT throw. +The system SHALL provide `@editorjs/default-block-settings-plugin`, an `EditorjsPlugin` with static `name` `default-block-settings` whose only runtime dependencies are `@editorjs/sdk` and `@codexteam/icons` (it takes `@editorjs/ui` as a devDependency, for `import type` alone, so that `api.plugins['block-settings']` typechecks without a runtime coupling). Once the editor is ready, it SHALL register a settings provider with `block-settings` at `order: 1000`, contributing "Move up", "Move down" and "Delete" items for every block. Their titles SHALL come from a message catalogue of the plugin's own, as `@editorjs/ui` keeps its own strings, so that localising them is a change to one module rather than to every item it builds. When no `block-settings` plugin is registered, it SHALL do nothing and SHALL NOT throw. #### Scenario: Items are contributed - **GIVEN** `BlockSettingsUI` and `DefaultBlockSettingsPlugin` are both registered diff --git a/openspec/changes/block-settings-ui/specs/ui/spec.md b/openspec/changes/block-settings-ui/specs/ui/spec.md index 06b3dff1..101bffaa 100644 --- a/openspec/changes/block-settings-ui/specs/ui/spec.md +++ b/openspec/changes/block-settings-ui/specs/ui/spec.md @@ -1,7 +1,7 @@ ## MODIFIED Requirements ### Requirement: Floating toolbar -The system SHALL provide `ToolbarUI`, which renders a floating toolbar with a plus-button and an actions area, repositions itself to the selected block's offset on `ui:blocks:block-selected` (unless the Toolbox or block settings are open), and opens the Toolbox on plus-button click. It SHALL mount both elements announced via `ui:block-settings:rendered` into its actions area -- the menu, and the button that opens it as a control of the container in its own right -- and SHALL reassign its single tab stop once that button joins. +The system SHALL provide `ToolbarUI`, which renders a floating toolbar with a plus-button and an actions area, repositions itself to the selected block's offset on `ui:blocks:block-selected` (unless the Toolbox or block settings are open), and opens the Toolbox on plus-button click. Once both are closed it SHALL move to whichever block the blocks plugin then reports as selected, rather than waiting for the next selection: nothing announces the ones it held through, so the toolbar would otherwise be left beside a block the caret has gone from. It SHALL mount both elements announced via `ui:block-settings:rendered` into its actions area -- the menu, and the button that opens it as a control of the container in its own right -- and SHALL reassign its single tab stop once that button joins. #### Scenario: Repositioning on block selection - **GIVEN** a `BlockSelectedUIEvent` is received and neither the Toolbox nor block settings are currently open @@ -13,6 +13,11 @@ The system SHALL provide `ToolbarUI`, which renders a floating toolbar with a pl - **WHEN** the click is handled - **THEN** `ToolbarUI` dispatches a `ToolboxOpenUIEvent` +#### Scenario: The toolbar's own button does not submit a form +- **GIVEN** the editor is mounted inside a `