svedit 0.11.1 → 0.13.0

package/dist/types.d.ts

@@ -1,15 +1,9 @@
 import type Session from './Session.svelte.js';
-import type Svedit from './Svedit.svelte';
-
-// ===== SVELTE TYPE IMPORTS =====
-
+import type { VisibilityRegistryApi } from './node_visibility.svelte.js';
 /**
  * Import Svelte's Snippet type for properly typing children in components
  */
-import type { Component, Snippet } from 'svelte';
-
-// ===== SELECTION TYPE DEFINITIONS =====
-
+import type { Snippet } from 'svelte';
 /**
  * A unique node identifier.
  *
@@ -18,469 +12,513 @@ import type { Component, Snippet } from 'svelte';
  * dashes, and must not contain `__`.
  */
 export type NodeId = string;
-
+export type DynamicRecord = Record<string, any>;
+export type SessionConfig = DynamicRecord;
+export type CommandRegistry = DynamicRecord;
+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.
  */
 export type DocumentPath = Array<string | number>;
-
 /**
  * Text selection within a text property
  */
 export type TextSelection = {
-	type: 'text';
-	path: DocumentPath;
-	anchor_offset: number;
-	focus_offset: number;
+    type: 'text';
+    path: DocumentPath;
+    anchor_offset: number;
+    focus_offset: number;
 };
-
 /**
  * Node selection within a node array
  */
 export type NodeSelection = {
-	type: 'node';
-	path: DocumentPath;
-	anchor_offset: number;
-	focus_offset: number;
+    type: 'node';
+    path: DocumentPath;
+    anchor_offset: number;
+    focus_offset: number;
 };
-
 /**
  * Property selection within a node
  */
 export type PropertySelection = {
-	type: 'property';
-	path: DocumentPath;
+    type: 'property';
+    path: DocumentPath;
 };
-
 /**
  * Union type for all possible selection types
  */
 export type Selection = TextSelection | NodeSelection | PropertySelection;
-
 /**
  * Represents only the range (no direction and payload) of a NodeSelection or TextSelection
  */
 export type SelectionRange = {
-	start_offset: number;
-	end_offset: number;
+    start_offset: number;
+    end_offset: number;
 };
-
-// ===== SCHEMA TYPE DEFINITIONS =====
-
 /**
  * Basic scalar types supported by the schema system.
  */
 export type ScalarType = 'string' | 'number' | 'boolean' | 'integer' | 'datetime';
-
 /**
  * Array types for collections of scalar values.
  */
 export type ArrayType = 'string_array' | 'number_array' | 'boolean_array' | 'integer_array';
-
 /**
  * Special types for rich content.
  */
-export type RichType = 'annotated_text';
-
+export type RichType = 'text';
 /**
  * Node reference types for linking to other nodes.
  */
 export type ReferenceType = 'node' | 'node_array';
-
 /**
  * All primitive types that can be used in property definitions.
  */
 export type PrimitiveType = ScalarType | ArrayType | RichType;
-
 /**
  * All possible property types in schemas.
  */
 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[];
-	allow_newlines: boolean;
-};
-
+/**
+ * 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;
+};
 /**
  * A property that stores a string value.
  */
 export type StringProperty = {
-	type: 'string';
-	default?: string;
+    type: 'string';
+    default?: string;
+    values?: readonly string[];
 };
-
 /**
  * A property that stores a number value.
  */
 export type NumberProperty = {
-	type: 'number';
-	default?: number;
+    type: 'number';
+    default?: number;
 };
-
 /**
  * A property that stores a boolean value.
  */
 export type BooleanProperty = {
-	type: 'boolean';
-	default?: boolean;
+    type: 'boolean';
+    default?: boolean;
 };
-
 /**
  * A property that stores an integer value.
  */
 export type IntegerProperty = {
-	type: 'integer';
-	default?: number;
+    type: 'integer';
+    default?: number;
+    min?: number;
+    max?: number;
 };
-
 /**
  * A property that stores a datetime value.
  */
 export type DatetimeProperty = {
-	type: 'datetime';
-	default?: string;
+    type: 'datetime';
+    default?: string;
 };
-
 /**
  * A property that stores an array of strings.
  */
 export type StringArrayProperty = {
-	type: 'string_array';
-	default?: string[];
+    type: 'string_array';
+    default?: string[];
 };
-
 /**
  * A property that stores an array of numbers.
  */
 export type NumberArrayProperty = {
-	type: 'number_array';
-	default?: number[];
+    type: 'number_array';
+    default?: number[];
 };
-
 /**
  * A property that stores an array of booleans.
  */
 export type BooleanArrayProperty = {
-	type: 'boolean_array';
-	default?: boolean[];
+    type: 'boolean_array';
+    default?: boolean[];
 };
-
 /**
  * A property that stores an array of integers.
  */
 export type IntegerArrayProperty = {
-	type: 'integer_array';
-	default?: number[];
+    type: 'integer_array';
+    default?: number[];
 };
-
 /**
- * A property that stores a primitive value (excluding annotated_text).
+ * A property that stores a primitive value (excluding text).
  */
