@sciflow/editor-start 0.0.1-beta

package/dist/lib/editor-element.d.ts

@@ -0,0 +1,256 @@
+/**
+ * @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 { LitElement } from 'lit';
+import type { PropertyValues } from 'lit';
+import type { Node as ProsemirrorNode, ResolvedPos } from 'prosemirror-model';
+import type { PluginKey } from 'prosemirror-state';
+import { Editor, type CommandRunner, type Feature, type Operation, type SciFlowDocJSON, type SnapshotFile, type SnapshotReference, type SelectionJSON, type Version } from '@sciflow/editor-core';
+/**
+ * Detail payload emitted with the `editor-change` event.
+ * Consumers receive both the latest document snapshot and the batch of
+ * operations that produced it. Framework ports can mirror this contract.
+ */
+export interface SciFlowEditorChangeDetail {
+    readonly doc: SciFlowDocJSON;
+    readonly operations: Operation[];
+    readonly files: SnapshotFile[];
+    readonly references: SnapshotReference[];
+}
+type ExternalDocUpdate = {
+    doc: SciFlowDocJSON;
+    selection?: SelectionJSON;
+    version?: Version;
+    files?: SnapshotFile[];
+    references?: SnapshotReference[];
+};
+type DocInput = SciFlowDocJSON | ExternalDocUpdate | null;
+export type ShadowStyleInput = string | string[] | CSSStyleSheet | CSSStyleSheet[] | null;
+export interface PositionAPI {
+    coordsAtPos(pos: number): {
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+    } | null;
+    resolve(pos: number): ResolvedPos | null;
+}
+export interface PluginAPI {
+    getState<T>(key: PluginKey<T>): T | null;
+    dispatchMeta(key: PluginKey, meta: any): boolean;
+}
+export interface DomAPI {
+    getBoundingRect(): DOMRect | null;
+    dispatchEvent(event: CustomEvent): boolean;
+}
+/**
+ * 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.
+ */
+export declare class SciFlowEditorElement extends LitElement {
+    /**
+     * Initial ProseMirror document to render.
+     * Provide a `@sciflow/schema-prosemirror` node instance.
+     */
+    initialContent: ProsemirrorNode | null;
+    /**
+     * JSON representation of a document to render.
+     * Provide a `SciFlowDocJSON` value, typically sourced from persistence.
+     */
+    doc: DocInput;
+    /**
+     * Optional list of editor features to load. When not provided, defaults to
+     * the bundled demo feature set (figures, citations, mark formatting, headings).
+     */
+    features: Feature[] | 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.
+     */
+    private _shadowStyles;
+    private _shadowStylesAppliedExternally;
+    get shadowStyles(): ShadowStyleInput;
+    set shadowStyles(styles: ShadowStyleInput);
+    /** Heading text rendered in the introductory document. */
+    headingText: string;
+    /** Paragraph text used when no initial content is provided. */
+    placeholder: string;
+    private view;
+    private editor?;
+    private docUnsub?;
+    private selectionUnsub?;
+    private validationUnsub?;
+    private pendingOps;
+    private pendingOpsFromTransform;
+    private initialSelection?;
+    private suppressFeatureUpdate;
+    private deferInitializationForDoc;
+    private shadowStyleElements;
+    private themeUnsub?;
+    private themeStyleElements;
+    /** Access the underlying ProseMirror view instance. */
+    get editorView(): ReturnType<Editor['getView']> | null;
+    /** Access SciFlow command helpers bound to the current editor view. */
+    get commands(): CommandRunner | null;
+    /** Get read-only access to the document structure for traversal. */
+    get document(): ProsemirrorNode | null;
+    /** Get position utilities for coordinate mapping. */
+    get positions(): {
+        coordsAtPos: (pos: number) => {
+            top: number;
+            left: number;
+            bottom: number;
+            right: number;
+        } | null;
+        resolve: (pos: number) => ResolvedPos | null;
+    };
+    /** Get plugin management utilities. */
+    get plugins(): {
+        getState: <T>(key: PluginKey<T>) => NonNullable<T> | null;
+        dispatchMeta: (key: PluginKey, meta: any) => boolean;
+    };
+    /** Get editor DOM utilities. */
+    get dom(): {
+        getBoundingRect: () => DOMRect | null;
+        dispatchEvent: (event: CustomEvent) => boolean;
+    };
+    static styles: import("lit").CSSResult;
+    protected render(): import("lit-html").TemplateResult<1>;
+    /** Lit lifecycle hook: start the editor once the DOM container exists. */
+    protected firstUpdated(): Promise<void>;
+    connectedCallback(): void;
+    /**
+     * React to property changes coming from the host application.
+     * When `doc` changes we push the new snapshot into the running editor.
+     */
+    protected updated(changedProperties: PropertyValues<this>): void;
+    /**
+     * Cleanly dispose the editor when the element leaves the DOM.
+     * Other frameworks should execute the same logic in their unmount hook.
+     */
+    disconnectedCallback(): void;
+    /**
+     * Public helper to update the feature list and reconfigure the editor.
+     * Consumers (including the demo) can call this to immediately apply changes.
+     */
+    configureFeatures(features: Feature[]): Promise<void>;
+    /**
+     * Bootstrap the SciFlow editor inside this component's shadow DOM.
+     * Resolves a mount point, creates the editor instance, and wires listeners.
+     */
+    private getDefaultFeatures;
+    private getActiveFeatures;
+    private shouldDeferInitialization;
+    private initializeView;
+    /** Apply the `doc` attribute to the running editor instance. */
+    private applyDocUpdate;
+    /**
+     * Minimal in-memory sync strategy used for the demo element.
+     * Reimplementations typically swap this out for their persistence layer.
+     */
+    private createLocalSync;
+    private isExternalDocUpdate;
+    private extractDocFromInput;
+    private buildSyncUpdate;
+    /**
+     * Determine which document should be loaded on startup.
+     * Preference order: externally supplied JSON, provided PM node, fallback.
+     */
+    private resolveInitialDoc;
+    /**
+     * Build the bundled demonstration document (heading + paragraph + figure).
+     * Feel free to replace this when embedding in your own product.
+     */
+    private createDefaultDoc;
+    /**
+     * Safely convert SciFlow document JSON back into a ProseMirror node.
+     * Falls back to the default document when parsing fails.
+     */
+    private docFromJSON;
+    /**
+     * 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.
+     */
+    private sanitizeDocJSON;
+    /**
+     * Emit a high-level `editor-change` event with the new document snapshot.
+     * Applications can listen and update their stores or routing state.
+     */
+    private dispatchEditorChange;
+    /**
+     * Emit `editor-selection-change` whenever the cursor or selection updates.
+     * Handy for co-ordinating ancillary UI like reference or outline panels.
+     */
+    private dispatchSelectionChange;
+    /** Notify listeners that the editor has mounted and is ready for input. */
+    private dispatchEditorReady;
+    /**
+     * Tear down subscriptions and dispose the editor instance.
+     * Called automatically when the element disconnects.
+     */
+    private reinitializeEditor;
+    /**
+     * 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: ShadowStyleInput): void;
+    private destroyEditor;
+    private capturePendingOps;
+    private applyShadowStyles;
+    private normalizeShadowStyles;
+    private extractCssFromSheet;
+    private debugTestLog;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'sciflow-editor': SciFlowEditorElement;
+    }
+}
+export {};
+//# sourceMappingURL=editor-element.d.ts.map

package/dist/lib/editor-element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor-element.d.ts","sourceRoot":"","sources":["../../src/lib/editor-element.ts"],"names":[],"mappings":"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"}