@sciflow/editor-start 0.0.1-beta

package/dist/lib/editor-element.js

@@ -0,0 +1,681 @@
+/**
+ * @module editor-element
+ *
+ * Developer overview:
+ * --------------------
+ * `SciFlowEditorElement` is the reference web component that embeds the
+ * SciFlow editor runtime. The implementation illustrates how to:
+ *
+ * - bootstrap `@sciflow/editor-core` inside an arbitrary host UI
+ * - bridge external state (props/attributes) into the ProseMirror document
+ * - expose the command runner and view handles for surrounding widgets
+ * - surface lifecycle events so other controls can observe the editor
+ *
+ * When porting the editor to another framework (React, Vue, Svelte, …) follow
+ * the same high-level flow:
+ *
+ * 1. Create an `Editor` instance with your feature set.
+ * 2. Mount it into a DOM container supplied by your framework.
+ * 3. Subscribe to `onDoc`, `onSelection`, and other hooks you care about.
+ * 4. Re-dispatch the updates (events, signals, stores).
+ * 5. Dispose of everything when the host view unmounts.
+ *
+ * The rest of this file is heavily documented to map those steps to concrete
+ * code. Treat it as a cookbook for your own integration.
+ */
+import { __decorate } from "tslib";
+import { css, html, unsafeCSS, LitElement } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+import { Editor, SourceField, citationFeature, figureFeature, headingFeature, markFormattingFeature, tableFeature, } from '@sciflow/editor-core';
+import { manuscript as manuscriptSchema } from '@sciflow/schema-prosemirror';
+import editorStyles from './editor-element.css?inline';
+import { applyThemeStylesToRoot, subscribeToSciFlowTheme } from './theme.js';
+/**
+ * Custom element that owns a SciFlow editor instance.
+ *
+ * Responsibilities:
+ * - translate properties (`doc`, `initialContent`) into an editor snapshot
+ * - manage the underlying ProseMirror view lifecycle
+ * - publish high-level change events for host applications
+ * - expose convenience getters (`commands`, `editorView`) for toolbars
+ *
+ * The element intentionally keeps all side effects inside class methods so it
+ * can be reproduced in other UI frameworks with the same sequencing.
+ */
+let SciFlowEditorElement = class SciFlowEditorElement extends LitElement {
+    constructor() {
+        super(...arguments);
+        /**
+         * Initial ProseMirror document to render.
+         * Provide a `@sciflow/schema-prosemirror` node instance.
+         */
+        this.initialContent = null;
+        /**
+         * JSON representation of a document to render.
+         * Provide a `SciFlowDocJSON` value, typically sourced from persistence.
+         */
+        this.doc = null;
+        /**
+         * Optional list of editor features to load. When not provided, defaults to
+         * the bundled demo feature set (figures, citations, mark formatting, headings).
+         */
+        this.features = null;
+        /**
+         * Optional CSS injected into the shadow root after the built-in styles.
+         * Can be set declaratively via property binding or imperatively via setShadowStyles().
+         *
+         * Note: Direct property assignment applies styles asynchronously via Lit's lifecycle.
+         * For immediate application (e.g., dynamic decorations), use setShadowStyles() instead.
+         */
+        this._shadowStyles = null;
+        this._shadowStylesAppliedExternally = false;
+        /** Heading text rendered in the introductory document. */
+        this.headingText = 'Moby-Dick: A Study in Obsession';
+        /** Paragraph text used when no initial content is provided. */
+        this.placeholder = 'Introduce Ishmael and the enigmatic Captain Ahab…';
+        this.view = null;
+        this.pendingOps = [];
+        this.pendingOpsFromTransform = false;
+        this.suppressFeatureUpdate = false;
+        this.deferInitializationForDoc = false;
+        this.shadowStyleElements = [];
+        this.themeStyleElements = [];
+    }
+    get shadowStyles() {
+        return this._shadowStyles;
+    }
+    set shadowStyles(styles) {
+        const oldValue = this._shadowStyles;
+        this._shadowStyles = styles;
+        this._shadowStylesAppliedExternally = false; // Mark as Lit-managed
+        this.requestUpdate('shadowStyles', oldValue);
+    }
+    /** Access the underlying ProseMirror view instance. */
+    get editorView() {
+        return this.view;
+    }
+    /** Access SciFlow command helpers bound to the current editor view. */
+    get commands() {
+        return this.editor?.getCommands() ?? null;
+    }
+    /** Get read-only access to the document structure for traversal. */
+    get document() {
+        return this.editor?.getDocument() ?? null;
+    }
+    /** Get position utilities for coordinate mapping. */
+    get positions() {
+        return {
+            coordsAtPos: (pos) => this.editor?.coordsAtPos(pos) ?? null,
+            resolve: (pos) => this.editor?.resolvePosition(pos) ?? null,
+        };
+    }
+    /** Get plugin management utilities. */
+    get plugins() {
+        return {
+            getState: (key) => this.editor?.getPluginState(key) ?? null,
+            dispatchMeta: (key, meta) => this.editor?.dispatchPluginMeta(key, meta) ?? false,
+        };
+    }
+    /** Get editor DOM utilities. */
+    get dom() {
+        return {
+            getBoundingRect: () => this.editor?.getBoundingRect() ?? null,
+            dispatchEvent: (event) => this.editor?.dispatchEvent(event) ?? false,
+        };
+    }
+    static { this.styles = css `${unsafeCSS(editorStyles)}`; }
+    render() {
+        return html `<div class="editor" part="editor"></div>`;
+    }
+    /** Lit lifecycle hook: start the editor once the DOM container exists. */
+    async firstUpdated() {
+        this.applyShadowStyles();
+        if (this.shouldDeferInitialization()) {
+            this.deferInitializationForDoc = true;
+            return;
+        }
+        await this.initializeView();
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.themeUnsub = subscribeToSciFlowTheme((cssTexts) => {
+            this.themeStyleElements = applyThemeStylesToRoot(this.renderRoot, this.themeStyleElements, cssTexts);
+            this.applyShadowStyles();
+        });
+        queueMicrotask(() => {
+            this.debugTestLog('connected microtask', { hasEditor: !!this.editor });
+            if (this.editor) {
+                return;
+            }
+            try {
+                const initialDoc = this.resolveInitialDoc();
+                this.dispatchEditorChange(initialDoc.toJSON(), [], []);
+            }
+            catch {
+                // Ignore errors during eager ready dispatch; initialization will retry in firstUpdated.
+            }
+        });
+    }
+    /**
+     * React to property changes coming from the host application.
+     * When `doc` changes we push the new snapshot into the running editor.
+     */
+    updated(changedProperties) {
+        super.updated(changedProperties);
+        if (this.deferInitializationForDoc && this.doc !== null) {
+            this.deferInitializationForDoc = false;
+            void this.initializeView();
+        }
+        if (!this.suppressFeatureUpdate && changedProperties.has('features') && this.editor) {
+            void this.reinitializeEditor();
+        }
+        // Only apply shadowStyles if changed via property (not via setShadowStyles method)
+        if (changedProperties.has('shadowStyles') && !this._shadowStylesAppliedExternally) {
+            this.applyShadowStyles();
+        }
+        // Reset flag for next update
+        if (changedProperties.has('shadowStyles')) {
+            this._shadowStylesAppliedExternally = false;
+        }
+        if (changedProperties.has('doc')) {
+            this.applyDocUpdate();
+        }
+    }
+    /**
+     * Cleanly dispose the editor when the element leaves the DOM.
+     * Other frameworks should execute the same logic in their unmount hook.
+     */
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.themeUnsub?.();
+        this.themeUnsub = undefined;
+        this.destroyEditor();
+        this.view = null;
+    }
+    /**
+     * Public helper to update the feature list and reconfigure the editor.
+     * Consumers (including the demo) can call this to immediately apply changes.
+     */
+    async configureFeatures(features) {
+        this.suppressFeatureUpdate = true;
+        this.features = [...features];
+        if (!this.editor) {
+            this.suppressFeatureUpdate = false;
+            return;
+        }
+        try {
+            await this.reinitializeEditor();
+        }
+        finally {
+            this.suppressFeatureUpdate = false;
+        }
+    }
+    /**
+     * Bootstrap the SciFlow editor inside this component's shadow DOM.
+     * Resolves a mount point, creates the editor instance, and wires listeners.
+     */
+    getDefaultFeatures() {
+        return [citationFeature, markFormattingFeature, headingFeature, figureFeature, tableFeature];
+    }
+    getActiveFeatures() {
+        return this.features ?? this.getDefaultFeatures();
+    }
+    shouldDeferInitialization() {
+        return this.doc === null && this.initialContent === null;
+    }
+    async initializeView() {
+        this.debugTestLog('initializeView invoked');
+        if (this.view) {
+            return;
+        }
+        const mountPoint = this.renderRoot.querySelector('.editor');
+        if (!mountPoint) {
+            this.debugTestLog('initializeView: mount point missing');
+            return;
+        }
+        const initialDoc = this.resolveInitialDoc();
+        const docInput = this.doc;
+        const initialFiles = this.isExternalDocUpdate(docInput) && Array.isArray(docInput.files) ? docInput.files : [];
+        const initialReferences = this.isExternalDocUpdate(docInput) && Array.isArray(docInput.references) ? docInput.references : [];
+        const activeFeatures = this.getActiveFeatures();
+        const externalSelection = this.isExternalDocUpdate(docInput) ? docInput.selection : undefined;
+        const initialVersion = this.isExternalDocUpdate(docInput) && typeof docInput.version === 'number' ? docInput.version : undefined;
+        const initialSelection = this.initialSelection ?? externalSelection;
+        try {
+            const editor = await Editor.create({
+                docId: `lit-${Math.random().toString(36).slice(2)}`,
+                sync: this.createLocalSync(initialDoc),
+                initialDoc: initialDoc.toJSON(),
+                initialFiles,
+                initialReferences,
+                features: activeFeatures,
+                initialSelection,
+                initialVersion,
+                transformOps: (snapshot, ops) => {
+                    this.capturePendingOps(ops, 'transform');
+                    return snapshot;
+                },
+            });
+            if (!this.isConnected) {
+                editor.destroy();
+                return;
+            }
+            this.editor = editor;
+            editor.mount(mountPoint);
+            this.view = editor.getView();
+            this.debugTestLog('editor mounted', { hasView: !!this.view });
+            const runner = editor.getCommands();
+            this.debugTestLog('command keys', runner ? Object.keys(runner.commands) : null);
+            this.docUnsub = editor.onDoc((doc) => {
+                this.debugTestLog('dispatching editor-change', { ops: this.pendingOps.length });
+                const files = editor.getFiles();
+                this.dispatchEditorChange(doc, this.pendingOps, files);
+                this.pendingOps = [];
+                this.pendingOpsFromTransform = false;
+            });
+            this.selectionUnsub = editor.onSelection((selection) => {
+                this.dispatchSelectionChange(selection);
+            });
+            this.validationUnsub = editor.onValidation(() => undefined);
+            this.dispatchEditorReady();
+            this.initialSelection = undefined;
+        }
+        catch (error) {
+            console.error('[sciflow-editor] failed to initialize editor', error);
+            throw error;
+        }
+    }
+    /** Apply the `doc` attribute to the running editor instance. */
+    applyDocUpdate() {
+        if (!this.editor) {
+            return;
+        }
+        const update = this.buildSyncUpdate(this.doc);
+        if (!update) {
+            return;
+        }
+        this.pendingOps = [];
+        this.pendingOpsFromTransform = false;
+        this.editor.updateFromSync(update);
+    }
+    /**
+     * Minimal in-memory sync strategy used for the demo element.
+     * Reimplementations typically swap this out for their persistence layer.
+     */
+    createLocalSync(initialDoc) {
+        const docJSON = initialDoc.toJSON();
+        return {
+            async load() {
+                return {
+                    doc: docJSON,
+                    version: 0,
+                    selection: { anchor: 0, head: 0 },
+                    files: [],
+                    references: [],
+                };
+            },
+            applyExternal(ops, meta) {
+                void ops;
+                void meta;
+            },
+            applyLocal: (ops, meta) => {
+                void meta;
+                if (ops.length === 0) {
+                    return;
+                }
+                this.capturePendingOps(ops, 'sync');
+            },
+            dispose() {
+                // No resources to release for the in-memory strategy.
+            },
+        };
+    }
+    isExternalDocUpdate(value) {
+        return (typeof value === 'object' &&
+            value !== null &&
+            'doc' in value &&
+            typeof value.doc !== 'undefined');
+    }
+    extractDocFromInput(input) {
+        if (!input) {
+            return null;
+        }
+        return this.isExternalDocUpdate(input) ? input.doc : input;
+    }
+    buildSyncUpdate(input) {
+        if (!input) {
+            return null;
+        }
+        if (this.isExternalDocUpdate(input)) {
+            const update = {
+                doc: input.doc,
+            };
+            if (input.selection) {
+                update.selection = input.selection;
+            }
+            if (typeof input.version === 'number') {
+                update.version = input.version;
+            }
+            if (Array.isArray(input.files)) {
+                update.files = input.files;
+            }
+            if (Array.isArray(input.references)) {
+                update.references = input.references;
+            }
+            return update;
+        }
+        return { doc: input };
+    }
+    /**
+     * Determine which document should be loaded on startup.
+     * Preference order: externally supplied JSON, provided PM node, fallback.
+     */
+    resolveInitialDoc() {
+        const docInput = this.extractDocFromInput(this.doc);
+        if (docInput) {
+            return this.docFromJSON(docInput);
+        }
+        if (this.initialContent) {
+            return this.initialContent;
+        }
+        return this.createDefaultDoc();
+    }
+    /**
+     * Build the bundled demonstration document (heading + paragraph + figure).
+     * Feel free to replace this when embedding in your own product.
+     */
+    createDefaultDoc() {
+        const heading = manuscriptSchema.node('heading', { level: 1 }, [manuscriptSchema.text(this.headingText || 'Moby-Dick: A Study in Obsession')]);
+        const introText = (this.placeholder ?? '').trim() || 'Introduce Ishmael and the enigmatic Captain Ahab…';
+        const citationSource = SourceField.toString([{ id: '299' }]) ?? '';
+        const citation = manuscriptSchema.node('citation', { id: 'citation-mobydick', style: 'apa', source: citationSource }, [manuscriptSchema.text('(Melville, 2018)')]);
+        const paragraph = manuscriptSchema.node('paragraph', undefined, [
+            manuscriptSchema.text(`${introText} `),
+            citation,
+            manuscriptSchema.text(' offers a canonical touchpoint for exploring literary obsession.'),
+        ]);
+        // Create a figure with a caption
+        const captionParagraph = manuscriptSchema.node('paragraph', undefined, [
+            manuscriptSchema.text('A figure caption demonstrating the figure node view.'),
+        ]);
+        const caption = manuscriptSchema.node('caption', undefined, [captionParagraph]);
+        const figure = manuscriptSchema.node('figure', {
+            id: 'demo-figure',
+            src: 'https://placehold.co/600x400',
+            alt: 'Demo figure',
+            type: 'figure',
+            orientation: 'landscape',
+        }, [caption]);
+        return manuscriptSchema.node('doc', undefined, [heading, paragraph, figure]);
+    }
+    /**
+     * Safely convert SciFlow document JSON back into a ProseMirror node.
+     * Falls back to the default document when parsing fails.
+     */
+    docFromJSON(doc) {
+        try {
+            const json = doc;
+            const sanitized = this.sanitizeDocJSON(json);
+            return manuscriptSchema.nodeFromJSON(sanitized);
+        }
+        catch (error) {
+            console.warn('[sciflow-editor] received invalid doc JSON; falling back to default document.', error);
+            return this.createDefaultDoc();
+        }
+    }
+    /**
+     * Remove or fix malformed nodes before handing JSON to the schema parser.
+     * - Drops empty xref/link nodes (no content).
+     * - Drops xref/link nodes that target missing ids.
+     * This avoids ProseMirror widget creation paths that receive undefined DOM.
+     */
+    sanitizeDocJSON(doc) {
+        const ids = new Set();
+        const collectIds = (node) => {
+            if (!node || typeof node !== 'object') {
+                return;
+            }
+            const id = node?.attrs?.id;
+            if (typeof id === 'string') {
+                ids.add(id);
+            }
+            if (Array.isArray(node?.content)) {
+                node.content.forEach((child) => collectIds(child));
+            }
+        };
+        collectIds(doc);
+        const sanitizeNode = (node) => {
+            if (!node || typeof node !== 'object') {
+                return node;
+            }
+            const rawContent = Array.isArray(node.content) ? node.content : [];
+            const content = rawContent
+                .map((child) => sanitizeNode(child))
+                .filter((child) => Boolean(child));
+            if (node.type === 'link') {
+                const href = node?.attrs?.href;
+                const target = typeof href === 'string' && href.startsWith('#') ? href.slice(1) : null;
+                const hasContent = content.length > 0;
+                const missingTarget = Boolean(target && !ids.has(target));
+                if (!hasContent || missingTarget) {
+                    console.warn('[sciflow-editor] dropping invalid link node', {
+                        href,
+                        hasContent,
+                        missingTarget,
+                    });
+                    return null;
+                }
+            }
+            const sanitized = { ...node };
+            if (rawContent.length > 0) {
+                sanitized.content = content;
+            }
+            else {
+                delete sanitized.content;
+            }
+            return sanitized;
+        };
+        return sanitizeNode(doc) ?? doc;
+    }
+    /**
+     * Emit a high-level `editor-change` event with the new document snapshot.
+     * Applications can listen and update their stores or routing state.
+     */
+    dispatchEditorChange(doc, operations, files) {
+        this.debugTestLog('editor-change event', { doc, operations });
+        this.dispatchEvent(new CustomEvent('editor-change', {
+            detail: { doc, operations, files, references: this.editor?.getReferences() ?? [] },
+            bubbles: true,
+            composed: true,
+        }));
+    }
+    /**
+     * Emit `editor-selection-change` whenever the cursor or selection updates.
+     * Handy for co-ordinating ancillary UI like reference or outline panels.
+     */
+    dispatchSelectionChange(selection) {
+        this.dispatchEvent(new CustomEvent('editor-selection-change', {
+            detail: selection,
+            bubbles: true,
+            composed: true,
+        }));
+    }
+    /** Notify listeners that the editor has mounted and is ready for input. */
+    dispatchEditorReady() {
+        this.dispatchEvent(new CustomEvent('editor-ready', {
+            bubbles: true,
+            composed: true,
+        }));
+    }
+    /**
+     * Tear down subscriptions and dispose the editor instance.
+     * Called automatically when the element disconnects.
+     */
+    async reinitializeEditor() {
+        if (!this.isConnected) {
+            return;
+        }
+        const currentDoc = this.editor?.getDoc() ?? null;
+        const currentSelection = this.editor?.getSelection() ?? null;
+        const currentFiles = this.editor?.getFiles() ?? [];
+        const currentVersion = this.editor?.getVersion();
+        this.destroyEditor();
+        this.view = null;
+        if (currentDoc) {
+            const nextDoc = {
+                doc: currentDoc,
+                files: currentFiles,
+            };
+            if (currentSelection) {
+                nextDoc.selection = currentSelection;
+            }
+            if (typeof currentVersion === 'number') {
+                nextDoc.version = currentVersion;
+            }
+            this.doc = nextDoc;
+        }
+        this.initialSelection = currentSelection ?? this.initialSelection;
+        await this.initializeView();
+    }
+    /**
+     * Convenience method to immediately apply shadow root styles.
+     * Recommended for dynamic style injection after editor initialization.
+     *
+     * @example
+     * ```typescript
+     * // Add styles for ProseMirror decorations dynamically
+     * editor.setShadowStyles([`
+     *   .my-annotation {
+     *     background: rgba(255, 200, 0, 0.3);
+     *     border-bottom: 2px solid orange;
+     *   }
+     * `]);
+     * ```
+     */
+    setShadowStyles(styles) {
+        const oldValue = this._shadowStyles;
+        this._shadowStyles = styles;
+        this._shadowStylesAppliedExternally = true; // Mark as externally managed
+        // Apply immediately (synchronous)
+        this.applyShadowStyles();
+        // Notify Lit of the change (for re-renders, but won't re-apply in updated())
+        this.requestUpdate('shadowStyles', oldValue);
+    }
+    destroyEditor() {
+        this.docUnsub?.();
+        this.selectionUnsub?.();
+        this.validationUnsub?.();
+        this.docUnsub = undefined;
+        this.selectionUnsub = undefined;
+        this.validationUnsub = undefined;
+        this.editor?.destroy();
+        this.editor = undefined;
+        this.pendingOps = [];
+        this.pendingOpsFromTransform = false;
+    }
+    capturePendingOps(ops, source) {
+        if (!ops || ops.length === 0) {
+            return;
+        }
+        if (source === 'transform') {
+            this.pendingOps = [...ops];
+            this.pendingOpsFromTransform = true;
+            return;
+        }
+        if (this.pendingOpsFromTransform) {
+            this.pendingOps = [...ops];
+            this.pendingOpsFromTransform = false;
+            return;
+        }
+        this.pendingOps = [...this.pendingOps, ...ops];
+    }
+    applyShadowStyles() {
+        const root = this.renderRoot;
+        if (!root || typeof root.appendChild !== 'function') {
+            return;
+        }
+        for (const styleEl of this.shadowStyleElements) {
+            if (styleEl.parentNode === root) {
+                root.removeChild(styleEl);
+            }
+        }
+        this.shadowStyleElements = [];
+        const cssTexts = this.normalizeShadowStyles(this.shadowStyles);
+        if (cssTexts.length === 0) {
+            return;
+        }
+        for (const cssText of cssTexts) {
+            const styleEl = document.createElement('style');
+            styleEl.textContent = cssText;
+            root.appendChild(styleEl);
+            this.shadowStyleElements.push(styleEl);
+        }
+    }
+    normalizeShadowStyles(styles) {
+        if (!styles) {
+            return [];
+        }
+        const list = Array.isArray(styles) ? styles : [styles];
+        const cssTexts = [];
+        for (const entry of list) {
+            if (!entry) {
+                continue;
+            }
+            if (typeof entry === 'string') {
+                const trimmed = entry.trim();
+                if (trimmed) {
+                    cssTexts.push(trimmed);
+                }
+                continue;
+            }
+            if (typeof CSSStyleSheet !== 'undefined' && entry instanceof CSSStyleSheet) {
+                const serialized = this.extractCssFromSheet(entry);
+                if (serialized) {
+                    cssTexts.push(serialized);
+                }
+            }
+        }
+        return cssTexts;
+    }
+    extractCssFromSheet(sheet) {
+        try {
+            const rules = Array.from(sheet.cssRules ?? []);
+            const cssText = rules.map((rule) => rule.cssText).join('\n');
+            return cssText.trim() ? cssText : null;
+        }
+        catch (error) {
+            console.warn('[sciflow-editor] unable to read supplied CSSStyleSheet', error);
+            return null;
+        }
+    }
+    debugTestLog(message, payload) {
+        const isDebug = (typeof process !== 'undefined' && process.env?.DEBUG_TESTS === 'true') ||
+            (typeof import.meta !== 'undefined' && import.meta.env?.DEBUG_TESTS === 'true');
+        if (!isDebug) {
+            return;
+        }
+        console.log('[sciflow-editor]', message, payload ?? '');
+    }
+};
+__decorate([
+    property({ attribute: false })
+], SciFlowEditorElement.prototype, "initialContent", void 0);
+__decorate([
+    property({ attribute: false })
+], SciFlowEditorElement.prototype, "doc", void 0);
+__decorate([
+    property({ attribute: false })
+], SciFlowEditorElement.prototype, "features", void 0);
+__decorate([
+    property({ attribute: false })
+], SciFlowEditorElement.prototype, "shadowStyles", null);
+__decorate([
+    property({ type: String })
+], SciFlowEditorElement.prototype, "headingText", void 0);
+__decorate([
+    property({ type: String })
+], SciFlowEditorElement.prototype, "placeholder", void 0);
+SciFlowEditorElement = __decorate([
+    customElement('sciflow-editor')
+], SciFlowEditorElement);
+export { SciFlowEditorElement };