Session.svelte.js

import Transaction from './Transaction.svelte.js';
import { char_slice, traverse } from './utils.js';
import {
	get as doc_get,
	property_type as doc_property_type,
	kind as doc_kind,
	inspect as doc_inspect,
	apply_op,
	count_references as doc_count_references,
	validate_document_schema,
	validate_node,
	get_active_annotation,
	validate_selection
} from './doc_utils.js';

/**
 * @import {
 *   NodeId,
 *   DocumentPath,
 *   Selection,
 *   Annotation,
 *   NodeKind,
 *   DocumentSchema,
 *   DocumentNode,
 *   Document
 * } from './types.d.ts';
 */

const BATCH_WINDOW_MS = 1000; // 1 second

/**
 * @typedef {Object} SessionOptions
 * @property {Selection} [selection] - Initial selection state
 */

export default class Session {
	/** @type {Selection | null} */
	#selection = $state.raw(null);

	/** @type {DocumentSchema} */
	schema = $state.raw();

	/** @type {Document} */
	doc = $state.raw();

	/** @type {any} */
	config = $state.raw();

	history = $state.raw([]);
	history_index = $state.raw(-1);
	last_batch_started = $state.raw(undefined); // Timestamp for debounced batching

	// Commands and keymap - initialized by Svedit when ready
	// NOTE: Assumes single Svedit instance per session
	commands = $state.raw({});
	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 = $derived(this.get_selected_node());
	available_annotation_types = $derived(this.get_available_annotation_types());

	/**
	 * @param {DocumentSchema} schema - The document schema
	 * @param {Document} doc - The document
	 * @param {object} config - configuration object
	 * @param {Object} [options]
	 * @param {Selection} [options.selection] - Initial selection state
	 */
	constructor(schema, doc, config, options = {}) {
		// Validate the schema first
		validate_document_schema(schema);

		this.schema = schema;
		this.doc = doc;
		this.config = config;

		// Set selection after doc is initialized so validation can work properly
		this.selection = options.selection ?? null;
	}

	/**
	 * Gets the current selection
	 * @returns {Selection | null}
	 */
	get selection() {
		return this.#selection;
	}

	/**
	 * Sets the selection with validation
	 * @param {Selection | null} value - The new selection
	 * @throws {Error} Throws if the selection is invalid
	 */
	set selection(value) {
		this._validate_selection(value);
		this.#selection = value;
	}

	/**
	 * Validates that a selection is within bounds and refers to valid paths.
	 *
	 * @param {Selection} selection - The selection to validate
	 * @throws {Error} Throws if the selection is invalid
	 * @private
	 */
	_validate_selection(selection) {
		validate_selection(selection, this);
	}

	/**
	 * Gets the document_id from the doc
	 * @returns {string}
	 */
	get document_id() {
		return this.doc.document_id;
	}

	validate_doc() {
		for (const node of Object.values(this.doc.nodes)) {
			validate_node(node, this.schema, this.doc.nodes);
		}
	}

	generate_id() {
		if (this.config?.generate_id) {
			return this.config.generate_id();
		} else {
			return crypto.randomUUID();
		}
	}

