svedit 0.11.1 → 0.13.0

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.
@@ -81,7 +88,7 @@ export type ArrayType = 'string_array' | 'number_array' | 'boolean_array' | 'int
 /**
  * Special types for rich content.
  */
-export type RichType = 'annotated_text';
+export type RichType = 'text';
 
 /**
  * Node reference types for linking to other nodes.
@@ -98,60 +105,89 @@ 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'
-// 	| 'annotated_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 'annotated_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']>;
-// };
-
-/**
- * A property that stores an annotated text with required allow_newlines setting.
- */
-export type AnnotatedTextProperty = {
-	type: 'annotated_text';
-	node_types?: string[];
+// ===== 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.
+ */
+export type TextProperty = {
+	type: 'text';
+	mark_types?: string[];
+	annotation_types?: string[];
 	allow_newlines: boolean;
 };
 
@@ -161,6 +197,7 @@ export type AnnotatedTextProperty = {
 export type StringProperty = {
 	type: 'string';
 	default?: string;
+	values?: readonly string[];
 };
 
 /**
@@ -185,6 +222,8 @@ export type BooleanProperty = {
 export type IntegerProperty = {
 	type: 'integer';
 	default?: number;
+	min?: number;
+	max?: number;
 };
 
 /**
@@ -228,7 +267,7 @@ export type IntegerArrayProperty = {
 };
 
 /**
- * A property that stores a primitive value (excluding annotated_text).
+ * A property that stores a primitive value (excluding text).
  */
 export type PrimitiveProperty =
 	| StringProperty
@@ -256,6 +295,8 @@ export type NodeProperty = {
 export type NodeArrayProperty = {
 	type: 'node_array';
 	node_types: string[];
+	mark_types?: string[];
+	annotation_types?: string[];
 	default_node_type?: string;
 };
 
@@ -263,29 +304,26 @@ export type NodeArrayProperty = {
  * Union type for all possible property definitions.
  */
 export type PropertyDefinition =
-	| PrimitiveProperty
-	| AnnotatedTextProperty
-	| NodeProperty
-	| NodeArrayProperty;
+	PrimitiveProperty | TextProperty | NodeProperty | NodeArrayProperty;
 
 /**
  * Node kind values for different types of content nodes
  */
-export type NodeKind = 'document' | 'block' | 'text' | 'annotation';
+export type NodeKind = 'document' | 'block' | 'text' | 'mark' | 'annotation';
 
 /**
- * Schema for text nodes - must have a content property of type annotated_text.
- * Use define_document_schema to also check that content is the only annotated_text property.
+ * Schema for text nodes - must have a content property of type text.
+ * Use define_document_schema to also check that content is the only text property.
  */
 export type TextNodeSchema = {
 	kind: 'text';
 	properties: {
-		content: AnnotatedTextProperty;
+		content: TextProperty;
 	} & Record<string, PropertyDefinition>;
 };
 
-export type AnnotatedTextPropertyNames<Properties> = {
-	[PropertyName in keyof Properties]: Properties[PropertyName] extends { type: 'annotated_text' }
+export type TextPropertyNames<Properties> = {
+	[PropertyName in keyof Properties]: Properties[PropertyName] extends { type: 'text' }
 		? PropertyName
 		: never;
 }[keyof Properties];
@@ -294,13 +332,11 @@ export type TextNodeSchemaError<Message extends string> = {
 	[SchemaError in `Svedit schema error: ${Message}`]: never;
 };
 
-export type TextNodeMissingContentError = TextNodeSchemaError<
-	'Text node schemas must define a "content" property of type annotated_text.'
->;
+export type TextNodeMissingContentError =
+	TextNodeSchemaError<'Text node schemas must define a "content" property of type text.'>;
 
-export type TextNodeExtraAnnotatedTextError<ExtraProperty extends string> = TextNodeSchemaError<
-	`Text node schemas must not define annotated_text property "${ExtraProperty}". Use "content" as the only annotated_text property.`
->;
+export type TextNodeExtraTextPropertyError<ExtraProperty extends string> =
+	TextNodeSchemaError<`Text node schemas must not define text property "${ExtraProperty}". Use "content" as the only text property.`>;
 
 export type ValidateTextNodeSchema<Schema> = Schema extends {
 	kind: 'text';
@@ -308,11 +344,11 @@ export type ValidateTextNodeSchema<Schema> = Schema extends {
 }
 	? string extends keyof Properties
 		? Schema
-		: Properties extends { content: AnnotatedTextProperty }
-			? Exclude<AnnotatedTextPropertyNames<Properties>, 'content'> extends infer ExtraProperties
+		: Properties extends { content: TextProperty }
+			? Exclude<TextPropertyNames<Properties>, 'content'> extends infer ExtraProperties
 				? [ExtraProperties] extends [never]
 					? Schema
-					: TextNodeExtraAnnotatedTextError<Extract<ExtraProperties, string>>
+					: TextNodeExtraTextPropertyError<Extract<ExtraProperties, string>>
 				: never
 			: TextNodeMissingContentError
 	: Schema;
@@ -325,7 +361,7 @@ export type ValidateDocumentSchema<Schema extends Record<string, NodeSchema>> =
  * Schema for non-text nodes
  */
 export type NonTextNodeSchema = {
-	kind: 'document' | 'block' | 'annotation';
+	kind: 'document' | 'block' | 'mark' | 'annotation';
 	properties: Record<string, PropertyDefinition>;
 };
 
@@ -348,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;
 };
 
@@ -362,10 +405,17 @@ 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 AnnotatedTextProperty component
+ * Props for the TextProperty component
  */
-export type AnnotatedTextPropertyProps = {
+export type TextPropertyProps = {
 	/** The full path to the property */
 	path: DocumentPath;
 	/** Optional custom HTML tag */
@@ -375,7 +425,7 @@ export type AnnotatedTextPropertyProps = {
 	/** 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;
 };
 
 /**
@@ -391,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;
 };
 
 /**
@@ -405,7 +455,7 @@ 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;
 };
 
 /**
@@ -414,6 +464,10 @@ export type NodeArrayPropertyProps = {
 export type NodeProps = {
 	/** The full path to the node */
 	path: DocumentPath;
+	/** The single node-array mark wrapping this node, if any */
+	mark?: NodeArrayAttachmentContext | null;
+	/** All node-array annotations covering this node */
+	annotations?: Array<NodeArrayAttachmentContext>;
 	/** Optional custom HTML tag */
 	tag?: string;
 	/** Optional string of CSS classes */
@@ -421,15 +475,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']) */
@@ -443,24 +497,88 @@ export type SveditProps = {
 };
 
 /**
- * Represents an annotation in an annotated string
+ * 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.
  */
-export type Annotation = {
+export type Attachment = {
 	start_offset: number;
 	end_offset: number;
 	node_id: NodeId;
 };
 
 /**
- * Represents an annotated text with text and annotations
+ * A content-level range (e.g. strong, emphasis, link, section).
+ * Marks are mutually exclusive within a property and render in-place.
+ */
+export type Mark = Attachment;
+
+/**
+ * A metadata/overlay range (e.g. comment, marker).
+ * Annotations may overlap and are data-only.
  */
-export type AnnotatedText = {
-	text: string;
+export type Annotation = Attachment;
+
+/**
+ * Represents text content with marks and annotations.
+ */
+export type Text = {
+	content: string;
+	marks: Array<Mark>;
 	annotations: Array<Annotation>;
 };
 
 /**
- * Represents a selection highlight fragment for non-annotated text selections
+ * Represents a node array with nodes, marks and annotations.
+ */
+export type NodeArray = {
+	nodes: Array<NodeId>;
+	marks: Array<Mark>;
+	annotations: Array<Annotation>;
+};
+
+/**
+ * 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.
+ */
+export type NodeArrayAttachmentContext = {
+	start_offset: number;
+	end_offset: number;
+	node_id: NodeId;
+	index: number;
+	node: DocumentNode;
+	is_start: boolean;
+	is_middle: boolean;
+	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 unmarked text selections
  */
 export type SelectionHighlightFragment = {
 	type: 'selection_highlight';
@@ -468,19 +586,48 @@ export type SelectionHighlightFragment = {
 };
 
 /**
- * Represents an annotation fragment in annotated text content
+ * Represents a mark fragment in text content
  */
-export type AnnotationFragment = {
-	type: 'annotation';
-	/** NodeId that has annotation type and details */
-	node: any;
-	/** The text content of the annotation */
+export type MarkFragment = {
+	type: 'mark';
+	/** NodeId that has mark type and details */
+	node: DocumentNode;
+	/** The text content of the mark */
 	content: string;
-	/** Index of the annotation in the original array */
-	annotation_index: number;
+	/** Index of the mark in the original array */
+	mark_index: number;
+};
+
+/**
+ * Represents a fragment of text content
+ */
+export type Fragment = string | MarkFragment | SelectionHighlightFragment;
+
+/**
+ * Represents a node array fragment for plain nodes
+ */
+export type NodeArrayPlainFragment = {
+	type: 'nodes';
+	nodes: Array<NodeId>;
+	start_index: number;
+};
+
+/**
+ * Represents a mark fragment in node array content
+ */
+export type NodeArrayMarkFragment = {
+	type: 'mark';
+	/** NodeId that has mark type and details */
+	node: DocumentNode;
+	/** The nodes wrapped by the mark */
+	nodes: Array<NodeId>;
+	/** Start index in the original nodes array */
+	start_index: number;
+	/** Index of the mark in the original array */
+	mark_index: number;
 };
 
 /**
- * Represents a fragment of annotated text content
+ * Represents a fragment of node array content
  */
-export type Fragment = string | AnnotationFragment | SelectionHighlightFragment;
+export type NodeArrayFragment = NodeArrayPlainFragment | NodeArrayMarkFragment;