@ecsplico/editor 2.1.1 → 3.0.0

package/dist/core/schema/index.js

@@ -4,30 +4,35 @@ import { NodeFlags, isBlockContainer, isChromeNode, isEditorBlock } from "./node
 import { OpaqueFence } from "./opaque-fence.js";
 import { StrikeX } from "./strike.js";
 import { HEX_COLOR } from "./hex-color.js";
+import { schemaExtensionsOf } from "./of-features.js";
 import StarterKit from "@tiptap/starter-kit";
 //#region src/core/schema/index.ts
 /**
-* Base Vue-free nodes and marks of every editor: StarterKit (history off: the surface enables it for standalone
-* editors, collaboration brings its own), StrikeX, the node-flags extension, `OpaqueFence` (Markdown fences of unknown
-* kinds, kept verbatim) and `BlockId`, which adds the `id` attribute to every block type (its ID-assigning plugins only
-* run in an editor). The server builds its schema from these as well (`getSchema(...)`).
+* The Vue-free nodes and marks of the content base (`core-content` feature): StarterKit (history off: the surface enables
+* it for standalone editors, collaboration brings its own), StrikeX, the node-flags extension and `OpaqueFence` (Markdown
+* fences of unknown kinds, kept verbatim). Without `BlockId`: `schemaExtensionsOf` appends it last.
 */
-const coreSchemaExtensions = () => [
+const coreContentSchemaExtensions = () => [
 	StarterKit.configure({
 		strike: false,
 		undoRedo: false
 	}),
 	StrikeX,
 	NodeFlags,
-	OpaqueFence,
-	BlockId
+	OpaqueFence
 ];
+/**
+* Base Vue-free nodes and marks of every editor: `coreContentSchemaExtensions()` and `BlockId`, which adds the `id`
+* attribute to every block type (its ID-assigning plugins only run in an editor). The server builds its schema from
+* these as well (`getSchema(...)`).
+*/
+const coreSchemaExtensions = () => [...coreContentSchemaExtensions(), BlockId];
 /** Content of a fresh, empty document. */
 const EMPTY_EDITOR_CONTENT = {
 	type: "doc",
 	content: [{ type: "paragraph" }]
 };
 //#endregion
-export { ABILITY, BLOCK_ID_ATTR, BLOCK_ID_TYPES, BlockId, EMPTY_EDITOR_CONTENT, HEX_COLOR, NodeFlags, OpaqueFence, ROOT_ABILITIES, StrikeX, TEXT_ABILITIES, TYPE_ABILITIES, assignBlockIds, blockIdOf, coreSchemaExtensions, findBlockById, isBlockContainer, isChromeNode, isEditorBlock, newBlockId, resolveAbilities };
+export { ABILITY, BLOCK_ID_ATTR, BLOCK_ID_TYPES, BlockId, EMPTY_EDITOR_CONTENT, HEX_COLOR, NodeFlags, OpaqueFence, ROOT_ABILITIES, StrikeX, TEXT_ABILITIES, TYPE_ABILITIES, assignBlockIds, blockIdOf, coreContentSchemaExtensions, coreSchemaExtensions, findBlockById, isBlockContainer, isChromeNode, isEditorBlock, newBlockId, resolveAbilities, schemaExtensionsOf };
 
 //# sourceMappingURL=index.js.map

package/dist/core/schema/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/core/schema/index.ts"],"sourcesContent":["import type { AnyExtension, JSONContent } from '@tiptap/core'\nimport StarterKit from '@tiptap/starter-kit'\nimport { BlockId } from './block-ids'\nimport { NodeFlags } from './node-flags'\nimport { OpaqueFence } from './opaque-fence'\nimport { StrikeX } from './strike'\n\nexport * from './abilities'\nexport * from './block-ids'\nexport * from './hex-color'\nexport * from './mark-flags'\nexport * from './node-flags'\nexport { OpaqueFence } from './opaque-fence'\nexport { StrikeX } from './strike'\n\n/**\n * Base Vue-free nodes and marks of every editor: StarterKit (history off: the surface enables it for standalone\n * editors, collaboration brings its own), StrikeX, the node-flags extension, `OpaqueFence` (Markdown fences of unknown\n * kinds, kept verbatim) and `BlockId`, which adds the `id` attribute to every block type (its ID-assigning plugins only\n * run in an editor). The server builds its schema from these as well (`getSchema(...)`).\n */\nexport const coreSchemaExtensions = (): AnyExtension[] => [StarterKit.configure({ strike: false, undoRedo: false }), StrikeX, NodeFlags, OpaqueFence, BlockId]\n\n/** Content of a fresh, empty document. */\nexport const EMPTY_EDITOR_CONTENT: JSONContent = { type: 'doc', content: [{ type: 'paragraph' }] }\n"],"mappings":";;;;;;;;;;;;;;AAqBA,MAAa,6BAA6C;CAAC,WAAW,UAAU;EAAE,QAAQ;EAAO,UAAU;CAAM,CAAC;CAAG;CAAS;CAAW;CAAa;AAAO;;AAG7J,MAAa,uBAAoC;CAAE,MAAM;CAAO,SAAS,CAAC,EAAE,MAAM,YAAY,CAAC;AAAE"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/core/schema/index.ts"],"sourcesContent":["import type { AnyExtension, JSONContent } from '@tiptap/core'\nimport StarterKit from '@tiptap/starter-kit'\nimport { BlockId } from './block-ids'\nimport { NodeFlags } from './node-flags'\nimport { OpaqueFence } from './opaque-fence'\nimport { StrikeX } from './strike'\n\nexport * from './abilities'\nexport * from './block-ids'\nexport * from './hex-color'\nexport * from './mark-flags'\nexport * from './node-flags'\nexport { OpaqueFence } from './opaque-fence'\nexport { StrikeX } from './strike'\nexport { schemaExtensionsOf } from './of-features'\n\n/**\n * The Vue-free nodes and marks of the content base (`core-content` feature): StarterKit (history off: the surface enables\n * it for standalone editors, collaboration brings its own), StrikeX, the node-flags extension and `OpaqueFence` (Markdown\n * fences of unknown kinds, kept verbatim). Without `BlockId`: `schemaExtensionsOf` appends it last.\n */\nexport const coreContentSchemaExtensions = (): AnyExtension[] => [StarterKit.configure({ strike: false, undoRedo: false }), StrikeX, NodeFlags, OpaqueFence]\n\n/**\n * Base Vue-free nodes and marks of every editor: `coreContentSchemaExtensions()` and `BlockId`, which adds the `id`\n * attribute to every block type (its ID-assigning plugins only run in an editor). The server builds its schema from\n * these as well (`getSchema(...)`).\n */\nexport const coreSchemaExtensions = (): AnyExtension[] => [...coreContentSchemaExtensions(), BlockId]\n\n/** Content of a fresh, empty document. */\nexport const EMPTY_EDITOR_CONTENT: JSONContent = { type: 'doc', content: [{ type: 'paragraph' }] }\n"],"mappings":";;;;;;;;;;;;;;AAqBA,MAAa,oCAAoD;CAAC,WAAW,UAAU;EAAE,QAAQ;EAAO,UAAU;CAAM,CAAC;CAAG;CAAS;CAAW;AAAW;;;;;;AAO3J,MAAa,6BAA6C,CAAC,GAAG,4BAA4B,GAAG,OAAO;;AAGpG,MAAa,uBAAoC;CAAE,MAAM;CAAO,SAAS,CAAC,EAAE,MAAM,YAAY,CAAC;AAAE"}

