@matrajs/svelte 0.15.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nahim Hossain Shohan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @matrajs/svelte
+
+Svelte bindings for [Matra](https://matrajs.com): a `use:` action and a store
+that follows the editor.
+
+```sh
+npm i @matrajs/core @matrajs/svelte
+```
+
+```svelte
+<script>
+  import { starterKit } from '@matrajs/core'
+  import { matra } from '@matrajs/svelte'
+
+  const { action, editor, state } = matra({
+    extensions: starterKit,
+    content: '<p>Hello</p>',
+  })
+</script>
+
+<button onclick={() => editor.commands.toggleBold()}
+        aria-pressed={$state.isActive('bold')}>
+  Bold
+</button>
+
+<div use:action></div>
+```
+
+## What it adds
+
+Svelte already has the right shape for this — an action runs when the element
+exists and is told when it goes away — so the binding is thin on purpose. What
+it adds over eight lines written inline is the two things people get wrong:
+
+- **The double-mount guard.** A component rendered twice, or an action re-run
+  by a hot reload, would otherwise attach a second view to one element, which
+  is two carets fighting over it.
+- **A store.** `$state` republishes on every change and every selection move,
+  so a toolbar's pressed states come from the document rather than from what
+  was last clicked.
+
+The editor is created immediately rather than on mount, so `commands`,
+`getJSON()` and `getText()` all work before anything is on screen — which is
+what a server render and a test both need.
+
+## Svelte 4 and 5
+
+Stores, not runes, so the same package works in both. A rune-only build would
+be a version boundary in exchange for nothing: `$state` on a store reads
+identically.
+
+## Styling
+
+Matra ships no appearance. See
+[the styling guide](https://matrajs.com/docs/styling).
+
+## Licence
+
+MIT.

package/dist/index.cjs

@@ -0,0 +1,34 @@
+'use strict';
+
+var core = require('@matrajs/core');
+var store = require('svelte/store');
+
+// src/index.ts
+function matra(options) {
+  const editor = core.createEditor(options);
+  const action = (node) => {
+    if (!editor.unsafe.view) editor.mount(node);
+    return {
+      destroy() {
+        editor.destroy();
+      }
+    };
+  };
+  return { action, editor, state: editorState(editor) };
+}
+function editorState(editor) {
+  return store.readable(editor, (set) => {
+    const republish = () => set(editor);
+    const offChange = editor.on("change", republish);
+    const offSelection = editor.on("selectionChange", republish);
+    return () => {
+      offChange();
+      offSelection();
+    };
+  });
+}
+
+exports.editorState = editorState;
+exports.matra = matra;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["createEditor","readable"],"mappings":";;;;;;AAkDO,SAAS,MACd,OAAA,EACgB;AAChB,EAAA,MAAM,MAAA,GAASA,kBAAa,OAAO,CAAA;AAEnC,EAAA,MAAM,MAAA,GAAS,CAAC,IAAA,KAAoC;AAGlD,IAAA,IAAI,CAAC,MAAA,CAAO,MAAA,CAAO,IAAA,EAAM,MAAA,CAAO,MAAM,IAAI,CAAA;AAC1C,IAAA,OAAO;AAAA,MACL,OAAA,GAAU;AACR,QAAA,MAAA,CAAO,OAAA,EAAQ;AAAA,MACjB;AAAA,KACF;AAAA,EACF,CAAA;AAEA,EAAA,OAAO,EAAE,MAAA,EAAQ,MAAA,EAAQ,KAAA,EAAO,WAAA,CAAY,MAAM,CAAA,EAAE;AACtD;AASO,SAAS,YACd,MAAA,EACqB;AACrB,EAAA,OAAOC,cAAA,CAAS,MAAA,EAAQ,CAAC,GAAA,KAAQ;AAC/B,IAAA,MAAM,SAAA,GAAY,MAAM,GAAA,CAAI,MAAM,CAAA;AAClC,IAAA,MAAM,SAAA,GAAY,MAAA,CAAO,EAAA,CAAG,QAAA,EAAU,SAAS,CAAA;AAC/C,IAAA,MAAM,YAAA,GAAe,MAAA,CAAO,EAAA,CAAG,iBAAA,EAAmB,SAAS,CAAA;AAC3D,IAAA,OAAO,MAAM;AACX,MAAA,SAAA,EAAU;AACV,MAAA,YAAA,EAAa;AAAA,IACf,CAAA;AAAA,EACF,CAAC,CAAA;AACH","file":"index.cjs","sourcesContent":["import { type AnyDef, type Editor, type EditorOptions, createEditor } from '@matrajs/core'\nimport { type Readable, readable } from 'svelte/store'\n\n/**\n * Svelte bindings, which are mostly an action.\n *\n * Svelte already has the shape this needs — an action runs when the element\n * exists and is told when it goes away — so the binding is thin on purpose.\n * What it adds over eight lines written inline is the double-mount guard and a\n * store, and both of those are the parts people get wrong rather than the\n * parts they find tedious.\n *\n * Written with stores rather than runes so it works the same in Svelte 4 and\n * 5. A rune-only package would be a version boundary in exchange for nothing.\n */\n\n/** The shape Svelte's `use:` directive expects back. */\nexport interface EditorAction {\n  destroy(): void\n}\n\nexport interface MatraAction<T extends readonly AnyDef[]> {\n  /** Pass this to `use:` on the element the editor should mount into. */\n  action: (node: HTMLElement) => EditorAction\n  /** The editor itself. It exists before the element does. */\n  editor: Editor<T>\n  /** Bumped on every change and selection move · read it in your markup. */\n  state: Readable<Editor<T>>\n}\n\n/**\n * Create an editor and the action that mounts it.\n *\n * ```svelte\n * <script>\n *   import { matra } from '@matrajs/svelte'\n *   import { starterKit } from '@matrajs/core'\n *\n *   const { action, editor, state } = matra({ extensions: starterKit })\n * </script>\n *\n * <button onclick={() => editor.commands.toggleBold()}\n *         aria-pressed={$state.isActive('bold')}>Bold</button>\n * <div use:action></div>\n * ```\n *\n * The editor is created immediately rather than on mount, so commands, content\n * and `getJSON()` all work before anything is on screen — which is what a\n * server render and a test both need.\n */\nexport function matra<const T extends readonly AnyDef[]>(\n  options: EditorOptions<T>,\n): MatraAction<T> {\n  const editor = createEditor(options)\n\n  const action = (node: HTMLElement): EditorAction => {\n    // A component rendered twice, or an action re-run by a hot reload, must not\n    // attach a second view to one element.\n    if (!editor.unsafe.view) editor.mount(node)\n    return {\n      destroy() {\n        editor.destroy()\n      },\n    }\n  }\n\n  return { action, editor, state: editorState(editor) }\n}\n\n/**\n * A store that changes whenever the editor does.\n *\n * The value is the editor itself, not a copy: a toolbar wants to ask\n * `isActive` and `getText` at render time, and cloning a document to answer\n * that would be the expensive way to do nothing.\n */\nexport function editorState<T extends readonly AnyDef[]>(\n  editor: Editor<T>,\n): Readable<Editor<T>> {\n  return readable(editor, (set) => {\n    const republish = () => set(editor)\n    const offChange = editor.on('change', republish)\n    const offSelection = editor.on('selectionChange', republish)\n    return () => {\n      offChange()\n      offSelection()\n    }\n  })\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,58 @@
+import { AnyDef, Editor, EditorOptions } from '@matrajs/core';
+import { Readable } from 'svelte/store';
+
+/**
+ * Svelte bindings, which are mostly an action.
+ *
+ * Svelte already has the shape this needs — an action runs when the element
+ * exists and is told when it goes away — so the binding is thin on purpose.
+ * What it adds over eight lines written inline is the double-mount guard and a
+ * store, and both of those are the parts people get wrong rather than the
+ * parts they find tedious.
+ *
+ * Written with stores rather than runes so it works the same in Svelte 4 and
+ * 5. A rune-only package would be a version boundary in exchange for nothing.
+ */
+/** The shape Svelte's `use:` directive expects back. */
+interface EditorAction {
+    destroy(): void;
+}
+interface MatraAction<T extends readonly AnyDef[]> {
+    /** Pass this to `use:` on the element the editor should mount into. */
+    action: (node: HTMLElement) => EditorAction;
+    /** The editor itself. It exists before the element does. */
+    editor: Editor<T>;
+    /** Bumped on every change and selection move · read it in your markup. */
+    state: Readable<Editor<T>>;
+}
+/**
+ * Create an editor and the action that mounts it.
+ *
+ * ```svelte
+ * <script>
+ *   import { matra } from '@matrajs/svelte'
+ *   import { starterKit } from '@matrajs/core'
+ *
+ *   const { action, editor, state } = matra({ extensions: starterKit })
+ * </script>
+ *
+ * <button onclick={() => editor.commands.toggleBold()}
+ *         aria-pressed={$state.isActive('bold')}>Bold</button>
+ * <div use:action></div>
+ * ```
+ *
+ * The editor is created immediately rather than on mount, so commands, content
+ * and `getJSON()` all work before anything is on screen — which is what a
+ * server render and a test both need.
+ */
+declare function matra<const T extends readonly AnyDef[]>(options: EditorOptions<T>): MatraAction<T>;
+/**
+ * A store that changes whenever the editor does.
+ *
+ * The value is the editor itself, not a copy: a toolbar wants to ask
+ * `isActive` and `getText` at render time, and cloning a document to answer
+ * that would be the expensive way to do nothing.
+ */
+declare function editorState<T extends readonly AnyDef[]>(editor: Editor<T>): Readable<Editor<T>>;
+
+export { type EditorAction, type MatraAction, editorState, matra };

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import { AnyDef, Editor, EditorOptions } from '@matrajs/core';
+import { Readable } from 'svelte/store';
+
+/**
+ * Svelte bindings, which are mostly an action.
+ *
+ * Svelte already has the shape this needs — an action runs when the element
+ * exists and is told when it goes away — so the binding is thin on purpose.
+ * What it adds over eight lines written inline is the double-mount guard and a
+ * store, and both of those are the parts people get wrong rather than the
+ * parts they find tedious.
+ *
+ * Written with stores rather than runes so it works the same in Svelte 4 and
+ * 5. A rune-only package would be a version boundary in exchange for nothing.
+ */
+/** The shape Svelte's `use:` directive expects back. */
+interface EditorAction {
+    destroy(): void;
+}
+interface MatraAction<T extends readonly AnyDef[]> {
+    /** Pass this to `use:` on the element the editor should mount into. */
+    action: (node: HTMLElement) => EditorAction;
+    /** The editor itself. It exists before the element does. */
+    editor: Editor<T>;
+    /** Bumped on every change and selection move · read it in your markup. */
+    state: Readable<Editor<T>>;
+}
+/**
+ * Create an editor and the action that mounts it.
+ *
+ * ```svelte
+ * <script>
+ *   import { matra } from '@matrajs/svelte'
+ *   import { starterKit } from '@matrajs/core'
+ *
+ *   const { action, editor, state } = matra({ extensions: starterKit })
+ * </script>
+ *
+ * <button onclick={() => editor.commands.toggleBold()}
+ *         aria-pressed={$state.isActive('bold')}>Bold</button>
+ * <div use:action></div>
+ * ```
+ *
+ * The editor is created immediately rather than on mount, so commands, content
+ * and `getJSON()` all work before anything is on screen — which is what a
+ * server render and a test both need.
+ */
+declare function matra<const T extends readonly AnyDef[]>(options: EditorOptions<T>): MatraAction<T>;
+/**
+ * A store that changes whenever the editor does.
+ *
+ * The value is the editor itself, not a copy: a toolbar wants to ask
+ * `isActive` and `getText` at render time, and cloning a document to answer
+ * that would be the expensive way to do nothing.
+ */
+declare function editorState<T extends readonly AnyDef[]>(editor: Editor<T>): Readable<Editor<T>>;
+
+export { type EditorAction, type MatraAction, editorState, matra };

package/dist/index.js

@@ -0,0 +1,31 @@
+import { createEditor } from '@matrajs/core';
+import { readable } from 'svelte/store';
+
+// src/index.ts
+function matra(options) {
+  const editor = createEditor(options);
+  const action = (node) => {
+    if (!editor.unsafe.view) editor.mount(node);
+    return {
+      destroy() {
+        editor.destroy();
+      }
+    };
+  };
+  return { action, editor, state: editorState(editor) };
+}
+function editorState(editor) {
+  return readable(editor, (set) => {
+    const republish = () => set(editor);
+    const offChange = editor.on("change", republish);
+    const offSelection = editor.on("selectionChange", republish);
+    return () => {
+      offChange();
+      offSelection();
+    };
+  });
+}
+
+export { editorState, matra };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;AAkDO,SAAS,MACd,OAAA,EACgB;AAChB,EAAA,MAAM,MAAA,GAAS,aAAa,OAAO,CAAA;AAEnC,EAAA,MAAM,MAAA,GAAS,CAAC,IAAA,KAAoC;AAGlD,IAAA,IAAI,CAAC,MAAA,CAAO,MAAA,CAAO,IAAA,EAAM,MAAA,CAAO,MAAM,IAAI,CAAA;AAC1C,IAAA,OAAO;AAAA,MACL,OAAA,GAAU;AACR,QAAA,MAAA,CAAO,OAAA,EAAQ;AAAA,MACjB;AAAA,KACF;AAAA,EACF,CAAA;AAEA,EAAA,OAAO,EAAE,MAAA,EAAQ,MAAA,EAAQ,KAAA,EAAO,WAAA,CAAY,MAAM,CAAA,EAAE;AACtD;AASO,SAAS,YACd,MAAA,EACqB;AACrB,EAAA,OAAO,QAAA,CAAS,MAAA,EAAQ,CAAC,GAAA,KAAQ;AAC/B,IAAA,MAAM,SAAA,GAAY,MAAM,GAAA,CAAI,MAAM,CAAA;AAClC,IAAA,MAAM,SAAA,GAAY,MAAA,CAAO,EAAA,CAAG,QAAA,EAAU,SAAS,CAAA;AAC/C,IAAA,MAAM,YAAA,GAAe,MAAA,CAAO,EAAA,CAAG,iBAAA,EAAmB,SAAS,CAAA;AAC3D,IAAA,OAAO,MAAM;AACX,MAAA,SAAA,EAAU;AACV,MAAA,YAAA,EAAa;AAAA,IACf,CAAA;AAAA,EACF,CAAC,CAAA;AACH","file":"index.js","sourcesContent":["import { type AnyDef, type Editor, type EditorOptions, createEditor } from '@matrajs/core'\nimport { type Readable, readable } from 'svelte/store'\n\n/**\n * Svelte bindings, which are mostly an action.\n *\n * Svelte already has the shape this needs — an action runs when the element\n * exists and is told when it goes away — so the binding is thin on purpose.\n * What it adds over eight lines written inline is the double-mount guard and a\n * store, and both of those are the parts people get wrong rather than the\n * parts they find tedious.\n *\n * Written with stores rather than runes so it works the same in Svelte 4 and\n * 5. A rune-only package would be a version boundary in exchange for nothing.\n */\n\n/** The shape Svelte's `use:` directive expects back. */\nexport interface EditorAction {\n  destroy(): void\n}\n\nexport interface MatraAction<T extends readonly AnyDef[]> {\n  /** Pass this to `use:` on the element the editor should mount into. */\n  action: (node: HTMLElement) => EditorAction\n  /** The editor itself. It exists before the element does. */\n  editor: Editor<T>\n  /** Bumped on every change and selection move · read it in your markup. */\n  state: Readable<Editor<T>>\n}\n\n/**\n * Create an editor and the action that mounts it.\n *\n * ```svelte\n * <script>\n *   import { matra } from '@matrajs/svelte'\n *   import { starterKit } from '@matrajs/core'\n *\n *   const { action, editor, state } = matra({ extensions: starterKit })\n * </script>\n *\n * <button onclick={() => editor.commands.toggleBold()}\n *         aria-pressed={$state.isActive('bold')}>Bold</button>\n * <div use:action></div>\n * ```\n *\n * The editor is created immediately rather than on mount, so commands, content\n * and `getJSON()` all work before anything is on screen — which is what a\n * server render and a test both need.\n */\nexport function matra<const T extends readonly AnyDef[]>(\n  options: EditorOptions<T>,\n): MatraAction<T> {\n  const editor = createEditor(options)\n\n  const action = (node: HTMLElement): EditorAction => {\n    // A component rendered twice, or an action re-run by a hot reload, must not\n    // attach a second view to one element.\n    if (!editor.unsafe.view) editor.mount(node)\n    return {\n      destroy() {\n        editor.destroy()\n      },\n    }\n  }\n\n  return { action, editor, state: editorState(editor) }\n}\n\n/**\n * A store that changes whenever the editor does.\n *\n * The value is the editor itself, not a copy: a toolbar wants to ask\n * `isActive` and `getText` at render time, and cloning a document to answer\n * that would be the expensive way to do nothing.\n */\nexport function editorState<T extends readonly AnyDef[]>(\n  editor: Editor<T>,\n): Readable<Editor<T>> {\n  return readable(editor, (set) => {\n    const republish = () => set(editor)\n    const offChange = editor.on('change', republish)\n    const offSelection = editor.on('selectionChange', republish)\n    return () => {\n      offChange()\n      offSelection()\n    }\n  })\n}\n"]}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@matrajs/svelte",
+  "version": "0.15.0",
+  "description": "Svelte bindings for Matra — a use: action and a store that follows the editor.",
+  "license": "MIT",
+  "author": "Nahim Hossain Shohan",
+  "homepage": "https://matrajs.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amrelaco/matra.git",
+    "directory": "packages/svelte"
+  },
+  "bugs": {
+    "url": "https://github.com/amrelaco/matra/issues"
+  },
+  "keywords": [
+    "editor",
+    "rich-text",
+    "svelte",
+    "matra"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@matrajs/core": "^0.15.0"
+  },
+  "peerDependencies": {
+    "svelte": ">=4"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist"
+  }
+}