svedit 0.9.0 → 0.10.0

package/src/lib/styles/svedit-animations.css

@@ -0,0 +1,8 @@
+@layer svedit-defaults {
+	@keyframes node-caret-blink {
+		0%, 60% { opacity: 1; }
+		68% { opacity: 0; }
+		88% { opacity: 0; }
+		100% { opacity: 1; }
+	}
+}

package/src/lib/styles/svedit-colors.css

@@ -4,5 +4,6 @@
 		--svedit-editing-stroke: var(--svedit-brand);
 		--svedit-editing-fill: oklch(from var(--svedit-brand) l c h / 0.1);
 		--svedit-canvas-stroke: color-mix(in oklch, currentColor 25%, transparent);
+		--svedit-caret-color: var(--svedit-brand);
 	}
 }

package/src/lib/types.d.ts

@@ -11,12 +11,17 @@ import type { Component, Snippet } from 'svelte';
 // ===== SELECTION TYPE DEFINITIONS =====
 
 /**
- * A unique node identifier (ideally UUID)
+ * A unique node identifier.
+ *
+ * Node ids must be valid Svedit path string segments: they must start with
+ * a letter or underscore, contain only letters, numbers, underscores, or
+ * dashes, and must not contain `__`.
  */
 export type NodeId = string;
 
 /**
- * Array of IDs, property names (strings), or indexes (integers) that identify a node or property in the document
+ * 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>;
 
@@ -269,7 +274,8 @@ export type PropertyDefinition =
 export type NodeKind = 'document' | 'block' | 'text' | 'annotation';
 
 /**
- * Schema for text nodes - must have a content property of type annotated_text
+ * 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.
  */
 export type TextNodeSchema = {
 	kind: 'text';
@@ -278,6 +284,43 @@ export type TextNodeSchema = {
 	} & Record<string, PropertyDefinition>;
 };
 
+export type AnnotatedTextPropertyNames<Properties> = {
+	[PropertyName in keyof Properties]: Properties[PropertyName] extends { type: 'annotated_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.`
+>;
+
+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;
+
+export type ValidateDocumentSchema<Schema extends Record<string, NodeSchema>> = {
+	[NodeType in keyof Schema]: ValidateTextNodeSchema<Schema[NodeType]>;
+};
+
 /**
  * Schema for non-text nodes
  */

package/src/lib/utils.js

@@ -21,7 +21,7 @@ export function is_mobile_browser() {
 	);
 }
 
-// ‼️‼️‼️‼️‼️‼️ UNUSED UTILITY BELOW ‼️‼️‼️‼️‼️‼️ 
+// ‼️‼️‼️‼️‼️‼️ UNUSED UTILITY BELOW ‼️‼️‼️‼️‼️‼️
 /**
  * Detect if the current browser is Chrome on desktop
  * @returns {boolean} true if Chrome desktop browser, false otherwise
@@ -54,8 +54,7 @@ export function get_char_length(str) {
 	return [...SEGMENTER.segment(str)].length;
 }
 
-
-// ‼️‼️‼️‼️‼️‼️ UNUSED UTILITY BELOW ‼️‼️‼️‼️‼️‼️ 
+// ‼️‼️‼️‼️‼️‼️ UNUSED UTILITY BELOW ‼️‼️‼️‼️‼️‼️
 /**
  * Get a single character at the specified position (accounting for multi-byte characters)
  *
@@ -278,6 +277,113 @@ export function snake_to_pascal(str) {
 		.join('');
 }
 
+export const PATH_SEPARATOR = '__';
+const PATH_STRING_SEGMENT_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+const PATH_INDEX_SEGMENT_RE = /^(0|[1-9]\d*)$/;
+
+/**
+ * Check whether a string can be used as a Svedit path segment.
+ *
+ * Path string segments include node ids and schema property names. Keeping
+ * them restricted makes serialized paths reversible, valid as HTML ids, and
+ * safe to use as CSS anchor-name suffixes.
+ *
+ * @param {string} segment
+ * @returns {boolean}
+ */
+export function is_path_string_segment_valid(segment) {
+	return (
+		typeof segment === 'string' &&
+		PATH_STRING_SEGMENT_RE.test(segment) &&
+		!segment.includes(PATH_SEPARATOR)
+	);
+}
+
+/**
+ * Assert that a string can be used as a Svedit path segment.
+ *
+ * @param {string} segment
+ * @param {string} [label]
+ * @returns {void}
+ */
+export function assert_path_string_segment(segment, label = 'Path segment') {
+	if (!is_path_string_segment_valid(segment)) {
+		throw new Error(
+			`${label} must start with a letter or underscore and contain only letters, numbers, underscores, or dashes. It must not contain "${PATH_SEPARATOR}".`
+		);
+	}
+}
+
+/**
+ * Serialize a document path while preserving whether each segment is a
+ * property/key string or an array index number.
+ *
+ * The result is reversible and safe to use as a data attribute value, HTML id,
+ * or CSS anchor-name suffix.
+ *
+ * @param {Array<string | number>} path
+ * @returns {string}
+ *
+ * @example
+ * serialize_path(['page_1', 'body', 0, 'items']) // Returns: 'page_1__body__0__items'
+ */
+export function serialize_path(path) {
+	return path
+		.map((segment) => {
+			if (typeof segment === 'number') {
+				if (!Number.isInteger(segment) || segment < 0) {
+					throw new Error(`Path index must be a non-negative integer: ${segment}`);
+				}
+				return String(segment);
+			}
+
+			assert_path_string_segment(segment);
+			return segment;
+		})
+		.join(PATH_SEPARATOR);
+}
+
+/**
+ * Deserialize a path string produced by serialize_path.
+ *
+ * @param {string} serialized_path
+ * @returns {Array<string | number>}
+ *
+ * @example
+ * deserialize_path('page_1__body__0__items') // Returns: ['page_1', 'body', 0, 'items']
+ */
+export function deserialize_path(serialized_path) {
+	if (serialized_path === '') return [];
+
+	return serialized_path.split(PATH_SEPARATOR).map((segment) => {
+		if (segment === '') {
+			throw new Error(`Invalid serialized path: ${serialized_path}`);
+		}
+
+		if (/^\d+$/.test(segment)) {
+			if (!PATH_INDEX_SEGMENT_RE.test(segment)) {
+				throw new Error(`Invalid serialized path index: ${segment}`);
+			}
+			return Number(segment);
+		}
+
+		assert_path_string_segment(segment, 'Serialized path segment');
+		return segment;
+	});
+}
+
+/**
+ * Compare two document paths segment-by-segment, preserving segment types.
+ *
+ * @param {Array<string | number>} a
+ * @param {Array<string | number>} b
+ * @returns {boolean}
+ */
+export function paths_equal(a, b) {
+	if (a.length !== b.length) return false;
+	return a.every((segment, index) => segment === b[index]);
+}
+
 export function traverse(node_id, schema, nodes) {
 	const json = [];
 	const visited = {};

package/dist/node_gap_computation.svelte.d.ts

@@ -1,5 +0,0 @@
-/**
- * @param {object} svedit - Svedit context (session, editable, doc, schema, etc.)
- */
-export function create_gap_computation(svedit: object): void;
-//# sourceMappingURL=node_gap_computation.svelte.d.ts.map

package/dist/node_gap_computation.svelte.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"node_gap_computation.svelte.d.ts","sourceRoot":"","sources":["../src/lib/node_gap_computation.svelte.js"],"names":[],"mappings":"AAkWA;;GAEG;AACH,+CAFW,MAAM,QAyQhB"}