package/dist/core/schema/mark-flags.d.ts

@@ -1,3 +1,4 @@
+import { JSONContent } from "@tiptap/core";
 //#region src/core/schema/mark-flags.d.ts
 declare module '@tiptap/core' {
   interface MarkConfig<Options, Storage> {
@@ -7,6 +8,12 @@ declare module '@tiptap/core' {
      */
     markdownInvisible?: boolean;
   }
+  interface NodeConfig<Options, Storage> {
+    /**
+     * Rewrites the document JSON just before `editor.markdown.serialize` renders it (every node extension that declares it,
+     * in extension order), e.g. to drop attributes that must not reach the Markdown. Must not modify its input.
+     */
+    markdownPrepare?: (json: JSONContent, editor: Editor) => JSONContent;
+  }
 }
-export {};
 //# sourceMappingURL=mark-flags.d.ts.map

package/dist/core/schema/of-features.d.ts

@@ -0,0 +1,13 @@
+import { EditorFeature } from "../feature.js";
+import { AnyExtension } from "@tiptap/core";
+//#region src/core/schema/of-features.d.ts
+/**
+ * The server schema of a feature list: every feature's Vue-free `schemaExtensions` in feature order, then `BlockId`
+ * (it adds the `id` attribute to every block type, so it comes last). The content features carry the document model;
+ * an interaction feature may also declare `schemaExtensions` for marks that stored documents contain (`comments`), so
+ * the collection looks at the declaration, not at the dimension. Takes the schema-bearing slice of a feature, so
+ * server code can pass schema-only sources and never load a feature's UI.
+ */
+export declare const schemaExtensionsOf: (features: readonly Pick<EditorFeature, "schemaExtensions">[]) => AnyExtension[];
+//#endregion
+//# sourceMappingURL=of-features.d.ts.map

package/dist/core/schema/of-features.js

@@ -0,0 +1,14 @@
+import { BlockId } from "./block-ids.js";
+//#region src/core/schema/of-features.ts
+/**
+* The server schema of a feature list: every feature's Vue-free `schemaExtensions` in feature order, then `BlockId`
+* (it adds the `id` attribute to every block type, so it comes last). The content features carry the document model;
+* an interaction feature may also declare `schemaExtensions` for marks that stored documents contain (`comments`), so
+* the collection looks at the declaration, not at the dimension. Takes the schema-bearing slice of a feature, so
+* server code can pass schema-only sources and never load a feature's UI.
+*/
+const schemaExtensionsOf = (features) => [...features.flatMap((feature) => feature.schemaExtensions?.() ?? []), BlockId];
+//#endregion
+export { schemaExtensionsOf };
+
+//# sourceMappingURL=of-features.js.map

package/dist/core/schema/of-features.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"of-features.js","names":[],"sources":["../../../src/core/schema/of-features.ts"],"sourcesContent":["import type { AnyExtension } from '@tiptap/core'\nimport type { EditorFeature } from '../feature'\nimport { BlockId } from './block-ids'\n\n/**\n * The server schema of a feature list: every feature's Vue-free `schemaExtensions` in feature order, then `BlockId`\n * (it adds the `id` attribute to every block type, so it comes last). The content features carry the document model;\n * an interaction feature may also declare `schemaExtensions` for marks that stored documents contain (`comments`), so\n * the collection looks at the declaration, not at the dimension. Takes the schema-bearing slice of a feature, so\n * server code can pass schema-only sources and never load a feature's UI.\n */\nexport const schemaExtensionsOf = (features: readonly Pick<EditorFeature, 'schemaExtensions'>[]): AnyExtension[] =>\n  [...features.flatMap(feature => feature.schemaExtensions?.() ?? []), BlockId]\n"],"mappings":";;;;;;;;;AAWA,MAAa,sBAAsB,aACjC,CAAC,GAAG,SAAS,SAAQ,YAAW,QAAQ,mBAAmB,KAAK,CAAC,CAAC,GAAG,OAAO"}

package/dist/core/slash.d.ts

