svedit 0.12.0 → 0.13.0

package/src/lib/{index.js → index.ts}

@@ -13,6 +13,53 @@ export { default as NodeSelectionMarkers } from './NodeSelectionMarkers.svelte';
 export { default as Session } from './Session.svelte.js';
 export { default as Transaction } from './Transaction.svelte.js';
 
+// Public types
+export type {
+	// Schema definition
+	DocumentSchema,
+	NodeSchema,
+	NodeKind,
+	PropertyDefinition,
+	PropertyType,
+	// Schema-derived node types
+	PropertyValue,
+	NodeOfType,
+	AnyNode,
+	NodeMap,
+	DynamicRecord,
+	SessionConfig,
+	CommandRegistry,
+	DocumentOperation,
+	Inspection,
+	// Documents and nodes
+	Document,
+	DocumentNode,
+	DocumentPath,
+	NodeId,
+	// Values
+	Text,
+	NodeArray,
+	Attachment,
+	Mark,
+	Annotation,
+	// Selections
+	Selection,
+	TextSelection,
+	NodeSelection,
+	PropertySelection,
+	SelectionRange,
+	// Component props and render contexts
+	SveditProps,
+	SveditContext,
+	TextPropertyProps,
+	CustomPropertyProps,
+	NodeArrayPropertyProps,
+	NodeProps,
+	NodeArrayAttachmentContext
+} from './types.js';
+export type { SelectedAttachment } from './doc_utils.js';
+export type { Keymap } from './KeyMapper.svelte.js';
+
 // Document utilities
 export {
 	define_document_schema,

package/src/lib/{node_visibility.svelte.js → node_visibility.svelte.ts}

@@ -120,9 +120,8 @@ class VisibilityRegistry {
 	 * Stable references — once a SvelteSet is created for an array path
 	 * it survives re-renders so consumers stay subscribed.
 	 *
-	 * @type {Map<string, SvelteSet<number>>}
 	 */
-	#array_indices = new Map();
+	#array_indices: Map<string, SvelteSet<number>> = new Map();
 
 	/**
 	 * Per-array edge-proximity state. `first` is true when the first
@@ -138,15 +137,12 @@ class VisibilityRegistry {
 	 * only render when the edge node has actually reached the matching
 	 * end of its container.
 	 *
-	 * @type {SvelteMap<string, { first: boolean, last: boolean }>}
 	 */
-	edge_map = new SvelteMap();
+	edge_map: SvelteMap<string, { first: boolean; last: boolean }> = new SvelteMap();
 
-	/** @type {IntersectionObserver | null} */
-	#io = null;
+	#io: IntersectionObserver | null = null;
 
-	/** @type {IntersectionObserver | null} */
-	#view_io = null;
+	#view_io: IntersectionObserver | null = null;
 
 	/**
 	 * Re-syncs edge state when a registered array's box changes size
@@ -156,35 +152,31 @@ class VisibilityRegistry {
 	 * change, so neither of the other two triggers would catch them.
 	 * Writes are change-detected, so redundant firings are no-ops.
 	 *
-	 * @type {ResizeObserver | null}
 	 */
-	#array_ro = null;
+	#array_ro: ResizeObserver | null = null;
 
 	/**
 	 * Registered node elements and the path each was registered under.
 	 * The attachment closure carries the path, so a stale data-path
 	 * attribute can never desync state.
 	 *
-	 * @type {Map<HTMLElement, string>}
 	 */
-	#registered_paths = new Map();
+	#registered_paths: Map<HTMLElement, string> = new Map();
 
 	/**
 	 * Which element currently owns a node path. Guards unregistration
 	 * against keyed-update collisions (see module doc).
 	 *
-	 * @type {Map<string, HTMLElement>}
 	 */
-	#path_owners = new Map();
+	#path_owners: Map<string, HTMLElement> = new Map();
 
-	/** @type {Set<HTMLElement>} */
-	#near_nodes = new Set();
+	#near_nodes: Set<HTMLElement> = new Set();
 
-	/** Registered node-array container elements. @type {Set<Element>} */
-	#array_els = new Set();
+	/** Registered node-array container elements. */
+	#array_els: Set<Element> = new Set();
 
-	/** Which element currently owns an array path. @type {Map<string, Element>} */
-	#array_owners = new Map();
+	/** Which element currently owns an array path. */
+	#array_owners: Map<string, Element> = new Map();
 
 	/**
 	 * When true, a second IO (rootMargin 0, actual viewport) toggles
@@ -271,10 +263,8 @@ class VisibilityRegistry {
 	 * the set and reads `.has()` in the same derived never subscribes
 	 * and never re-evaluates.
 	 *
-	 * @param {string} array_path_str
-	 * @returns {SvelteSet<number>}
 	 */
-	get_array_indices(array_path_str) {
+	get_array_indices(array_path_str: string): SvelteSet<number> {
 		let set = this.#array_indices.get(array_path_str);
 		if (!set) {
 			set = new SvelteSet();
@@ -291,10 +281,9 @@ class VisibilityRegistry {
 	 * viewport transitions. Re-runs when the element is recreated or
 	 * its path changes; the teardown unregisters collision-safely.
 	 *
-	 * @param {string} path
 	 */
-	track_node(path) {
-		return (/** @type {HTMLElement} */ el) => {
+	track_node(path: string) {
+		return (el: HTMLElement) => {
 			this.#register_node(el, path);
 			return () => this.#unregister_node(el, path);
 		};
@@ -305,10 +294,9 @@ class VisibilityRegistry {
 	 * arrays get their edge state synced on mount, on scroll (via the
 	 * document scroll listener) and after document changes.
 	 *
-	 * @param {string} path
 	 */
-	track_array(path) {
-		return (/** @type {Element} */ el) => {
+	track_array(path: string) {
+		return (el: Element) => {
 			this.start();
 			this.#array_els.add(el);
 			this.#array_owners.set(path, el);
@@ -334,9 +322,8 @@ class VisibilityRegistry {
 	 * registry instance. Scopes the document-level scroll listener to
 	 * this editor without any DOM traversal.
 	 *
-	 * @param {Element} el
 	 */
-	has_array(el) {
+	has_array(el: Element): boolean {
 		return this.#array_els.has(el);
 	}
 
@@ -351,11 +338,7 @@ class VisibilityRegistry {
 		}
 	}
 
-	/**
-	 * @param {HTMLElement} el
-	 * @param {string} path
-	 */
-	#register_node(el, path) {
+	#register_node(el: HTMLElement, path: string): void {
 		this.start();
 		untrack(() => {
 			this.#registered_paths.set(el, path);
@@ -373,24 +356,20 @@ class VisibilityRegistry {
 			const vw = window.innerWidth;
 			const is_near =
 				!this.visibility_culling ||
-				(bcr.bottom > -OVERSCAN_PX &&
-					bcr.top < vh + OVERSCAN_PX &&
-					bcr.right > -OVERSCAN_PX &&
-					bcr.left < vw + OVERSCAN_PX);
+				(bcr!.bottom > -OVERSCAN_PX &&
+					bcr!.top < vh + OVERSCAN_PX &&
+					bcr!.right > -OVERSCAN_PX &&
+					bcr!.left < vw + OVERSCAN_PX);
 			if (is_near) this.#add_near_node(el, path);
 
 			if (this.view_classes) {
-				const in_viewport = bcr.bottom > 0 && bcr.top < vh && bcr.right > 0 && bcr.left < vw;
-				this.#apply_view_classes(el, in_viewport, bcr, vh);
+				const in_viewport = bcr!.bottom > 0 && bcr!.top < vh && bcr!.right > 0 && bcr!.left < vw;
+				this.#apply_view_classes(el, in_viewport, bcr!, vh);
 			}
 		});
 	}
 
-	/**
-	 * @param {HTMLElement} el
-	 * @param {string} path
-	 */
-	#unregister_node(el, path) {
+	#unregister_node(el: HTMLElement, path: string): void {
 		this.#registered_paths.delete(el);
 		this.#near_nodes.delete(el);
 		this.#io?.unobserve(el);
@@ -406,21 +385,13 @@ class VisibilityRegistry {
 		});
 	}
 
-	/**
-	 * @param {HTMLElement} el
-	 * @param {string} path
-	 */
-	#add_near_node(el, path) {
+	#add_near_node(el: HTMLElement, path: string): void {
 		this.#near_nodes.add(el);
 		const split = this.#split_path(path);
 		if (split) this.get_array_indices(split.array_path).add(split.index);
 	}
 
-	/**
-	 * @param {HTMLElement} el
-	 * @param {string} path
-	 */
-	#remove_near_node(el, path) {
+	#remove_near_node(el: HTMLElement, path: string): void {
 		this.#near_nodes.delete(el);
 		if (this.#path_owners.get(path) !== el) return;
 		const split = this.#split_path(path);
@@ -445,12 +416,10 @@ class VisibilityRegistry {
 	 * called transitively from $effect contexts without self-
 	 * invalidation.
 	 *
-	 * @param {Element} array_el
-	 * @returns {boolean}
 	 */
-	sync_edge_state(array_el) {
+	sync_edge_state(array_el: Element): boolean {
 		if (!array_el) return false;
-		const path = /** @type {HTMLElement} */ (array_el).dataset.path;
+		const path = (array_el as HTMLElement).dataset.path;
 		if (!path) return false;
 
 		// Check computed overflow BEFORE touching scroll metrics. Reading
@@ -487,13 +456,12 @@ class VisibilityRegistry {
 		});
 	}
 
-	/**
-	 * @param {HTMLElement} el
-	 * @param {boolean} in_viewport
-	 * @param {DOMRectReadOnly} bcr
-	 * @param {number} vh
-	 */
-	#apply_view_classes(el, in_viewport, bcr, vh) {
+	#apply_view_classes(
+		el: HTMLElement,
+		in_viewport: boolean,
+		bcr: DOMRectReadOnly,
+		vh: number
+	): void {
 		const cl = el.classList;
 		cl.toggle('in-view', in_viewport);
 		if (in_viewport) {
@@ -508,11 +476,7 @@ class VisibilityRegistry {
 		}
 	}
 
-	/**
-	 * @param {string} path
-	 * @returns {{ array_path: string, index: number } | null}
-	 */
-	#split_path(path) {
+	#split_path(path: string): { array_path: string; index: number } | null {
 		const sep = path.lastIndexOf(PATH_SEPARATOR);
 		if (sep < 0) return null;
 		const index = parseInt(path.slice(sep + PATH_SEPARATOR.length), 10);
@@ -524,11 +488,10 @@ class VisibilityRegistry {
 	 * Overscan IO callback. Manages the array_indices sets; NodeGap
 	 * reacts to the map writes and updates .positioned declaratively.
 	 *
-	 * @param {IntersectionObserverEntry[]} entries
 	 */
-	#process_near(entries) {
+	#process_near(entries: IntersectionObserverEntry[]): void {
 		for (const entry of entries) {
-			const el = /** @type {HTMLElement} */ (entry.target);
+			const el = entry.target as HTMLElement;
 			const path = this.#registered_paths.get(el);
 			if (!path || !el.isConnected) continue;
 
@@ -544,12 +507,11 @@ class VisibilityRegistry {
 	 * Runs on a separate observer with rootMargin 0 so thresholds
 	 * fire at actual viewport edges, not the overscan boundary.
 	 *
-	 * @param {IntersectionObserverEntry[]} entries
 	 */
-	#process_view(entries) {
+	#process_view(entries: IntersectionObserverEntry[]): void {
 		const vh = window.innerHeight;
 		for (const entry of entries) {
-			const el = /** @type {HTMLElement} */ (entry.target);
+			const el = entry.target as HTMLElement;
 			if (!this.#registered_paths.has(el) || !el.isConnected) continue;
 			this.#apply_view_classes(el, entry.isIntersecting, entry.boundingClientRect, vh);
 		}
@@ -564,9 +526,16 @@ class VisibilityRegistry {
  * The IntersectionObservers own viewport changes; document changes
  * only trigger an edge-state re-sync over the registered arrays.
  *
- * @param {object} svedit - Svedit context (session, editable)
+ * @param svedit - Svedit context (session, editable)
  */
-export function create_node_visibility(svedit) {
+export function create_node_visibility(svedit: {
+	session: {
+		config?: { view_classes?: boolean; visibility_culling?: boolean };
+		doc: unknown;
+	};
+	editable: boolean;
+	visibility_registry?: VisibilityRegistryApi;
+}): void {
 	const registry = new VisibilityRegistry();
 	registry.view_classes = svedit.session?.config?.view_classes !== false;
 	registry.visibility_culling = svedit.session?.config?.visibility_culling !== false;
@@ -587,9 +556,8 @@ export function create_node_visibility(svedit) {
 		 * coalesces array scrolls into one RAF that reads only scrollLeft /
 		 * scrollWidth / clientWidth — no per-node BCRs.
 		 */
-		/** @type {Set<Element>} */
 		// eslint-disable-next-line svelte/prefer-svelte-reactivity -- Non-reactive RAF queue.
-		const pending_scroll_arrays = new Set();
+		const pending_scroll_arrays: Set<Element> = new Set();
 		let scroll_raf = 0;
 		function flush_scroll_sync() {
 			scroll_raf = 0;
@@ -598,9 +566,8 @@ export function create_node_visibility(svedit) {
 			}
 			pending_scroll_arrays.clear();
 		}
-		/** @param {Event} event */
-		function on_scroll(event) {
-			const target = /** @type {Element | null} */ (event.target);
+		function on_scroll(event: Event) {
+			const target = event.target as Element | null;
 			const arr = target?.closest?.('[data-type="node_array"]');
 			if (!arr || !registry.has_array(arr)) return;
 			pending_scroll_arrays.add(arr);
@@ -636,6 +603,13 @@ export function create_node_visibility(svedit) {
 	});
 }
 
+export type VisibilityRegistryApi = {
+	edge_map: SvelteMap<string, { first: boolean; last: boolean }>;
+	get_array_indices(array_path_str: string): SvelteSet<number>;
+	track_node(path: string): (el: HTMLElement) => () => void;
+	track_array(path: string): (el: Element) => () => void;
+};
+
 /**
  * Pure visibility check for a gap's `.positioned` class. NodeGap calls
  * this from a $derived, so the `near.has()` reads are tracked at
@@ -648,13 +622,15 @@ export function create_node_visibility(svedit) {
  * $derived (see the note there): membership reads on a set created
  * within the same derived are not tracked by Svelte.
  *
- * @param {SvelteSet<number>} near - near child indices of the array
- * @param {{ first: boolean, last: boolean } | undefined} edge_state
- * @param {number} offset
- * @param {boolean} is_last
- * @param {boolean} empty
+ * @param near - near child indices of the array
  */
-export function should_position_gap(near, edge_state, offset, is_last, empty) {
+export function should_position_gap(
+	near: SvelteSet<number>,
+	edge_state: { first: boolean; last: boolean } | undefined,
+	offset: number,
+	is_last: boolean,
+	empty: boolean
+): boolean {
 	if (!near) return false;
 
 	if (empty) {

package/src/lib/{paste_utils.js → paste_utils.ts}

@@ -1,12 +1,23 @@
-/**
- * @import { DocumentSchema } from './types.d.ts'
- */
+import type { Text, DocumentNode, DocumentSchema } from './types.js';
 
-export function normalize_line_endings(text) {
+function is_record(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null;
+}
+
+function is_text(value: unknown): value is Text {
+	return (
+		is_record(value) &&
+		typeof value.content === 'string' &&
+		Array.isArray(value.marks) &&
+		Array.isArray(value.annotations)
+	);
+}
+
+export function normalize_line_endings(text: string): string {
 	return text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
 }
 
-export function dedent_plain_text(plain_text) {
+export function dedent_plain_text(plain_text: string): string {
 	const lines = normalize_line_endings(plain_text).split('\n');
 	if (lines.length < 2) return plain_text;
 
@@ -42,23 +53,21 @@ export function dedent_plain_text(plain_text) {
 		.join('\n');
 }
 
-export function split_plain_text_paragraphs(plain_text) {
+export function split_plain_text_paragraphs(plain_text: string): string[] {
 	return normalize_line_endings(plain_text)
 		.split(/\n{2,}/)
 		.map((fragment) => fragment.trim())
 		.filter(Boolean);
 }
 
-export function normalize_plain_text_for_single_line_property(plain_text) {
+export function normalize_plain_text_for_single_line_property(plain_text: string): string {
 	return normalize_line_endings(plain_text).replace(/\s*\n+\s*/g, ' ');
 }
 
-/**
- * @param {string | null | undefined} node_type
- * @param {DocumentSchema} schema
- * @returns {string | null}
- */
-export function get_text_property_name(node_type, schema) {
+export function get_text_property_name(
+	node_type: string | null | undefined,
+	schema: DocumentSchema
+): string | null {
 	if (!node_type) return null;
 	const node_schema = schema[node_type];
 	if (!node_schema || node_schema.kind !== 'text') return null;
@@ -70,75 +79,55 @@ export function get_text_property_name(node_type, schema) {
 	);
 }
 
-/**
- * @param {any} node
- * @param {DocumentSchema} schema
- * @returns {{ content: string, marks: any[], annotations: any[] } | null}
- */
-export function get_text_content(node, schema) {
-	if (!node || typeof node !== 'object') return null;
-
-	const is_text_value = (value) =>
-		value &&
-		typeof value.content === 'string' &&
-		Array.isArray(value.marks) &&
-		Array.isArray(value.annotations);
+export function get_text_content(node: unknown, schema: DocumentSchema): Text | null {
+	if (!is_record(node)) return null;
 
-	const text_property_name = get_text_property_name(node.type, schema);
-	if (text_property_name && is_text_value(node[text_property_name])) {
+	const node_type = typeof node.type === 'string' ? node.type : null;
+	const text_property_name = get_text_property_name(node_type, schema);
+	if (text_property_name && is_text(node[text_property_name])) {
 		return node[text_property_name];
 	}
 
-	if (is_text_value(node.content)) {
+	if (is_text(node.content)) {
 		return node.content;
 	}
 
 	return null;
 }
 
-/**
- * @param {any} node
- * @param {DocumentSchema} schema
- * @returns {boolean}
- */
-export function is_text_like_node_payload(node, schema) {
-	if (!node || typeof node !== 'object') return false;
-	if (schema[node.type]?.kind === 'text') return true;
+export function is_text_like_node_payload(node: unknown, schema: DocumentSchema): boolean {
+	if (!is_record(node)) return false;
+	if (typeof node.type === 'string' && schema[node.type]?.kind === 'text') return true;
 	return !!get_text_content(node, schema);
 }
 
-/**
- * @param {any} node_array_property_definition
- * @param {DocumentSchema} schema
- * @returns {string | null}
- */
-export function get_default_text_node(node_array_property_definition, schema) {
+export function get_default_text_node(
+	node_array_property_definition: unknown,
+	schema: DocumentSchema
+): string | null {
 	if (
-		node_array_property_definition?.type !== 'node_array' ||
+		!is_record(node_array_property_definition) ||
+		node_array_property_definition.type !== 'node_array' ||
 		!Array.isArray(node_array_property_definition.node_types)
 	) {
 		return null;
 	}
 
 	const default_node_type = node_array_property_definition.default_node_type;
-	if (default_node_type && schema[default_node_type]?.kind === 'text') {
+	if (typeof default_node_type === 'string' && schema[default_node_type]?.kind === 'text') {
 		return default_node_type;
 	}
 
-	return (
-		node_array_property_definition.node_types.find(
-			(node_type) => schema[node_type]?.kind === 'text'
-		) || null
-	);
+	return (node_array_property_definition.node_types.find(
+		(node_type: unknown) => typeof node_type === 'string' && schema[node_type]?.kind === 'text'
+	) || null) as string | null;
 }
 
-/**
- * @param {string[]} paragraph_fragments
- * @param {string | null | undefined} node_type
- * @param {DocumentSchema} schema
- * @returns {{ main_nodes: string[], nodes: Record<string, any> } | null}
- */
-export function create_plain_text_nodes_payload(paragraph_fragments, node_type, schema) {
+export function create_plain_text_nodes_payload(
+	paragraph_fragments: string[],
+	node_type: string | null | undefined,
+	schema: DocumentSchema
+): { main_nodes: string[]; nodes: Record<string, DocumentNode> } | null {
 	if (!Array.isArray(paragraph_fragments) || paragraph_fragments.length === 0 || !node_type) {
 		return null;
 	}
@@ -146,7 +135,7 @@ export function create_plain_text_nodes_payload(paragraph_fragments, node_type,
 	const text_property_name = get_text_property_name(node_type, schema);
 	if (!text_property_name) return null;
 
-	const payload = {
+	const payload: { main_nodes: string[]; nodes: Record<string, DocumentNode> } = {
 		main_nodes: [],
 		nodes: {}
 	};