-export type PrimitiveProperty =
-	| StringProperty
-	| NumberProperty
-	| BooleanProperty
-	| IntegerProperty
-	| DatetimeProperty
-	| StringArrayProperty
-	| NumberArrayProperty
-	| BooleanArrayProperty
-	| IntegerArrayProperty;
-
+export type PrimitiveProperty = StringProperty | NumberProperty | BooleanProperty | IntegerProperty | DatetimeProperty | StringArrayProperty | NumberArrayProperty | BooleanArrayProperty | IntegerArrayProperty;
 /**
  * A property that stores a reference to a single node.
  */
 export type NodeProperty = {
-	type: 'node';
-	node_types: string[];
-	default_node_type?: string;
+    type: 'node';
+    node_types: string[];
+    default_node_type?: string;
 };
-
 /**
  * A property that stores an array of node references.
  */
 export type NodeArrayProperty = {
-	type: 'node_array';
-	node_types: string[];
-	default_node_type?: string;
+    type: 'node_array';
+    node_types: string[];
+    mark_types?: string[];
+    annotation_types?: string[];
+    default_node_type?: string;
 };
-
 /**
  * Union type for all possible property definitions.
  */
-export type PropertyDefinition =
-	| PrimitiveProperty
-	| AnnotatedTextProperty
-	| NodeProperty
-	| NodeArrayProperty;
-
+export type PropertyDefinition = 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;
-	} & Record<string, PropertyDefinition>;
-};
-
-export type AnnotatedTextPropertyNames<Properties> = {
-	[PropertyName in keyof Properties]: Properties[PropertyName] extends { type: 'annotated_text' }
-		? PropertyName
-		: never;
+    kind: 'text';
+    properties: {
+        content: TextProperty;
+    } & Record<string, PropertyDefinition>;
+};
+export type TextPropertyNames<Properties> = {
+    [PropertyName in keyof Properties]: Properties[PropertyName] extends {
+        type: 'text';
+    } ? PropertyName : never;
 }[keyof Properties];
-
 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 TextNodeExtraAnnotatedTextError<ExtraProperty extends string> = TextNodeSchemaError<
-	`Text node schemas must not define annotated_text property "${ExtraProperty}". Use "content" as the only annotated_text property.`
->;
-
+    [SchemaError in `Svedit schema error: ${Message}`]: never;
+};
+export type TextNodeMissingContentError = TextNodeSchemaError<'Text node schemas must define a "content" property of type text.'>;
+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';
-	properties: infer Properties;
-}
-	? string extends keyof Properties
-		? Schema
-		: Properties extends { content: AnnotatedTextProperty }
-			? Exclude<AnnotatedTextPropertyNames<Properties>, 'content'> extends infer ExtraProperties
-				? [ExtraProperties] extends [never]
-					? Schema
-					: TextNodeExtraAnnotatedTextError<Extract<ExtraProperties, string>>
-				: never
-			: TextNodeMissingContentError
-	: Schema;
-
+    kind: 'text';
+    properties: infer Properties;
+} ? string extends keyof Properties ? Schema : Properties extends {
+    content: TextProperty;
+} ? Exclude<TextPropertyNames<Properties>, 'content'> extends infer ExtraProperties ? [ExtraProperties] extends [never] ? Schema : TextNodeExtraTextPropertyError<Extract<ExtraProperties, string>> : never : TextNodeMissingContentError : Schema;
 export type ValidateDocumentSchema<Schema extends Record<string, NodeSchema>> = {
-	[NodeType in keyof Schema]: ValidateTextNodeSchema<Schema[NodeType]>;
+    [NodeType in keyof Schema]: ValidateTextNodeSchema<Schema[NodeType]>;
 };
-
 /**
  * Schema for non-text nodes
  */
 export type NonTextNodeSchema = {
-	kind: 'document' | 'block' | 'annotation';
-	properties: Record<string, PropertyDefinition>;
+    kind: 'document' | 'block' | 'mark' | 'annotation';
+    properties: Record<string, PropertyDefinition>;
 };
-
 /**
  * A node schema defines the structure of a specific node type.
  * Contains a kind and properties object that maps property names to their definitions.
  */
 export type NodeSchema = TextNodeSchema | NonTextNodeSchema;
-
 /**
  * A document schema defines all node types available in a document.
  * Maps node type names to their schemas.
  */
 export type DocumentSchema = Record<string, NodeSchema>;
-
 /**
  * A node in the document.
  * Must have id and type properties, with other properties defined by the schema.
  */
 export type DocumentNode = {
-	id: string;
-	type: string;
-	[key: string]: any;
+    id: string;
+    type: string;
+    [key: string]: any;
+};
+export type Inspection = {
+    kind: 'property' | 'node';
+    [key: string]: any;
 };
-
 /**
  * The document format - an object with document_id and nodes.
  * The nodes object maps node IDs to their node data.
  */
 export type Document = {
-	document_id: string;
-	nodes: {
-		[key: string]: DocumentNode;
-	};
+    document_id: string;
+    nodes: {
+        [key: string]: DocumentNode;
+    };
 };