@@ -1,10 +1,11 @@
-import { SlashCommandItem } from "./extension-points.js";
+import { CommandDef } from "./command-types.js";
+import "./commands.js";
 import { Extension } from "@tiptap/core";
 import { PluginKey } from "@tiptap/pm/state";
 //#region src/core/slash.d.ts
 export interface SlashCommandOptions {
-  /** The final `/` menu: features' commands after the host's `slashCommands` transformer. */
-  items: SlashCommandItem[];
+  /** The final command list (features' commands after the host's `commands` transformer); the ones with a `slash` placement make the menu. */
+  commands: CommandDef[];
   /** Popup text while no command matches the typed query (`ctx.t('slash.empty')`). */
   emptyText: string;
   /** Popup text while the commands are pending (`ctx.t('common.loading')`). */
@@ -14,9 +15,10 @@ export interface SlashCommandOptions {
 export declare const SlashCommandPluginKey: PluginKey<any>;
 /**
  * `/` menu on an empty line: typing `/` as the only content of a textblock (outside code) opens the shared suggestion
- * popup with the commands allowed at the caret (`SlashCommandItem.ability`) whose id or label starts with the typed
- * query; picking one deletes `/query` and runs it. A query no allowed command matches (`/foo`) shows nothing and stays
- * plain text. The commands come from features and the host; the core feature has none of its own.
+ * popup with the commands that have a `slash` placement and are visible and enabled at the caret (`commandState`: ability,
+ * structural check, schema and accepted-children fit) whose slash id or label starts with the typed query; picking one
+ * deletes `/query` and runs it. A query no such command matches (`/foo`) shows nothing and stays plain text. The commands
+ * come from features and the host.
  * Client-only: not part of the Vue-free schema.
  */
 export declare const SlashCommand: Extension<SlashCommandOptions, any>;

package/dist/core/slash.js

@@ -1,33 +1,41 @@
-import { abilitiesAt } from "./abilities.js";
+import { commandState } from "./commands.js";
 import { createSuggestionRender } from "./suggestion-popup.js";
 import { Extension } from "@tiptap/core";
 import { PluginKey } from "@tiptap/pm/state";
 import { Suggestion } from "@tiptap/suggestion";
 //#region src/core/slash.ts
-function matching(items, query, abilities) {
+const slashIdOf = (cmd) => cmd.slash.id ?? cmd.id;
+/** The slash commands that are visible and enabled at the caret (`$at` when the editor state lags, see `commandState`) and whose slash id or label starts with `query`. */
+function matching(editor, commands, query, $at) {
 	const q = query.toLowerCase();
-	return items.filter((item) => (!item.ability || abilities.has(item.ability)) && (item.id.startsWith(q) || item.label.toLowerCase().startsWith(q)));
+	return commands.filter((cmd) => {
+		if (!cmd.slash || !("run" in cmd)) return false;
+		if (!(slashIdOf(cmd).startsWith(q) || cmd.label.toLowerCase().startsWith(q))) return false;
+		const state = commandState(editor, cmd, "caret", $at);
+		return state.visible && state.enabled;
+	});
 }
 /** Own key, so the `/` popup runs next to the `@` and `#` popups. */
 const SlashCommandPluginKey = new PluginKey("slashCommand");
 /**
 * `/` menu on an empty line: typing `/` as the only content of a textblock (outside code) opens the shared suggestion
-* popup with the commands allowed at the caret (`SlashCommandItem.ability`) whose id or label starts with the typed
-* query; picking one deletes `/query` and runs it. A query no allowed command matches (`/foo`) shows nothing and stays
-* plain text. The commands come from features and the host; the core feature has none of its own.
+* popup with the commands that have a `slash` placement and are visible and enabled at the caret (`commandState`: ability,
+* structural check, schema and accepted-children fit) whose slash id or label starts with the typed query; picking one
+* deletes `/query` and runs it. A query no such command matches (`/foo`) shows nothing and stays plain text. The commands
+* come from features and the host.
 * Client-only: not part of the Vue-free schema.
 */
 const SlashCommand = Extension.create({
 	name: "slashCommand",
 	addOptions() {
 		return {
-			items: [],
+			commands: [],
 			emptyText: "",
 			loadingText: ""
 		};
 	},
 	addProseMirrorPlugins() {
-		const { items, emptyText, loadingText } = this.options;
+		const { commands, emptyText, loadingText } = this.options;
 		return [Suggestion({
 			pluginKey: SlashCommandPluginKey,
 			editor: this.editor,
@@ -35,18 +43,18 @@ const SlashCommand = Extension.create({
 			startOfLine: true,
 			shouldShow: ({ editor, range, query, transaction }) => {
 				const $from = transaction.doc.resolve(range.from);
-				return $from.parentOffset === 0 && range.to === $from.end() && !$from.parent.type.spec.code && matching(items, query, abilitiesAt(editor, $from)).length > 0;
+				return $from.parentOffset === 0 && range.to === $from.end() && !$from.parent.type.spec.code && matching(editor, commands, query, $from).length > 0;
 			},
-			items: ({ editor, query }) => matching(items, query, abilitiesAt(editor, editor.state.selection.$from)),
-			command: ({ editor, range, props: item }) => {
+			items: ({ editor, query }) => matching(editor, commands, query),
+			command: ({ editor, range, props: cmd }) => {
 				editor.chain().focus().deleteRange(range).run();
-				item.run(editor);
+				cmd.run(editor);
 			},
 			render: createSuggestionRender({
-				display: (item) => ({
-					label: item.label,
-					description: `/${item.id}`,
-					icon: item.icon
+				display: (cmd) => ({
+					label: cmd.label,
+					description: `/${slashIdOf(cmd)}`,
+					icon: cmd.icon
 				}),
 				emptyText,
 				loadingText

package/dist/core/slash.js.map

@@ -1 +1 @@
-{"version":3,"file":"slash.js","names":[],"sources":["../../src/core/slash.ts"],"sourcesContent":["import { Extension } from '@tiptap/core'\nimport { PluginKey } from '@tiptap/pm/state'\nimport { Suggestion } from '@tiptap/suggestion'\nimport { abilitiesAt } from './abilities'\nimport type { SlashCommandItem } from './extension-points'\nimport type { Ability } from './schema/abilities'\nimport { createSuggestionRender } from './suggestion-popup'\n\nexport interface SlashCommandOptions {\n  /** The final `/` menu: features' commands after the host's `slashCommands` transformer. */\n  items: SlashCommandItem[]\n  /** Popup text while no command matches the typed query (`ctx.t('slash.empty')`). */\n  emptyText: string\n  /** Popup text while the commands are pending (`ctx.t('common.loading')`). */\n  loadingText: string\n}\n\nfunction matching(items: SlashCommandItem[], query: string, abilities: ReadonlySet<Ability>): SlashCommandItem[] {\n  const q = query.toLowerCase()\n  return items.filter(item => (!item.ability || abilities.has(item.ability))\n    && (item.id.startsWith(q) || item.label.toLowerCase().startsWith(q)))\n}\n\n/** Own key, so the `/` popup runs next to the `@` and `#` popups. */\nexport const SlashCommandPluginKey = new PluginKey('slashCommand')\n\n/**\n * `/` menu on an empty line: typing `/` as the only content of a textblock (outside code) opens the shared suggestion\n * popup with the commands allowed at the caret (`SlashCommandItem.ability`) whose id or label starts with the typed\n * query; picking one deletes `/query` and runs it. A query no allowed command matches (`/foo`) shows nothing and stays\n * plain text. The commands come from features and the host; the core feature has none of its own.\n * Client-only: not part of the Vue-free schema.\n */\nexport const SlashCommand = Extension.create<SlashCommandOptions>({\n  name: 'slashCommand',\n\n  addOptions() {\n    return { items: [], emptyText: '', loadingText: '' }\n  },\n\n  addProseMirrorPlugins() {\n    const { items, emptyText, loadingText } = this.options\n    return [Suggestion<SlashCommandItem>({\n      pluginKey: SlashCommandPluginKey,\n      editor: this.editor,\n      char: '/',\n      startOfLine: true,\n      // `shouldShow` runs inside the plugin's `apply`, before `editor.state` is the new state: resolve in the new doc.\n      shouldShow: ({ editor, range, query, transaction }) => {\n        const $from = transaction.doc.resolve(range.from)\n        return $from.parentOffset === 0 && range.to === $from.end() && !$from.parent.type.spec.code\n          && matching(items, query, abilitiesAt(editor, $from)).length > 0\n      },\n      items: ({ editor, query }) => matching(items, query, abilitiesAt(editor, editor.state.selection.$from)),\n      command: ({ editor, range, props: item }) => {\n        editor.chain().focus().deleteRange(range).run()\n        item.run(editor)\n      },\n      render: createSuggestionRender<SlashCommandItem>({\n        display: item => ({ label: item.label, description: `/${item.id}`, icon: item.icon }),\n        emptyText,\n        loadingText,\n      }),\n    })]\n  },\n})\n"],"mappings":";;;;;;AAiBA,SAAS,SAAS,OAA2B,OAAe,WAAqD;CAC/G,MAAM,IAAI,MAAM,YAAY;CAC5B,OAAO,MAAM,QAAO,UAAS,CAAC,KAAK,WAAW,UAAU,IAAI,KAAK,OAAO,OAClE,KAAK,GAAG,WAAW,CAAC,KAAK,KAAK,MAAM,YAAY,CAAC,CAAC,WAAW,CAAC,EAAE;AACxE;;AAGA,MAAa,wBAAwB,IAAI,UAAU,cAAc;;;;;;;;AASjE,MAAa,eAAe,UAAU,OAA4B;CAChE,MAAM;CAEN,aAAa;EACX,OAAO;GAAE,OAAO,CAAC;GAAG,WAAW;GAAI,aAAa;EAAG;CACrD;CAEA,wBAAwB;EACtB,MAAM,EAAE,OAAO,WAAW,gBAAgB,KAAK;EAC/C,OAAO,CAAC,WAA6B;GACnC,WAAW;GACX,QAAQ,KAAK;GACb,MAAM;GACN,aAAa;GAEb,aAAa,EAAE,QAAQ,OAAO,OAAO,kBAAkB;IACrD,MAAM,QAAQ,YAAY,IAAI,QAAQ,MAAM,IAAI;IAChD,OAAO,MAAM,iBAAiB,KAAK,MAAM,OAAO,MAAM,IAAI,KAAK,CAAC,MAAM,OAAO,KAAK,KAAK,QAClF,SAAS,OAAO,OAAO,YAAY,QAAQ,KAAK,CAAC,CAAC,CAAC,SAAS;GACnE;GACA,QAAQ,EAAE,QAAQ,YAAY,SAAS,OAAO,OAAO,YAAY,QAAQ,OAAO,MAAM,UAAU,KAAK,CAAC;GACtG,UAAU,EAAE,QAAQ,OAAO,OAAO,WAAW;IAC3C,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,IAAI;IAC9C,KAAK,IAAI,MAAM;GACjB;GACA,QAAQ,uBAAyC;IAC/C,UAAS,UAAS;KAAE,OAAO,KAAK;KAAO,aAAa,IAAI,KAAK;KAAM,MAAM,KAAK;IAAK;IACnF;IACA;GACF,CAAC;EACH,CAAC,CAAC;CACJ;AACF,CAAC"}
+{"version":3,"file":"slash.js","names":[],"sources":["../../src/core/slash.ts"],"sourcesContent":["import { type Editor, Extension } from '@tiptap/core'\nimport type { ResolvedPos } from '@tiptap/pm/model'\nimport { PluginKey } from '@tiptap/pm/state'\nimport { Suggestion } from '@tiptap/suggestion'\nimport { type CommandDef, commandState } from './commands'\nimport { createSuggestionRender } from './suggestion-popup'\n\n/** A command with a `/` placement: only `run` commands have one. */\ntype SlashCommandDef = CommandDef & { run: (editor: Editor) => void, slash: { id?: string } }\n\nexport interface SlashCommandOptions {\n  /** The final command list (features' commands after the host's `commands` transformer); the ones with a `slash` placement make the menu. */\n  commands: CommandDef[]\n  /** Popup text while no command matches the typed query (`ctx.t('slash.empty')`). */\n  emptyText: string\n  /** Popup text while the commands are pending (`ctx.t('common.loading')`). */\n  loadingText: string\n}\n\nconst slashIdOf = (cmd: SlashCommandDef) => cmd.slash.id ?? cmd.id\n\n/** The slash commands that are visible and enabled at the caret (`$at` when the editor state lags, see `commandState`) and whose slash id or label starts with `query`. */\nfunction matching(editor: Editor, commands: CommandDef[], query: string, $at?: ResolvedPos): SlashCommandDef[] {\n  const q = query.toLowerCase()\n  return commands.filter((cmd): cmd is SlashCommandDef => {\n    if (!cmd.slash || !('run' in cmd)) return false\n    if (!(slashIdOf(cmd as SlashCommandDef).startsWith(q) || cmd.label.toLowerCase().startsWith(q))) return false\n    const state = commandState(editor, cmd, 'caret', $at)\n    return state.visible && state.enabled\n  })\n}\n\n/** Own key, so the `/` popup runs next to the `@` and `#` popups. */\nexport const SlashCommandPluginKey = new PluginKey('slashCommand')\n\n/**\n * `/` menu on an empty line: typing `/` as the only content of a textblock (outside code) opens the shared suggestion\n * popup with the commands that have a `slash` placement and are visible and enabled at the caret (`commandState`: ability,\n * structural check, schema and accepted-children fit) whose slash id or label starts with the typed query; picking one\n * deletes `/query` and runs it. A query no such command matches (`/foo`) shows nothing and stays plain text. The commands\n * come from features and the host.\n * Client-only: not part of the Vue-free schema.\n */\nexport const SlashCommand = Extension.create<SlashCommandOptions>({\n  name: 'slashCommand',\n\n  addOptions() {\n    return { commands: [], emptyText: '', loadingText: '' }\n  },\n\n  addProseMirrorPlugins() {\n    const { commands, emptyText, loadingText } = this.options\n    return [Suggestion<SlashCommandDef>({\n      pluginKey: SlashCommandPluginKey,\n      editor: this.editor,\n      char: '/',\n      startOfLine: true,\n      // `shouldShow` runs inside the plugin's `apply`, before `editor.state` is the new state: resolve in the new doc.\n      shouldShow: ({ editor, range, query, transaction }) => {\n        const $from = transaction.doc.resolve(range.from)\n        return $from.parentOffset === 0 && range.to === $from.end() && !$from.parent.type.spec.code\n          && matching(editor, commands, query, $from).length > 0\n      },\n      items: ({ editor, query }) => matching(editor, commands, query),\n      command: ({ editor, range, props: cmd }) => {\n        editor.chain().focus().deleteRange(range).run()\n        cmd.run(editor)\n      },\n      render: createSuggestionRender<SlashCommandDef>({\n        display: cmd => ({ label: cmd.label, description: `/${slashIdOf(cmd)}`, icon: cmd.icon }),\n        emptyText,\n        loadingText,\n      }),\n    })]\n  },\n})\n"],"mappings":";;;;;;AAmBA,MAAM,aAAa,QAAyB,IAAI,MAAM,MAAM,IAAI;;AAGhE,SAAS,SAAS,QAAgB,UAAwB,OAAe,KAAsC;CAC7G,MAAM,IAAI,MAAM,YAAY;CAC5B,OAAO,SAAS,QAAQ,QAAgC;EACtD,IAAI,CAAC,IAAI,SAAS,EAAE,SAAS,MAAM,OAAO;EAC1C,IAAI,EAAE,UAAU,GAAsB,CAAC,CAAC,WAAW,CAAC,KAAK,IAAI,MAAM,YAAY,CAAC,CAAC,WAAW,CAAC,IAAI,OAAO;EACxG,MAAM,QAAQ,aAAa,QAAQ,KAAK,SAAS,GAAG;EACpD,OAAO,MAAM,WAAW,MAAM;CAChC,CAAC;AACH;;AAGA,MAAa,wBAAwB,IAAI,UAAU,cAAc;;;;;;;;;AAUjE,MAAa,eAAe,UAAU,OAA4B;CAChE,MAAM;CAEN,aAAa;EACX,OAAO;GAAE,UAAU,CAAC;GAAG,WAAW;GAAI,aAAa;EAAG;CACxD;CAEA,wBAAwB;EACtB,MAAM,EAAE,UAAU,WAAW,gBAAgB,KAAK;EAClD,OAAO,CAAC,WAA4B;GAClC,WAAW;GACX,QAAQ,KAAK;GACb,MAAM;GACN,aAAa;GAEb,aAAa,EAAE,QAAQ,OAAO,OAAO,kBAAkB;IACrD,MAAM,QAAQ,YAAY,IAAI,QAAQ,MAAM,IAAI;IAChD,OAAO,MAAM,iBAAiB,KAAK,MAAM,OAAO,MAAM,IAAI,KAAK,CAAC,MAAM,OAAO,KAAK,KAAK,QAClF,SAAS,QAAQ,UAAU,OAAO,KAAK,CAAC,CAAC,SAAS;GACzD;GACA,QAAQ,EAAE,QAAQ,YAAY,SAAS,QAAQ,UAAU,KAAK;GAC9D,UAAU,EAAE,QAAQ,OAAO,OAAO,UAAU;IAC1C,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,IAAI;IAC9C,IAAI,IAAI,MAAM;GAChB;GACA,QAAQ,uBAAwC;IAC9C,UAAS,SAAQ;KAAE,OAAO,IAAI;KAAO,aAAa,IAAI,UAAU,GAAG;KAAK,MAAM,IAAI;IAAK;IACvF;IACA;GACF,CAAC;EACH,CAAC,CAAC;CACJ;AACF,CAAC"}

package/dist/core/surface-session.js

@@ -1,10 +1,12 @@
+import { ROOT_ABILITIES } from "./schema/abilities.js";
 import { presetExtension } from "./pipeline.js";
-import { createMetadataRegistry } from "./metadata.js";
-import { SuggestionPopup } from "./suggestion-popup.js";
 import { contributions } from "./define-editor.js";
+import { createMetadataRegistry } from "./metadata.js";
 import { registerEditor } from "./editor-ui.js";
-import { blockActionsOf, createFeatureContext } from "./feature-context.js";
+import { toolbarOf } from "./commands.js";
 import { EMPTY_EDITOR_CONTENT } from "./schema/index.js";
+import { SuggestionPopup } from "./suggestion-popup.js";
+import { blockActionsOf, createFeatureContext } from "./feature-context.js";
 import { getSchema } from "@tiptap/core";
 //#region src/core/surface-session.ts
 /**
@@ -17,6 +19,10 @@ import { getSchema } from "@tiptap/core";
 function createSurfaceSession(options) {
 	const { app, preset, ui, collaboration, getEditor } = options;
 	if (collaboration && !preset.features.some((feature) => feature.id === "collab")) throw new Error("@ecsplico/editor: `collaboration` needs a preset with the collaboration feature");
+	for (const feature of preset.features) for (const capability of feature.backend ?? []) {
+		if (capability === "collaboration") continue;
+		if (!app.backend[capability]) throw new Error(`@ecsplico/editor: feature "${feature.id}" needs backend capability "${capability}", which "${app.backend.name}" lacks`);
+	}
 	const registry = createMetadataRegistry({ onCreate: (list, item) => options.onMetadataCreate?.(list, item) });
 	registry.replace({ ...options.metadata });
 	const ctx = createFeatureContext({
@@ -27,11 +33,13 @@ function createSurfaceSession(options) {
 		notify: options.notify,
 		getEditor,
 		...options.documentId !== void 0 && { documentId: options.documentId },
-		...options.upload && { upload: options.upload },
 		...collaboration && { collaboration },
 		...options.abilities && { abilities: options.abilities },
-		...options.slashCommands && { slashCommands: options.slashCommands }
+		...options.commands && { commands: options.commands }
 	});
+	toolbarOf(preset, ctx);
+	const root = new Set(options.abilities?.root ?? ROOT_ABILITIES);
+	for (const cmd of ctx.commands()) if (cmd.ability && !root.has(cmd.ability)) console.warn(`@ecsplico/editor: command "${cmd.id}" needs ability "${cmd.ability}", which neither ROOT_ABILITIES nor \`abilities.root\` grants; it stays unavailable at document root`);
 	const extensions = [
 		presetExtension(preset),
 		SuggestionPopup.configure({ renderer: options.suggestionRenderer }),

package/dist/core/surface-session.js.map

@@ -1 +1 @@
-{"version":3,"file":"surface-session.js","names":[],"sources":["../../src/core/surface-session.ts"],"sourcesContent":["import { type AnyExtension, type Editor, type EditorOptions, getSchema, type JSONContent } from '@tiptap/core'\nimport type { EditorContext } from './context'\nimport { contributions } from './define-editor'\nimport { type EditorUi, registerEditor } from './editor-ui'\nimport type { AbilitiesOptions, BlockAction, SlashCommandItem } from './extension-points'\nimport type { CollaborationSession, EditorPreset, UploadFn } from './feature'\nimport { blockActionsOf, createFeatureContext } from './feature-context'\nimport { createMetadataRegistry } from './metadata'\nimport type { EditorMetadata, MetadataItem } from './metadata-types'\nimport type { Notifier } from './notify'\nimport { presetExtension } from './pipeline'\nimport { EMPTY_EDITOR_CONTENT } from './schema'\nimport { SuggestionPopup, type SuggestionPopupRenderer } from './suggestion-popup'\n\n/**\n * What a surface hands its session. The framework layer owns everything that lives in its reactivity: the chrome\n * (`ui`), the notice renderer, the suggestion popup renderer and the editor instance (`getEditor`).\n * `preset`, `collaboration`, `documentId`, `upload`, `abilities`, `extensions`, `blockActions`, `slashCommands`, `value` and\n * `editable` are read once, when the session is created; later changes reach it through `setValue`, `setEditable` and\n * `setMetadata`.\n */\nexport interface SurfaceSessionOptions<C = unknown> {\n  app: EditorContext\n  /** The features the editor is made of. With `collaboration` it must contain the collaboration feature (else creating the session throws). */\n  preset: EditorPreset<C>\n  /** The chrome the features reach through `FeatureContext.ui`; registered for the editor by `register`. */\n  ui: EditorUi\n  /** The surface's notice renderer (`FeatureContext.notify`). */\n  notify: Notifier\n  /** The framework's popup for `@` / `#` / `/` suggestions. */\n  suggestionRenderer: SuggestionPopupRenderer\n  /** The mounted editor, `undefined` until the framework layer created it; used by `FeatureContext.getEditor`, `setValue` and `setEditable`. */\n  getEditor: () => Editor | undefined\n  /** Collaborative mode: the Y.Doc is the document, so there is no `value` and no `onChange`. */\n  collaboration?: CollaborationSession | undefined\n  /** Standalone initial document (TipTap JSON, unproxied); absent = an empty document. */\n  value?: JSONContent | undefined\n  /** Default `true`. */\n  editable?: boolean | undefined\n  /** The host's lists; later ones go through `setMetadata`. */\n  metadata?: EditorMetadata | undefined\n  documentId?: string | undefined\n  upload?: UploadFn | undefined\n  abilities?: Partial<AbilitiesOptions> | undefined\n  slashCommands?: ((defaults: SlashCommandItem[]) => SlashCommandItem[]) | undefined\n  /** Added after the features' extensions. */\n  extensions?: readonly AnyExtension[] | undefined\n  /** Added after the features' block actions. */\n  blockActions?: readonly BlockAction[] | undefined\n  /** Standalone: the document after every edit (the JSON the session remembers as its own, see `setValue`). */\n  onChange?: ((content: JSONContent) => void) | undefined\n  /** A new item was created in a metadata list. */\n  onMetadataCreate?: ((list: string, item: MetadataItem) => void) | undefined\n  /** A document handed in (initially or through `setValue`) does not fit the schema. */\n  onContentError?: ((error: Error) => void) | undefined\n  /** A mounted editor was registered for the first time (see `register`). */\n  onReady?: ((editor: Editor) => void) | undefined\n}\n\n/**\n * Everything of an `EditorSurface` that does not depend on the UI framework: the preset's extensions and context,\n * the document's validation and echo handling, the features' `setup` lifecycle and the registration of the editor's\n * chrome. The framework layer creates the session once (state of the component instance), mounts a TipTap editor from\n * `editorOptions`, and forwards prop changes and lifecycle moments to it.\n */\nexport interface SurfaceSession<C = unknown> {\n  /**\n   * Options for the TipTap editor. Standalone mode (no `collaboration`) carries the initial document (`content`, already\n   * migrated; an empty document when the given one was rejected) and the `onUpdate` that feeds `onChange`. The framework\n   * layer may add its own options (rendering flags) but must not replace these.\n   */\n  readonly editorOptions: Partial<EditorOptions> & { extensions: AnyExtension[] }\n  /** The features' overlay components, in feature order; the framework layer renders them beside the editor with `{ editor }`. */\n  readonly overlays: readonly C[]\n  /**\n   * Starts the features' `setup` contributions, then reports a rejected initial document through `onContentError` (once\n   * per session, not per activation). A no-op while active. Pair every activation with `deactivate`: React StrictMode\n   * mounts, cleans up and mounts again, which must leave exactly one active setup.\n   */\n  activate: () => void\n  /** Runs the teardowns of the active `setup` contributions, in the order they were started; a no-op while inactive. */\n  deactivate: () => void\n  /**\n   * Registers the chrome of `editor` (the raw instance, see `registerEditor`) and announces it through `onReady` the\n   * first time this editor is registered, so a host toolbar that receives it finds the chrome. Returns the unregister\n   * function (idempotent). Call it again after the framework layer replaced the editor instance.\n   */\n  register: (editor: Editor) => () => void\n  /**\n   * The host's document changed (standalone only; ignored with `collaboration`). Not an edit: no `onChange`, no update\n   * event. Ignored when `value` is the very object `onChange` last received (the host handing the surface's own JSON\n   * back), is absent, or was already given; otherwise it is migrated and checked against the schema and applied, or\n   * reported through `onContentError` with the current document kept. A missing or destroyed editor ignores it.\n   */\n  setValue: (value: JSONContent | undefined) => void\n  /**\n   * Switches the editor's editable state; ignored when it equals the last given one, and while no (or a destroyed)\n   * editor exists. TipTap's `setEditable(…, false)` changes the flag without any event, so it is followed by an empty\n   * `addToHistory: false` transaction: components that follow `isEditable` on `transaction` (block UI, the composite\n   * inspector) notice. It has no steps, so nothing syncs and the history is untouched.\n   */\n  setEditable: (editable: boolean) => void\n  /** Replaces the host's metadata lists; ignored when `metadata` is the object that was last given. */\n  setMetadata: (metadata: EditorMetadata | undefined) => void\n}\n\n/**\n * Builds the session of one mounted surface: metadata registry, feature context, the extension list, the block actions\n * and the initial document. Throws when `collaboration` is given and the preset has no collaboration feature. Extension\n * order is fixed: the preset extension, the suggestion popup, the features' extensions in feature order, the host's.\n * The document is checked as `preset.pipeline.migrateContent` followed by the schema's `check()`; a failure is an error\n * value, never a throw.\n */\nexport function createSurfaceSession<C = unknown>(options: SurfaceSessionOptions<C>): SurfaceSession<C> {\n  const { app, preset, ui, collaboration, getEditor } = options\n  if (collaboration && !preset.features.some(feature => feature.id === 'collab')) {\n    throw new Error('@ecsplico/editor: `collaboration` needs a preset with the collaboration feature')\n  }\n\n  const registry = createMetadataRegistry({ onCreate: (list, item) => options.onMetadataCreate?.(list, item) })\n  registry.replace({ ...options.metadata })\n\n  const ctx = createFeatureContext({\n    app,\n    preset,\n    ui,\n    metadata: registry,\n    notify: options.notify,\n    getEditor,\n    ...(options.documentId !== undefined && { documentId: options.documentId }),\n    ...(options.upload && { upload: options.upload }),\n    ...(collaboration && { collaboration }),\n    ...(options.abilities && { abilities: options.abilities }),\n    ...(options.slashCommands && { slashCommands: options.slashCommands }),\n  })\n\n  const extensions: AnyExtension[] = [\n    presetExtension(preset),\n    SuggestionPopup.configure({ renderer: options.suggestionRenderer }),\n    ...contributions(preset, 'extensions').flatMap(factory => factory(ctx)),\n    ...(options.extensions ?? []),\n  ]\n  const schema = getSchema(extensions)\n  const overlays = preset.features.flatMap(feature => [...(feature.overlays ?? [])])\n  const blockActions = blockActionsOf(preset, ctx, options.blockActions)\n\n  const validated = (json: JSONContent): { json: JSONContent } | { error: Error } => {\n    try {\n      const migrated = preset.pipeline.migrateContent(json)\n      schema.nodeFromJSON(migrated).check()\n      return { json: migrated }\n    }\n    catch (error) {\n      return { error: error instanceof Error ? error : new Error(String(error)) }\n    }\n  }\n\n  // Standalone: the JSON last sent through `onChange`; the host handing it back is not an external change.\n  let lastEmitted: JSONContent | undefined\n  let pendingContentError: Error | undefined\n  const editorOptions: SurfaceSession<C>['editorOptions'] = {\n    extensions,\n    editable: options.editable ?? true,\n    editorProps: { attributes: { class: 'tiptap' } },\n  }\n  if (!collaboration) {\n    const initial = options.value ? validated(options.value) : { json: EMPTY_EDITOR_CONTENT }\n    if ('error' in initial) pendingContentError = initial.error\n    editorOptions.content = 'json' in initial ? initial.json : EMPTY_EDITOR_CONTENT\n    editorOptions.onUpdate = ({ editor }) => {\n      lastEmitted = editor.getJSON()\n      options.onChange?.(lastEmitted)\n    }\n  }\n\n  // What the setters below already applied; they only react to a change.\n  let appliedValue = options.value\n  let appliedEditable = options.editable ?? true\n  let appliedMetadata = options.metadata\n  // Teardowns of the `setup` contributions that are currently active; undefined while inactive.\n  let teardowns: (() => void)[] | undefined\n  let announced: Editor | undefined\n\n  return {\n    editorOptions,\n    overlays,\n    activate() {\n      if (teardowns) return\n      const active: (() => void)[] = []\n      teardowns = active\n      for (const run of contributions(preset, 'setup')) {\n        const teardown = run(ctx)\n        if (teardown) active.push(teardown)\n      }\n      if (pendingContentError) {\n        const error = pendingContentError\n        pendingContentError = undefined\n        options.onContentError?.(error)\n      }\n    },\n    deactivate() {\n      const active = teardowns\n      teardowns = undefined\n      for (const teardown of active ?? []) teardown()\n    },\n    register(editor) {\n      const unregister = registerEditor(editor, { ui, preset, ctx, blockActions })\n      if (announced !== editor) {\n        announced = editor\n        options.onReady?.(editor)\n      }\n      return unregister\n    },\n    setValue(value) {\n      if (value === appliedValue) return\n      appliedValue = value\n      const editor = getEditor()\n      if (collaboration || !value || !editor || editor.isDestroyed || value === lastEmitted) return\n      const checked = validated(value)\n      if ('error' in checked) {\n        options.onContentError?.(checked.error)\n        return\n      }\n      editor.commands.setContent(checked.json, { emitUpdate: false })\n    },\n    setEditable(editable) {\n      if (editable === appliedEditable) return\n      appliedEditable = editable\n      const editor = getEditor()\n      if (!editor || editor.isDestroyed) return\n      editor.setEditable(editable, false)\n      editor.view.dispatch(editor.state.tr.setMeta('addToHistory', false))\n    },\n    setMetadata(metadata) {\n      if (metadata === appliedMetadata) return\n      appliedMetadata = metadata\n      registry.replace({ ...metadata })\n    },\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"surface-session.js","names":[],"sources":["../../src/core/surface-session.ts"],"sourcesContent":["import { type AnyExtension, type Editor, type EditorOptions, getSchema, type JSONContent } from '@tiptap/core'\nimport type { EditorContext } from './context'\nimport { contributions } from './define-editor'\nimport { type EditorUi, registerEditor } from './editor-ui'\nimport { type CommandDef, toolbarOf } from './commands'\nimport type { AbilitiesOptions, BlockAction } from './extension-points'\nimport type { CollaborationSession, EditorPreset } from './feature'\nimport { blockActionsOf, createFeatureContext } from './feature-context'\nimport { createMetadataRegistry } from './metadata'\nimport type { EditorMetadata, MetadataItem } from './metadata-types'\nimport type { Notifier } from './notify'\nimport { presetExtension } from './pipeline'\nimport { EMPTY_EDITOR_CONTENT } from './schema'\nimport { ROOT_ABILITIES } from './schema/abilities'\nimport { SuggestionPopup, type SuggestionPopupRenderer } from './suggestion-popup'\n\n/**\n * What a surface hands its session. The framework layer owns everything that lives in its reactivity: the chrome\n * (`ui`), the notice renderer, the suggestion popup renderer and the editor instance (`getEditor`).\n * `preset`, `collaboration`, `documentId`, `abilities`, `extensions`, `blockActions`, `commands`, `value` and\n * `editable` are read once, when the session is created; later changes reach it through `setValue`, `setEditable` and\n * `setMetadata`.\n */\nexport interface SurfaceSessionOptions<C = unknown> {\n  app: EditorContext\n  /** The features the editor is made of. With `collaboration` it must contain the collaboration feature (else creating the session throws). */\n  preset: EditorPreset<C>\n  /** The chrome the features reach through `FeatureContext.ui`; registered for the editor by `register`. */\n  ui: EditorUi\n  /** The surface's notice renderer (`FeatureContext.notify`). */\n  notify: Notifier\n  /** The framework's popup for `@` / `#` / `/` suggestions. */\n  suggestionRenderer: SuggestionPopupRenderer\n  /** The mounted editor, `undefined` until the framework layer created it; used by `FeatureContext.getEditor`, `setValue` and `setEditable`. */\n  getEditor: () => Editor | undefined\n  /** Collaborative mode: the Y.Doc is the document, so there is no `value` and no `onChange`. */\n  collaboration?: CollaborationSession | undefined\n  /** Standalone initial document (TipTap JSON, unproxied); absent = an empty document. */\n  value?: JSONContent | undefined\n  /** Default `true`. */\n  editable?: boolean | undefined\n  /** The host's lists; later ones go through `setMetadata`. */\n  metadata?: EditorMetadata | undefined\n  documentId?: string | undefined\n  abilities?: Partial<AbilitiesOptions> | undefined\n  commands?: ((defaults: CommandDef[]) => CommandDef[]) | undefined\n  /** Added after the features' extensions. */\n  extensions?: readonly AnyExtension[] | undefined\n  /** Added after the features' block actions. */\n  blockActions?: readonly BlockAction[] | undefined\n  /** Standalone: the document after every edit (the JSON the session remembers as its own, see `setValue`). */\n  onChange?: ((content: JSONContent) => void) | undefined\n  /** A new item was created in a metadata list. */\n  onMetadataCreate?: ((list: string, item: MetadataItem) => void) | undefined\n  /** A document handed in (initially or through `setValue`) does not fit the schema. */\n  onContentError?: ((error: Error) => void) | undefined\n  /** A mounted editor was registered for the first time (see `register`). */\n  onReady?: ((editor: Editor) => void) | undefined\n}\n\n/**\n * Everything of an `EditorSurface` that does not depend on the UI framework: the preset's extensions and context,\n * the document's validation and echo handling, the features' `setup` lifecycle and the registration of the editor's\n * chrome. The framework layer creates the session once (state of the component instance), mounts a TipTap editor from\n * `editorOptions`, and forwards prop changes and lifecycle moments to it.\n */\nexport interface SurfaceSession<C = unknown> {\n  /**\n   * Options for the TipTap editor. Standalone mode (no `collaboration`) carries the initial document (`content`, already\n   * migrated; an empty document when the given one was rejected) and the `onUpdate` that feeds `onChange`. The framework\n   * layer may add its own options (rendering flags) but must not replace these.\n   */\n  readonly editorOptions: Partial<EditorOptions> & { extensions: AnyExtension[] }\n  /** The features' overlay components, in feature order; the framework layer renders them beside the editor with `{ editor }`. */\n  readonly overlays: readonly C[]\n  /**\n   * Starts the features' `setup` contributions, then reports a rejected initial document through `onContentError` (once\n   * per session, not per activation). A no-op while active. Pair every activation with `deactivate`: React StrictMode\n   * mounts, cleans up and mounts again, which must leave exactly one active setup.\n   */\n  activate: () => void\n  /** Runs the teardowns of the active `setup` contributions, in the order they were started; a no-op while inactive. */\n  deactivate: () => void\n  /**\n   * Registers the chrome of `editor` (the raw instance, see `registerEditor`) and announces it through `onReady` the\n   * first time this editor is registered, so a host toolbar that receives it finds the chrome. Returns the unregister\n   * function (idempotent). Call it again after the framework layer replaced the editor instance.\n   */\n  register: (editor: Editor) => () => void\n  /**\n   * The host's document changed (standalone only; ignored with `collaboration`). Not an edit: no `onChange`, no update\n   * event. Ignored when `value` is the very object `onChange` last received (the host handing the surface's own JSON\n   * back), is absent, or was already given; otherwise it is migrated and checked against the schema and applied, or\n   * reported through `onContentError` with the current document kept. A missing or destroyed editor ignores it.\n   */\n  setValue: (value: JSONContent | undefined) => void\n  /**\n   * Switches the editor's editable state; ignored when it equals the last given one, and while no (or a destroyed)\n   * editor exists. TipTap's `setEditable(…, false)` changes the flag without any event, so it is followed by an empty\n   * `addToHistory: false` transaction: components that follow `isEditable` on `transaction` (block UI, the composite\n   * inspector) notice. It has no steps, so nothing syncs and the history is untouched.\n   */\n  setEditable: (editable: boolean) => void\n  /** Replaces the host's metadata lists; ignored when `metadata` is the object that was last given. */\n  setMetadata: (metadata: EditorMetadata | undefined) => void\n}\n\n/**\n * Builds the session of one mounted surface: metadata registry, feature context, the extension list, the block actions\n * and the initial document. Throws when `collaboration` is given and the preset has no collaboration feature. Extension\n * order is fixed: the preset extension, the suggestion popup, the features' extensions in feature order, the host's.\n * The document is checked as `preset.pipeline.migrateContent` followed by the schema's `check()`; a failure is an error\n * value, never a throw.\n */\nexport function createSurfaceSession<C = unknown>(options: SurfaceSessionOptions<C>): SurfaceSession<C> {\n  const { app, preset, ui, collaboration, getEditor } = options\n  if (collaboration && !preset.features.some(feature => feature.id === 'collab')) {\n    throw new Error('@ecsplico/editor: `collaboration` needs a preset with the collaboration feature')\n  }\n  // The surface only consumes a `collaboration` session the host opened (`useEditorDocument(id, { collaboration })`\n  // opens it through `backend.collaboration` and checks that itself), so the collaboration capability is never needed\n  // here: a host with its own provider mounts the collaboration feature over a backend that offers none.\n  for (const feature of preset.features) {\n    for (const capability of feature.backend ?? []) {\n      if (capability === 'collaboration') continue\n      if (!app.backend[capability]) {\n        throw new Error(`@ecsplico/editor: feature \"${feature.id}\" needs backend capability \"${capability}\", which \"${app.backend.name}\" lacks`)\n      }\n    }\n  }\n\n  const registry = createMetadataRegistry({ onCreate: (list, item) => options.onMetadataCreate?.(list, item) })\n  registry.replace({ ...options.metadata })\n\n  const ctx = createFeatureContext({\n    app,\n    preset,\n    ui,\n    metadata: registry,\n    notify: options.notify,\n    getEditor,\n    ...(options.documentId !== undefined && { documentId: options.documentId }),\n    ...(collaboration && { collaboration }),\n    ...(options.abilities && { abilities: options.abilities }),\n    ...(options.commands && { commands: options.commands }),\n  })\n  // Fails here, not on the first toolbar render, when a command names a toolbar group no feature declares.\n  toolbarOf(preset, ctx)\n  // A command whose ability the document root does not grant never shows (its state is permanently disabled): say so once.\n  const root = new Set<string>(options.abilities?.root ?? ROOT_ABILITIES)\n  for (const cmd of ctx.commands()) {\n    if (cmd.ability && !root.has(cmd.ability)) {\n      console.warn(`@ecsplico/editor: command \"${cmd.id}\" needs ability \"${cmd.ability}\", which neither ROOT_ABILITIES nor \\`abilities.root\\` grants; it stays unavailable at document root`)\n    }\n  }\n\n  const extensions: AnyExtension[] = [\n    presetExtension(preset),\n    SuggestionPopup.configure({ renderer: options.suggestionRenderer }),\n    ...contributions(preset, 'extensions').flatMap(factory => factory(ctx)),\n    ...(options.extensions ?? []),\n  ]\n  const schema = getSchema(extensions)\n  const overlays = preset.features.flatMap(feature => [...(feature.overlays ?? [])])\n  const blockActions = blockActionsOf(preset, ctx, options.blockActions)\n\n  const validated = (json: JSONContent): { json: JSONContent } | { error: Error } => {\n    try {\n      const migrated = preset.pipeline.migrateContent(json)\n      schema.nodeFromJSON(migrated).check()\n      return { json: migrated }\n    }\n    catch (error) {\n      return { error: error instanceof Error ? error : new Error(String(error)) }\n    }\n  }\n\n  // Standalone: the JSON last sent through `onChange`; the host handing it back is not an external change.\n  let lastEmitted: JSONContent | undefined\n  let pendingContentError: Error | undefined\n  const editorOptions: SurfaceSession<C>['editorOptions'] = {\n    extensions,\n    editable: options.editable ?? true,\n    editorProps: { attributes: { class: 'tiptap' } },\n  }\n  if (!collaboration) {\n    const initial = options.value ? validated(options.value) : { json: EMPTY_EDITOR_CONTENT }\n    if ('error' in initial) pendingContentError = initial.error\n    editorOptions.content = 'json' in initial ? initial.json : EMPTY_EDITOR_CONTENT\n    editorOptions.onUpdate = ({ editor }) => {\n      lastEmitted = editor.getJSON()\n      options.onChange?.(lastEmitted)\n    }\n  }\n\n  // What the setters below already applied; they only react to a change.\n  let appliedValue = options.value\n  let appliedEditable = options.editable ?? true\n  let appliedMetadata = options.metadata\n  // Teardowns of the `setup` contributions that are currently active; undefined while inactive.\n  let teardowns: (() => void)[] | undefined\n  let announced: Editor | undefined\n\n  return {\n    editorOptions,\n    overlays,\n    activate() {\n      if (teardowns) return\n      const active: (() => void)[] = []\n      teardowns = active\n      for (const run of contributions(preset, 'setup')) {\n        const teardown = run(ctx)\n        if (teardown) active.push(teardown)\n      }\n      if (pendingContentError) {\n        const error = pendingContentError\n        pendingContentError = undefined\n        options.onContentError?.(error)\n      }\n    },\n    deactivate() {\n      const active = teardowns\n      teardowns = undefined\n      for (const teardown of active ?? []) teardown()\n    },\n    register(editor) {\n      const unregister = registerEditor(editor, { ui, preset, ctx, blockActions })\n      if (announced !== editor) {\n        announced = editor\n        options.onReady?.(editor)\n      }\n      return unregister\n    },\n    setValue(value) {\n      if (value === appliedValue) return\n      appliedValue = value\n      const editor = getEditor()\n      if (collaboration || !value || !editor || editor.isDestroyed || value === lastEmitted) return\n      const checked = validated(value)\n      if ('error' in checked) {\n        options.onContentError?.(checked.error)\n        return\n      }\n      editor.commands.setContent(checked.json, { emitUpdate: false })\n    },\n    setEditable(editable) {\n      if (editable === appliedEditable) return\n      appliedEditable = editable\n      const editor = getEditor()\n      if (!editor || editor.isDestroyed) return\n      editor.setEditable(editable, false)\n      editor.view.dispatch(editor.state.tr.setMeta('addToHistory', false))\n    },\n    setMetadata(metadata) {\n      if (metadata === appliedMetadata) return\n      appliedMetadata = metadata\n      registry.replace({ ...metadata })\n    },\n  }\n}\n"],"mappings":"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"}

package/dist/core/toolbar-items.d.ts

@@ -1,10 +1,16 @@
-import { ToolbarGroup } from "./toolbar.js";
+import { CommandDef, ToolbarGroupDef } from "./command-types.js";
 import { FeatureContext } from "./feature.js";
 //#region src/core/toolbar-items.d.ts
 /**
- * The core toolbar: undo/redo, paragraph and headings, text marks, lists, quote, code block
- * and rule. Orders leave room for the groups features contribute.
+ * The toolbar groups of the core UI (undo/redo, paragraph and headings, text marks, lists/quote/code block/rule) and the
+ * two groups other features' commands name: `inserts` (media, transcript, …) and `collaboration` (comments, authors).
+ * Orders leave room for the groups features contribute (composites and tables 60, AI 1000).
  */
-export declare function coreToolbarGroups(ctx: FeatureContext): ToolbarGroup<never>[];
+export declare const CORE_TOOLBAR_GROUPS: ToolbarGroupDef[];
+/**
+ * The core commands: undo/redo, paragraph and headings, text marks, lists, quote, code block and rule. The five block
+ * types (headings, lists, quote, code block, rule) are also in the `/` menu.
+ */
+export declare function coreCommands(ctx: FeatureContext): CommandDef<never>[];
 //#endregion
 //# sourceMappingURL=toolbar-items.d.ts.map