svedit 0.12.0 → 0.14.0

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

@@ -1,20 +1,33 @@
 import { split_text, join_text, get_char_length } from './utils.js';
 import { get_default_node_type } from './doc_utils.js';
+import type Transaction from './Transaction.svelte.js';
+import type {
+	DocumentNode,
+	DocumentPath,
+	NodeArrayProperty,
+	NodeProperty,
+	Selection,
+	TextSelection
+} from './types.js';
 
 /**
  * Set multiple properties on a node via a transaction.
  *
- * @param {object} tr - The transaction
- * @param {Array} path - Path to the node
- * @param {Record<string, any>} properties - Key/value pairs to set
+ * @param tr - The transaction
+ * @param path - Path to the node
+ * @param properties - Key/value pairs to set
  */
-export function set_properties(tr, path, properties) {
+export function set_properties(
+	tr: Transaction,
+	path: DocumentPath,
+	properties: Record<string, unknown>
+): void {
 	for (const [key, value] of Object.entries(properties)) {
 		tr.set([...path, key], value);
 	}
 }
 
-export function break_text_node(tr) {
+export function break_text_node(tr: Transaction): boolean {
 	// Keep a reference of the original selection (before any transforms are applied)
 	const selection = tr.selection;
 	// First we need to ensure we have a text selection
@@ -28,7 +41,7 @@ export function break_text_node(tr) {
 	if (tr.kind(node) !== 'text') return false;
 	const is_inside_node_array = tr.inspect(selection.path.slice(0, -2))?.type === 'node_array';
 	if (!is_inside_node_array) return false; // Do nothing if we're not inside a node_array
-	const node_array_prop = selection.path.at(-3);
+	const node_array_prop = String(selection.path.at(-3));
 	// Get the node that owns the node_array property (e.g. a page.body)
 	const node_array_node = tr.get(selection.path.slice(0, -3));
 
@@ -37,23 +50,26 @@ export function break_text_node(tr) {
 		tr.delete_selection();
 	}
 
-	const split_at_position = tr.selection.anchor_offset;
+	// After delete_selection the selection is still a (collapsed) text selection
+	const split_at_position = (tr.selection as TextSelection).anchor_offset;
 	const content = tr.get(selection.path);
 	const [left_text, right_text] = split_text(content, split_at_position);
 
 	tr.set([node.id, 'content'], left_text);
 
-	const node_insert_position = {
+	const node_insert_position: Selection = {
 		type: 'node',
 		path: tr.selection.path.slice(0, -2),
-		anchor_offset: parseInt(tr.selection.path.at(-2), 10) + 1,
-		focus_offset: parseInt(tr.selection.path.at(-2), 10) + 1
+		anchor_offset: (tr.selection.path.at(-2) as number) + 1,
+		focus_offset: (tr.selection.path.at(-2) as number) + 1
 	};
 
 	// TODO: Only use default_node_type when caret is at the end of
 	const node_array_property_definition =
 		tr.schema[node_array_node.type].properties[node_array_prop];
-	const target_node_type = get_default_node_type(node_array_property_definition);
+	const target_node_type = get_default_node_type(
+		node_array_property_definition as NodeProperty | NodeArrayProperty
+	);
 
 	if (!target_node_type) {
 		console.warn(
@@ -68,7 +84,7 @@ export function break_text_node(tr) {
 	return true;
 }
 
-export function join_text_node(tr) {
+export function join_text_node(tr: Transaction): boolean {
 	// Keep a reference of the original selection (before any transforms are applied)
 	const selection = tr.selection;
 	// First we need to ensure we have a text selection
@@ -79,16 +95,16 @@ export function join_text_node(tr) {
 	const is_inside_node_array = tr.inspect(selection.path.slice(0, -2))?.type === 'node_array';
 	if (!is_inside_node_array) return false; // Do nothing if we're not inside a node_array
 
-	const node_index = parseInt(tr.selection.path.at(-2), 10);
+	const node_index = tr.selection.path.at(-2) as number;
 
 	// Determine if we can join with the previous node
 	let can_join = false;
-	let predecessor_node = null;
+	let predecessor_node: DocumentNode | null = null;
 
 	if (node_index > 0) {
 		const previous_text_path = [...tr.selection.path.slice(0, -2), node_index - 1];
 		predecessor_node = tr.get(previous_text_path);
-		can_join = tr.kind(predecessor_node) === 'text';
+		can_join = predecessor_node !== null && tr.kind(predecessor_node) === 'text';
 	}
 
 	// Special behavior: if we can't join and current node is empty, delete it
@@ -104,7 +120,7 @@ export function join_text_node(tr) {
 	}
 
 	// If we can't join for any reason, return false
-	if (!can_join) {
+	if (!can_join || !predecessor_node) {
 		return false;
 	}
 
@@ -138,7 +154,7 @@ export function join_text_node(tr) {
 	return true;
 }
 
-export function insert_default_node(tr) {
+export function insert_default_node(tr: Transaction): boolean {
 	const selection = tr.selection;
 
 	// Only work with collapsed node selections
@@ -148,15 +164,17 @@ export function insert_default_node(tr) {
 
 	const path = selection.path;
 	const node_array_node = tr.get(path.slice(0, -1));
-	const property_name = path.at(-1);
+	const property_name = String(path.at(-1));
 
 	// Get the definition for this property
 	const property_definition = tr.schema[node_array_node.type].properties[property_name];
-	const default_type = get_default_node_type(property_definition);
+	const default_type = get_default_node_type(
+		property_definition as NodeProperty | NodeArrayProperty
+	);
 
 	// Use the inserter function if available
-	if (tr.config?.inserters?.[default_type]) {
-		tr.config.inserters[default_type](tr);
+	if (tr.config?.inserters?.[default_type as string]) {
+		tr.config.inserters[default_type as string](tr);
 		return true;
 	} else {
 		throw new Error(`No inserter function available for default node type '${default_type}'`);

package/src/lib/{types.d.ts → types.ts}

@@ -1,12 +1,12 @@
 import type Session from './Session.svelte.js';
-import type Svedit from './Svedit.svelte';
+import type { VisibilityRegistryApi } from './node_visibility.svelte.js';
 
 // ===== SVELTE TYPE IMPORTS =====
 
 /**
  * Import Svelte's Snippet type for properly typing children in components
  */
-import type { Component, Snippet } from 'svelte';
+import type { Snippet } from 'svelte';
 
 // ===== SELECTION TYPE DEFINITIONS =====
 
@@ -19,6 +19,13 @@ import type { Component, Snippet } from 'svelte';
  */
 export type NodeId = string;
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type DynamicRecord = Record<string, any>;
+export type SessionConfig = DynamicRecord;
+export type CommandRegistry = DynamicRecord;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type DocumentOperation = [string, ...any[]];
+
 /**
  * Array of IDs, property names (strings), or indexes (integers) that identify a node or property in the document.
  * String segments must follow the same path segment rules as NodeId.
@@ -98,54 +105,82 @@ export type PrimitiveType = ScalarType | ArrayType | RichType;
  */
 export type PropertyType = PrimitiveType | ReferenceType;
 
-// TODO: We may later want more sophisticated type inference, so that typing
-// e.g. `session.get('image')` auto-completes the node's properties based on
-// the schema definition. The types below are a starting point for that.
-//
-// export type DocumentSchemaPrimitive =
-// 	| 'string'
-// 	| 'number'
-// 	| 'boolean'
-// 	| 'integer'
-// 	| 'datetime'
-// 	| 'string_array'
-// 	| 'number_array'
-// 	| 'boolean_array'
-// 	| 'integer_array'
-// 	| 'text'
-// 	| 'node'
-// 	| 'node_array';
-//
-// export type DocumentSchemaValueToJs<T> = T extends 'string'
-// 	? string
-// 	: T extends 'number'
-// 		? number
-// 		: T extends 'boolean'
-// 			? boolean
-// 			: T extends 'integer'
-// 				? number
-// 				: T extends 'datetime'
-// 					? string
-// 					: T extends 'string_array'
-// 						? Array<string>
-// 						: T extends 'number_array'
-// 							? Array<number>
-// 							: T extends 'boolean_array'
-// 								? Array<boolean>
-// 								: T extends 'integer_array'
-// 									? Array<number>
-// 									: T extends 'text'
-// 										? AnnotatedText
-// 										: T extends 'node'
-// 											? string
-// 											: T extends 'node_array'
-// 												? Array<string>
-// 												: never;
-//
-// export type DocumentNodeToJs<S extends NodeSchema> = { id: string; type: string } & {
-// 	[K in keyof S['properties']]: DocumentSchemaValueToJs<S['properties'][K]['type']>;
-// };
+// ===== SCHEMA-DERIVED NODE TYPES =====
 
+/**
+ * Maps a schema property definition to the runtime value type it stores.
+ */
+export type PropertyValue<P extends PropertyDefinition> = P extends {
+	type: 'string';
+	values: readonly (infer Value extends string)[];
+}
+	? Value
+	: P extends { type: 'string' }
+		? string
+		: P extends { type: 'number' }
+			? number
+			: P extends { type: 'integer' }
+				? number
+				: P extends { type: 'boolean' }
+					? boolean
+					: P extends { type: 'datetime' }
+						? string
+						: P extends { type: 'string_array' }
+							? string[]
+							: P extends { type: 'number_array' }
+								? number[]
+								: P extends { type: 'integer_array' }
+									? number[]
+									: P extends { type: 'boolean_array' }
+										? boolean[]
+										: P extends { type: 'text' }
+											? Text
+											: P extends { type: 'node' }
+												? NodeId
+												: P extends { type: 'node_array' }
+													? NodeArray
+													: never;
+
+/**
+ * The runtime shape of a node of a specific type, derived from the schema.
+ *
+ * Falls back to the untyped DocumentNode when the schema is not a concrete
+ * schema literal (e.g. the DocumentSchema default of Session).
+ */
+export type NodeOfType<S extends DocumentSchema, T extends keyof S> = string extends keyof S
+	? DocumentNode
+	: {
+			id: NodeId;
+			type: T;
+		} & {
+			[K in keyof S[T]['properties']]: PropertyValue<S[T]['properties'][K]>;
+		};
+
+/**
+ * Discriminated union of all node types in a schema. Narrow with
+ * `node.type === '...'` to get exact property types.
+ *
+ * Falls back to the untyped DocumentNode when the schema is not a concrete
+ * schema literal (e.g. the DocumentSchema default of Session).
+ */
+export type AnyNode<S extends DocumentSchema> = string extends keyof S
+	? DocumentNode
+	: {
+			[T in keyof S]: NodeOfType<S, T>;
+		}[keyof S];
+
+/**
+ * Convenience map from node type name to its runtime node shape,
+ * e.g. `NodeMap<typeof document_schema>['story']`.
+ */
+export type NodeMap<S extends DocumentSchema> = {
+	[T in keyof S]: NodeOfType<S, T>;
+};
+
+/**
+ * Assert that a node is of the given type. Narrows the static type and
+ * checks at runtime — for call sites that know what they expect.
+ */
 /**
  * A property that stores text with optional marks and annotations and required allow_newlines setting.
  */
@@ -162,6 +197,7 @@ export type TextProperty = {
 export type StringProperty = {
 	type: 'string';
 	default?: string;
+	values?: readonly string[];
 };
 
 /**
@@ -186,6 +222,8 @@ export type BooleanProperty = {
 export type IntegerProperty = {
 	type: 'integer';
 	default?: number;
+	min?: number;
+	max?: number;
 };
 
 /**
@@ -346,6 +384,13 @@ export type DocumentSchema = Record<string, NodeSchema>;
 export type DocumentNode = {
 	id: string;
 	type: string;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	[key: string]: any;
+};
+
+export type Inspection = {
+	kind: 'property' | 'node';
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	[key: string]: any;
 };
 
@@ -360,6 +405,13 @@ export type Document = {
 	};
 };
 
+/** Converts a document node to HTML, with access to recursive exporters. */
+export type NodeHtmlExporter<S extends DocumentSchema = DocumentSchema> = (
+	node: DocumentNode,
+	session: Session<S>,
+	html_exporters: Record<string, NodeHtmlExporter<S>>
+) => string;
+
 /**
  * Props for the TextProperty component
  */
@@ -373,7 +425,7 @@ export type TextPropertyProps = {
 	/** A placeholder to be rendered for empty content */
 	placeholder?: string;
 	/** Rest props to spread onto the rendered element (e.g. href, target, etc.) */
-	[key: string]: any;
+	[key: string]: unknown;
 };
 
 /**
@@ -389,7 +441,7 @@ export type CustomPropertyProps = {
 	/** The content of the custom property (e.g. an image) */
 	children: Snippet;
 	/** Rest props to spread onto the rendered element */
-	[key: string]: any;
+	[key: string]: unknown;
 };
 
 /**
@@ -403,7 +455,25 @@ export type NodeArrayPropertyProps = {
 	/** The `class` attribute on the container element */
 	class?: string;
 	/** Rest props to spread onto the rendered element (e.g. href, target, etc.) */
-	[key: string]: any;
+	[key: string]: unknown;
+};
+
+/**
+ * Props passed to the consumer's `system_components.node_gap_tools`
+ * component. It renders inside the active node gap marker (the one carrying
+ * the caret), so it inherits the `--row` orientation variable and
+ * appears/disappears together with the caret. The marker has
+ * pointer-events: none — interactive tools must set pointer-events: auto.
+ */
+export type NodeGapToolsProps = {
+	/** The full path to the node_array the gap belongs to */
+	path: DocumentPath;
+	/** The insertion offset of the gap (0..count) */
+	offset: number;
+	/** True for the gap before the first node */
+	is_first: boolean;
+	/** True for the gap after the last node */
+	is_last: boolean;
 };
 
 /**
@@ -423,15 +493,15 @@ export type NodeProps = {
 	/** The type-specific content of the node */
 	children: Snippet;
 	/** Rest props to spread onto the rendered element (e.g. href, target, etc.) */
-	[key: string]: any;
+	[key: string]: unknown;
 };
 
 /**
  * Props for the Svedit component
  */
-export type SveditProps = {
-	/** The session instance */
-	session: Session;
+export type SveditProps<S extends DocumentSchema = DocumentSchema> = {
+	/** The schema-typed session instance */
+	session: Session<S>;
 	/** Determines wether the document should be editable or read-only. */
 	editable?: boolean;
 	/** The path to the root element (e.g. ['page_1']) */
@@ -444,6 +514,24 @@ export type SveditProps = {
 	spellcheck?: 'true' | 'false';
 };
 
+/**
+ * Context provided by the Svedit component to commands and descendant components.
+ */
+export type SveditContext<S extends DocumentSchema = DocumentSchema> = {
+	session: Session<S>;
+	editable: boolean;
+	is_composing: boolean;
+	canvas_el: HTMLElement | undefined;
+	canvas_focused: boolean;
+	focus_canvas: () => void;
+	visibility_registry?: VisibilityRegistryApi;
+};
+
+/** Internal descendant context after Svedit's visibility registry is installed. */
+export type SveditRenderContext<S extends DocumentSchema = DocumentSchema> = SveditContext<S> & {
+	visibility_registry: VisibilityRegistryApi;
+};
+
 /**
  * A range with an attached payload node, used for both marks and annotations.
  */
@@ -468,23 +556,23 @@ export type Annotation = Attachment;
 /**
  * Represents text content with marks and annotations.
  */
-export type AnnotatedText = {
+export type Text = {
 	content: string;
 	marks: Array<Mark>;
 	annotations: Array<Annotation>;
 };
 
 /**
- * Represents an annotated node array with nodes, marks and annotations
+ * Represents a node array with nodes, marks and annotations.
  */
-export type AnnotatedNodeArray = {
+export type NodeArray = {
 	nodes: Array<NodeId>;
 	marks: Array<Mark>;
 	annotations: Array<Annotation>;
 };
 
 /**
- * Attachment context passed to a node rendered inside an annotated node array.
+ * Attachment context passed to a node rendered inside a node array.
  * It is the flattened mark or annotation attachment, enriched with the resolved
  * payload node, its index in the parent attachment array, and this child node's
  * position in the attachment range.
@@ -500,8 +588,15 @@ export type NodeArrayAttachmentContext = {
 	is_end: boolean;
 };
 
+/** Internal context shared by a node array and its rendered child nodes. */
+export type NodeArrayRenderContext = {
+	length: number;
+	mark_for: (node_index: number) => NodeArrayAttachmentContext | null;
+	annotations_for: (node_index: number) => NodeArrayAttachmentContext[];
+};
+
 /**
- * Represents a selection highlight fragment for non-annotated text selections
+ * Represents a selection highlight fragment for unmarked text selections
  */
 export type SelectionHighlightFragment = {
 	type: 'selection_highlight';
@@ -509,12 +604,12 @@ export type SelectionHighlightFragment = {
 };
 
 /**
- * Represents a mark fragment in annotated text content
+ * Represents a mark fragment in text content
  */
 export type MarkFragment = {
 	type: 'mark';
 	/** NodeId that has mark type and details */
-	node: any;
+	node: DocumentNode;
 	/** The text content of the mark */
 	content: string;
 	/** Index of the mark in the original array */
@@ -522,7 +617,7 @@ export type MarkFragment = {
 };
 
 /**
- * Represents a fragment of annotated text content
+ * Represents a fragment of text content
  */
 export type Fragment = string | MarkFragment | SelectionHighlightFragment;
 
@@ -541,7 +636,7 @@ export type NodeArrayPlainFragment = {
 export type NodeArrayMarkFragment = {
 	type: 'mark';
 	/** NodeId that has mark type and details */
-	node: any;
+	node: DocumentNode;
 	/** The nodes wrapped by the mark */
 	nodes: Array<NodeId>;
 	/** Start index in the original nodes array */
@@ -551,6 +646,6 @@ export type NodeArrayMarkFragment = {
 };
 
 /**
- * Represents a fragment of annotated node array content
+ * Represents a fragment of node array content
  */
 export type NodeArrayFragment = NodeArrayPlainFragment | NodeArrayMarkFragment;