stilo-editor 0.2.1 → 0.3.1

package/README.md

@@ -20,6 +20,9 @@
 
 <p align="center">
   <a href="https://kojak8791.github.io/stilo-editor/"><strong>Live demo</strong></a> ·
+  <a href="docs/frameworks/react.md"><strong>React</strong></a> ·
+  <a href="docs/frameworks/vue.md"><strong>Vue</strong></a> ·
+  <a href="docs/frameworks/svelte.md"><strong>Svelte</strong></a> ·
   <a href="docs/API.md"><strong>API</strong></a> ·
   <a href="docs/FEATURES.md"><strong>All features</strong></a>
 </p>
@@ -76,6 +79,48 @@ document.querySelector('#undo')!.addEventListener('click', () => editor.commands
 
 Commands, button states and events: [API reference](docs/API.md).
 
+### React
+
+```tsx
+import 'stilo-editor/style.css';
+import { StiloEditor } from 'stilo-editor/react';
+
+<StiloEditor content="<p>Hello</p>" onInput={({ editor }) => save(editor.getHTML())} />;
+```
+
+React 18 and 19, server-side rendering included; `useStiloEditor` for your own UI:
+[React guide](docs/frameworks/react.md).
+
+### Vue
+
+```vue
+<script setup>
+import 'stilo-editor/style.css';
+import { StiloEditor } from 'stilo-editor/vue';
+</script>
+
+<template>
+  <StiloEditor content="<p>Hello</p>" @input="({ editor }) => save(editor.getHTML())" />
+</template>
+```
+
+Vue 3.4 and later, server-side rendering included; `useStiloEditor` for your own UI:
+[Vue guide](docs/frameworks/vue.md).
+
+### Svelte
+
+```svelte
+<script>
+  import 'stilo-editor/style.css';
+  import { StiloEditor } from 'stilo-editor/svelte';
+</script>
+
+<StiloEditor content="<p>Hello</p>" oninput={({ editor }) => save(editor.getHTML())} />
+```
+
+A component for Svelte 5, actions for Svelte 4 and 5, server-side rendering included:
+[Svelte guide](docs/frameworks/svelte.md).
+
 ## What's included
 
 - **Text:** bold, italic, underline, strikethrough, code, sub/superscript, fonts, sizes,
@@ -104,7 +149,7 @@ from the keyboard alone. Every feature, shortcut and option: [All features](docs
 
 `0.x` preview: it works, but APIs may change in minor versions until `1.0.0`.
 Read the [changelog](CHANGELOG.md) before updating.
-Next: framework wrappers, real-time collaboration ([roadmap](docs/SPEC.md)).
+Next: real-time collaboration ([roadmap](docs/SPEC.md)).
 
 ## Contributing
 

package/dist/action-lB2jnYNO.js

@@ -0,0 +1,66 @@
+import { Q as e, t } from "./src-DxTXpULc.js";
+import { h as n, t as r } from "./ui-WFNvrkbM.js";
+//#region src/svelte/editor-action.ts
+function i(t, n) {
+	let { onready: r, ...i } = n, o = new e({
+		...i,
+		element: t
+	});
+	return r?.(o), {
+		update: (e) => a(o, e.editable),
+		destroy: () => o.destroy()
+	};
+}
+function a(e, t) {
+	let n = t ?? !0;
+	e.isEditable !== n && e.setEditable(n);
+}
+//#endregion
+//#region src/svelte/editor-with-ui-action.ts
+var o = {
+	input: "oninput",
+	selectionchange: "onselectionchange",
+	transaction: "ontransaction",
+	focus: "onfocus",
+	blur: "onblur"
+};
+function s(i, s = {}) {
+	let u = s, { extensions: d = [t()], toolbar: f = !0, statusBar: p = !1, messages: m, onready: h, ...g } = s, _ = f ? c(i) : null, v = c(i), y = p ? c(i) : null, b = new e({
+		...g,
+		extensions: d,
+		element: v
+	});
+	_ && r(b, {
+		...f === !0 ? {} : f,
+		container: _,
+		messages: m
+	}), y && n(b, {
+		container: y,
+		messages: m
+	});
+	for (let e of Object.keys(o)) l(b, e, () => u);
+	return h?.(b), {
+		update: (e) => {
+			u = e, a(b, e.editable);
+		},
+		destroy: () => {
+			b.destroy();
+			for (let e of [
+				_,
+				v,
+				y
+			]) e?.remove();
+		}
+	};
+}
+function c(e) {
+	return e.appendChild(document.createElement("div"));
+}
+function l(e, t, n) {
+	e.on(t, (e) => {
+		let r = n()[o[t]];
+		r?.(e);
+	});
+}
+//#endregion
+export { i as n, s as t };

package/dist/content.css

@@ -152,6 +152,15 @@ li.ProseMirror-selectednode:after {
 
 /* Stilo content defaults */
 
+/*
+ * The editable area gets some room around the text and a visible height when empty.
+ * `:where()` has no specificity, so any rule of the page replaces these values.
+ */
+:where(.stilo-content.ProseMirror) {
+  min-height: 6em;
+  padding: 12px 16px;
+}
+
 /* Lists: list items hold paragraphs, which must not add their own margins. */
 .stilo-content ul,
 .stilo-content ol {

package/dist/core/editor.d.ts

@@ -94,7 +94,10 @@ export declare class Editor {
      * the name is unknown.
      */
     getAttributes(name: string): Record<string, unknown>;
-    /** Switches read-only mode on/off. */
+    /**
+     * Switches read-only mode on/off. A change dispatches an empty transaction, so the UIs that
+     * refresh on `transaction` follow it.
+     */
     setEditable(editable: boolean): void;
     /** Focuses the editor; optionally moves the cursor to the start or end of the document. */
     focus(position?: 'start' | 'end'): void;
@@ -107,8 +110,15 @@ export declare class Editor {
     /** Emits `destroy`, destroys the view, removes all handlers. Calling it twice is a no-op. */
     destroy(): void;
     private createState;
-    /** Builds `commands` from the extension commands; `can` runs without `dispatch`. */
+    /** Builds `commands` from the extension commands; `can` does not apply them. */
     private createRunners;
+    /**
+     * Runs `command`, or only tells whether it would apply. In read-only mode a command that
+     * changes the document or the stored marks does not apply and returns `false`; the others
+     * (selection, search) do. To know, the command builds its transaction: `can` costs as much
+     * as a run there.
+     */
+    private runCommand;
     private setContent;
     /**
      * Removes the DOM selection when it lies inside the editor. Replacing many nodes while the

package/dist/index.js

@@ -1 +1 @@
-export { B as Blockquote, z as Bold, R as BulletList, L as ClearFormatting, I as Code, F as CodeBlock, X as DEFAULT_PRIORITY, P as Document, N as DropCursor, Q as Editor, M as GapCursor, j as HardBreak, A as Heading, k as Highlight, O as History, D as HorizontalRule, E as Image, T as Italic, w as LineHeight, C as Link, S as ListItem, x as MoveBlock, b as OrderedList, y as Paragraph, v as Placeholder, g as Search, nt as StiloError, h as Strike, m as Subscript, p as Superscript, d as Table, u as TaskItem, l as TaskList, c as Text, s as TextAlign, o as TextCase, r as TextStyle, n as Underline, $ as attrsMatch, t as defaultExtensions, Z as defineExtension, i as getFontSize, _ as getSearchResults, f as getTableHeaders, V as getWordCount, U as insertBlock, W as insertBlockNode, et as isMarkActive, tt as isNodeActive, Y as markInputRule, G as setMark, H as textDecorationRules, a as toFontSize, J as toggleList, K as toggleMark, q as unsetMark } from "./src-CV6pgfTS.js";
+export { B as Blockquote, z as Bold, R as BulletList, L as ClearFormatting, I as Code, F as CodeBlock, X as DEFAULT_PRIORITY, P as Document, N as DropCursor, Q as Editor, M as GapCursor, j as HardBreak, A as Heading, k as Highlight, O as History, D as HorizontalRule, E as Image, T as Italic, w as LineHeight, C as Link, S as ListItem, x as MoveBlock, b as OrderedList, y as Paragraph, v as Placeholder, g as Search, nt as StiloError, h as Strike, m as Subscript, p as Superscript, d as Table, u as TaskItem, l as TaskList, c as Text, s as TextAlign, o as TextCase, r as TextStyle, n as Underline, $ as attrsMatch, t as defaultExtensions, Z as defineExtension, i as getFontSize, _ as getSearchResults, f as getTableHeaders, V as getWordCount, U as insertBlock, W as insertBlockNode, et as isMarkActive, tt as isNodeActive, Y as markInputRule, G as setMark, H as textDecorationRules, a as toFontSize, J as toggleList, K as toggleMark, q as unsetMark } from "./src-DxTXpULc.js";

package/dist/react/index.d.ts

@@ -0,0 +1,5 @@
+/** Public API of the Stilo React wrapper. */
+/** The editor with the default UI. */
+export { StiloEditor, type StiloEditorEventProps, type StiloEditorProps } from './stilo-editor';
+/** The editor alone, for a custom UI. */
+export { type UseStiloEditorOptions, type UseStiloEditorResult, useStiloEditor, } from './use-stilo-editor';

package/dist/react/stilo-editor.d.ts

@@ -0,0 +1,37 @@
+import { type ReactElement } from 'react';
+import { type Editor, type EditorEvents, type EditorOptions, type EventHandler } from '../index';
+import { type Messages, type ToolbarOptions } from '../ui/index';
+/** Editor events forwarded to the props of {@link StiloEditor}. */
+declare const EVENT_PROPS: {
+    readonly input: 'onInput';
+    readonly selectionchange: 'onSelectionChange';
+    readonly transaction: 'onTransaction';
+    readonly focus: 'onFocus';
+    readonly blur: 'onBlur';
+};
+type ForwardedEvent = keyof typeof EVENT_PROPS;
+/** Event props of {@link StiloEditor}: `onInput` for `input`, and so on. */
+export type StiloEditorEventProps = {
+    [E in ForwardedEvent as (typeof EVENT_PROPS)[E]]?: EventHandler<EditorEvents[E]>;
+};
+/** Props of {@link StiloEditor}. */
+export interface StiloEditorProps extends Omit<EditorOptions, 'element' | 'extensions'>, StiloEditorEventProps {
+    /** Extensions to load. Default: `[defaultExtensions()]`. */
+    extensions?: EditorOptions['extensions'];
+    /** The default toolbar: `true` (default), `false`, or its options without `container`. */
+    toolbar?: boolean | Omit<ToolbarOptions, 'container' | 'messages'>;
+    /** The status bar with the word and character count, under the editor. Default: `false`. */
+    statusBar?: boolean;
+    /** Strings of the toolbar and the status bar. Default: `en`. */
+    messages?: Messages;
+    /** Class of the element that holds the toolbar, the editor and the status bar. */
+    className?: string;
+    /** Called once the editor is created, with the editor. */
+    onReady?: (editor: Editor) => void;
+}
+/**
+ * The editor with the default UI. The props are read once, when the editor is created, except
+ * `editable` and the event handlers, which follow their changes.
+ */
+export declare function StiloEditor(props: StiloEditorProps): ReactElement;
+export {};

package/dist/react/use-stilo-editor.d.ts

@@ -0,0 +1,15 @@
+import { Editor, type EditorOptions } from '../index';
+/** Options of {@link useStiloEditor}: the editor options without `element`. */
+export type UseStiloEditorOptions = Omit<EditorOptions, 'element'>;
+/** What {@link useStiloEditor} returns. */
+export interface UseStiloEditorResult {
+    /** Ref of the element that holds the editor. */
+    ref: (element: HTMLElement | null) => void;
+    /** The editor; `null` before the element is mounted, on the server and after unmount. */
+    editor: Editor | null;
+}
+/**
+ * Creates an editor inside the element that gets `ref` and destroys it when the element goes.
+ * The options are read once, when the editor is created; only `editable` follows its changes.
+ */
+export declare function useStiloEditor(options: UseStiloEditorOptions): UseStiloEditorResult;

package/dist/react.js

@@ -0,0 +1,75 @@
+"use client";
+import { Q as e, t } from "./src-DxTXpULc.js";
+import { h as n, t as r } from "./ui-WFNvrkbM.js";
+import { createElement as i, useEffect as a, useRef as o, useState as s } from "react";
+//#region src/react/use-stilo-editor.ts
+function c(t) {
+	let [n, r] = s(null), [i, c] = s(null), l = o(t);
+	a(() => {
+		if (!n) return;
+		let t = new e({
+			...l.current,
+			element: n
+		});
+		return c(t), () => {
+			t.destroy(), c(null);
+		};
+	}, [n]);
+	let u = t.editable ?? !0;
+	return a(() => {
+		i && !i.isDestroyed && i.isEditable !== u && i.setEditable(u);
+	}, [i, u]), {
+		ref: r,
+		editor: i
+	};
+}
+//#endregion
+//#region src/react/stilo-editor.ts
+var l = {
+	input: "onInput",
+	selectionchange: "onSelectionChange",
+	transaction: "onTransaction",
+	focus: "onFocus",
+	blur: "onBlur"
+};
+function u(e) {
+	let [u] = s(() => ({
+		extensions: e.extensions ?? [t()],
+		toolbar: e.toolbar ?? !0,
+		statusBar: e.statusBar ?? !1,
+		messages: e.messages
+	})), { ref: f, editor: p } = c({
+		...e,
+		extensions: u.extensions
+	}), m = o(null), h = o(null), g = o(e);
+	return a(() => {
+		g.current = e;
+	}), a(() => {
+		if (!p || p.isDestroyed) return;
+		let { toolbar: e, statusBar: t, messages: i } = u, a, o;
+		e && m.current && (a = r(p, {
+			...e === !0 ? {} : e,
+			container: m.current,
+			messages: i
+		})), t && h.current && (o = n(p, {
+			container: h.current,
+			messages: i
+		}));
+		let s = Object.keys(l).map((e) => d(p, e, g));
+		return g.current.onReady?.(p), () => {
+			if (!p.isDestroyed) {
+				a?.destroy(), o?.destroy();
+				for (let e of s) e();
+			}
+		};
+	}, [p, u]), i("div", { className: e.className }, u.toolbar ? i("div", { ref: m }) : null, i("div", { ref: f }), u.statusBar ? i("div", { ref: h }) : null);
+}
+function d(e, t, n) {
+	let r = (e) => {
+		let r = n.current[l[t]];
+		r?.(e);
+	};
+	return e.on(t, r), () => e.off(t, r);
+}
+//#endregion
+export { u as StiloEditor, c as useStiloEditor };