svedit 0.11.1 → 0.13.0

package/src/lib/Session.svelte.ts

@@ -0,0 +1,656 @@
+import Transaction from './Transaction.svelte.js';
+import { char_slice, traverse, traverse_ids } from './utils.js';
+import {
+	get as doc_get,
+	property_type as doc_property_type,
+	kind as doc_kind,
+	inspect as doc_inspect,
+	create_document_draft,
+	apply_op_to_draft,
+	count_references as doc_count_references,
+	validate_document_schema,
+	validate_document,
+	validate_config_components,
+	validate_node,
+	is_id_valid,
+	get_referencing_node_ids,
+	get_selected_marks,
+	get_selected_annotations,
+	validate_selection
+} from './doc_utils.js';
+import type { SelectedAttachment } from './doc_utils.js';
+import type {
+	NodeId,
+	DocumentPath,
+	Selection,
+	Attachment,
+	NodeKind,
+	DocumentSchema,
+	DocumentNode,
+	Document,
+	AnyNode,
+	Text,
+	NodeArray,
+	CommandRegistry,
+	Inspection,
+	SessionConfig,
+	SveditContext
+} from './types.js';
+import type { Keymap } from './KeyMapper.svelte.js';
+
+const BATCH_WINDOW_MS = 1000; // 1 second
+
+type HistoryEntry = {
+	ops: Transaction['ops'];
+	inverse_ops: Transaction['inverse_ops'];
+	selection_before: Selection | null;
+	selection_after: Selection | null;
+};
+
+export default class Session<S extends DocumentSchema = DocumentSchema> {
+	#selection: Selection | null = $state.raw(null);
+
+	schema: S = $state.raw() as S;
+
+	doc: Document = $state.raw() as Document;
+
+	config: SessionConfig = $state.raw({});
+
+	history: HistoryEntry[] = $state.raw([]);
+	history_index = $state.raw(-1);
+	last_batch_started: number | undefined = $state.raw(undefined); // Timestamp for debounced batching
+
+	// Commands and keymap - initialized by Svedit when ready
+	// NOTE: Assumes single Svedit instance per session
+	commands: CommandRegistry = $state.raw({});
+	keymap: Keymap = $state.raw({});
+
+	// Reactive helpers for UI state
+	can_undo = $derived(this.history_index >= 0);
+	can_redo = $derived(this.history_index < this.history.length - 1);
+
+	// Reactive variable for selected node
+	selected_node: AnyNode<S> | null = $derived(this.get_selected_node());
+	available_mark_types = $derived(this.get_available_mark_types());
+	available_annotation_types = $derived(this.get_available_annotation_types());
+	selected_marks = $derived(get_selected_marks(this.schema, this.doc, this.selection));
+	active_mark: SelectedAttachment | null = $derived(
+		this.selected_marks.length === 1 ? this.selected_marks[0] : null
+	);
+	selected_annotations = $derived(get_selected_annotations(this.schema, this.doc, this.selection));
+	active_annotation: SelectedAttachment | null = $derived(
+		this.selected_annotations.length === 1 ? this.selected_annotations[0] : null
+	);
+
+	/**
+	 * @param schema - The document schema
+	 * @param doc - The document
+	 * @param config - configuration object
+	 * @param options - Optional settings (e.g. initial selection state)
+	 */
+	constructor(
+		schema: S,
+		doc: Document,
+		config: SessionConfig,
+		options: { selection?: Selection | null } = {}
+	) {
+		// Validate the schema first
+		validate_document_schema(schema);
+
+		this.schema = schema;
+		this.doc = doc;
+		this.config = config;
+		validate_document(this.doc, this.schema);
+		validate_config_components(this.schema, this.config);
+
+		// Set selection after doc is initialized so validation can work properly
+		this.selection = options.selection ?? null;
+	}
+
+	/**
+	 * Gets the current selection
+	 */
+	get selection(): Selection | null {
+		return this.#selection;
+	}
+
+	/**
+	 * Sets the selection with validation
+	 * @throws {Error} Throws if the selection is invalid
+	 */
+	set selection(value: Selection | null) {
+		this._validate_selection(value);
+		this.#selection = value;
+	}
+
+	/**
+	 * Validates that a selection is within bounds and refers to valid paths.
+	 *
+	 * @throws {Error} Throws if the selection is invalid
+	 */
+	private _validate_selection(selection: Selection | null): void {
+		validate_selection(selection, this);
+	}
+
+	/**
+	 * Gets the document_id from the doc
+	 */
+	get document_id(): string {
+		return this.doc.document_id;
+	}
+
+	/**
+	 * Validates the parts of a transaction result that can be affected by the transaction.
+	 *
+	 * This is intentionally narrower than full document validation. It validates all
+	 * created/modified nodes, plus nodes that still reference created, modified, or
+	 * deleted nodes. That catches local node invariants and dangling references left
+	 * behind by deletes without scanning every node on every apply.
+	 *
+	 * @throws {Error} Throws if the transaction result is invalid
+	 */
+	validate_transaction_result(transaction: Transaction): void {
+		const doc = transaction.doc;
+		// eslint-disable-next-line svelte/prefer-svelte-reactivity -- Non-reactive local dedup set.
+		const affected_node_ids: Set<NodeId> = new Set([
+			...transaction.created_node_ids,
+			...transaction.modified_node_ids
+		]);
+
+		// A full-document referrer scan is only needed when a reference held
+		// by an UNTOUCHED node can have become invalid:
+		// - deletions can leave dangling references behind
+		// - a 'type' change can violate a referrer's node/mark/annotation type
+		//   constraint
+		// References to created nodes can only live in nodes that were
+		// themselves created or modified in this transaction (the reference
+		// did not exist before), and modifying a node's other properties
+		// cannot invalidate its referrers — so those cases are already
+		// covered by the affected set and need no scan.
+		if (transaction.deleted_node_ids.length > 0 || transaction.changed_node_types) {
+			// eslint-disable-next-line svelte/prefer-svelte-reactivity -- Non-reactive local dedup set.
+			const scan_targets = new Set([
+				...transaction.created_node_ids,
+				...transaction.modified_node_ids,
+				...transaction.deleted_node_ids
+			]);
+			for (const node_id of get_referencing_node_ids(this.schema, doc, scan_targets)) {
+				affected_node_ids.add(node_id);
+			}
+		}
+
+		for (const node_id of affected_node_ids) {
+			const node = doc.nodes[node_id];
+			if (node) validate_node(node, this.schema, doc.nodes);
+		}
+	}
+
+	generate_id(): string {
+		const id = this.config?.generate_id ? this.config.generate_id() : `node_${crypto.randomUUID()}`;
+		if (!is_id_valid(id)) {
+			throw new Error(
+				`Generated node id ${JSON.stringify(id)} is invalid. Node ids must be non-empty strings that start with a letter or underscore, contain only letters, numbers, underscores, or dashes, and must not contain "__".`
+			);
+		}
+		return id;
+	}
+
+	/**
+	 * Initialize commands and keymap for this session.
+	 * Called by Svedit component when it has the necessary context.
+	 *
+	 * NOTE: This assumes a single Svedit instance per session.
+	 * For multiple editors on the same document, this architecture would need
+	 * to be refactored to support multiple sessions per document.
+	 *
+	 * @param context - The svedit context with session, editable, canvas, etc.
+	 */
+	initialize_commands(context: SveditContext<S>): void {
+		if (this.config?.create_commands_and_keymap) {
+			const { commands, keymap } = this.config.create_commands_and_keymap(context);
+			this.commands = commands;
+			this.keymap = keymap;
+		}
+	}
+
+	get_available_mark_types(): string[] {
+		if (this.selection?.type !== 'text' && this.selection?.type !== 'node') return [];
+		const property_definition = this.inspect(this.selection.path);
+		return property_definition.mark_types || [];
+	}
+
+	get_available_annotation_types(): string[] {
+		if (this.selection?.type !== 'text' && this.selection?.type !== 'node') return [];
+		const property_definition = this.inspect(this.selection.path);
+		return property_definition.annotation_types || [];
+	}
+
+	// Helper function to get the currently selected node
+	get_selected_node(): AnyNode<S> | null {
+		if (!this.selection) return null;
+
+		if (this.selection.type === 'node') {
+			const start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
+			const end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
+			// Only consider selection of a single node
+			if (end - start !== 1) return null;
+			const node_array: NodeArray = this.get(this.selection.path);
+			const node_id = node_array.nodes[start];
+			return node_id ? this.get(node_id) : null;
+		} else {
+			// we are assuming we are either in a text or property (=custom) selection
+			const owner_node_path = this.selection?.path?.slice(0, -1);
+			if (!owner_node_path) return null;
+			const owner_node = this.get(owner_node_path);
+			return owner_node;
+		}
+	}
+
+	/**
+	 * Creates a new transaction for making atomic changes to the document.
+	 */
+	get tr(): Transaction {
+		// We create a copy of the current state to avoid modifying the original
+		return new Transaction(this.schema, this.doc, this.selection, this.config);
+	}
+
+	/**
+	 * Applies a transaction to the document.
+	 * Auto-batches history entries with debounced behavior (max one entry per second) when batch is true.
+	 *
+	 * @param transaction - The transaction to apply
+	 * @param options - Optional configuration (batch: whether to allow batching with previous transaction)
+	 */
+	apply(transaction: Transaction, { batch = false }: { batch?: boolean } = {}): this {
+		this.validate_transaction_result(transaction);
+		// Only swap the doc when something changed. The transaction draft is
+		// always a fresh object, and assigning it for an ops-less transaction
+		// (e.g. selection-only) would needlessly invalidate every doc-dependent
+		// derived in the component tree.
+		if (transaction.ops.length > 0) {
+			this.doc = transaction.doc;
+		}
+		// Make sure selection gets a new reference (is rerendered)
+		this.selection = structuredClone(transaction.selection);
+		if (this.history_index < this.history.length - 1) {
+			this.history = this.history.slice(0, this.history_index + 1);
+		}
+
+		const now = Date.now();
+		const should_batch =
+			batch &&
+			this.last_batch_started !== undefined &&
+			now - this.last_batch_started < BATCH_WINDOW_MS;
+
+		if (should_batch) {
+			// Append to existing history entry (within the batch window)
+			const last_entry = this.history[this.history_index];
+			last_entry.ops.push(...transaction.ops);
+			last_entry.inverse_ops.push(...transaction.inverse_ops);
+			last_entry.selection_after = this.selection;
+			// Trigger update
+			this.history = [...this.history];
+		} else {
+			// Create new history entry (batch window elapsed, first edit, or batch not requested)
+			this.history = [
+				...this.history,
+				{
+					ops: transaction.ops,
+					inverse_ops: transaction.inverse_ops,
+					selection_before: transaction.selection_before,
+					selection_after: this.selection
+				}
+			];
+			this.history_index = this.history_index + 1;
+			// Only set last_batch_started if batching was requested
+			if (batch) {
+				this.last_batch_started = now;
+			} else {
+				this.last_batch_started = undefined;
+			}
+		}
+
+		return this;
+	}
+
+	undo(): this | undefined {
+		if (this.history_index < 0) {
+			return;
+		}
+		const change = this.history[this.history_index];
+		// One draft for the whole change set — ops mutate the draft with
+		// node-level copy-on-write instead of copying the nodes map per op.
+		const doc = create_document_draft(this.doc);
+		change.inverse_ops
+			.slice()
+			.reverse()
+			.forEach((op) => {
+				apply_op_to_draft(doc, op);
+			});
+		this.doc = doc;
+		this.selection = change.selection_before;
+		this.history_index = this.history_index - 1;
+		// History navigation ends any open typing batch, so the next batched
+		// apply starts a fresh entry instead of appending to a stale one.
+		this.last_batch_started = undefined;
+		return this;
+	}
+
+	redo(): this | undefined {
+		if (this.history_index >= this.history.length - 1) {
+			return;
+		}
+		this.history_index = this.history_index + 1;
+		const change = this.history[this.history_index];
+		const doc = create_document_draft(this.doc);
+		change.ops.forEach((op) => {
+			apply_op_to_draft(doc, op);
+		});
+		this.doc = doc;
+		this.selection = change.selection_after;
+		// Redo ends any open typing batch, matching undo().
+		this.last_batch_started = undefined;
+		return this;
+	}
+
+	/**
+	 * Gets a node instance or property value at the specified path.
+	 *
+	 * The result type defaults to `any` because a path can address a node or
+	 * any property value. Annotate the target to type the result.
+	 *
+	 * @example
+	 * // Get a node by ID
+	 * session.get('list_1') // => { type: 'list', id: 'list_1', ... }
+	 *
+	 * @example
+	 * // Get a node array property
+	 * session.get(['list_1', 'list_items']) // => [ 'list_item_1', 'list_item_2' ]
+	 *
+	 * @example
+	 * // Get a specific node from an array
+	 * session.get(['page_1', 'body', 3, 'list_items', 0]) // => { type: 'list_item', id: 'list_item_1', ... }
+	 *
+	 * @example
+	 * // Get a text property
+	 * session.get(['page_1', 'cover', 'title']) // => {content: 'Hello world', marks: [], annotations: []}
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	get<T = any>(path: DocumentPath | string): T {
+		return doc_get(this.schema, this.doc, path);
+	}
+
+	/**
+	 * While .get gives you the value of a path, inspect gives you
+	 * the type info of that value.
+	 *
+	 * @todo The layout of these should be improved and more explictly typed
+	 *
+	 * @example
+	 * session.inspect(['page_1', 'body']) => {
+	 *   kind: 'property',
+	 *   name: 'body',
+	 *   type: 'node_array',
+	 *   node_types: ['text', 'story', 'list'],
+	 *   default_node_type: 'text'
+	 * }
+	 *
+	 * @example
+	 * session.inspect(['page_1', 'body', 1]) => {
+	 *   kind: 'node',
+	 *   id: 'paragraph_234',
+	 *   type: 'paragraph',
+	 *   properties: {...}
+	 * }
+	 */
+	inspect(path: DocumentPath): Inspection {
+		return doc_inspect(this.schema, this.doc, path);
+	}
+
+	/**
+	 * Determines the kind of a node ('document' for root nodes, 'block' for
+	 * structured blocks, 'text' for pure text nodes, 'mark' for mark nodes or
+	 * 'annotation' for annotation nodes).
+	 */
+	kind(node: DocumentNode): NodeKind {
+		return doc_kind(this.schema, node);
+	}
+
+	/**
+	 * Determines whether a node type can be inserted at a given selection.
+	 *
+	 * @param node_type - The type of node to insert.
+	 * @param selection - The selection at which to insert the node.
+	 * @returns True if the node type can be inserted, false otherwise.
+	 */
+	can_insert(node_type: string, selection: Selection | null = this.selection): boolean {
+		if (selection?.type === 'node') {
+			const property_definition = this.inspect(selection.path);
+			if (property_definition.node_types.includes(node_type)) {
+				return true;
+			}
+		}
+
+		// No insert position found yet, and root not reached, try one level up if possible
+		let next_node_insert_caret = this.get_next_node_insert_caret(selection);
+		if (!next_node_insert_caret) return false;
+		return this.can_insert(node_type, next_node_insert_caret);
+	}
+
+	/**
+	 * Compute next possible insert position from a given selection
+	 *
+	 * @param selection - Reference selection
+	 * @returns The next node insert caret selection, or null if none is available
+	 */
+	get_next_node_insert_caret(selection: Selection | null = this.selection): Selection | null {
+		// There's no parent path to insert into
+		if (!selection || selection.path.length <= 2) {
+			return null;
+		}
+
+		const node_offset = (selection.path.at(-2) as number) + 1;
+		return {
+			type: 'node',
+			path: selection.path.slice(0, -2),
+			anchor_offset: node_offset,
+			focus_offset: node_offset
+		};
+	}
+
+	get_selected_text(): (Text & { nodes: Record<string, DocumentNode> }) | null {
+		if (this.selection?.type !== 'text') return null;
+
+		const selection_start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
+		const selection_end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
+		const text_value: Text = this.get(this.selection.path);
+		const selected_text = char_slice(text_value.content, selection_start, selection_end);
+		const nodes: Record<string, DocumentNode> = {};
+
+		const clip_ranges = (ranges: Attachment[]) =>
+			ranges
+				.map((range) => {
+					if (selection_start < range.end_offset && selection_end > range.start_offset) {
+						const sub_graph = this.traverse(range.node_id);
+						for (const node of sub_graph) {
+							if (!nodes[node.id]) {
+								nodes[node.id] = node;
+							}
+						}
+						return {
+							start_offset: Math.max(range.start_offset - selection_start, 0),
+							end_offset: Math.min(
+								range.end_offset - selection_start,
+								selection_end - selection_start
+							),
+							node_id: range.node_id
+						};
+					} else {
+						return null;
+					}
+				})
+				.filter((range): range is Attachment => range !== null);
+
+		const marks = clip_ranges(text_value.marks);
+		const annotations = clip_ranges(text_value.annotations);
+
+		return { content: selected_text, marks, annotations, nodes };
+	}
+
+	get_selected_annotated_nodes(): {
+		nodes: Record<string, DocumentNode>;
+		main_nodes: NodeId[];
+		marks: Attachment[];
+		annotations: Attachment[];
+	} | null {
+		if (this.selection?.type !== 'node') return null;
+
+		const selection_start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
+		const selection_end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
+		const node_array: NodeArray = this.get(this.selection.path);
+		const main_nodes = node_array.nodes.slice(selection_start, selection_end);
+		const nodes: Record<string, DocumentNode> = {};
+
+		const add_subgraph = (node_id: NodeId) => {
+			for (const node of this.traverse(node_id)) {
+				if (!nodes[node.id]) nodes[node.id] = node;
+			}
+		};
+
+		for (const node_id of main_nodes) add_subgraph(node_id);
+
+		const clip_ranges = (ranges: Attachment[]) =>
+			ranges
+				.map((range) => {
+					if (selection_start >= range.end_offset || selection_end <= range.start_offset) {
+						return null;
+					}
+
+					add_subgraph(range.node_id);
+					return {
+						start_offset: Math.max(range.start_offset - selection_start, 0),
+						end_offset: Math.min(
+							range.end_offset - selection_start,
+							selection_end - selection_start
+						),
+						node_id: range.node_id
+					};
+				})
+				.filter((range): range is Attachment => range !== null);
+
+		const marks = clip_ranges(node_array.marks);
+		const annotations = clip_ranges(node_array.annotations);
+
+		return { nodes, main_nodes, marks, annotations };
+	}
+
+	// TODO: think about ways how we can also turn a node selection into plain text.
+	get_selected_plain_text(): string | null {
+		if (this.selection?.type !== 'text') return null;
+
+		const start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
+		const end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
+		const text: Text = this.get(this.selection.path);
+		return char_slice(text.content, start, end);
+	}
+
+	get_selected_nodes(): NodeId[] | null {
+		if (this.selection?.type !== 'node') return null;
+
+		const start = Math.min(this.selection.anchor_offset, this.selection.focus_offset);
+		const end = Math.max(this.selection.anchor_offset, this.selection.focus_offset);
+		const node_array: NodeArray = this.get(this.selection.path);
+		// node_array.nodes is a plain array of id strings (doc is $state.raw),
+		// so a slice is already a safe fresh copy.
+		return node_array.nodes.slice(start, end);
+	}
+
+	select_parent(): void {
+		if (!this.selection) return;
+		if (['text', 'property'].includes(this.selection.type)) {
+			// For text and property selections (e.g. ['page_1', 'body', 0, 'image']), we need to go up two levels
+			// in the path
+			if (this.selection.path.length > 3) {
+				const parent_path = this.selection.path.slice(0, -2);
+				const current_index = this.selection.path[this.selection.path.length - 2] as number;
+				this.selection = {
+					type: 'node',
+					path: parent_path,
+					anchor_offset: current_index,
+					focus_offset: current_index + 1
+				};
+			} else {
+				this.selection = null;
+			}
+		} else if (this.selection.type === 'node') {
+			// For node selections, we go up one level
+			if (this.selection.path.length > 3) {
+				const parent_path = this.selection.path.slice(0, -2);
+				const current_index = this.selection.path[this.selection.path.length - 2] as number;
+
+				this.selection = {
+					type: 'node',
+					path: parent_path,
+					anchor_offset: current_index,
+					focus_offset: current_index + 1
+				};
+			} else {
+				this.selection = null;
+			}
+		} else {
+			this.selection = null;
+		}
+	}
+
+	/**
+	 * Traverses the document and returns a list of nodes in depth-first order.
+	 *
+	 * The traversal order is:
+	 * 1. Leaf nodes first
+	 * 2. Branch nodes second
+	 * 3. Root node (entry point) last
+	 *
+	 * Nodes that are not reachable from the entry point node will not be included.
+	 */
+	traverse(node_id: string): Array<DocumentNode> {
+		// doc is $state.raw, so doc.nodes is a plain (non-proxied) object —
+		// traverse() reads it directly and deep-clones each visited node.
+		// The previous $state.snapshot(this.doc.nodes) here deep-cloned the
+		// ENTIRE document per call, which made copying M nodes O(M·N).
+		return traverse(node_id, this.schema, this.doc.nodes);
+	}
+
+	/**
+	 * Convert the document to a clean format for persistence.
+	 *
+	 * We make a traversal to ensure that orphaned nodes are not included,
+	 * and that leaf nodes go first, followed by branches and the root node at last.
+	 */
+	to_json(): Document {
+		// this will order the nodes (depth-first traversal)
+		const nodes_array = this.traverse(this.document_id);
+		// convert nodes array to object with node IDs as keys
+		const nodes = Object.fromEntries(nodes_array.map((node) => [node.id, node]));
+		return {
+			document_id: this.document_id,
+			nodes
+		};
+	}
+
+	// property_type('page', 'body') => 'node_array'
+	// property_type('paragraph', 'content') => 'text'
+	property_type(type: string, property: string): string {
+		return doc_property_type(this.schema, type, property);
+	}
+
+	// Count how many times a node is referenced in the document
+	count_references(node_id: NodeId): number {
+		return doc_count_references(this.schema, this.doc, node_id);
+	}
+
+	// Get all nodes referenced by a given node (recursively)
+	get_referenced_nodes(node_id: NodeId): NodeId[] {
+		// Id-only traversal — no need to deep-clone the subgraph for ids.
+		return traverse_ids(node_id, this.schema, this.doc.nodes).slice(0, -1);
+	}
+}