	/**
	 * 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 {object} context - The svedit context with session, editable, canvas, etc.
	 */
	initialize_commands(context) {
		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_annotation_types() {
		if (this.selection?.type !== 'text') return [];
		const path = this.selection.path;
		const property_definition = this.inspect(path);
		return property_definition.node_types || [];
	}

	// Helper function to get the currently selected node
	get_selected_node() {
		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 = this.get(this.selection.path);
			const node_id = node_array[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.
	 *
	 * @returns {Transaction} A new transaction instance
	 */
	get tr() {
		// 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 2 seconds) when batch is true.
	 *
	 * @param {Transaction} transaction - The transaction to apply
	 * @param {object} [options] - Optional configuration
	 * @param {boolean} [options.batch=false] - Whether to allow batching with previous transaction
	 */
	apply(transaction, { batch = false } = {}) {
		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 2s of batch start)
			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 (more than 2s since batch started, or 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() {
		if (this.history_index < 0) {
			return;
		}
		const change = this.history[this.history_index];
		let doc = this.doc;
		change.inverse_ops
			.slice()
			.reverse()
			.forEach((op) => {
				doc = apply_op(doc, op);
			});
		this.doc = doc;
		this.selection = change.selection_before;
		this.history_index = this.history_index - 1;
		return this;
	}

	redo() {
		if (this.history_index >= this.history.length - 1) {
			return;
		}
		this.history_index = this.history_index + 1;
		const change = this.history[this.history_index];
		let doc = this.doc;
		change.ops.forEach((op) => {
			doc = apply_op(doc, op);
		});
		this.doc = doc;
		this.selection = change.selection_after;
		return this;
	}

	/**
	 * Gets a node instance or property value at the specified path.
	 * @param {DocumentPath|string} path - Path to the node or property
	 * @returns {any} Either a node instance object or the value of a property
	 * @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 an annotated text property
	 * session.get(['page_1', 'cover', 'title']) // => {text: 'Hello world', annotations: []}
	 */
	get(path) {
		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: {...}
	 * }
	 *
	 * @param {DocumentPath} path
	 * @returns {{kind: 'property'|'node', [key: string]: any}}
	 */
	inspect(path) {
		return doc_inspect(this.schema, this.doc, path);
	}

	/**
	 * Determines the kind of a node ('block' for structured blocks, 'text' for pure
	 * text nodes or 'annotation' for annotation nodes.
	 * @param {any} node
	 * @returns {NodeKind}
	 */
	kind(node) {
		return doc_kind(this.schema, node);
	}

	/**
	 * Determines whether a node type can be inserted at a given selection.
	 * @param {string} node_type - The type of node to insert.
	 * @param {Selection} [selection] - The selection at which to insert the node.
	 * @returns {boolean} True if the node type can be inserted, false otherwise.
	 */
	can_insert(node_type, selection = this.selection) {
		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} [selection] - Reference selection
	 * @returns {Selection|null} The next node insert caret selection, or null if none is available
	 */
	get_next_node_insert_caret(selection = this.selection) {
		// There's no parent path to insert into
		if (!selection || selection.path.length <= 2) {
			return null;
		}

		const node_offset = parseInt(String(selection.path.at(-2)), 10) + 1;
		return {
			type: 'node',
			path: selection.path.slice(0, -2),
			anchor_offset: node_offset,
			focus_offset: node_offset
		};
	}

	/**
	 * Returns the annotation object that is currently "under the cursor".
	 * NOTE: Annotations in Svedit are exclusive, so there can only be one active_annotation
	 *
	 * @param {string} [annotation_type] Optional annotation type to filter by
	 * @returns {Annotation|null}
	 */
	active_annotation(annotation_type) {
		return get_active_annotation(this.schema, this.doc, this.selection, annotation_type);
	}

	get_selected_annotated_text() {
		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 annotated_text = this.get(this.selection.path);
		const text = char_slice(annotated_text.text, selection_start, selection_end);
		const nodes = {};
		const annotations = annotated_text.annotations
			.map((a) => {
				if (selection_start < a.end_offset && selection_end > a.start_offset) {
					const sub_graph = this.traverse(a.node_id);
					for (const node of sub_graph) {
						if (!nodes[node.id]) {
							nodes[node.id] = node;
						}
					}
					return {
						start_offset: Math.max(a.start_offset - selection_start, 0),
						end_offset: Math.min(a.end_offset - selection_start, selection_end - selection_start),
						node_id: a.node_id
					};
				} else {
					return null;
				}
			})
			.filter(Boolean);

		return { text, annotations, nodes };
	}

	// TODO: think about ways how we can also turn a node selection into plain text.
	get_selected_plain_text() {
		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 annotated_text = this.get(this.selection.path);
		return char_slice(annotated_text.text, start, end);
	}

	get_selected_nodes() {
		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 = this.get(this.selection.path);
		return $state.snapshot(node_array.slice(start, end));
	}

	select_parent() {
		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 = parseInt(String(this.selection.path[this.selection.path.length - 2]));
				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 = parseInt(String(this.selection.path[this.selection.path.length - 2]));

				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
	 *
	 * @param {string} node_id - The ID of the node to start traversing from
	 * @returns {Array<DocumentNode>} Array of nodes in depth-first order
	 * @note Nodes that are not reachable from the entry point node will not be included
	 */
	traverse(node_id) {
		return traverse(node_id, this.schema, $state.snapshot(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.
	 *
	 * @returns {Document} The document
	 */
	to_json() {
		// 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') => 'annotated_text'
	property_type(type, property) {
		return doc_property_type(this.schema, type, property);
	}

	// Count how many times a node is referenced in the document
	count_references(node_id) {
		return doc_count_references(this.schema, this.doc, node_id);
	}

	// Get all nodes referenced by a given node (recursively)
	/**
	 * @param {NodeId} node_id
	 * @returns {NodeId[]}
	 */
	get_referenced_nodes(node_id) {
		const traversed_nodes = this.traverse(node_id);

		// Extract IDs and exclude the last element (root node)
		return traversed_nodes.slice(0, -1).map((node) => node.id);
	}
}