-
-/**
- * Props for the AnnotatedTextProperty component
- */
-export type AnnotatedTextPropertyProps = {
-	/** The full path to the property */
-	path: DocumentPath;
-	/** Optional custom HTML tag */
-	tag?: string;
-	/** The `class` attribute on the content element */
-	class?: string;
-	/** 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;
+/** 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
+ */
+export type TextPropertyProps = {
+    /** The full path to the property */
+    path: DocumentPath;
+    /** Optional custom HTML tag */
+    tag?: string;
+    /** The `class` attribute on the content element */
+    class?: string;
+    /** 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]: unknown;
 };
-
 /**
  * Props for the CustomProperty component
  */
 export type CustomPropertyProps = {
-	/** The full path to the property */
-	path: DocumentPath;
-	/** Optional custom HTML tag */
-	tag?: string;
-	/** The `class` attribute on the content element */
-	class?: string;
-	/** The content of the custom property (e.g. an image) */
-	children: Snippet;
-	/** Rest props to spread onto the rendered element */
-	[key: string]: any;
-};
-
+    /** The full path to the property */
+    path: DocumentPath;
+    /** Optional custom HTML tag */
+    tag?: string;
+    /** The `class` attribute on the content element */
+    class?: string;
+    /** The content of the custom property (e.g. an image) */
+    children: Snippet;
+    /** Rest props to spread onto the rendered element */
+    [key: string]: unknown;
+};
 /**
  * Props for the NodeArray component
  */
 export type NodeArrayPropertyProps = {
-	/** The full path to the property */
-	path: DocumentPath;
-	/** Optional custom HTML tag */
-	tag?: string;
-	/** 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;
+    /** The full path to the property */
+    path: DocumentPath;
+    /** Optional custom HTML tag */
+    tag?: string;
+    /** The `class` attribute on the container element */
+    class?: string;
+    /** Rest props to spread onto the rendered element (e.g. href, target, etc.) */
+    [key: string]: unknown;
 };
-
 /**
  * Props for the Node component
  */
 export type NodeProps = {
-	/** The full path to the node */
-	path: DocumentPath;
-	/** Optional custom HTML tag */
-	tag?: string;
-	/** Optional string of CSS classes */
-	class?: string;
-	/** 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;
-};
-
+    /** 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 */
+    class?: string;
+    /** The type-specific content of the node */
+    children: Snippet;
+    /** Rest props to spread onto the rendered element (e.g. href, target, etc.) */
+    [key: string]: unknown;
+};
 /**
  * Props for the Svedit component
  */
-export type SveditProps = {
-	/** The session instance */
-	session: Session;
-	/** Determines wether the document should be editable or read-only. */
-	editable?: boolean;
-	/** The path to the root element (e.g. ['page_1']) */
-	path: DocumentPath;
-	/** The `class` attribute on the canvas element */
-	class?: string;
-	/** The `autocapitalize` attribute on the canvas element */
-	autocapitalize?: 'on' | 'off';
-	/** The `spellcheck` attribute on the canvas element */
-	spellcheck?: 'true' | 'false';
+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']) */
+    path: DocumentPath;
+    /** The `class` attribute on the canvas element */
+    class?: string;
+    /** The `autocapitalize` attribute on the canvas element */
+    autocapitalize?: 'on' | 'off';
+    /** The `spellcheck` attribute on the canvas element */
+    spellcheck?: 'true' | 'false';
 };
-
 /**
- * Represents an annotation in an annotated string
+ * Context provided by the Svedit component to commands and descendant components.
  */
-export type Annotation = {
-	start_offset: number;
-	end_offset: number;
-	node_id: NodeId;
+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;
 };
-
 /**
- * Represents an annotated text with text and annotations
+ * A range with an attached payload node, used for both marks and annotations.
  */
-export type AnnotatedText = {
-	text: string;
-	annotations: Array<Annotation>;
+export type Attachment = {
+    start_offset: number;
+    end_offset: number;
+    node_id: NodeId;
 };
-
 /**
- * Represents a selection highlight fragment for non-annotated text selections
+ * 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 Annotation = Attachment;
+/**
+ * Represents text content with marks and annotations.
+ */
+export type Text = {
+    content: string;
+    marks: Array<Mark>;
+    annotations: Array<Annotation>;
+};
+/**
+ * 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';
-	content: string;
+    type: 'selection_highlight';
+    content: string;
+};
+/**
+ * Represents a mark fragment in text content
+ */
+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 mark in the original array */
+    mark_index: number;
 };
-
 /**
- * Represents an annotation fragment in annotated text content
+ * Represents a fragment of text content
+ */
+export type Fragment = string | MarkFragment | SelectionHighlightFragment;
+/**
+ * Represents a node array fragment for plain nodes
  */
-export type AnnotationFragment = {
-	type: 'annotation';
-	/** NodeId that has annotation type and details */
-	node: any;
-	/** The text content of the annotation */
-	content: string;
-	/** Index of the annotation in the original array */
-	annotation_index: number;
+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;
+//# sourceMappingURL=types.d.ts.map