@slexkit/tiptap 0.3.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) SlexKit contributors
+
+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,88 @@
+# @slexkit/tiptap
+
+Tiptap extension for explicit `slex` fenced UI blocks.
+
+```sh
+npm install slexkit @slexkit/theme-shadcn @slexkit/tiptap @tiptap/core @tiptap/pm @tiptap/starter-kit @tiptap/extension-code-block @tiptap/markdown
+```
+
+Import the SlexKit theme once in your app entry:
+
+```ts
+import "@slexkit/theme-shadcn/style.css";
+import "@slexkit/tiptap/style.css";
+```
+
+## Minimal setup
+
+```ts
+import { Editor } from "@tiptap/core";
+import StarterKit from "@tiptap/starter-kit";
+import { createSlexKitTiptapExtension } from "@slexkit/tiptap";
+
+const editor = new Editor({
+  element: document.querySelector("#editor"),
+  extensions: [
+    StarterKit.configure({ codeBlock: false }),
+    createSlexKitTiptapExtension({
+      artifactId: "note-42",
+    }),
+  ],
+});
+```
+
+Only code blocks whose language is exactly `slex` are rendered by SlexKit. Other code blocks stay ordinary Tiptap code blocks.
+
+## Markdown roundtrip
+
+Add Tiptap's Markdown extension when loading or exporting Markdown:
+
+```ts
+import { Markdown } from "@tiptap/markdown";
+
+const editor = new Editor({
+  extensions: [
+    StarterKit.configure({ codeBlock: false }),
+    Markdown,
+    createSlexKitTiptapExtension({ artifactId: "doc" }),
+  ],
+  content: markdown,
+  contentType: "markdown",
+});
+
+const nextMarkdown = editor.getMarkdown();
+```
+
+The adapter uses normal fenced code blocks instead of a custom tokenizer, so ` ```slex ` blocks remain readable in plain Markdown hosts.
+
+## Shared state across fences
+
+All `slex` blocks in one editor share the same artifact runtime by default. A state-only fence can seed later renderable fences:
+
+````md
+```slex
+{
+  namespace: "calc",
+  g: { value: 21 }
+}
+```
+
+```slex
+{
+  namespace: "calc",
+  layout: {
+    "text:answer": { "$text": "'answer: ' + (g.value * 2)" }
+  }
+}
+```
+````
+
+## Runtime boundary
+
+This adapter defaults to trusted runtime mode, intended for application-authored content, repository-maintained snippets, reviewed examples, and local document workflows. Use SlexKit secure runtime APIs for untrusted user Markdown or direct agent output.
+
+## Documentation
+
+- [Official Tiptap editor example](https://slexkit.app.simgor.cn/examples/tiptap-host)
+- [Runnable example source](https://github.com/slexkit/slexkit/tree/main/examples/tiptap)
+- [SlexKit Host integration](https://github.com/slexkit/slexkit/blob/main/site/content/reference/integration/en-US.md)

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import type { Editor } from "@tiptap/core";
+import { type SlexKitMarkdownRuntimeHost, type ThemeMode } from "slexkit";
+export type SlexKitTiptapOptions = {
+    artifactId?: string | ((ctx: {
+        editor: Editor;
+    }) => string);
+    runtimeHost?: SlexKitMarkdownRuntimeHost;
+    theme?: ThemeMode;
+    showSource?: boolean;
+    sourceLabel?: string;
+    previewLabel?: string;
+    className?: string;
+    onError?: (error: unknown, source: string) => void;
+};
+export type SlexKitTiptapNodeViewOptions = Required<Pick<SlexKitTiptapOptions, "showSource" | "sourceLabel" | "previewLabel">> & Pick<SlexKitTiptapOptions, "artifactId" | "className" | "onError" | "runtimeHost" | "theme">;
+export declare function createSlexKitTiptapExtension(options?: SlexKitTiptapOptions): import("@tiptap/core").Node<import("@tiptap/extension-code-block").CodeBlockOptions, any>;
+export declare const SlexKitTiptapExtension: import("@tiptap/core").Node<import("@tiptap/extension-code-block").CodeBlockOptions, any>;

package/dist/index.js

@@ -0,0 +1,372 @@
+import CodeBlock from "@tiptap/extension-code-block";
+import { createSlexKitMarkdownRuntimeHost, parseSlexSource, } from "slexkit";
+const DEFAULT_OPTIONS = {
+    showSource: true,
+    sourceLabel: "Source",
+    previewLabel: "",
+};
+const PREVIEW_INTERACTIVE_SELECTOR = [
+    "a[href]",
+    "button",
+    "input",
+    "select",
+    "textarea",
+    "[tabindex]:not([tabindex='-1'])",
+    "[role='button']",
+    "[role='checkbox']",
+    "[role='radio']",
+    "[role='slider']",
+    "[role='switch']",
+    "[role='tab']",
+    "[role='textbox']",
+].join(",");
+const editorArtifactIds = new WeakMap();
+let nextArtifactId = 0;
+const sourceOpenStates = new Map();
+const editorArtifactRuntimes = new WeakMap();
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isRenderableSource(value) {
+    if (!isRecord(value))
+        return false;
+    if ("layout" in value)
+        return isRecord(value.layout) && Object.keys(value.layout).length > 0;
+    if ("namespace" in value || "g" in value)
+        return false;
+    return Object.keys(value).some((key) => key.includes(":"));
+}
+function isStateOnlySource(value) {
+    return isRecord(value)
+        && !isRenderableSource(value)
+        && ("slex" in value || "namespace" in value || "g" in value);
+}
+function resolveArtifactId(editor, option) {
+    if (typeof option === "function")
+        return option({ editor });
+    if (typeof option === "string" && option.trim())
+        return option;
+    const existing = editorArtifactIds.get(editor);
+    if (existing)
+        return existing;
+    const artifactId = `tiptap-${++nextArtifactId}`;
+    editorArtifactIds.set(editor, artifactId);
+    return artifactId;
+}
+function codeBlockLanguage(node) {
+    return String(node.attrs.language ?? node.attrs.defaultLanguage ?? "").toLowerCase();
+}
+function sourceOpenStateKey(artifactId, node) {
+    return `${artifactId}::${node.textContent}`;
+}
+function compareNodeViewOrder(a, b) {
+    if (a.dom === b.dom)
+        return 0;
+    const position = a.dom.compareDocumentPosition(b.dom);
+    if (position & Node.DOCUMENT_POSITION_FOLLOWING)
+        return -1;
+    if (position & Node.DOCUMENT_POSITION_PRECEDING)
+        return 1;
+    return 0;
+}
+function resolveArtifactRuntime(editor, artifactId, runtimeHost) {
+    let runtimes = editorArtifactRuntimes.get(editor);
+    if (!runtimes) {
+        runtimes = new Map();
+        editorArtifactRuntimes.set(editor, runtimes);
+    }
+    let runtime = runtimes.get(artifactId);
+    if (!runtime) {
+        runtime = {
+            artifactId,
+            runtimeHost: runtimeHost ?? createSlexKitMarkdownRuntimeHost(),
+            views: new Set(),
+            scheduled: false,
+        };
+        runtimes.set(artifactId, runtime);
+    }
+    return runtime;
+}
+function scheduleArtifactRender(runtime) {
+    if (runtime.scheduled)
+        return;
+    runtime.scheduled = true;
+    queueMicrotask(() => {
+        runtime.scheduled = false;
+        runtime.runtimeHost.disposeArtifact(runtime.artifactId);
+        for (const view of Array.from(runtime.views).sort(compareNodeViewOrder)) {
+            view.renderWithRuntime(runtime.runtimeHost);
+        }
+    });
+}
+function unregisterArtifactRuntime(editor, runtime, view) {
+    runtime.views.delete(view);
+    if (runtime.views.size > 0) {
+        scheduleArtifactRender(runtime);
+        return;
+    }
+    runtime.runtimeHost.disposeArtifact(runtime.artifactId);
+    editorArtifactRuntimes.get(editor)?.delete(runtime.artifactId);
+}
+function createElement(doc, tag, className) {
+    const element = doc.createElement(tag);
+    if (className)
+        element.className = className;
+    return element;
+}
+function stopPropagation(event) {
+    event.stopPropagation();
+}
+function stopProseMirrorEvents(element, events) {
+    for (const eventName of events)
+        element.addEventListener(eventName, stopPropagation);
+}
+function focusPreviewInteractiveTarget(event) {
+    const target = event.target;
+    const targetElement = target instanceof Element ? target : target instanceof Node ? target.parentElement : null;
+    const interactive = targetElement?.closest(PREVIEW_INTERACTIVE_SELECTOR);
+    if (interactive instanceof HTMLElement)
+        interactive.focus({ preventScroll: true });
+}
+function markPreviewInteractive(preview, force = false) {
+    if (preview.getAttribute("contenteditable") !== "false") {
+        preview.setAttribute("contenteditable", "false");
+    }
+    preview.querySelectorAll(PREVIEW_INTERACTIVE_SELECTOR).forEach((element) => {
+        if (element instanceof HTMLElement && (force || element.getAttribute("contenteditable") !== "true")) {
+            if (force)
+                element.removeAttribute("contenteditable");
+            element.setAttribute("contenteditable", "true");
+        }
+    });
+}
+function schedulePreviewInteractiveMark(preview) {
+    markPreviewInteractive(preview);
+    queueMicrotask(() => markPreviewInteractive(preview, true));
+    const win = preview.ownerDocument.defaultView;
+    win?.setTimeout(() => markPreviewInteractive(preview, true), 0);
+    win?.requestAnimationFrame(() => markPreviewInteractive(preview, true));
+}
+function renderError(error, source, container) {
+    const doc = container.ownerDocument || document;
+    const alert = createElement(doc, "div", "slex-tiptap-error");
+    alert.setAttribute("role", "alert");
+    const title = createElement(doc, "div", "slex-tiptap-error-title");
+    title.textContent = "Failed to render SlexKit";
+    const message = createElement(doc, "div", "slex-tiptap-error-message");
+    message.textContent = error instanceof Error ? error.message : String(error);
+    alert.append(title, message);
+    if (source) {
+        const excerpt = doc.createElement("pre");
+        excerpt.className = "slex-tiptap-error-source";
+        excerpt.textContent = source;
+        alert.append(excerpt);
+    }
+    container.replaceChildren(alert);
+}
+class PlainCodeBlockNodeView {
+    dom;
+    contentDOM;
+    constructor(node, doc) {
+        const language = codeBlockLanguage(node);
+        this.dom = doc.createElement("pre");
+        this.dom.className = "slex-tiptap-code-block";
+        this.contentDOM = doc.createElement("code");
+        if (language)
+            this.contentDOM.className = `language-${language}`;
+        this.dom.append(this.contentDOM);
+    }
+    update(node) {
+        if (node.type.name !== "codeBlock" || codeBlockLanguage(node) === "slex")
+            return false;
+        const language = codeBlockLanguage(node);
+        this.contentDOM.className = language ? `language-${language}` : "";
+        return true;
+    }
+}
+class SlexKitCodeBlockNodeView {
+    node;
+    dom;
+    contentDOM;
+    artifactId;
+    editor;
+    options;
+    preview;
+    runtime;
+    interactiveObserver;
+    renderToken = 0;
+    constructor(node, props, options) {
+        this.node = node;
+        this.options = options;
+        this.editor = props.editor;
+        this.artifactId = resolveArtifactId(props.editor, options.artifactId);
+        this.runtime = resolveArtifactRuntime(props.editor, this.artifactId, options.runtimeHost);
+        this.runtime.views.add(this);
+        const doc = props.view.dom.ownerDocument || document;
+        this.dom = createElement(doc, "div", ["slex-tiptap-block", options.className].filter(Boolean).join(" "));
+        this.dom.dataset.language = "slex";
+        this.dom.setAttribute("data-slexkit-tiptap", "true");
+        const label = options.previewLabel.trim() ? createElement(doc, "div", "slex-tiptap-label") : undefined;
+        if (label)
+            label.textContent = options.previewLabel;
+        this.preview = createElement(doc, "div", "slex-tiptap-preview");
+        this.preview.setAttribute("contenteditable", "false");
+        this.preview.addEventListener("pointerdown", focusPreviewInteractiveTarget, { capture: true });
+        this.preview.addEventListener("mousedown", focusPreviewInteractiveTarget, { capture: true });
+        this.preview.addEventListener("click", focusPreviewInteractiveTarget, { capture: true });
+        if (typeof MutationObserver !== "undefined") {
+            this.interactiveObserver = new MutationObserver(() => schedulePreviewInteractiveMark(this.preview));
+            this.interactiveObserver.observe(this.preview, { childList: true, subtree: true });
+        }
+        this.contentDOM = doc.createElement("code");
+        this.contentDOM.className = "language-slex";
+        const pre = doc.createElement("pre");
+        pre.append(this.contentDOM);
+        if (options.showSource) {
+            const openStateKey = sourceOpenStateKey(this.artifactId, node);
+            const sourceShell = createElement(doc, "div", "slex-tiptap-source");
+            const sourceToggle = doc.createElement("button");
+            sourceToggle.type = "button";
+            sourceToggle.className = "slex-tiptap-source-toggle slex-tiptap-source-summary";
+            sourceToggle.textContent = options.sourceLabel;
+            sourceToggle.setAttribute("aria-expanded", "false");
+            let sourceOpen = sourceOpenStates.get(openStateKey) ?? false;
+            const setSourceOpen = (open) => {
+                sourceOpen = open;
+                sourceOpenStates.set(openStateKey, open);
+                pre.hidden = !open;
+                sourceShell.dataset.open = open ? "true" : "false";
+                sourceToggle.setAttribute("aria-expanded", String(open));
+                for (const delay of [0, 16, 50, 100, 200]) {
+                    sourceShell.ownerDocument.defaultView?.setTimeout(() => {
+                        pre.hidden = !sourceOpen;
+                        sourceShell.dataset.open = sourceOpen ? "true" : "false";
+                        sourceToggle.setAttribute("aria-expanded", String(sourceOpen));
+                    }, delay);
+                }
+            };
+            const enforceSourceOpen = (event) => {
+                event.preventDefault();
+                event.stopPropagation();
+                setSourceOpen(!sourceOpen);
+            };
+            const stopSourceClick = (event) => {
+                event.preventDefault();
+                event.stopPropagation();
+            };
+            stopProseMirrorEvents(sourceToggle, ["mousedown", "keydown"]);
+            sourceToggle.addEventListener("pointerdown", enforceSourceOpen, { capture: true });
+            sourceToggle.addEventListener("click", stopSourceClick, { capture: true });
+            setSourceOpen(sourceOpen);
+            sourceShell.append(sourceToggle, pre);
+            this.dom.append(...[label, this.preview, sourceShell].filter((element) => !!element));
+        }
+        else {
+            const sourceShell = createElement(doc, "div", "slex-tiptap-source slex-tiptap-source-hidden");
+            sourceShell.hidden = true;
+            sourceShell.append(pre);
+            this.dom.append(...[label, this.preview, sourceShell].filter((element) => !!element));
+        }
+        scheduleArtifactRender(this.runtime);
+    }
+    update(node) {
+        if (node.type.name !== "codeBlock" || codeBlockLanguage(node) !== "slex")
+            return false;
+        this.node = node;
+        this.renderSoon();
+        return true;
+    }
+    destroy() {
+        this.interactiveObserver?.disconnect();
+        this.preview.replaceChildren();
+        unregisterArtifactRuntime(this.editor, this.runtime, this);
+    }
+    stopEvent(event) {
+        const target = event.target;
+        if (!(target instanceof Node))
+            return false;
+        if (this.preview.contains(target))
+            return true;
+        const targetElement = target instanceof HTMLElement ? target : target.parentElement;
+        if (targetElement?.closest(".slex-tiptap-source-summary")) {
+            return true;
+        }
+        return false;
+    }
+    ignoreMutation(mutation) {
+        const target = mutation.target;
+        if (this.preview.contains(target))
+            return true;
+        if (target === this.contentDOM || this.contentDOM.contains(target))
+            return false;
+        const targetElement = target instanceof Element ? target : target.parentElement;
+        if (targetElement?.closest(".slex-tiptap-source"))
+            return true;
+        return false;
+    }
+    source() {
+        return this.node.textContent;
+    }
+    renderSoon() {
+        const token = ++this.renderToken;
+        queueMicrotask(() => {
+            if (token !== this.renderToken)
+                return;
+            scheduleArtifactRender(this.runtime);
+        });
+    }
+    renderWithRuntime(runtimeHost) {
+        const source = this.source();
+        this.dom.hidden = false;
+        this.preview.hidden = false;
+        this.preview.replaceChildren();
+        const parsed = parseSlexSource(source);
+        if (!parsed.ok) {
+            renderError(parsed.error, source, this.preview);
+            this.options.onError?.(parsed.error, source);
+            return;
+        }
+        try {
+            runtimeHost.mountBlock({
+                artifactId: this.artifactId,
+                source,
+                container: this.preview,
+                theme: this.options.theme,
+            });
+            schedulePreviewInteractiveMark(this.preview);
+        }
+        catch (error) {
+            renderError(error, source, this.preview);
+            this.options.onError?.(error, source);
+            return;
+        }
+        if (isStateOnlySource(parsed.value) && !this.preview.querySelector(".slexkit-root")) {
+            if (!this.options.showSource) {
+                this.dom.hidden = true;
+                this.preview.hidden = true;
+                return;
+            }
+            const placeholder = createElement(this.preview.ownerDocument || document, "div", "slex-tiptap-state");
+            placeholder.textContent = "State block";
+            this.preview.append(placeholder);
+        }
+    }
+}
+export function createSlexKitTiptapExtension(options = {}) {
+    const resolvedOptions = {
+        ...DEFAULT_OPTIONS,
+        ...options,
+    };
+    return CodeBlock.extend({
+        addNodeView() {
+            return (props) => {
+                const doc = props.view.dom.ownerDocument || document;
+                if (codeBlockLanguage(props.node) !== "slex") {
+                    return new PlainCodeBlockNodeView(props.node, doc);
+                }
+                return new SlexKitCodeBlockNodeView(props.node, props, resolvedOptions);
+            };
+        },
+    });
+}
+export const SlexKitTiptapExtension = createSlexKitTiptapExtension();

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@slexkit/tiptap",
+  "version": "0.3.3",
+  "description": "Tiptap extension for SlexKit fenced UI blocks.",
+  "author": "SlexKit contributors",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/slexkit/slexkit.git",
+    "directory": "packages/tiptap"
+  },
+  "homepage": "https://github.com/slexkit/slexkit/tree/main/packages/tiptap#readme",
+  "bugs": {
+    "url": "https://github.com/slexkit/slexkit/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./style.css": "./style.css"
+  },
+  "files": [
+    "dist/",
+    "style.css",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun run scripts/build.ts"
+  },
+  "keywords": [
+    "slexkit",
+    "tiptap",
+    "prosemirror",
+    "markdown",
+    "editor"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@tiptap/core": "^3.0.0",
+    "@tiptap/extension-code-block": "^3.0.0",
+    "@tiptap/markdown": "^3.0.0",
+    "@tiptap/pm": "^3.0.0",
+    "slexkit": "^0.3.3"
+  },
+  "peerDependenciesMeta": {
+    "@tiptap/markdown": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tiptap/core": "^3.27.1",
+    "@tiptap/extension-code-block": "^3.27.1",
+    "@tiptap/markdown": "^3.27.1",
+    "@tiptap/pm": "^3.27.1",
+    "@tiptap/starter-kit": "^3.27.1",
+    "slexkit": "file:../.."
+  }
+}

package/style.css

@@ -0,0 +1,100 @@
+.slex-tiptap-block {
+  display: grid;
+  gap: 0.5rem;
+  margin: 1.25rem 0;
+}
+
+.slex-tiptap-label {
+  color: var(--muted-foreground, #64748b);
+  font-size: 0.8125rem;
+  font-weight: 650;
+  line-height: 1.3;
+}
+
+.slex-tiptap-preview[contenteditable="false"] {
+  outline: none;
+}
+
+.slex-tiptap-source {
+  display: grid;
+  justify-items: start;
+}
+
+.slex-tiptap-source-toggle {
+  display: inline-flex;
+  align-items: center;
+  min-height: 1.75rem;
+  border: 1px solid var(--border, #dbe3ef);
+  border-radius: calc(var(--radius, 0.5rem) - 2px);
+  cursor: pointer;
+  padding: 0 0.625rem;
+  color: var(--muted-foreground, #64748b);
+  background: var(--background, #ffffff);
+  font-size: 0.75rem;
+  font-weight: 650;
+  font-family: inherit;
+  line-height: 1;
+}
+
+.slex-tiptap-source pre,
+.slex-tiptap-code-block {
+  overflow: auto;
+  width: 100%;
+  margin: 0.5rem 0 0;
+  padding: 0.75rem;
+  border: 1px solid var(--border, #dbe3ef);
+  border-radius: var(--radius, 0.5rem);
+  background: var(--muted, #f1f5f9);
+  font: 0.875rem/1.55 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  white-space: pre;
+}
+
+.slex-tiptap-code-block {
+  margin: 1rem 0;
+}
+
+.slex-tiptap-state {
+  display: inline-flex;
+  align-items: center;
+  min-height: 1.5rem;
+  padding: 0 0.5rem;
+  border: 0;
+  border-radius: calc(var(--radius, 0.5rem) - 2px);
+  color: var(--muted-foreground, #64748b);
+  background: var(--muted, #f1f5f9);
+  font-size: 0.75rem;
+  font-weight: 650;
+}
+
+.slex-tiptap-error {
+  display: grid;
+  gap: 0.5rem;
+  padding: 0.75rem;
+  border: 1px solid var(--destructive, #dc2626);
+  border-radius: var(--radius, 0.5rem);
+  color: var(--destructive, #dc2626);
+  background: color-mix(in srgb, var(--destructive, #dc2626) 8%, transparent);
+}
+
+.slex-tiptap-error-title {
+  font-weight: 750;
+}
+
+.slex-tiptap-error-message {
+  color: inherit;
+  font-size: 0.875rem;
+}
+
+.slex-tiptap-error-source {
+  overflow: auto;
+  margin: 0;
+  color: inherit;
+  font: 0.8125rem/1.5 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  white-space: pre;
+}
+
+.slex-tiptap-block[hidden],
+.slex-tiptap-preview[hidden],
+.slex-tiptap-source[hidden] {
+  display: none;
+}