diff --git a/docs/README.md b/docs/README.md index 8fb98390..d93f3855 100644 --- a/docs/README.md +++ b/docs/README.md @@ -61,7 +61,7 @@ The system stays decoupled because each step communicates through interfaces and - `EditorjsPlugin`: general UI/behavior plugin registered via `core.use()` with `PluginType.Plugin`. UI components like `BlocksUI` typically declare a `static type` from `UiComponentType` but are bound to `PluginType.Plugin` internally. - `UiComponentType`: reserved string keys for UI component slots (`shell`, `blocks`, `inline-toolbar`, `toolbox`, `toolbar`). These name components in the UI layer but are **not** used as arguments to `core.use()` — plugins are registered by `PluginType` or `ToolType` values. -- `BlockTool` / `InlineTool` / `BlockTune`: tool contracts registered via `core.use(ToolConstructor, options)` during setup. The `tools` config field provides tool settings that `ToolsManager` applies during `initialize()`. +- `BlockTool` / `InlineTool`: tool contracts registered via `core.use(ToolConstructor, options)` during setup. The `tools` config field provides tool settings that `ToolsManager` applies during `initialize()`. - `Index`: serializable location in the document tree, independent of DOM nodes. Subclasses (e.g. `BlockIndex`, `TextIndex`, `DataIndex`) cover distinct target types. Built with immutable factory methods like `Index.block()` or `Index.text()`; serialized to a compact JSON string for caret storage and OT operations. - `DataKey`: branded string identifying a data slot inside a `BlockNode` (e.g. `"text"`, `"caption"`). Created via `createDataKey()`. - `BatchedOperation`: groups rapid single-character inserts or deletes on the same data key into one logical edit for undo/redo. Lives in `@editorjs/collaboration-manager`. diff --git a/docs/diagrams/plugin-lifecycle-flow.mmd b/docs/diagrams/plugin-lifecycle-flow.mmd index 7c9d9250..09562ec3 100644 --- a/docs/diagrams/plugin-lifecycle-flow.mmd +++ b/docs/diagrams/plugin-lifecycle-flow.mmd @@ -31,7 +31,7 @@ sequenceDiagram Core->>Plugins: bind PluginType.Plugin = SomePlugin Dev->>Core: use(SomeTool, settings) - Core->>Plugins: bind ToolType.Block / Inline / Tune = [SomeTool, settings] + Core->>Plugins: bind ToolType.Block / Inline = [SomeTool, settings] %% ── await initialize() ─────────────────────────── Dev->>Core: await initialize() @@ -47,9 +47,9 @@ sequenceDiagram Core->>CollabMgr: new CollaborationManager(config, api, eventBus) CollabMgr->>EventBus: wire event listeners - Core->>Plugins: getAll(ToolType.Block / Inline / Tune) + Core->>Plugins: getAll(ToolType.Block / Inline) Plugins-->>Core: [[SomeTool, settings], ...] - Core->>ToolsManager: prepareTools(blockTools, inlineTools, blockTunes) + Core->>ToolsManager: prepareTools(blockTools, inlineTools) loop for each tool ToolsManager->>Tool: Tool.prepare({ toolName, config }) ToolsManager->>ToolsManager: wrap in BlockToolFacade or InlineToolFacade diff --git a/docs/plugins.md b/docs/plugins.md index 30722b3b..cce3fb35 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -2,7 +2,7 @@ ## Package boundary -Tools and plugins should only depend on `@editorjs/sdk` — never on `@editorjs/model` or `@editorjs/model-types` directly. `sdk` re-exports every type a tool/plugin author needs (`Index`, event classes, `BlockTool`/`InlineTool`/`BlockTune` contracts, etc.); `model` is the engine implementation that `core` and `ot-server` orchestrate, and `model-types` is an internal foundation shared only by `model` and `sdk`. Neither is part of the stable, tool-facing API. +Tools and plugins should only depend on `@editorjs/sdk` — never on `@editorjs/model` or `@editorjs/model-types` directly. `sdk` re-exports every type a tool/plugin author needs (`Index`, event classes, `BlockTool`/`InlineTool` contracts, etc.); `model` is the engine implementation that `core` and `ot-server` orchestrate, and `model-types` is an internal foundation shared only by `model` and `sdk`. Neither is part of the stable, tool-facing API. ## Registration @@ -26,7 +26,9 @@ Tools are registered via `core.use(ToolConstructor, options)` during setup. The | UI Plugin | `EditorjsPlugin` | UI component/behavior registered via `core.use(...)` | | Block Tool | `BlockTool` (from config `tools`) | Block rendering and block-specific behavior | | Inline Tool | `InlineTool` (from config `tools`) | Selection formatting actions | -| Block Tune | `BlockTune` (from config `tools`) | Per-block tune behavior | + +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). ## Initialization sequence diff --git a/openspec/changes/plugin-block-data/.openspec.yaml b/openspec/changes/archive/2026-11-08-plugin-block-data/.openspec.yaml similarity index 100% rename from openspec/changes/plugin-block-data/.openspec.yaml rename to openspec/changes/archive/2026-11-08-plugin-block-data/.openspec.yaml diff --git a/openspec/changes/plugin-block-data/design.md b/openspec/changes/archive/2026-11-08-plugin-block-data/design.md similarity index 100% rename from openspec/changes/plugin-block-data/design.md rename to openspec/changes/archive/2026-11-08-plugin-block-data/design.md diff --git a/openspec/changes/plugin-block-data/proposal.md b/openspec/changes/archive/2026-11-08-plugin-block-data/proposal.md similarity index 100% rename from openspec/changes/plugin-block-data/proposal.md rename to openspec/changes/archive/2026-11-08-plugin-block-data/proposal.md diff --git a/openspec/changes/plugin-block-data/specs/collaboration-manager/spec.md b/openspec/changes/archive/2026-11-08-plugin-block-data/specs/collaboration-manager/spec.md similarity index 100% rename from openspec/changes/plugin-block-data/specs/collaboration-manager/spec.md rename to openspec/changes/archive/2026-11-08-plugin-block-data/specs/collaboration-manager/spec.md diff --git a/openspec/changes/plugin-block-data/specs/core/spec.md b/openspec/changes/archive/2026-11-08-plugin-block-data/specs/core/spec.md similarity index 100% rename from openspec/changes/plugin-block-data/specs/core/spec.md rename to openspec/changes/archive/2026-11-08-plugin-block-data/specs/core/spec.md diff --git a/openspec/changes/plugin-block-data/specs/model-types/spec.md b/openspec/changes/archive/2026-11-08-plugin-block-data/specs/model-types/spec.md similarity index 100% rename from openspec/changes/plugin-block-data/specs/model-types/spec.md rename to openspec/changes/archive/2026-11-08-plugin-block-data/specs/model-types/spec.md diff --git a/openspec/changes/plugin-block-data/specs/model/spec.md b/openspec/changes/archive/2026-11-08-plugin-block-data/specs/model/spec.md similarity index 100% rename from openspec/changes/plugin-block-data/specs/model/spec.md rename to openspec/changes/archive/2026-11-08-plugin-block-data/specs/model/spec.md diff --git a/openspec/changes/plugin-block-data/specs/plugin-block-data/spec.md b/openspec/changes/archive/2026-11-08-plugin-block-data/specs/plugin-block-data/spec.md similarity index 100% rename from openspec/changes/plugin-block-data/specs/plugin-block-data/spec.md rename to openspec/changes/archive/2026-11-08-plugin-block-data/specs/plugin-block-data/spec.md diff --git a/openspec/changes/plugin-block-data/specs/sdk/spec.md b/openspec/changes/archive/2026-11-08-plugin-block-data/specs/sdk/spec.md similarity index 97% rename from openspec/changes/plugin-block-data/specs/sdk/spec.md rename to openspec/changes/archive/2026-11-08-plugin-block-data/specs/sdk/spec.md index 24cf06d8..897e4172 100644 --- a/openspec/changes/plugin-block-data/specs/sdk/spec.md +++ b/openspec/changes/archive/2026-11-08-plugin-block-data/specs/sdk/spec.md @@ -3,7 +3,7 @@ ### Requirement: Augmentable plugin type maps The system SHALL declare three empty, augmentable interfaces — `EditorjsPluginApiMap` (plugin id → public API type), `ToolPluginOptionsMap` (plugin id → tool-directed options type), and `EditorjsPluginDataMap` (plugin id → the shape of the per-block data that plugin stores) — that plugin packages extend via module augmentation of `@editorjs/sdk`. `PluginId` SHALL include the keys of all three maps. `BlocksAPI.getPluginData`/`updatePluginData` SHALL resolve their data type from `EditorjsPluginDataMap` for a declared id, and SHALL fall back to `Record` for an id absent from it, using a non-distributive conditional so the `string & {}` member of `PluginId` does not widen a declared id's type. -#### Scenario: Plugin package augments the api and options maps +#### Scenario: Plugin package augments both maps - **GIVEN** a plugin package declares `declare module '@editorjs/sdk'` augmenting `EditorjsPluginApiMap` and `ToolPluginOptionsMap` under its `name` - **WHEN** a consumer's compilation includes that package's types - **THEN** `api.plugins.` and `options.plugins.` are both fully typed with no cast diff --git a/openspec/changes/plugin-block-data/tasks.md b/openspec/changes/archive/2026-11-08-plugin-block-data/tasks.md similarity index 99% rename from openspec/changes/plugin-block-data/tasks.md rename to openspec/changes/archive/2026-11-08-plugin-block-data/tasks.md index f13451db..6627a5b9 100644 --- a/openspec/changes/plugin-block-data/tasks.md +++ b/openspec/changes/archive/2026-11-08-plugin-block-data/tasks.md @@ -51,7 +51,7 @@ - [x] 6.1 Update `docs/model.md`, `docs/index-serialization.md` and `docs/events.md` for `PluginDataNode`, `PluginDataIndex` and `PluginDataModifiedEvent`, plus `docs/plugins.md` (the SDK declares **three** augmentable interfaces now) and `.github/agents/docs-updater.agent.md` (its `BlockTune` → `docs/model.md` mapping) - [x] 6.2 Update the diagrams `model-tree-structure.mmd`, `events-catalog.mmd` and `architecture-overview.mmd` - [x] 6.3 Run `yarn lint`, `yarn test`, and the mutation tests for the touched packages that have them. Fix any regressions -- [ ] 6.4 Run `openspec validate plugin-block-data --type change` and confirm it passes. After archiving, fill the `## Purpose` of the new `plugin-block-data` spec from the proposal's intended-Purpose text +- [x] 6.4 Run `openspec validate plugin-block-data --type change` and confirm it passes. After archiving, fill the `## Purpose` of the new `plugin-block-data` spec from the proposal's intended-Purpose text ## 7. Review follow-ups diff --git a/openspec/changes/remove-block-tunes/.openspec.yaml b/openspec/changes/archive/2026-11-08-remove-block-tunes/.openspec.yaml similarity index 100% rename from openspec/changes/remove-block-tunes/.openspec.yaml rename to openspec/changes/archive/2026-11-08-remove-block-tunes/.openspec.yaml diff --git a/openspec/changes/remove-block-tunes/design.md b/openspec/changes/archive/2026-11-08-remove-block-tunes/design.md similarity index 100% rename from openspec/changes/remove-block-tunes/design.md rename to openspec/changes/archive/2026-11-08-remove-block-tunes/design.md diff --git a/openspec/changes/remove-block-tunes/proposal.md b/openspec/changes/archive/2026-11-08-remove-block-tunes/proposal.md similarity index 100% rename from openspec/changes/remove-block-tunes/proposal.md rename to openspec/changes/archive/2026-11-08-remove-block-tunes/proposal.md diff --git a/openspec/changes/remove-block-tunes/specs/core/spec.md b/openspec/changes/archive/2026-11-08-remove-block-tunes/specs/core/spec.md similarity index 100% rename from openspec/changes/remove-block-tunes/specs/core/spec.md rename to openspec/changes/archive/2026-11-08-remove-block-tunes/specs/core/spec.md diff --git a/openspec/changes/remove-block-tunes/specs/sdk/spec.md b/openspec/changes/archive/2026-11-08-remove-block-tunes/specs/sdk/spec.md similarity index 100% rename from openspec/changes/remove-block-tunes/specs/sdk/spec.md rename to openspec/changes/archive/2026-11-08-remove-block-tunes/specs/sdk/spec.md diff --git a/openspec/changes/remove-block-tunes/tasks.md b/openspec/changes/archive/2026-11-08-remove-block-tunes/tasks.md similarity index 64% rename from openspec/changes/remove-block-tunes/tasks.md rename to openspec/changes/archive/2026-11-08-remove-block-tunes/tasks.md index b79330e8..39846cd4 100644 --- a/openspec/changes/remove-block-tunes/tasks.md +++ b/openspec/changes/archive/2026-11-08-remove-block-tunes/tasks.md @@ -1,26 +1,26 @@ ## 1. Guard the removal with tests -- [ ] 1.1 Add type-level assertions (`@ts-expect-error`) that these no longer exist: `ToolType.Tune`, the `BlockTune*` entity exports, `BlockTuneFacade`, `BlockToolOptionKey.Tunes`, `BlockToolOptions['tunes']`, `UserToolOptions.EnabledBlockTunes` and `BlockToolFacade#enabledBlockTunes`. Enumerate tool-kind names only — the model-layer `BlockTuneName`/`BlockTuneSerialized` re-exports belong to `plugin-block-data` -- [ ] 1.2 Write a failing `ToolsCollection` spec case: the collection should expose only `blockTools`/`inlineTools`. Also write a `Core`/`ToolsManager` case: a plugin that contributes block settings items should be instantiated as a plugin and absent from the tool collections +- [x] 1.1 Add type-level assertions (`@ts-expect-error`) that these no longer exist: `ToolType.Tune`, the `BlockTune*` entity exports, `BlockTuneFacade`, `BlockToolOptionKey.Tunes`, `BlockToolOptions['tunes']`, `UserToolOptions.EnabledBlockTunes` and `BlockToolFacade#enabledBlockTunes`. Enumerate tool-kind names only — the model-layer `BlockTuneName`/`BlockTuneSerialized` re-exports belong to `plugin-block-data` +- [x] 1.2 Write a failing `ToolsCollection` spec case: the collection should expose only `blockTools`/`inlineTools`. Also write a `Core`/`ToolsManager` case: a plugin that contributes block settings items should be instantiated as a plugin and absent from the tool collections ## 2. Remove from SDK -- [ ] 2.1 Delete `sdk/src/entities/BlockTune.ts` and `sdk/src/tools/facades/BlockTuneFacade.ts` (with its spec), and remove their exports -- [ ] 2.2 Remove `ToolType.Tune`, `BaseToolFacade#isTune()` and `ToolsCollection#blockTunes` (its only consumer) -- [ ] 2.3 Remove `BlockTuneConstructor` from `ToolConstructable`, `BlockTuneFacade` from `ToolFacadeClass` (and its export), `ToolTypeToOptions[ToolType.Tune]`, the `ToolStaticOptions` member, the `BlockTuneOptions` re-exports in `BaseTool.ts`/`BaseToolFacade.ts`, and the `./BlockTune.js` line in the entities barrel -- [ ] 2.4 Remove `BlockToolOptionKey.Tunes` and its `BlockToolOptions` member, `UserToolOptions.EnabledBlockTunes`, `BlockToolFacade#enabledBlockTunes` and `BlockToolFacade#tunes` +- [x] 2.1 Delete `sdk/src/entities/BlockTune.ts` and `sdk/src/tools/facades/BlockTuneFacade.ts` (it had no spec), and remove their exports +- [x] 2.2 Remove `ToolType.Tune`, `BaseToolFacade#isTune()` and `ToolsCollection#blockTunes` (its only consumer) +- [x] 2.3 Remove `BlockTuneConstructor` from `ToolConstructable`, `BlockTuneFacade` from `ToolFacadeClass` (and its export), `ToolTypeToOptions[ToolType.Tune]`, the `ToolStaticOptions` member, the `BlockTuneOptions` re-exports in `BaseTool.ts`/`BaseToolFacade.ts`, and the `./BlockTune.js` line in the entities barrel +- [x] 2.4 Remove `BlockToolOptionKey.Tunes` and its `BlockToolOptions` member, `UserToolOptions.EnabledBlockTunes`, `BlockToolFacade#enabledBlockTunes` and `BlockToolFacade#tunes` ## 3. Remove from Core and dependents -- [ ] 3.1 Remove the Tune branch from `Core#use`, the `getAll(ToolType.Tune)` step in tool preparation, the Tune case in `ToolsFactory`, and `ToolsManager#blockTunes` -- [ ] 3.2 Remove `#processBlockTune` and the `BlockTuneFacade` import from `packages/plugins/shortcuts-plugin/src/index.ts` -- [ ] 3.3 Grep the workspace for the removed tool-kind symbols (not the bare word `tunes`, which the model layer still uses until `plugin-block-data` lands), fix any leftovers, and confirm `yarn build` is clean +- [x] 3.1 Remove the Tune branch from `Core#use`, the `getAll(ToolType.Tune)` step in tool preparation, the Tune case in `ToolsFactory`, and `ToolsManager#blockTunes` +- [x] 3.2 Remove `#processBlockTune` and the `BlockTuneFacade` import from `packages/plugins/shortcuts-plugin/src/index.ts` +- [x] 3.3 Grep the workspace for the removed tool-kind symbols (not the bare word `tunes`, which the model layer still uses until `plugin-block-data` lands), fix any leftovers, and confirm `yarn build` is clean ## 4. Docs and wrap-up -- [ ] 4.1 Update `docs/plugins.md` (the "Block Tune" table row and the SDK re-export list on line 5), `docs/README.md` (drop the `BlockTune` contract mention) and `docs/diagrams/plugin-lifecycle-flow.mmd` (drop the `ToolType.Tune` binding and `blockTunes`) -- [ ] 4.2 Hand-edit the **Purpose** preamble of `openspec/specs/sdk/spec.md` to drop "block tunes" — the mechanical archive fold only rewrites `### Requirement:` blocks -- [ ] 4.3 Change the `shortcuts-plugin` spec's reserved-work note from "block tunes" to "block settings items" -- [ ] 4.4 Run `yarn lint` and `yarn test`. Fix any regressions -- [ ] 4.5 Comment on PR #157 linking `plugin-block-data`, `block-settings-ui` and `remove-block-tunes` as its replacement -- [ ] 4.6 Run `openspec validate remove-block-tunes --type change` and confirm it passes +- [x] 4.1 Update `docs/plugins.md` (the "Block Tune" table row and the SDK re-export list on line 5), `docs/README.md` (drop the `BlockTune` contract mention) and `docs/diagrams/plugin-lifecycle-flow.mmd` (drop the `ToolType.Tune` binding and `blockTunes`) +- [x] 4.2 Hand-edit the **Purpose** preamble of `openspec/specs/sdk/spec.md` to drop "block tunes" — the mechanical archive fold only rewrites `### Requirement:` blocks +- [x] 4.3 Change the `shortcuts-plugin` spec's reserved-work note from "block tunes" to "block settings items" +- [x] 4.4 Run `yarn lint` and `yarn test`. Fix any regressions +- [x] 4.5 Comment on PR #157 linking `plugin-block-data`, `block-settings-ui` and `remove-block-tunes` as its replacement +- [x] 4.6 Run `openspec validate remove-block-tunes --type change` and confirm it passes diff --git a/openspec/specs/collaboration-manager/spec.md b/openspec/specs/collaboration-manager/spec.md index ef7e19ac..8a5c9dd7 100644 --- a/openspec/specs/collaboration-manager/spec.md +++ b/openspec/specs/collaboration-manager/spec.md @@ -3,9 +3,7 @@ ## Purpose `@editorjs/collaboration-manager` is a core plugin that listens to document model events, converts them into operational-transformation (OT) `Operation`s, batches rapid local edits for undo/redo, maintains local undo/redo stacks transformed against remote edits, and optionally syncs with a remote OT server over WebSocket using a handshake + serialized-ack protocol. - ## Requirements - ### Requirement: Operation model The system SHALL represent every document mutation as an `Operation` (Insert/Delete/Modify/Neutral) supporting `inverse()`, `transform()` against another operation, `serialize()`, and `getEffectiveRange()`. @@ -105,3 +103,67 @@ The system SHALL classify how two text ranges relate (None/Left/Right/Includes/I - **THEN** it returns one of `None`, `Left`, `Right`, `Includes`, or `IncludedBy` describing how the ranges overlap Implemented in `src/utils/getRangesIntersectionType.ts`. + +### Requirement: Plugin data operations +`CollaborationManager` SHALL translate a `PluginDataModifiedEvent` into a `Modify` `Operation` on its `PluginDataIndex`, with `payload` set to the new value and `prevPayload` to the previous value. `OperationsTransformer` SHALL shift a plugin data operation's block index against block insertions and removals the same way it does for data index operations, SHALL turn it into a `Neutral` operation when its block is removed, and SHALL resolve two concurrent writes to the same block, plugin and key the same way it resolves two concurrent writes to the same data key: the operation being transformed becomes `Neutral` when the operation it is transformed against is the later of the two, a local operation the server has not acknowledged counting as later than any revision. A local operation SHALL count as unacknowledged for the whole round trip, not merely until it leaves for the server, so the client SHALL keep it among the operations an incoming one is transformed against until its acknowledgement arrives. The acknowledgement is what establishes the server's order: while it is outstanding, every remote operation the server delivers was ordered before the local one, and once it arrives, everything after it was ordered later. Writes to different blocks, different plugins or different keys SHALL be left untransformed, since one cannot shift another's position. An operation carrying no revision of its own SHALL lose to whatever it is transformed against. Such an operation comes from an undo or redo stack, whose entries are built from model events and are never numbered, while an operation from the server always is; and the operation it is transformed against has already been applied to the document. Keeping it would leave an undo step that writes a value the document has moved on from, and whose recorded previous value is older still, so undoing a local write that a collaborator had overwritten would delete the collaborator's value. Transformation SHALL also accept a plugin data operation as the operation being transformed *against*, rather than rejecting its index kind. The `Modify` operation payload type SHALL admit any JSON value, including primitives. + +#### Scenario: Local plugin data change becomes an operation +- **GIVEN** the local user changes `anchors.visible` on block 1 from `true` to `false` +- **WHEN** `CollaborationManager` handles the resulting event +- **THEN** it sends a `Modify` operation on `Index.pluginData(1, 'anchors', 'visible')` with `payload` `false` and `prevPayload` `true`, rather than logging an unknown event + +#### Scenario: Inverting a plugin data operation +- **GIVEN** a plugin data `Modify` operation with `payload` `false` and `prevPayload` `true` +- **WHEN** `inverse()` is called +- **THEN** it returns a `Modify` operation on the same index with `payload` `true` and `prevPayload` `false` + +#### Scenario: Transforming against a block insertion +- **GIVEN** a plugin data operation on block 2 and a concurrent block insertion at index 0 +- **WHEN** the plugin data operation is transformed against the insertion +- **THEN** its index targets block 3 + +#### Scenario: A plugin data operation as the against-operation +- **GIVEN** any pending or stacked operation and a plugin data `Modify` operation to transform it against +- **WHEN** the transformation runs — as it does for pending operations on the client, for the undo/redo stacks on every remote plugin data event, and for conflicting operations on the server +- **THEN** it completes and returns an operation, rather than throwing an unsupported-index error + +#### Scenario: A scalar payload +- **GIVEN** a plugin data change whose value is a boolean +- **WHEN** the operation is constructed +- **THEN** the payload type admits it, so scalar plugin data is representable in an operation + +#### Scenario: Transforming against removal of its block +- **GIVEN** a plugin data operation on block 2 and a concurrent removal of block 2 +- **WHEN** the plugin data operation is transformed against the removal +- **THEN** it becomes a `Neutral` operation + +#### Scenario: Two clients write the same key concurrently +- **GIVEN** clients A and B both write `anchors.visible` on block 1, and the server applies A before B +- **WHEN** B receives A's operation while its own write is still unacknowledged +- **THEN** A's operation is transformed to `Neutral` on B, so B keeps the value the server will end up holding rather than being left on A's + +#### Scenario: A collaborator writes while the local write is in flight +- **GIVEN** the local client has sent a write of `anchors.color` and is waiting for its acknowledgement +- **WHEN** a collaborator's write to the same key arrives before that acknowledgement +- **THEN** it is transformed to `Neutral` and not applied, since the server will apply the local write after it -- and a client's own operations are not echoed back to it, so nothing would restore the value the server ends up holding + +#### Scenario: A collaborator writes once the local write is acknowledged +- **GIVEN** the local client's write of `anchors.color` has been acknowledged +- **WHEN** a collaborator's write to the same key arrives +- **THEN** it is applied, because the server ordered it after the local write + +#### Scenario: Undoing a write a collaborator overwrote +- **GIVEN** the local user wrote `anchors.color` on block 0, and a collaborator then overwrote the same key +- **WHEN** the undo stack is transformed against the collaborator's operation +- **THEN** the entry is dropped, so undo reaches past it rather than writing a value that is gone and deleting the collaborator's + +#### Scenario: Undoing a write to a key nobody else touched +- **GIVEN** the local user wrote `anchors.color` and a collaborator wrote `anchors.label` on the same block +- **WHEN** the undo stack is transformed against the collaborator's operation +- **THEN** the entry survives, because the two do not describe the same value + +#### Scenario: Concurrent writes to different keys +- **GIVEN** a plugin data operation on `anchors.visible` and a concurrent one on `anchors.id` of the same block +- **WHEN** one is transformed against the other +- **THEN** it is returned unchanged, because the two do not describe the same value + diff --git a/openspec/specs/core/spec.md b/openspec/specs/core/spec.md index e30db5f9..60a2349c 100644 --- a/openspec/specs/core/spec.md +++ b/openspec/specs/core/spec.md @@ -35,17 +35,22 @@ The system SHALL provide a `Core` class owning two IoC containers (one for singl Implemented in `src/index.ts`, validated by its co-located `.spec.ts`. ### Requirement: Tool registration and validation -The system SHALL validate configured tools via `ToolsManager`, calling each tool's static `prepare()`, and sorting tools into `available`/`unavailable` collections exposed as `blockTools`/`inlineTools`/`blockTunes`. +The system SHALL validate configured tools via `ToolsManager`, calling each tool's static `prepare()`, and sorting tools into `available`/`unavailable` collections exposed as `blockTools`/`inlineTools`. `Core#use` SHALL accept block tools, inline tools, adapter plugins, and generic plugins; there SHALL be no separate Block Tune registration path. #### Scenario: Rejecting a malformed tool - **GIVEN** a configured tool is neither a constructor function nor an object with a `class` property - **WHEN** `ToolsManager` validates the configuration - **THEN** it throws an error naming the offending tool and describing the required shape -Implemented in `src/tools/ToolsManager.ts`, `src/tools/ToolsFactory.ts`, validated by co-located `.spec.ts` files. +#### Scenario: A former tune is registered as a plugin +- **GIVEN** a class implementing `EditorjsPlugin` that does what a Block Tune used to do +- **WHEN** it is registered via `core.use()` +- **THEN** it is instantiated with the other plugins and never appears in `ToolsManager`'s collections + +Implemented in `src/tools/ToolsManager.ts`, `src/tools/ToolsFactory.ts`, validated by `src/index.spec.ts` and co-located `.spec.ts` files. ### Requirement: EditorAPI surface -The system SHALL expose an `EditorAPI` aggregating `BlocksAPI` (insert/insertMany/delete/move/render/clear/getBlocksCount), `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. +The system SHALL expose an `EditorAPI` aggregating `BlocksAPI` (insert/insertMany/delete/move/render/clear/getBlocksCount/getPluginData/updatePluginData), `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. #### Scenario: Deleting with no block selected - **GIVEN** no block is currently selected/no caret is set @@ -57,6 +62,11 @@ The system SHALL expose an `EditorAPI` aggregating `BlocksAPI` (insert/insertMan - **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 + 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. ### Requirement: Block rendering lifecycle @@ -136,3 +146,26 @@ Implemented in `src/components/UndoRedoManager.ts`, validated by its co-located - **WHEN** each plugin's `destroy()` runs - **THEN** its registry entry is removed so no stale public API remains reachable +### Requirement: v2 data conversion carries tune data into plugin data +`composeDataFromVersion2` SHALL map each v2 block's `tunes` map into the v3 block's `plugins` map, preserving each entry's key verbatim, so a v3 plugin that takes over a v2 tune's `name` finds its data. An entry whose v2 data is a plain object SHALL be copied key by key. An entry whose v2 data is a primitive or an array SHALL be stored under the single key `value`. A v2 block without `tunes`, or with an empty `tunes` map, SHALL produce no `plugins` entry. + +#### Scenario: Converting object tune data +- **GIVEN** a v2 block with `tunes: { anchors: { id: 'intro' } }` +- **WHEN** it is converted to v3 +- **THEN** the resulting block init carries `plugins: { anchors: { id: 'intro' } }` + +#### Scenario: Converting non-object tune data +- **GIVEN** a v2 block with `tunes: { alignment: 'left' }` +- **WHEN** it is converted +- **THEN** the resulting entry is `plugins: { alignment: { value: 'left' } }` + +#### Scenario: Block without tunes +- **GIVEN** a v2 block with no `tunes` key, or with `tunes: {}` +- **WHEN** it is converted +- **THEN** the resulting block init has no `plugins` key + +#### Scenario: Tune with no registered plugin +- **GIVEN** a v2 block carrying tune data whose name matches no plugin registered in this editor +- **WHEN** the document is converted and loaded +- **THEN** the entry is still present in the block's `plugins` and survives serialization, per the plugin data store's preservation rule + diff --git a/openspec/specs/model-types/spec.md b/openspec/specs/model-types/spec.md index 02d10f4e..265dff33 100644 --- a/openspec/specs/model-types/spec.md +++ b/openspec/specs/model-types/spec.md @@ -3,36 +3,39 @@ ## Purpose `@editorjs/model-types` provides the shared, dependency-free low-level types, nominal identifiers, event payload shapes, and base event classes used internally by `@editorjs/model` and `@editorjs/sdk`. It contains no editor runtime logic beyond the `Index` class hierarchy of location-pointer types, `keypath` object helpers, and block ID generation. It exists so `model` and `sdk` can share type definitions without depending on each other, and is not intended for direct use by other packages or tools. - ## Requirements - ### Requirement: Nominal identifier types -The system SHALL provide nominal (branded) types for `BlockId`, `BlockToolName`, `BlockTuneName`, `DataKey`, and `InlineToolName` so that structurally identical primitives (e.g. two different kinds of string IDs) are not interchangeable at the type level. +The system SHALL provide nominal (branded) types for `BlockId`, `BlockToolName`, `PluginDataName`, `DataKey`, and `InlineToolName` so that structurally identical primitives (e.g. two different kinds of string IDs) are not interchangeable at the type level. #### Scenario: Generating a block id - **GIVEN** a new block is being created - **WHEN** `generateBlockId()` is called - **THEN** it returns a 21-character URL-safe random `BlockId`, generated via `crypto.getRandomValues` -Implemented in `src/Nominal.ts`, `src/BlockId.ts`, `src/BlockTune.ts`, `src/DataKey.ts`, `src/InlineTool.ts`. +Implemented in `src/Nominal.ts`, `src/BlockId.ts`, `src/PluginData.ts`, `src/DataKey.ts`, `src/InlineTool.ts`. ### Requirement: Document and block serialization shapes -The system SHALL define the serialized shapes for blocks, text nodes, and documents (`BlockData`, `BlockNodeInit`, `BlockNodeSerialized`, `TextNodeSerialized`, `EditorDocumentSerialized`, `ChangeData`) so `model` and `sdk` agree on wire/storage format. +The system SHALL define the serialized shapes for blocks, text nodes, and documents (`BlockData`, `BlockNodeInit`, `BlockNodeSerialized`, `TextNodeSerialized`, `EditorDocumentSerialized`, `ChangeData`) so `model` and `sdk` agree on wire/storage format. A block's per-plugin data SHALL be carried under the optional `plugins` key as a record of `PluginDataSerialized` keyed by plugin data name. #### Scenario: Distinguishing child node types - **GIVEN** a block's data tree contains both plain values and text nodes - **WHEN** a data node is serialized - **THEN** it is tagged with the hidden discriminator property `$t` (`NODE_TYPE_HIDDEN_PROP`) set to a `BlockChildType` (`Value` or `Text`) so consumers can distinguish node kinds without inspecting shape -Implemented in `src/BlockNode.ts`, `src/Text.ts`, `src/Value.ts`, `src/EditorDocument.ts`, `src/ChangeData.ts`, `src/BlockChildType.ts`. +#### Scenario: Serializing plugin data +- **GIVEN** a block carrying data for plugin `anchors` +- **WHEN** it is serialized +- **THEN** the data appears under `plugins.anchors`, and no `tunes` key is produced + +Implemented in `src/BlockNode.ts`, `src/Text.ts`, `src/Value.ts`, `src/EditorDocument.ts`, `src/ChangeData.ts`, `src/BlockChildType.ts`, `src/PluginData.ts`. ### Requirement: Index — composite document location pointer -The system SHALL provide an abstract `IndexBase` class and one concrete subclass per pointer kind — `DocumentIndex`, `PropertyIndex`, `BlockIndex`, `TuneIndex`, `DataIndex`, `TextIndex` — each carrying only the fields structurally valid for that kind (e.g. `TuneIndex` always has `tuneName`+`tuneKey`, `PropertyIndex` never carries block-related fields), a `kind` discriminant (`IndexKind`) for narrowing, and immutable `with*` copy methods (`withBlockIndex`/`withTextRange`/`withDocumentId`) that return a new instance. The abstract `Index` class exposes static factory methods (`Index.document`/`property`/`block`/`tune`/`data`/`text`) and `Index.parse`, and overrides `Symbol.hasInstance` so `value instanceof Index` is true for any `IndexBase` instance even though concrete classes extend `IndexBase` directly. +The system SHALL provide an abstract `IndexBase` class and one concrete subclass per pointer kind — `DocumentIndex`, `PropertyIndex`, `BlockIndex`, `PluginDataIndex`, `DataIndex`, `TextIndex` — each carrying only the fields structurally valid for that kind (e.g. `PluginDataIndex` always has `pluginName`+`pluginKey`, `PropertyIndex` never carries block-related fields), a `kind` discriminant (`IndexKind`) for narrowing, and immutable `with*` copy methods (`withBlockIndex`/`withTextRange`/`withDocumentId`) that return a new instance. The abstract `Index` class exposes static factory methods (`Index.document`/`property`/`block`/`pluginData`/`data`/`text`) and `Index.parse`, and overrides `Symbol.hasInstance` so `value instanceof Index` is true for any `IndexBase` instance even though concrete classes extend `IndexBase` directly. #### Scenario: Constructing an index of a given kind - **GIVEN** a location needs to be pointed to - **WHEN** the corresponding `Index.*` factory (or a concrete class constructor) is called -- **THEN** it returns an instance of the matching subclass whose `kind` and fields are fixed by the constructor signature, so invalid field combinations (e.g. a tune name without a tune key, or a property name combined with a block index) cannot be constructed for that subclass +- **THEN** it returns an instance of the matching subclass whose `kind` and fields are fixed by the constructor signature, so invalid field combinations (e.g. a plugin name without a plugin key, or a property name combined with a block index) cannot be constructed for that subclass #### Scenario: Composite text selections - **GIVEN** a selection spans multiple disjoint text ranges (e.g. across blocks) @@ -42,21 +45,26 @@ The system SHALL provide an abstract `IndexBase` class and one concrete subclass #### Scenario: Parsing a serialized index - **GIVEN** a JSON string produced by `IndexBase#serialize()` - **WHEN** `Index.parse` is called -- **THEN** it parses the JSON and dispatches on its `k` discriminator field (`doc`/`prop`/`block`/`tune`/`data`/`text`/`composite`) to reconstruct the matching concrete instance, and throws if the value isn't a JSON object with a string `k` field or `k` is unrecognized +- **THEN** it parses the JSON and dispatches on its `k` discriminator field (`doc`/`prop`/`block`/`plugin`/`data`/`text`/`composite`) to reconstruct the matching concrete instance, and throws if the value isn't a JSON object with a string `k` field or `k` is unrecognized + +#### Scenario: Serializing a plugin data index +- **GIVEN** `Index.pluginData(1, 'anchors', 'id')` +- **WHEN** it is serialized +- **THEN** the result is `{"k":"plugin","b":1,"plugin":"anchors","key":"id"}`, and `Index.parse` of that string returns an equal `PluginDataIndex` #### Scenario: Resolving a partial index accumulated during event bubbling -- **GIVEN** a leaf node (text/value/tune) dispatches an event carrying only its locally-known fields as a `PartialIndex`, which parent nodes progressively complete via `withBlockIndex`/`withDocumentId` as the event bubbles up +- **GIVEN** a leaf node (text/value/plugin data) dispatches an event carrying only its locally-known fields as a `PartialIndex`, which parent nodes progressively complete via `withBlockIndex`/`withDocumentId` as the event bubbles up - **WHEN** `PartialIndex#resolve()` is called once all context has been attached -- **THEN** it returns the concrete `IndexBase` subclass matching the accumulated fields, throwing a specific error naming the missing/conflicting field (e.g. `TuneIndex requires tuneKey`, `DataIndex cannot be combined with tuneName`, `PropertyIndex cannot be combined with block-related fields`) when the fields don't resolve to a valid index; `PartialIndex` itself throws on `serialize()`, so it must always be resolved before leaving `model` +- **THEN** it returns the concrete `IndexBase` subclass matching the accumulated fields, throwing a specific error naming the missing/conflicting field (e.g. `PluginDataIndex requires pluginKey`, `DataIndex cannot be combined with pluginName`, `PropertyIndex cannot be combined with block-related fields`) when the fields don't resolve to a valid index; `PartialIndex` itself throws on `serialize()`, so it must always be resolved before leaving `model` -Implemented in `src/Index/IndexBase.ts`, `src/Index/index.ts` (factory/parse), `src/Index/DocumentIndex.ts`, `src/Index/PropertyIndex.ts`, `src/Index/BlockIndex.ts`, `src/Index/TuneIndex.ts`, `src/Index/DataIndex.ts`, `src/Index/TextIndex.ts`, `src/Index/PartialIndex.ts`, validated by `src/Index/Index.spec.ts`. +Implemented in `src/Index/IndexBase.ts`, `src/Index/index.ts` (factory/parse), `src/Index/DocumentIndex.ts`, `src/Index/PropertyIndex.ts`, `src/Index/BlockIndex.ts`, `src/Index/PluginDataIndex.ts`, `src/Index/DataIndex.ts`, `src/Index/TextIndex.ts`, `src/Index/PartialIndex.ts`, validated by `src/Index/Index.spec.ts`. ### Requirement: Base document event and event bus -The system SHALL provide a `BaseDocumentEvent` base class carrying `{ index, action, data, userId }` that fires under the `EventType.Changed` DOM event type, concrete event subclasses for each kind of document mutation (block/data/text add/remove/modify, tune/property modification), and a thin `EventBus` (`EventTarget` subclass) used to dispatch them. +The system SHALL provide a `BaseDocumentEvent` base class carrying `{ index, action, data, userId }` that fires under the `EventType.Changed` DOM event type, concrete event subclasses for each kind of document mutation (block/data/text add/remove/modify, plugin data/property modification), and a thin `EventBus` (`EventTarget` subclass) used to dispatch them. #### Scenario: Emitting a document mutation event -- **GIVEN** a block, text, or value node is added, removed, or modified -- **THEN** the corresponding concrete event (e.g. `DataNodeAddedEvent`, `TextFormattedEvent`, `BlockAddedEvent`, `PropertyModifiedEvent`, `TuneModifiedEvent`) is dispatched as `EventType.Changed`, carrying an `EventAction` (`Added`/`Removed`/`Modified`) and the affected `Index` +- **GIVEN** a block, text, value, or plugin data node is added, removed, or modified +- **THEN** the corresponding concrete event (e.g. `DataNodeAddedEvent`, `TextFormattedEvent`, `BlockAddedEvent`, `PropertyModifiedEvent`, `PluginDataModifiedEvent`) is dispatched as `EventType.Changed`, carrying an `EventAction` (`Added`/`Removed`/`Modified`) and the affected `Index` #### Scenario: Emitting a caret event - **GIVEN** a caret is added, removed, or updated @@ -73,3 +81,4 @@ The system SHALL provide generic dot-path object utilities (`get`, `set`, `has`, - **THEN** the corresponding nested value is read, written, checked, inserted, or removed, including array paths (e.g. `items.0.text`) Implemented in `src/keypath.ts`, validated by `src/keypath.spec.ts`. (Noted in `src/index.ts` as a candidate for extraction into a standalone `@editorjs/utils` package.) + diff --git a/openspec/specs/model/spec.md b/openspec/specs/model/spec.md index 22860e7f..d3e76279 100644 --- a/openspec/specs/model/spec.md +++ b/openspec/specs/model/spec.md @@ -48,7 +48,7 @@ The system SHALL provide `EditorDocument` as the root container of `BlockNode`s, - **THEN** the range is formatted with that `tool` and its `data`, so re-applying a data-carrying tool (e.g. redo or a remote op) keeps the fragment's data ### Requirement: BlockNode data tree -The system SHALL provide `BlockNode` representing a single block's data tree (nested value/text nodes, arrays, and objects) plus its `BlockTune`s, supporting creation/removal/lookup of data nodes, text insert/remove/format/unformat, tune/value updates, and text content extraction. +The system SHALL provide `BlockNode` representing a single block's data tree (nested value/text nodes, arrays, and objects) plus its per-plugin `PluginDataNode`s, supporting creation/removal/lookup of data nodes, text insert/remove/format/unformat, plugin-data/value updates, and text content extraction. Updating plugin data for a plugin name the block has no entry for SHALL create that entry rather than throw. #### Scenario: Creating a data node at an existing key - **GIVEN** a block already has a data node at a given key @@ -60,6 +60,16 @@ The system SHALL provide `BlockNode` representing a single block's data tree (ne - **WHEN** `createDataNode` targets an index within that array - **THEN** existing entries at or after that index are shifted rather than the operation erroring +#### Scenario: Updating plugin data for a new plugin name +- **GIVEN** a block with no plugin data entry named `anchors` +- **WHEN** `updatePluginData('anchors', { id: 'intro' })` is called +- **THEN** a `PluginDataNode` named `anchors` is created, its event listener is attached before any value is set, and a `PluginDataModifiedEvent` bubbles from the block with `previous` `undefined` + +#### Scenario: Plugin data events carry the acting user +- **GIVEN** a plugin data change made in a user context +- **WHEN** the event bubbles from the `PluginDataNode` through the `BlockNode` +- **THEN** its `userId` is taken from the active context, like value-node events, rather than a placeholder + Implemented in `src/entities/BlockNode/index.ts`, validated by its co-located `.spec.ts`. ### Requirement: Inline text tree @@ -97,16 +107,6 @@ The system SHALL provide `TextNode` (extending `ParentInlineNode`) as the inline Implemented in `src/entities/inline-fragments/ParentInlineNode/index.ts`, `src/entities/inline-fragments/FormattingInlineNode/index.ts`, `src/entities/inline-fragments/TextNode/index.ts`, validated by `src/entities/inline-fragments/TextNode/*.spec.ts`, `src/entities/inline-fragments/FormattingInlineNode/*.spec.ts`, and `src/entities/inline-fragments/specs/InlineTree.integration.spec.ts`. -### Requirement: Value nodes and block tunes -The system SHALL provide `ValueNode` for leaf non-text data storage and `BlockTune` for per-block tune data, both participating in the block's event-emitting data tree. - -#### Scenario: Modifying a value node -- **GIVEN** a `ValueNode` holding a leaf value within a block -- **WHEN** its value is updated -- **THEN** a `ValueModifiedEvent` is emitted carrying the previous and new value - -Implemented in `src/entities/ValueNode`, `src/entities/BlockTune`. - ### Requirement: Caret management The system SHALL provide `CaretManager` as a per-user-id registry of `Caret`s (create/get/update/remove, dispatching Added/Updated/Removed events) and `Caret` as a holder of a nullable `Index` whose `update()` dispatches a `CaretUpdatedEvent` and which serializes via `toJSON()`. @@ -127,3 +127,26 @@ The system SHALL provide an internal `ToolsRegistry` and IoC container for tool/ Implemented in `src/tools/ToolsRegistry.ts`, `src/IoC/`. +### Requirement: Value nodes and plugin data +The system SHALL provide `ValueNode` for leaf non-text data storage and `PluginDataNode` for per-block data owned by a plugin, both participating in the block's event-emitting data tree. A `PluginDataNode` SHALL hold a flat key/value record, SHALL emit one `PluginDataModifiedEvent` per changed key, and SHALL delete a key when it is set to `undefined`. + +#### Scenario: Modifying a value node +- **GIVEN** a `ValueNode` holding a leaf value within a block +- **WHEN** its value is updated +- **THEN** a `ValueModifiedEvent` is emitted carrying the previous and new value + +#### Scenario: Removing a plugin data key +- **GIVEN** a `PluginDataNode` holding `{ id: 'intro' }` +- **WHEN** `id` is updated to `undefined` +- **THEN** a `PluginDataModifiedEvent` is emitted with `previous` `'intro'` and `value` `undefined`, and the node's serialized form no longer contains `id` + +Implemented in `src/entities/ValueNode`, `src/entities/PluginDataNode`. + +### Requirement: Generic modification of plugin data +`EditorDocument.modifyData` SHALL apply a `Modified` change addressed by a `PluginDataIndex` by setting that plugin's key on the indexed block to the change's `value`, so undo/redo and remote operations can replay plugin data changes through the generic index-based entry point. + +#### Scenario: Replaying a plugin data change by index +- **GIVEN** a block at index 1 whose `anchors` plugin data has `visible: true` +- **WHEN** `modifyData(Index.pluginData(1, 'anchors', 'visible'), { value: false, previous: true })` is called +- **THEN** the block's `anchors.visible` becomes `false` and a `PluginDataModifiedEvent` is emitted with that index + diff --git a/openspec/specs/plugin-block-data/spec.md b/openspec/specs/plugin-block-data/spec.md new file mode 100644 index 00000000..1554d923 --- /dev/null +++ b/openspec/specs/plugin-block-data/spec.md @@ -0,0 +1,195 @@ +# plugin-block-data Specification + +## Purpose + +Plugins persist per-block data in the document Model under their own `name`, instead of through a dedicated Block Tune entity. This capability owns the contract end to end: the `plugins` store on `BlockNode` and its serialized form, the `BlocksAPI` methods plugins use to read and write it, and the guarantee that plugin-data changes are undoable and synchronized like any other document change. The storage primitives live in [[model]] and [[model-types]], the API surface in [[core]] and [[sdk]], and the OT handling in [[collaboration-manager]]. + +## Requirements +### Requirement: Per-block plugin data store +Each block SHALL be able to hold data owned by plugins, stored as a map from a plugin data name (by convention the owning plugin's static `name`) to a flat record of string keys and JSON-serializable values. The store SHALL be serialized under the block's `plugins` key, and a block without plugin data SHALL serialize without a `plugins` entry for that plugin. + +A write that would leave the stored data as it is — the value a key already holds, or the removal of a key that is not present — SHALL emit no event, and so SHALL produce neither an operation for collaborators nor an undo step. Plugins re-apply their current state routinely, and an entry that undoes nothing is worse than no entry at all. + +Plugin names and the keys within an entry are document data, not identifiers the editor chooses, so neither SHALL be able to collide with `Object.prototype`. A key arriving from a stored document SHALL be held as data whatever it is called, `__proto__` included; a key the entry does not hold SHALL read as absent rather than as an inherited member, both when asking for a plugin's entry and when reading a key within one. + +What `getPluginData` and the serialized document hand back SHALL be detached from the store, so that changing it does not change the document. Reading an entry, editing it and passing it back to `updatePluginData` is the obvious way to use the two together, and over a live record the no-op rule above turns it into silent loss: the document has already changed, so the write that should have announced it emits nothing. + +A value handed to the store SHALL be detached the same way before it is stored and before the change is recorded, down to nested objects and arrays, and so SHALL the data a block is initialized with. This is the same read-modify-write from the other end: a plugin keeps the object it wrote and edits it again, and over a shared object the document moves with no write at all, no operation for collaborators and no step to undo — two documents diverging with nothing to say so. What is recorded needs detaching for the same reason, since an operation and an undo step both outlive the call that produced them. Because what is stored is therefore a copy of what was written, the no-op rule above SHALL compare values structurally rather than by identity, which could only ever match a primitive. + +#### Scenario: A block with no plugin data +- **GIVEN** a block that has no plugin data at all +- **WHEN** it is serialized +- **THEN** its `plugins` value is an empty map rather than being absent, matching how the store serializes today + +#### Scenario: Block initialized with plugin data +- **GIVEN** a block is inserted with `plugins: { anchors: { id: "intro" } }` +- **WHEN** the document is serialized +- **THEN** the block's serialized form contains `plugins: { anchors: { id: "intro" } }` + +#### Scenario: Writing plugin data for the first time +- **GIVEN** a block that has no data for plugin `anchors` +- **WHEN** plugin data `{ id: "intro" }` is written for `anchors` on that block +- **THEN** the entry is created with that value instead of an error being thrown, and a `PluginDataModifiedEvent` is emitted for key `id` with `previous` `undefined` and `value` `"intro"` + +#### Scenario: Updating one key keeps the others +- **GIVEN** a block with `plugins.anchors` equal to `{ id: "intro", visible: true }` +- **WHEN** `{ visible: false }` is written for `anchors` +- **THEN** the entry becomes `{ id: "intro", visible: false }`, and exactly one `PluginDataModifiedEvent` is emitted, for key `visible` + +#### Scenario: Removing the last key drops the entry +- **GIVEN** a block with `plugins.anchors` equal to `{ id: "intro" }` +- **WHEN** `{ id: undefined }` is written for `anchors` +- **THEN** the key is removed, and the serialized block no longer contains an `anchors` entry under `plugins` + +#### Scenario: Writing the value a key already holds +- **GIVEN** a block with `plugins.anchors` equal to `{ visible: true }` +- **WHEN** `{ visible: true }` is written for `anchors` again +- **THEN** the data is unchanged and no `PluginDataModifiedEvent` is emitted + +#### Scenario: Removing a key that is not there +- **GIVEN** a block whose `anchors` entry has no `visible` key +- **WHEN** `{ visible: undefined }` is written for `anchors` +- **THEN** the data is unchanged and no `PluginDataModifiedEvent` is emitted + +#### Scenario: Editing a value that was written earlier +- **GIVEN** a plugin wrote `{ align: "left" }` for a key and still holds that object +- **WHEN** it changes the object to `{ align: "center" }` and writes it again +- **THEN** the document held `left` until that write, which emits a `PluginDataModifiedEvent` with `previous` `{ align: "left" }` and `value` `{ align: "center" }` + +#### Scenario: Writing an equal object again +- **GIVEN** a key holds `{ align: "left" }` +- **WHEN** a different object holding `{ align: "left" }` is written for it +- **THEN** no `PluginDataModifiedEvent` is emitted, because nothing about the stored data changed + +#### Scenario: Editing an object after the change was recorded +- **GIVEN** a plugin wrote an object for a key, and the change was recorded +- **WHEN** it changes that object afterwards +- **THEN** the recorded value is unaffected, so neither the operation sent to collaborators nor the undo step is rewritten + +#### Scenario: Reusing the data a block was initialized with +- **GIVEN** a block is initialized with a `plugins` map whose nested values the caller still holds +- **WHEN** the caller changes one of them +- **THEN** the block's plugin data is unaffected + +#### Scenario: Reading an entry whose keys were all removed +- **GIVEN** a block whose `anchors` entry existed and then had every key removed +- **WHEN** its plugin data is read +- **THEN** `undefined` is returned, the same as for an entry that never existed + +#### Scenario: A plugin name that collides with an object-prototype member +- **GIVEN** plugin data is written for a plugin named `__proto__` or `toString` +- **WHEN** it is written and read back, and the document is serialized and re-loaded +- **THEN** the entry is stored and returned as ordinary data, with no prototype of the store affected and no silent loss + +#### Scenario: An empty plugin name +- **WHEN** plugin data is written for an empty plugin name +- **THEN** it throws, rather than creating an unaddressable entry + +#### Scenario: Unknown plugin data is preserved +- **GIVEN** a document whose block carries a `plugins` entry for a plugin that is not registered in this editor +- **WHEN** the document is loaded and serialized again +- **THEN** that plugin's entry is preserved verbatim + +### Requirement: Plugin data API +The system SHALL expose `BlocksAPI.getPluginData({ block, plugin })` and `BlocksAPI.updatePluginData({ block, plugin, data, userId? })`, where `block` is a block index or id. `updatePluginData` SHALL merge the given keys into the plugin's entry, attributing the change to `userId` or, when omitted, to the configured user. Each changed key SHALL be recorded as its own modification, so a call that writes several keys is not a single undo step. `BlocksAPI.insert` and `insertMany` SHALL accept an initial `plugins` map per block. + +#### Scenario: Reading plugin data +- **GIVEN** a block with id `b1` whose `plugins.anchors` is `{ id: "intro" }` +- **WHEN** `api.blocks.getPluginData({ block: "b1", plugin: "anchors" })` is called +- **THEN** it returns `{ id: "intro" }` + +#### Scenario: Reading absent plugin data +- **WHEN** `getPluginData` is called for a plugin that has no entry on the block +- **THEN** it returns `undefined` + +#### Scenario: A plugin named after a member of Object.prototype +- **GIVEN** a block that has no entry for a plugin named `toString` +- **WHEN** `getPluginData({ block: 0, plugin: "toString" })` is called +- **THEN** it returns `undefined`, rather than the function the prototype would answer with + +#### Scenario: A key named __proto__ in a stored document +- **GIVEN** a document whose `plugins.anchors` holds a `__proto__` key +- **WHEN** it is loaded and serialized again +- **THEN** the key is still there, because it was held as data rather than reaching a prototype setter + +#### Scenario: The first write to a key named after a member of Object.prototype +- **GIVEN** an entry that holds no `toString` key +- **WHEN** `toString` is written for the first time +- **THEN** the change records no previous value, so undoing it removes the key rather than restoring an inherited function + +#### Scenario: Editing what was read +- **GIVEN** `getPluginData` returned a plugin's entry +- **WHEN** the caller changes a key on it and passes it to `updatePluginData` +- **THEN** the document is unchanged until that call, which records the change as its own modification + +#### Scenario: Writing plugin data +- **WHEN** `api.blocks.updatePluginData({ block: 0, plugin: "anchors", data: { id: "intro" } })` is called +- **THEN** the block at index 0 carries `plugins.anchors.id === "intro"`, and the emitted event's `userId` is the configured user + +#### Scenario: Unknown block +- **WHEN** `getPluginData` or `updatePluginData` references a block index or id that does not exist +- **THEN** it throws — naming the id when an id was given, or reporting an out-of-bounds index when an index was given + +#### Scenario: Writing several keys at once +- **WHEN** `updatePluginData` is called with two keys in `data` +- **THEN** both are applied, two modifications are recorded, and a single undo reverts only the last one + +### Requirement: Plugin data survives block restructuring +Block operations that relocate or transform a block SHALL keep its plugin data consistent: `move` SHALL preserve it, `convert` SHALL carry it over to the converted block, and `split` SHALL leave it on the original block and create the new block without plugin data. + +#### Scenario: Moving a block +- **GIVEN** a block carrying plugin data +- **WHEN** it is moved to another index +- **THEN** the block at the new index carries the same plugin data + +#### Scenario: Converting a block +- **GIVEN** a block carrying plugin data +- **WHEN** it is converted to another block tool +- **THEN** the resulting block carries the same plugin data + +#### Scenario: Splitting a block +- **GIVEN** a block carrying plugin data +- **WHEN** it is split at a caret offset +- **THEN** the original block keeps its plugin data, and the newly inserted block has none + +### Requirement: Plugin data changes are undoable +A plugin data change SHALL be recorded by local undo/redo like any other document modification. Undoing it SHALL restore the previous value, including removing a key that did not exist before the change. + +#### Scenario: Undoing a first write +- **GIVEN** a block with no `anchors` data, then `updatePluginData` writes `{ id: "intro" }` for `anchors` +- **WHEN** `api.document.undo()` is called +- **THEN** the block serializes without an `anchors` entry, and `api.document.redo()` restores `{ id: "intro" }` + +#### Scenario: Undoing an update +- **GIVEN** `plugins.anchors.visible` changed from `true` to `false` +- **WHEN** undo is performed +- **THEN** `visible` is `true` again + +#### Scenario: A write that changes nothing adds no undo step +- **GIVEN** `plugins.anchors.visible` is `true` and a plugin writes `{ visible: true }` again +- **WHEN** undo is performed +- **THEN** it reverts whatever the user did before that write, because the no-op write recorded nothing of its own + +### Requirement: Plugin data changes are collaborative +A local plugin data change SHALL be sent to collaborators as a `Modify` operation on a `PluginDataIndex`, and a received one SHALL be applied to the local model. Plugin data operations SHALL be transformed against concurrent block insertions and removals so they keep targeting the same block. + +#### Scenario: Remote client receives a plugin data change +- **GIVEN** two clients editing the same document +- **WHEN** client A writes `{ visible: false }` for `anchors` on a block +- **THEN** client B's model reflects `visible: false` for that block + +#### Scenario: Concurrent block insertion above +- **GIVEN** client A writes plugin data for the block at index 2 while client B concurrently inserts a block at index 0 +- **WHEN** both operations are applied on both clients +- **THEN** the plugin data change lands on the same logical block (index 3 after B's insertion) on both clients + +#### Scenario: Removing a key reaches collaborators +- **GIVEN** client A removes the `visible` key of a block's `anchors` data +- **WHEN** the operation is serialized, sent, and applied on client B +- **THEN** B's block no longer has that key — a removal carries no value, so it SHALL survive a round trip through JSON, where a key holding `undefined` does not + +#### Scenario: Target block removed concurrently +- **GIVEN** client A writes plugin data for a block that client B concurrently removes +- **WHEN** A's operation is transformed against B's removal +- **THEN** it becomes a no-op rather than modifying a different block + diff --git a/openspec/specs/sdk/spec.md b/openspec/specs/sdk/spec.md index 6a51a0c5..7c418033 100644 --- a/openspec/specs/sdk/spec.md +++ b/openspec/specs/sdk/spec.md @@ -16,50 +16,15 @@ Since `EventBus` itself carries no custom subscribe/unsubscribe/error-handling l Implemented in `src/entities/EventBus/EventBus.ts`, `Event.ts`, `events/core/*`, `events/ui/*`, `events/adapter/*` (base classes `CoreEventBase`, `UIEventBase`; enums `CoreEventType`, `AdapterEventType`). -### Requirement: Tool and tune contracts -The system SHALL define the static/instance contracts that block tools, inline tools, and block tunes must satisfy: `BaseTool`/`BaseToolConstructor` (common `name`, `options`, `prepare()`, `reset()`), `BlockTool`/`BlockToolConstructor` (adds `toolbox`, `shortcut`, `inlineToolbar`, `tunes`, `conversionConfig`, `canBeSplit`), `InlineTool`/`InlineToolConstructor` (adds `isActive`, `getFormattingOptions`, `createWrapper`, `getToolbarConfig`), and `BlockTune`/`BlockTuneConstructor`. `ToolConfig` SHALL be an SDK-owned contract (not a re-exported passthrough from `@editorjs/editorjs`), kept formally distinct from `ToolOptions`: `options` describes core/plugin-facing wiring available before any block instance exists, while `ToolConfig` describes tool-author-facing user data resolved per tool registration. A tool's static `options` SHALL be either a plain options object or a synchronous factory taking the tool's `ToolConfig` and returning that options object; the facade SHALL resolve the factory exactly once, at construction, and serve every option-reading getter from that resolved value without writing it back onto the tool class. - -#### Scenario: Options and config merging in a tool facade -- **GIVEN** a tool class has static `options` (and optionally `options.config` typed as `ToolConfig`) -- **WHEN** the tool is registered via `use(Tool, options)` with overriding options -- **THEN** the facade's `options` getter merges the tool's resolved static options with `use()`-time options, with `use()`-time keys taking precedence, and the `config` getter merges similarly, injecting `defaultPlaceholder` only when `isDefault` is true and no `placeholder` key is already present - -#### Scenario: Resolving static options from a config factory -- **GIVEN** a tool class declares `static options` as a function of its `ToolConfig` rather than as a plain object -- **WHEN** its facade is constructed for a registration made via `use(Tool, { config })` -- **THEN** the function is invoked exactly once with the `config` supplied at `use()` time, its returned options object becomes the tool's resolved static options for that facade, and the tool class's own `options` property is left untouched - -#### Scenario: Deriving a toolbox entry from a config value -- **GIVEN** a block tool's `options` factory computes `toolbox` entries from a field of the config it receives -- **WHEN** the facade's `toolbox` getter is read -- **THEN** the entries reflect the config supplied at `use()` time, and any explicit `use()`-time `toolbox` override is merged on top using the existing array/object positional-merge algorithm, with a `use()`-time `toolbox: false` still hiding the tool from the toolbox - -#### Scenario: Isolating factory-derived options per facade instance -- **GIVEN** two `Core` instances each register the same tool class through `use()` with a different `config` -- **WHEN** each instance's facade resolves the tool's `options` factory -- **THEN** each facade holds its own resolved options and neither instance's derived values are observable from the other - -#### Scenario: Text content conversion without config -- **GIVEN** a block tool has no `conversionConfig` -- **WHEN** `exportTextContent`/`importTextContent` is called on its facade -- **THEN** it throws a descriptive error stating the tool does not have export/import configuration - -#### Scenario: Text content conversion with a keypath -- **GIVEN** a block tool's `conversionConfig` specifies a dot-notation string key (including nested array paths, e.g. `items.0.text`) -- **WHEN** `exportTextContent`/`importTextContent` is called -- **THEN** the value at that keypath is read/written, producing or consuming a `TextNodeSerialized` value tagged with the hidden `Text` block-child-type marker - -Implemented in `src/entities/BaseTool.ts`, `BlockTool.ts`, `InlineTool.ts`, `BlockTune.ts`, `src/tools/facades/{BaseToolFacade,BlockToolFacade,InlineToolFacade,BlockTuneFacade}.ts`, validated by `src/tools/facades/BaseToolFacade.spec.ts`. - ### Requirement: Tools collection -The system SHALL provide a `ToolsCollection` (a `Map` subclass) exposing filtered `blockTools`/`inlineTools`/`blockTunes` views over registered tool facades. +The system SHALL provide a `ToolsCollection` (a `Map` subclass) exposing filtered `blockTools`/`inlineTools` views over registered tool facades. #### Scenario: Filtering registered facades by kind -- **GIVEN** a `ToolsCollection` containing a mix of block tool, inline tool, and tune facades -- **WHEN** `blockTools`, `inlineTools`, or `blockTunes` is accessed +- **GIVEN** a `ToolsCollection` containing a mix of block tool and inline tool facades +- **WHEN** `blockTools` or `inlineTools` is accessed - **THEN** each getter returns only the facades matching that kind -Implemented in `src/tools/ToolsCollection.ts`. +Implemented in `src/tools/ToolsCollection.ts`, validated by its co-located `.spec.ts`. ### Requirement: BlockToolAdapter bridges model events to per-block DOM state The system SHALL provide an abstract `BlockToolAdapter` (extending `EventTarget`) that subscribes to `api.document.onUpdate`, translates model-level `DataNodeAddedEvent`/`DataNodeRemovedEvent`/`ValueModifiedEvent` into adapter-level `KeyAddedEvent`/`KeyRemovedEvent`/`ValueNodeChangedEvent` dispatched on itself, and exposes `registerTextInputKey`, `registerValueKey`, `removeKey`, and `destroy()`. @@ -112,17 +77,29 @@ The system SHALL provide `matchKeyboardShortcut(event, shortcutString)` to test Implemented in `src/utils/keyboardShortcut.ts`, `src/utils/keypath.ts`. ### Requirement: Augmentable plugin type maps -The system SHALL declare two empty, augmentable interfaces — `EditorjsPluginApiMap` (plugin id → public API type) and `ToolPluginOptionsMap` (plugin id → tool-directed options type) — that plugin packages extend via module augmentation of `@editorjs/sdk`. +The system SHALL declare three empty, augmentable interfaces — `EditorjsPluginApiMap` (plugin id → public API type), `ToolPluginOptionsMap` (plugin id → tool-directed options type), and `EditorjsPluginDataMap` (plugin id → the shape of the per-block data that plugin stores) — that plugin packages extend via module augmentation of `@editorjs/sdk`. `PluginId` SHALL include the keys of all three maps. `BlocksAPI.getPluginData`/`updatePluginData` SHALL resolve their data type from `EditorjsPluginDataMap` for a declared id, and SHALL fall back to `Record` for an id absent from it, using a non-distributive conditional so the `string & {}` member of `PluginId` does not widen a declared id's type. #### Scenario: Plugin package augments both maps -- **GIVEN** a plugin package declares `declare module '@editorjs/sdk'` augmenting both interfaces under its `name` +- **GIVEN** a plugin package declares `declare module '@editorjs/sdk'` augmenting `EditorjsPluginApiMap` and `ToolPluginOptionsMap` under its `name` - **WHEN** a consumer's compilation includes that package's types - **THEN** `api.plugins.` and `options.plugins.` are both fully typed with no cast #### Scenario: No augmentation present -- **GIVEN** no plugin package has augmented either interface +- **GIVEN** no plugin package has augmented any of the three interfaces - **WHEN** `@editorjs/sdk` is compiled on its own -- **THEN** both interfaces are empty and `Partial<...>` of them permits no keys, so the base package remains self-consistent +- **THEN** all three are empty and `Partial<...>` of them permits no keys, so the base package remains self-consistent + +#### Scenario: Plugin package declares its block data shape +- **GIVEN** a plugin package augments `EditorjsPluginDataMap` with `{ anchors: { id: string } }` +- **WHEN** a consumer calls `api.blocks.getPluginData({ plugin: 'anchors' })` +- **THEN** the result is typed `{ id: string } | undefined`, and `updatePluginData({ plugin: 'anchors', data: { id: 1 } })` is a compile error + +#### Scenario: Plugin data for an undeclared id +- **GIVEN** a plugin that has not augmented `EditorjsPluginDataMap` +- **WHEN** `getPluginData({ plugin: 'whatever' })` is called +- **THEN** the result is typed `Record | undefined` rather than `never`, so an undeclared plugin still compiles + +Implemented in `src/index.ts` (the map declarations, `PluginId`, `PluginsAPI`, `ToolPluginOptions`), `src/api/BlocksAPI.ts`, validated by `src/pluginTypeMaps.spec.ts`. ### Requirement: Tool options carry plugin-directed configuration `BaseToolOptions` SHALL include an optional `plugins` key typed as `Partial`, and `BaseToolFacade` SHALL expose an accessor returning the merged slice for a single plugin id. @@ -134,3 +111,42 @@ The system SHALL declare two empty, augmentable interfaces — `EditorjsPluginAp Implemented in `src/entities/BaseTool.ts`, `src/tools/facades/BaseToolFacade.ts`. +### Requirement: Tool contracts +The system SHALL define the static/instance contracts that block tools and inline tools must satisfy: `BaseTool`/`BaseToolConstructor` (common `name`, `options`, `prepare()`, `reset()`), `BlockTool`/`BlockToolConstructor` (adds `toolbox`, `shortcut`, `inlineToolbar`, `conversionConfig`, `canBeSplit`), and `InlineTool`/`InlineToolConstructor` (adds `isActive`, `getFormattingOptions`, `createWrapper`, `getToolbarConfig`). The SDK SHALL NOT define a Block Tune tool kind: per-block settings and per-block data are provided by plugins (see `block-settings` and `plugin-block-data`), and `ToolType` SHALL have no `Tune` member. `ToolConfig` SHALL be an SDK-owned contract (not a re-exported passthrough from `@editorjs/editorjs`), kept formally distinct from `ToolOptions`: `options` describes core/plugin-facing wiring available before any block instance exists, while `ToolConfig` describes tool-author-facing user data resolved per tool registration. A tool's static `options` SHALL be either a plain options object or a synchronous factory taking the tool's `ToolConfig` and returning that options object; the facade SHALL resolve the factory exactly once, at construction, and serve every option-reading getter from that resolved value without writing it back onto the tool class. + +#### Scenario: Options and config merging in a tool facade +- **GIVEN** a tool class has static `options` (and optionally `options.config` typed as `ToolConfig`) +- **WHEN** the tool is registered via `use(Tool, options)` with overriding options +- **THEN** the facade's `options` getter merges the tool's resolved static options with `use()`-time options, with `use()`-time keys taking precedence, and the `config` getter merges similarly, injecting `defaultPlaceholder` only when `isDefault` is true and no `placeholder` key is already present + +#### Scenario: Resolving static options from a config factory +- **GIVEN** a tool class declares `static options` as a function of its `ToolConfig` rather than as a plain object +- **WHEN** its facade is constructed for a registration made via `use(Tool, { config })` +- **THEN** the function is invoked exactly once with the `config` supplied at `use()` time, its returned options object becomes the tool's resolved static options for that facade, and the tool class's own `options` property is left untouched + +#### Scenario: Deriving a toolbox entry from a config value +- **GIVEN** a block tool's `options` factory computes `toolbox` entries from a field of the config it receives +- **WHEN** the facade's `toolbox` getter is read +- **THEN** the entries reflect the config supplied at `use()` time, and any explicit `use()`-time `toolbox` override is merged on top using the existing array/object positional-merge algorithm, with a `use()`-time `toolbox: false` still hiding the tool from the toolbox + +#### Scenario: Isolating factory-derived options per facade instance +- **GIVEN** two `Core` instances each register the same tool class through `use()` with a different `config` +- **WHEN** each instance's facade resolves the tool's `options` factory +- **THEN** each facade holds its own resolved options and neither instance's derived values are observable from the other + +#### Scenario: Text content conversion without config +- **GIVEN** a block tool has no `conversionConfig` +- **WHEN** `exportTextContent`/`importTextContent` is called on its facade +- **THEN** it throws a descriptive error stating the tool does not have export/import configuration + +#### Scenario: Text content conversion with a keypath +- **GIVEN** a block tool's `conversionConfig` specifies a dot-notation string key (including nested array paths, e.g. `items.0.text`) +- **WHEN** `exportTextContent`/`importTextContent` is called +- **THEN** the value at that keypath is read/written, producing or consuming a `TextNodeSerialized` value tagged with the hidden `Text` block-child-type marker + +#### Scenario: No tune tool kind +- **WHEN** the SDK's public exports are inspected +- **THEN** there is no `BlockTune`, `BlockTuneConstructor`, `BlockTuneOptions`, `BlockTuneFacade`, or `ToolType.Tune`, and `BlockToolConstructor` has no `tunes` member + +Implemented in `src/entities/BaseTool.ts`, `BlockTool.ts`, `InlineTool.ts`, `src/tools/facades/{BaseToolFacade,BlockToolFacade,InlineToolFacade}.ts`, validated by `src/tools/facades/BaseToolFacade.spec.ts`. + diff --git a/packages/core/src/index.spec.ts b/packages/core/src/index.spec.ts index 3338540a..5b525f6b 100644 --- a/packages/core/src/index.spec.ts +++ b/packages/core/src/index.spec.ts @@ -1,7 +1,8 @@ /* eslint-disable jsdoc/require-jsdoc -- inline test stubs */ -import { describe, it, expect } from '@jest/globals'; +import { afterEach, describe, it, expect, jest } from '@jest/globals'; import { PluginType, ToolType } from '@editorjs/sdk'; import type { CoreConfig } from '@editorjs/sdk'; +import ToolsManager from './tools/ToolsManager.js'; import Core from './index.js'; /** @@ -56,6 +57,22 @@ class StubPlugin { } } +/** + * Stands in for a former Block Tune: a plain plugin that contributes an item to the + * block settings menu. It carries no `type`, so `use()` must route it to the plugins + * container rather than to any tool collection. + */ +class StubSettingsPlugin { + public static type = PluginType.Plugin as const; + public static name = 'delete-block'; + + public static instances = 0; + + constructor() { + StubSettingsPlugin.instances += 1; + } +} + describe('Core', () => { describe('initialize() preconditions', () => { it('should throw naming the rendering adapter when no adapter has been registered', async () => { @@ -107,4 +124,39 @@ describe('Core', () => { expect(StubPlugin.instances).toBe(1); }); }); + + describe('registering a former block tune', () => { + afterEach(() => { + jest.restoreAllMocks(); + }); + + it('should instantiate a block settings plugin as a plugin and keep it out of the tools handed to ToolsManager', async () => { + StubSettingsPlugin.instances = 0; + + const prepareTools = jest.spyOn(ToolsManager.prototype, 'prepareTools'); + const core = new Core(createConfig()); + + core.use(StubAdapter); + core.use(StubBlockTool); + core.use(StubSettingsPlugin); + + await core.initialize(); + + const prepared = prepareTools.mock.calls[0][0]; + + expect(StubSettingsPlugin.instances).toBe(1); + expect(prepared.map(([tool]) => tool.name)).toEqual(['paragraph']); + }); + + it('should no longer expose a blockTunes collection on ToolsManager', () => { + type ManagerCollections = { + // @ts-expect-error -- `blockTunes` went with the tune tool kind + blockTunes: ToolsManager['blockTunes']; + }; + + const probe: ManagerCollections | undefined = undefined; + + expect(probe).toBeUndefined(); + }); + }); }); diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 01ab27ae..52fcf44d 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -16,7 +16,7 @@ import { } from '@editorjs/sdk'; import { composeDataFromVersion2 } from './utils/composeDataFromVersion2.js'; import ToolsManager from './tools/ToolsManager.js'; -import type { CoreConfigValidated, CoreConfig, EditorjsPluginConstructor, BlockTuneConstructor, ToolConstructable, EditorjsAdapterPluginConstructor } from '@editorjs/sdk'; +import type { CoreConfigValidated, CoreConfig, EditorjsPluginConstructor, ToolConstructable, EditorjsAdapterPluginConstructor } from '@editorjs/sdk'; import { EditorAPI } from './api/index.js'; import { generateId } from './utils/uid.js'; import { BlocksManager } from './components/BlockManager.js'; @@ -134,7 +134,6 @@ export default class Core { switch (pluginType) { case ToolType.Block: case ToolType.Inline: - case ToolType.Tune: this.#plugins.bind<[ToolConstructable, ToolStaticOptions | undefined]>(pluginType).toConstantValue([pluginOrTool as ToolConstructable, options]); break; case PluginType.Adapter: @@ -218,11 +217,10 @@ export default class Core { async #initializeTools(): Promise { const blockTools = this.#plugins.getAll<[BlockToolConstructor, ToolStaticOptions | undefined]>(ToolType.Block); const inlineTools = this.#plugins.getAll<[InlineToolConstructor, ToolStaticOptions | undefined]>(ToolType.Inline); - const blockTunes = this.#plugins.getAll<[BlockTuneConstructor, ToolStaticOptions | undefined]>(ToolType.Tune); const toolsManager = this.#iocContainer.get(ToolsManager); - return toolsManager.prepareTools([...blockTools, ...inlineTools, ...blockTunes]); + return toolsManager.prepareTools([...blockTools, ...inlineTools]); } /** diff --git a/packages/core/src/tools/ToolsFactory.spec.ts b/packages/core/src/tools/ToolsFactory.spec.ts new file mode 100644 index 00000000..4dd3672a --- /dev/null +++ b/packages/core/src/tools/ToolsFactory.spec.ts @@ -0,0 +1,66 @@ +/* eslint-disable jsdoc/require-jsdoc -- inline test stubs */ +import { describe, it, expect } from '@jest/globals'; +import type { EditorAPI, ToolConstructable, ToolStaticOptions } from '@editorjs/sdk'; +import { BlockToolFacade, InlineToolFacade, ToolType } from '@editorjs/sdk'; +import type { EditorConfig } from 'editorjs-v2'; +import { ToolsFactory } from './ToolsFactory.js'; + +class StubBlockTool { + public static type = ToolType.Block as const; + public static name = 'paragraph'; +} + +class StubInlineTool { + public static type = ToolType.Inline as const; + public static name = 'bold'; +} + +/** + * Builds a factory holding both stub tools, optionally registering the block tool + * with `use()`-time options. The factory only reads `defaultBlock` + * and `placeholder` off the editor config, so a partial object stands in for it, + * and `get()` never instantiates a tool — so the stubs implement no tool methods + * and are cast to satisfy the registration signature. + * @param blockToolSettings - second argument of `use()` for the block tool + */ +function createFactory(blockToolSettings?: ToolStaticOptions): ToolsFactory { + const factory = new ToolsFactory( + {}, + { defaultBlock: 'paragraph' } as EditorConfig, + {} as EditorAPI + ); + + factory.setTools([ + [StubBlockTool as unknown as ToolConstructable, blockToolSettings], + [StubInlineTool as unknown as ToolConstructable, undefined], + ]); + + return factory; +} + +describe('ToolsFactory', () => { + describe('.get()', () => { + it('should wrap a block tool in a BlockToolFacade', () => { + expect(createFactory().get('paragraph')).toBeInstanceOf(BlockToolFacade); + }); + + it('should wrap an inline tool in an InlineToolFacade', () => { + expect(createFactory().get('bold')).toBeInstanceOf(InlineToolFacade); + }); + + it('should mark the configured defaultBlock tool as default', () => { + expect(createFactory().get('paragraph').isDefault).toBe(true); + expect(createFactory().get('bold').isDefault).toBe(false); + }); + + it('should hand the registration options to the facade it builds', () => { + const factory = createFactory({ config: { placeholder: 'Type here' } }); + + expect(factory.get('paragraph').config).toEqual({ placeholder: 'Type here' }); + }); + + it('should throw naming a tool that was never registered', () => { + expect(() => createFactory().get('header')).toThrow('Tool header is not registered'); + }); + }); +}); diff --git a/packages/core/src/tools/ToolsFactory.ts b/packages/core/src/tools/ToolsFactory.ts index 8fbe9362..0ea206d5 100644 --- a/packages/core/src/tools/ToolsFactory.ts +++ b/packages/core/src/tools/ToolsFactory.ts @@ -4,14 +4,13 @@ import { ToolType } from '@editorjs/sdk'; import type { ToolConstructable, ToolStaticOptions } from '@editorjs/sdk'; import { InlineToolFacade, - BlockTuneFacade, BlockToolFacade } from '@editorjs/sdk'; import type { EditorConfig } from 'editorjs-v2'; -type ToolConstructor = typeof InlineToolFacade | typeof BlockToolFacade | typeof BlockTuneFacade; +type ToolConstructor = typeof InlineToolFacade | typeof BlockToolFacade; /** * Full tool registration entry: the constructor class plus its options. @@ -81,7 +80,7 @@ export class ToolsFactory { * Returns Tool object based on it's type * @param name - tool name */ - public get(name: string): InlineToolFacade | BlockToolFacade | BlockTuneFacade { + public get(name: string): InlineToolFacade | BlockToolFacade { const toolSettings = this.#toolsSettings.get(name); if (!toolSettings) { @@ -91,7 +90,6 @@ export class ToolsFactory { const { class: constructable, ...useToolOptions } = toolSettings; const Constructor = this.#getConstructor(constructable); - // const isTune = constructable[InternalTuneSettings.IsTune]; return new Constructor({ name, @@ -115,8 +113,6 @@ export class ToolsFactory { switch (constructable.type) { case ToolType.Inline: return InlineToolFacade; - case ToolType.Tune: - return BlockTuneFacade; default: return BlockToolFacade; } diff --git a/packages/core/src/tools/ToolsManager.ts b/packages/core/src/tools/ToolsManager.ts index 297f30fd..6b4e968b 100644 --- a/packages/core/src/tools/ToolsManager.ts +++ b/packages/core/src/tools/ToolsManager.ts @@ -9,7 +9,7 @@ import type { import { InlineTool, ToolLoadedCoreEvent, - BlockToolFacade, BlockTuneFacade, + BlockToolFacade, InlineToolFacade, ToolFacadeClass, ToolsCollection, @@ -84,14 +84,6 @@ export default class ToolsManager { return this.available.blockTools; } - /** - * Return available Block Tunes - * @returns - object of Inline Tool's classes - */ - public get blockTunes(): ToolsCollection { - return this.available.blockTunes; - } - /** * @param editorConfig - EditorConfig object * @param apiFactory - Editor API factory function diff --git a/packages/plugins/shortcuts-plugin/src/index.ts b/packages/plugins/shortcuts-plugin/src/index.ts index a222cea3..653c7708 100644 --- a/packages/plugins/shortcuts-plugin/src/index.ts +++ b/packages/plugins/shortcuts-plugin/src/index.ts @@ -1,6 +1,5 @@ import type { BlockToolFacade, - BlockTuneFacade, EditorAPI, EditorjsPlugin, EditorjsPluginParams, @@ -207,14 +206,4 @@ export class ShortcutsPlugin implements EditorjsPlugin<'shortcuts'> { * @todo `shortcuts` map for block tools (e.g. list styles) — apply render/data overrides */ } - - /** - * Block tune shortcuts — reserved for future use. - * @param _tool - loaded block tune facade - */ - #processBlockTune(_tool: BlockTuneFacade): void { - /* - * @todo block tune shortcuts if needed - */ - } } diff --git a/packages/sdk/src/api/BlocksAPI.ts b/packages/sdk/src/api/BlocksAPI.ts index 6e1e1281..896477bd 100644 --- a/packages/sdk/src/api/BlocksAPI.ts +++ b/packages/sdk/src/api/BlocksAPI.ts @@ -285,9 +285,8 @@ export interface BlocksAPI { * Updates block data by id * @param id - id of the block to update * @param data - (optional) the new data. Can be partial. - * @param tunes - (optional) tune data */ - // update(id: string, data?: Partial, tunes?: { [name: string]: BlockTuneData }): Promise; + // update(id: string, data?: Partial): Promise; /** * Converts block to another type. Both blocks should provide the conversionConfig. diff --git a/packages/sdk/src/entities/BaseTool.ts b/packages/sdk/src/entities/BaseTool.ts index 83e34e72..e3f00f55 100644 --- a/packages/sdk/src/entities/BaseTool.ts +++ b/packages/sdk/src/entities/BaseTool.ts @@ -1,6 +1,5 @@ import type { BlockToolOptions } from './BlockTool.js'; import type { InlineToolOptions } from './InlineTool.js'; -import type { BlockTuneOptions } from './BlockTune.js'; import type { ToolType } from './EntityType.js'; import type { ToolPluginOptions } from '../index.js'; @@ -75,13 +74,13 @@ export type ToolOptionsFactory< > = (config: Config) => Options; // Re-export so consumers can import all option types from this file -export type { BlockToolOptions, InlineToolOptions, BlockTuneOptions }; +export type { BlockToolOptions, InlineToolOptions }; /** * Union of all per-tool option shapes. * Used as the type of the second argument of `core.use(Tool, options)`. */ -export type ToolStaticOptions = BlockToolOptions | InlineToolOptions | BlockTuneOptions; +export type ToolStaticOptions = BlockToolOptions | InlineToolOptions; /** * Maps a {@link ToolType} value to its corresponding tool options interface. @@ -97,10 +96,6 @@ export type ToolTypeToOptions = { * InlineTool Options */ [ToolType.Inline]: InlineToolOptions; - /** - * BlockTune Options - */ - [ToolType.Tune]: BlockTuneOptions; }; /** diff --git a/packages/sdk/src/entities/BlockTool.ts b/packages/sdk/src/entities/BlockTool.ts index 1f77f69c..8cc8ad9e 100644 --- a/packages/sdk/src/entities/BlockTool.ts +++ b/packages/sdk/src/entities/BlockTool.ts @@ -41,8 +41,6 @@ export enum BlockToolOptionKey { Shortcut = 'shortcut', /** Inline tools enabled for blocks of this type. */ InlineToolbar = 'inlineToolbar', - /** Block tunes enabled for blocks of this type. */ - Tunes = 'tunes', /** Conversion configuration for this tool. */ ConversionConfig = 'conversionConfig', /** Whether the block can be split into multiple blocks of its type. */ @@ -77,12 +75,6 @@ export interface BlockToolOptions - extends BaseToolOptions { - /** Any additional custom options exposed by the tune developer. */ - [key: string]: unknown; -} - -/** - * BlockTune data type - * @todo move to data description section when migrated from V2 - */ -export type BlockTuneData = any; - -/** - * Extended BlockToolConstructorOptions interface for version 3. - */ -export interface BlockTuneConstructorOptions< - /** - * Data structure describing the tool's input/output data - */ - Data extends BlockTuneData = BlockTuneData, - /** - * User-end configuration for the tool - */ - Config extends ToolConfig = ToolConfig -> { - /** - * Tool's input/output data - */ - data: Data; - - /** - * Config could be passed by tools user through the Editor config - */ - config: Config; -} - -/** - * Block Tune interface for version 3 - * @todo describe the interface when the adapter implementation is done - */ -export type BlockTune< - /** - * Data structure describing the tool's input/output data - * - * any is used as a placeholder to allow using BlockToolData without generic - */ - // eslint-disable-next-line @typescript-eslint/no-unused-vars - Data extends BlockTuneData = any, - /** - * User-end configuration for the tool - * - * any is used as a placeholder to allow using BlockToolData without generic - */ - // eslint-disable-next-line @typescript-eslint/no-unused-vars - Config extends ToolConfig = any -> = Omit; - -/** - * Block Tune constructor class - */ -export interface BlockTuneConstructor extends BaseToolConstructor { - new(options: BlockTuneConstructorOptions): BlockTune; - - /** - * Property specifies that the class is a Tune - */ - type: ToolType.Tune; -}; diff --git a/packages/sdk/src/entities/EntityType.ts b/packages/sdk/src/entities/EntityType.ts index 02c8a2e0..09aaf2ca 100644 --- a/packages/sdk/src/entities/EntityType.ts +++ b/packages/sdk/src/entities/EntityType.ts @@ -40,12 +40,7 @@ export enum ToolType { /** * Inline Tool */ - Inline = 'inline', - - /** - * Block Tune - */ - Tune = 'tune' + Inline = 'inline' } /** diff --git a/packages/sdk/src/entities/MenuConfig.ts b/packages/sdk/src/entities/MenuConfig.ts index db7ea4a2..be487a4c 100644 --- a/packages/sdk/src/entities/MenuConfig.ts +++ b/packages/sdk/src/entities/MenuConfig.ts @@ -11,7 +11,7 @@ export { PopoverItemType }; /** * Menu configuration format. - * Is used for defining Block Tunes Menu items via Block Tool's renderSettings(), Block Tune's render() and Inline Tool's render(). + * Is used for defining menu items via Block Tool's renderSettings() and Inline Tool's render(). */ export type MenuConfig = MenuConfigItem | MenuConfigItem[]; diff --git a/packages/sdk/src/entities/index.ts b/packages/sdk/src/entities/index.ts index 7bbfed56..eef4535d 100644 --- a/packages/sdk/src/entities/index.ts +++ b/packages/sdk/src/entities/index.ts @@ -1,7 +1,6 @@ export * from './BaseTool.js'; export type * from './InlineTool.js'; export * from './BlockTool.js'; -export type * from './BlockTune.js'; export type * from './Config.js'; export * from './BlockToolAdapter.js'; export * from './EventBus/index.js'; diff --git a/packages/sdk/src/tools/ToolsCollection.spec.ts b/packages/sdk/src/tools/ToolsCollection.spec.ts new file mode 100644 index 00000000..63f39c05 --- /dev/null +++ b/packages/sdk/src/tools/ToolsCollection.spec.ts @@ -0,0 +1,63 @@ +/* eslint-disable jsdoc/require-jsdoc -- inline test stubs */ + +import { describe, expect, it } from '@jest/globals'; +import { ToolType } from '../entities/index.js'; +import type { ToolFacadeClass } from './facades/index.js'; +import { ToolsCollection } from './ToolsCollection.js'; + +/** + * Stands in for a registered facade: `ToolsCollection` filters purely on the kind + * predicates, so a bare object carrying `type` and those predicates is enough. + * @param name - name the facade is registered under + * @param type - kind the facade reports + */ +function facadeStub(name: string, type: ToolType): [string, ToolFacadeClass] { + const facade = { + name, + type, + isBlock: () => type === ToolType.Block, + isInline: () => type === ToolType.Inline, + }; + + return [name, facade as unknown as ToolFacadeClass]; +} + +describe('ToolsCollection', () => { + const collection = new ToolsCollection([ + facadeStub('paragraph', ToolType.Block), + facadeStub('header', ToolType.Block), + facadeStub('bold', ToolType.Inline), + ]); + + it('should return only block tool facades from blockTools', () => { + expect([...collection.blockTools.keys()]).toEqual(['paragraph', 'header']); + }); + + it('should return only inline tool facades from inlineTools', () => { + expect([...collection.inlineTools.keys()]).toEqual(['bold']); + }); + + it('should expose no view beyond blockTools and inlineTools', () => { + /* + * Own getters live on the prototype, so the collection's kind views are read from + * there rather than from the instance. + */ + const views = Object + .entries(Object.getOwnPropertyDescriptors(ToolsCollection.prototype)) + .filter(([, descriptor]) => descriptor.get !== undefined) + .map(([key]) => key); + + expect(views.sort()).toEqual(['blockTools', 'inlineTools']); + }); + + it('should no longer expose a blockTunes view', () => { + type CollectionViews = { + // @ts-expect-error -- `blockTunes` went with the tune tool kind + blockTunes: ToolsCollection['blockTunes']; + }; + + const probe: CollectionViews | undefined = undefined; + + expect(probe).toBeUndefined(); + }); +}); diff --git a/packages/sdk/src/tools/ToolsCollection.ts b/packages/sdk/src/tools/ToolsCollection.ts index 979a91e9..1ed3c86d 100644 --- a/packages/sdk/src/tools/ToolsCollection.ts +++ b/packages/sdk/src/tools/ToolsCollection.ts @@ -1,6 +1,5 @@ import { type BlockToolFacade } from './facades/BlockToolFacade.js'; import { type InlineToolFacade } from './facades/InlineToolFacade.js'; -import { type BlockTuneFacade } from './facades/BlockTuneFacade.js'; import type { ToolFacadeClass } from './facades/index.js'; /** @@ -28,15 +27,4 @@ export class ToolsCollection extend return new ToolsCollection(tools); } - - /** - * Returns Block Tunes collection - */ - public get blockTunes(): ToolsCollection { - const tools = Array - .from(this.entries()) - .filter(([, tool]) => tool.isTune()) as [string, BlockTuneFacade][]; - - return new ToolsCollection(tools); - } } diff --git a/packages/sdk/src/tools/facades/BaseToolFacade.spec.ts b/packages/sdk/src/tools/facades/BaseToolFacade.spec.ts index c0ad6635..e05afb97 100644 --- a/packages/sdk/src/tools/facades/BaseToolFacade.spec.ts +++ b/packages/sdk/src/tools/facades/BaseToolFacade.spec.ts @@ -1,11 +1,33 @@ /* eslint-disable jsdoc/require-jsdoc,@typescript-eslint/no-magic-numbers */ import { describe, expect, it } from '@jest/globals'; -import type { BlockToolConstructor, BlockToolData } from '../../entities/index.js'; +import type { + BlockToolConstructor, + BlockToolData, + /* + * Everything below is asserted absent: under `ts-jest` a stale `@ts-expect-error` is + * itself a diagnostic, so each directive fails this suite while its name still exists. + * Only tool-kind names are enumerated — the model layer keeps its own per-block data + * vocabulary, renamed separately by `plugin-block-data`. + */ + // @ts-expect-error -- the `BlockTune` contract went with the tune tool kind + BlockTune, + // @ts-expect-error -- the `BlockTuneConstructor` contract went with the tune tool kind + BlockTuneConstructor, + // @ts-expect-error -- the `BlockTuneConstructorOptions` contract went with the tune tool kind + BlockTuneConstructorOptions, + // @ts-expect-error -- the `BlockTuneOptions` contract went with the tune tool kind + BlockTuneOptions, + // @ts-expect-error -- the `BlockTuneData` contract went with the tune tool kind + BlockTuneData +} from '../../entities/index.js'; import { BlockToolOptionKey, ToolType } from '../../entities/index.js'; import type { ToolOptions } from './BaseToolFacade.js'; import { UserToolOptions } from './BaseToolFacade.js'; import { BlockToolFacade } from './BlockToolFacade.js'; +// @ts-expect-error -- the `BlockTuneFacade` class went with the tune tool kind +import type { BlockTuneFacade } from './index.js'; +import type { BaseToolFacade } from './BaseToolFacade.js'; import type { InlineFragment } from '@editorjs/model-types'; import { BlockChildType, NODE_TYPE_HIDDEN_PROP } from '@editorjs/model-types'; import type { EditorAPI } from '../../api'; @@ -507,3 +529,59 @@ describe('BaseToolFacade (via BlockToolFacade)', () => { }); }); }); + +describe('Tune tool kind removal', () => { + it('should no longer export the tune tool contracts', () => { + /** + * References the absent names so the import directives above are the assertion, + * rather than unused imports the linter would strip. + */ + type ToolContracts = { + tune: BlockTune; + constructor: BlockTuneConstructor; + constructorOptions: BlockTuneConstructorOptions; + options: BlockTuneOptions; + data: BlockTuneData; + facade: BlockTuneFacade; + }; + + const probe: ToolContracts | undefined = undefined; + + expect(probe).toBeUndefined(); + }); + + it('should no longer define a Tune member on ToolType', () => { + // @ts-expect-error -- `Tune` was removed from the ToolType enum + expect(ToolType.Tune).toBeUndefined(); + }); + + it('should no longer define a Tunes member on BlockToolOptionKey', () => { + /* + * `BlockToolOptions['tunes']` itself cannot be asserted: the interface carries an + * open `[key: string]: unknown` index signature for tool-author options, so every + * key resolves. The enum member is the removable surface. + */ + // @ts-expect-error -- `Tunes` was removed from the BlockToolOptionKey enum + expect(BlockToolOptionKey.Tunes).toBeUndefined(); + }); + + it('should no longer define an EnabledBlockTunes member on UserToolOptions', () => { + // @ts-expect-error -- `EnabledBlockTunes` was removed from the UserToolOptions enum + expect(UserToolOptions.EnabledBlockTunes).toBeUndefined(); + }); + + it('should no longer expose tune members on the facades', () => { + type FacadeMembers = { + // @ts-expect-error -- `isTune()` went with the tune tool kind + isTune: BaseToolFacade['isTune']; + // @ts-expect-error -- `enabledBlockTunes` went with the tune tool option + enabledBlockTunes: BlockToolFacade['enabledBlockTunes']; + // @ts-expect-error -- the per-tool `tunes` collection went with the tune tool kind + tunes: BlockToolFacade['tunes']; + }; + + const probe: FacadeMembers | undefined = undefined; + + expect(probe).toBeUndefined(); + }); +}); diff --git a/packages/sdk/src/tools/facades/BaseToolFacade.ts b/packages/sdk/src/tools/facades/BaseToolFacade.ts index 136ad777..0751c62e 100644 --- a/packages/sdk/src/tools/facades/BaseToolFacade.ts +++ b/packages/sdk/src/tools/facades/BaseToolFacade.ts @@ -5,17 +5,16 @@ import { isFunction } from '@editorjs/helpers'; import { type BlockToolFacade } from './BlockToolFacade.js'; import { type InlineToolFacade } from './InlineToolFacade.js'; import { ToolType, BaseToolOptionKey } from '../../entities/index.js'; -import { type BlockTuneFacade } from './BlockTuneFacade.js'; import type { - BlockTool, BlockToolConstructor, InlineTool, InlineToolConstructor, BlockTuneConstructor, - ToolTypeToOptions, ToolStaticOptions, BlockToolOptions, InlineToolOptions, BlockTuneOptions, + BlockTool, BlockToolConstructor, InlineTool, InlineToolConstructor, + ToolTypeToOptions, ToolStaticOptions, BlockToolOptions, InlineToolOptions, ToolOptionsFactory } from '../../entities/index.js'; import type { EditorAPI } from '../../api'; import type { ToolPluginOptions, ToolPluginOptionsMap } from '../../index.js'; // eslint-disable-next-line @typescript-eslint/no-explicit-any -- need to allow any type here so extended interfaces pass -export type ToolConstructable = BlockToolConstructor | InlineToolConstructor | BlockTuneConstructor; +export type ToolConstructable = BlockToolConstructor | InlineToolConstructor; // Re-export canonical option-key enums so facades/consumers can import from one place export { BaseToolOptionKey } from '../../entities/BaseTool.js'; @@ -31,8 +30,6 @@ export enum UserToolOptions { Toolbox = 'toolbox', /** Inline tools enabled for blocks of this type. */ EnabledInlineTools = 'inlineToolbar', - /** Block tunes enabled for blocks of this type. */ - EnabledBlockTunes = 'tunes', /** Plugin-specific configuration. */ Config = 'config' } @@ -40,7 +37,7 @@ export enum UserToolOptions { export type ToolOptions = ToolStaticOptions; // Re-export per-tool option types so consumers can import them from here -export type { BlockToolOptions, InlineToolOptions, BlockTuneOptions }; +export type { BlockToolOptions, InlineToolOptions }; /** * BlockToolFacade constructor options inteface @@ -122,7 +119,7 @@ export abstract class BaseToolFacade { */ public inlineTools: ToolsCollection = new ToolsCollection(); - /** - * BlockTune collection for current Block Tool - */ - public tunes: ToolsCollection = new ToolsCollection(); - /** * Tool's constructable blueprint — narrowed to BlockToolConstructor */ @@ -224,13 +218,6 @@ export class BlockToolFacade extends BaseToolFacade { return this.useToolOptions[UserToolOptions.EnabledInlineTools] ?? false; } - /** - * Returns enabled tunes for Tool - */ - public get enabledBlockTunes(): boolean | string[] { - return this.useToolOptions[UserToolOptions.EnabledBlockTunes] ?? false; - } - // /** // * Returns Tool paste configuration // */ @@ -239,7 +226,7 @@ export class BlockToolFacade extends BaseToolFacade { // } /** - * Returns sanitize configuration for Block Tool including configs from related Inline Tools and Block Tunes + * Returns sanitize configuration for Block Tool including configs from related Inline Tools */ // @cacheable // public get sanitizeConfig(): SanitizerConfig { diff --git a/packages/sdk/src/tools/facades/BlockTuneFacade.ts b/packages/sdk/src/tools/facades/BlockTuneFacade.ts deleted file mode 100644 index ff92ecca..00000000 --- a/packages/sdk/src/tools/facades/BlockTuneFacade.ts +++ /dev/null @@ -1,36 +0,0 @@ -import { BaseToolFacade } from './BaseToolFacade.js'; -import type { BlockAPI } from 'editorjs-v2'; -import type { BlockTuneConstructor, BlockTune as IBlockTune, BlockTuneData } from '../../entities'; -import { ToolType } from '../../entities'; -// import type { BlockTuneData } from 'editorjs-v2'; - -/** - * Stub class for BlockTunes - * @todo Implement - */ -export class BlockTuneFacade extends BaseToolFacade { - /** - * Tool type — Tune - */ - public type: ToolType.Tune = ToolType.Tune; - - /** - * Tool's constructable blueprint - */ - protected declare constructable: BlockTuneConstructor; - - /** - * Constructs new BlockTune instance from constructable - * @param data - Tunes data - * @param _block - Block API object - */ - public create(data: BlockTuneData, _block: BlockAPI): IBlockTune { - return new this.constructable({ - // api: this.api, - config: this.config, - // block, - // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment - data, - }); - } -} diff --git a/packages/sdk/src/tools/facades/index.ts b/packages/sdk/src/tools/facades/index.ts index d7c388cc..8ad5034c 100644 --- a/packages/sdk/src/tools/facades/index.ts +++ b/packages/sdk/src/tools/facades/index.ts @@ -1,10 +1,8 @@ import type { BlockToolFacade } from './BlockToolFacade.js'; import type { InlineToolFacade } from './InlineToolFacade.js'; -import type { BlockTuneFacade } from './BlockTuneFacade.js'; -export type ToolFacadeClass = BlockToolFacade | InlineToolFacade | BlockTuneFacade; +export type ToolFacadeClass = BlockToolFacade | InlineToolFacade; export * from './BaseToolFacade.js'; export * from './BlockToolFacade.js'; -export * from './BlockTuneFacade.js'; export * from './InlineToolFacade.js';