@oscarpalmer/abydon 0.22.0 → 0.23.0

package/dist/abydon.full.mjs

@@ -783,6 +783,14 @@ function isEventTarget(value) {
 function isHTMLOrSVGElement(value) {
 	return value instanceof HTMLElement || value instanceof SVGElement;
 }
+/**
+* Is the value an input element? _(`<input>`, `<select>`, or `<textarea>`)_
+* @param value Value to check
+* @returns `true` if it's an input element, otherwise `false`
+*/
+function isInputElement(value) {
+	return value instanceof HTMLInputElement || value instanceof HTMLSelectElement || value instanceof HTMLTextAreaElement;
+}
 //#endregion
 //#region node_modules/@oscarpalmer/toretto/dist/is.mjs
 /**
@@ -1062,6 +1070,10 @@ const delimiters = {
 let memoizedCapitalize;
 //#endregion
 //#region node_modules/@oscarpalmer/toretto/dist/internal/element-value.mjs
+function ignoreSetAttribute(element, name) {
+	if (element instanceof HTMLTextAreaElement && name === "value") return true;
+	return false;
+}
 function normalizeKey(key, style) {
 	return style && key.startsWith(CSS_VARIABLE_PREFIX) ? key : kebabCase(key);
 }
@@ -1091,16 +1103,21 @@ function setElementValues(element, first, second, third, callback, style) {
 }
 function updateElementValue(element, key, value, set, remove, isBoolean, json) {
 	if (isBoolean ? value == null : isNullableOrWhitespace(value)) remove.call(element, key);
-	else set.call(element, key, json ? JSON.stringify(value) : String(value));
+	else if (!ignoreSetAttribute(element, key)) set.call(element, key, json ? JSON.stringify(value) : getString(value));
 }
 const CSS_VARIABLE_PREFIX = "--";
 //#endregion
 //#region node_modules/@oscarpalmer/toretto/dist/internal/property.mjs
+function getPropertyValue(element, name, value) {
+	if (isInputElement(element) && name === "value") return getString(value);
+	return value;
+}
 function updateProperty(element, name, value, dispatch) {
 	let property = name;
 	if (!(property in element)) property = camelCase(name);
-	if (!(property in element) || Object.is(element[property], value)) return;
-	element[property] = value;
+	const next = getPropertyValue(element, name, value);
+	if (!(property in element) || Object.is(element[property], next)) return;
+	element[property] = next;
 	const event = dispatch && elementEvents[element.tagName]?.[property];
 	if (typeof event === "string") element.dispatchEvent(new Event(event, {
 		bubbles: true,
@@ -1141,7 +1158,7 @@ function handleAttribute(callback, decode, first, second) {
 	let value;
 	if (isAttribute(first)) {
 		name = first.name;
-		value = String(first.value);
+		value = getString(first.value);
 	} else if (typeof first === "string" && typeof second === "string") {
 		name = first;
 		value = second;
@@ -1413,7 +1430,7 @@ const ARRAY_COMPARISON_DISSIMILAR = "dissimilar";
 const ARRAY_COMPARISON_REMOVED = "removed";
 const CHANGE_INPUTS = new Set(["checkbox", "radio"]);
 const ERROR_FRAGMENT = "Fragment function must return a Fragment instance";
-const ERROR_IDENTIFIER_DUPLICATE = "Duplicate identifier found: '<id>'";
+const ERROR_IDENTIFIER_DUPLICATE = "Duplicate identifier found: '<>'";
 const ERROR_IDENTIFIER_TYPE = "Identifier cannot be null or undefined";
 const EVENT_CHANGE = "change";
 const EVENT_INPUT = "input";
@@ -1432,12 +1449,12 @@ const EXPRESSION_ABYDON_CONTENT = /^abydon\.(\d+)$/;
 const EXPRESSION_ATTRIBUTE_CLASS = /^class\./;
 const EXPRESSION_ATTRIBUTE_STYLE_FULL = /^style\.([\w-]+)(?:\.([\w-]+))?$/;
 const EXPRESSION_ATTRIBUTE_STYLE_PREFIX = /^style\./;
-const EXPRESSION_ATTRIBUTE_STYLE_PROPERTY = /^style\.--/;
+const EXPRESSION_ATTRIBUTE_STYLE_VARIABLE = /^style\.--/;
 const EXPRESSION_EVENT_ATTRIBUTE = /^@([\w-]+)(?::([a-z:]+))?="$/i;
 const EXPRESSION_EVENT_NAME = /^@?([\w-]+)(?::([a-z:]+))?$/i;
-const EXPRESSION_EVENT_OPTIONS_ACTIVE = /^a(ctive)$/i;
-const EXPRESSION_EVENT_OPTIONS_CAPTURE = /^c(apture)$/i;
-const EXPRESSION_EVENT_OPTIONS_ONCE = /^o(nce)$/i;
+const EXPRESSION_EVENT_OPTIONS_ACTIVE = /^a(?:ctive)$/i;
+const EXPRESSION_EVENT_OPTIONS_CAPTURE = /^c(?:apture)$/i;
+const EXPRESSION_EVENT_OPTIONS_ONCE = /^o(?:nce)$/i;
 const EXPRESSION_EVENT_PREFIX = /^@/;
 const EXPRESSION_TEXTAREA_VALUE = /(?:<|&lt;)!--abydon\.(\d+)--(?:>|&gt;)/;
 const NAME_FRAGMENT = "$fragment";
@@ -1453,17 +1470,17 @@ function compareArrays(first, second) {
 	return firstIsLarger ? ARRAY_COMPARISON_REMOVED : ARRAY_COMPARISON_ADDED;
 }
 /**
-* Is the value a Fragment?
+* Is the value a _Fragment_?
 * @param value Value to check
-* @returns `true` if the value is a Fragment, otherwise `false`
+* @returns `true` if the value is a _Fragment_, otherwise `false`
 */
 function isFragment(value) {
 	return isNamed(value, NAME_FRAGMENT);
 }
 /**
-* Is the value a Fragments?
+* Is the value a _Fragments_ instance?
 * @param value Value to check
-* @returns `true` if the value is a Fragments, otherwise `false`
+* @returns `true` if the value is a _Fragments_ instance, otherwise `false`
 */
 function isFragments(value) {
 	return isNamed(value, NAME_FRAGMENTS);
@@ -1471,6 +1488,11 @@ function isFragments(value) {
 function isNamed(value, name) {
 	return typeof value === "object" && value != null && name in value && value[name] === true;
 }
+function setComputedValue(data, callback, after) {
+	const computation = computed(callback);
+	data.mora.values.add(computation);
+	after(computation);
+}
 //#endregion
 //#region src/fragments.ts
 var Fragments = class {
@@ -1491,7 +1513,7 @@ var Fragments = class {
 };
 function handleFragments(item, remove) {
 	const state = isFragments(item) ? fragmentsStates.get(item) : item;
-	(remove ? removeFragments$1 : initializeFragments)(state);
+	(remove ? removeFragments : initializeFragments)(state);
 }
 function handleItems(state, items) {
 	const keys = /* @__PURE__ */ new Set();
@@ -1508,7 +1530,7 @@ function handleItems(state, items) {
 			instance = state.fragment(item);
 			if (!isFragment(instance)) throw new Error(ERROR_FRAGMENT);
 		}
-		instance.identify(key);
+		instance.configure({ identifier: key });
 		state.instances[key] = instance;
 		keys.add(key);
 		mapped.push(instance);
@@ -1521,7 +1543,7 @@ function initializeFragments(state) {
 		handleItems(state, items);
 	});
 }
-function removeFragments$1(state) {
+function removeFragments(state) {
 	state.subscriber?.();
 	updateFragments(state);
 	state.subscriber = void 0;
@@ -1547,9 +1569,6 @@ function createNodes(value) {
 	if (isChildNode(value)) return [value];
 	return [new Text(getString(value))];
 }
-function isInputElement(node) {
-	return node instanceof HTMLInputElement || node instanceof HTMLSelectElement;
-}
 function removeNodes(nodes) {
 	const { length } = nodes;
 	for (let index = 0; index < length; index += 1) nodes[index].remove();
@@ -1558,6 +1577,7 @@ function replaceNodes(from, to) {
 	from[0]?.replaceWith(...to);
 	const { length } = from;
 	for (let index = 1; index < length; index += 1) from[index].remove();
+	return to;
 }
 //#endregion
 //#region node_modules/@oscarpalmer/toretto/dist/internal/get-value.mjs
@@ -1721,8 +1741,8 @@ function setStyle(element, property, value) {
 }
 function updateStyleProperty(element, key, value) {
 	updateElementValue(element, key, value, function(property, style) {
-		if (property.startsWith(VARIABLE_PREFIX)) this.style.setProperty(property, String(style));
-		else this.style[property] = String(style);
+		if (property.startsWith(VARIABLE_PREFIX)) this.style.setProperty(property, getString(style));
+		else this.style[property] = getString(style);
 	}, function(property) {
 		if (property.startsWith(VARIABLE_PREFIX)) this.style.removeProperty(property);
 		else this.style[property] = "";
@@ -1733,12 +1753,12 @@ const ATTRIBUTE_STYLE = "style";
 const VARIABLE_PREFIX = "--";
 //#endregion
 //#region src/attribute/value.ts
-function getStyleValue(value, unit, isProperty) {
-	if (removeStyleValue(value, unit, isProperty)) return;
+function getStyleValue(value, unit, isVariable) {
+	if (removeStyleValue(value, unit, isVariable)) return;
 	return value === true || value === "true" ? unit : `${getString(value)}${unit ?? ""}`;
 }
-function removeStyleValue(value, unit, isProperty) {
-	if (value == null || value === false || isProperty && isNullableOrWhitespace(value)) return true;
+function removeStyleValue(value, unit, isVariable) {
+	if (value == null || value === false || isVariable && isNullableOrWhitespace(value)) return true;
 	return unit == null && (value === true || value === "true");
 }
 function setAttribute(data, element, name, value) {
@@ -1755,78 +1775,73 @@ function setAttribute(data, element, name, value) {
 	}
 }
 function setClassValues(data, element, name, value) {
-	function update(value) {
+	const classes = name.slice(6).split(".");
+	updateValue(data, value, (value) => {
 		if (value === true || value === "true") element.classList.add(...classes);
 		else element.classList.remove(...classes);
-	}
-	const classes = name.slice(6).split(".");
-	if (isReactive(value)) data.mora.subscribers.add(value.subscribe(update));
-	else update(value);
+	});
 }
 function setStyleValues(data, element, name, value) {
 	let [, property, unit] = EXPRESSION_ATTRIBUTE_STYLE_FULL.exec(name);
-	const isProperty = EXPRESSION_ATTRIBUTE_STYLE_PROPERTY.test(name);
-	property = camelCase(property);
-	if (isProperty) property = `--${property}`;
-	function update(value) {
-		setStyle(element, property, getStyleValue(value, unit, isProperty));
-	}
-	if (isReactive(value)) data.mora.subscribers.add(value.subscribe(update));
-	else update(value);
+	const isVariable = EXPRESSION_ATTRIBUTE_STYLE_VARIABLE.test(name);
+	updateValue(data, value, (value) => {
+		setStyle(element, property, getStyleValue(value, unit, isVariable));
+	});
 }
 function setValue(data, element, name, value) {
-	const isReactiveValue = isReactive(value);
-	unsetValue(element, name, isReactiveValue ? value.peek() : value);
-	if (isReactiveValue) data.mora.subscribers.add(value.subscribe((next) => {
-		setAttribute$1(element, name, next);
-	}));
-	else setAttribute$1(element, name, value);
+	updateValue(data, value, (value) => {
+		setAttribute$1(element, name, value);
+	});
 }
-function unsetValue(element, name, value) {
-	if (name === "checked") element.checked = !(value === true || value === "true");
-	if (name === "value") element.value = element.value === "" ? "_" : "";
+function updateValue(data, value, updater) {
+	if (isReactive(value)) data.mora.subscribers.add(value.subscribe(updater));
+	else updater(value);
 }
 //#endregion
 //#region src/attribute/index.ts
+function compareAttributes(first, second) {
+	return first.name.localeCompare(second.name);
+}
 function getValue(data, original) {
 	const matches = EXPRESSION_ABYDON_CONTENT.exec(original);
 	return matches == null ? original : data.values[+matches[1]];
 }
-function mapAttributes(data, element) {
-	const attributes = [...element.attributes].sort((first, second) => first.name.localeCompare(second.name));
+function mapAttributeValue(data, element, name, value) {
+	if (typeof value === "function") setComputedAttribute(data, element, name, value);
+	else setAttribute(data, element, name, value);
+	if (isInputElement(element) && isSignal(value) && name in element) mapEvent(element, "on", () => {
+		value.set(element[name]);
+	});
+}
+function mapAttributes(data, element, ignoreValue) {
+	const attributes = [...element.attributes].sort(compareAttributes);
 	const { length } = attributes;
 	for (let index = 0; index < length; index += 1) {
 		const { name, value } = attributes[index];
 		const actualName = name.replace(EXPRESSION_ABYDON_ATTRIBUTE_PREFIX, "");
 		const actualValue = getValue(data, value);
 		if (actualName !== name) element.removeAttribute(name);
+		if (actualName === "value" && ignoreValue) continue;
 		switch (true) {
 			case EXPRESSION_EVENT_PREFIX.test(actualName):
 				mapEvent(element, actualName, actualValue);
 				break;
 			default:
-				mapValue$1(data, element, actualName, actualValue);
+				mapAttributeValue(data, element, actualName, actualValue);
 				break;
 		}
 	}
 }
-function mapValue$1(data, element, name, value) {
-	if (typeof value === "function") setComputedAttribute(data, element, name, value);
-	else setAttribute(data, element, name, value);
-	if (isInputElement(element) && isSignal(value) && name in element) mapEvent(element, "on", () => {
-		value.set(element[name]);
-	});
-}
 function setComputedAttribute(data, element, name, callback) {
-	const value = computed(callback);
-	data.mora.values.add(value);
-	setAttribute(data, element, name, value);
+	setComputedValue(data, callback, (computation) => {
+		setAttribute(data, element, name, computation);
+	});
 }
 //#endregion
 //#region src/node/value.ts
 function addToArray(identifiers, items, nodes, added) {
 	let position = nodes[0];
-	const before = added && !identifiers.previous.has(items.templates[0].identifier);
+	const before = added && !identifiers.previous.set.has(items.templates[0].identifier);
 	const next = items.next.flatMap((fragment) => fragment.get().flatMap((node) => ({
 		identifier: fragment.identifier,
 		value: node
@@ -1834,19 +1849,48 @@ function addToArray(identifiers, items, nodes, added) {
 	const { length } = next;
 	for (let index = 0; index < length; index += 1) {
 		const node = next[index];
-		if (!(added && identifiers.previous.has(node.identifier))) if (index === 0 && before) position.before(node.value);
+		if (!(added && identifiers.previous.set.has(node.identifier))) if (index === 0 && before) position.before(node.value);
 		else position.after(node.value);
 		position = node.value;
 	}
 }
+function getArrayData(item, values) {
+	const { length } = values;
+	const next = [];
+	let templates = [];
+	for (let index = 0; index < length; index += 1) {
+		const value = values[index];
+		if (isFragment(value) && value.identifier != null) {
+			next.push(value.identifier);
+			templates.push(value);
+		}
+	}
+	const previous = item.fragments?.map((fragment) => fragment.identifier) ?? [];
+	const nextSet = new Set(next);
+	if (nextSet.size !== templates.length) templates = [];
+	return {
+		next: {
+			array: next,
+			set: nextSet
+		},
+		previous: {
+			array: previous,
+			set: new Set(previous)
+		},
+		template: {
+			empty: templates.length === 0,
+			items: templates
+		}
+	};
+}
 function handleArray(identifiers, items, nodes) {
-	const next = items.templates.map((template) => items.fragments?.find((fragment) => fragment.identifier === template.identifier) ?? template);
-	const comparison = compareArrays(items.fragments ?? [], items.templates);
+	const next = items.templates.map((template) => items.fragments.find((fragment) => fragment.identifier === template.identifier) ?? template);
+	const comparison = compareArrays(identifiers.previous.array, identifiers.next.array);
 	if (comparison !== "removed") addToArray(identifiers, {
 		...items,
 		next
 	}, nodes, comparison === ARRAY_COMPARISON_ADDED);
-	const toRemove = items.fragments?.filter((fragment) => !identifiers.next.has(fragment.identifier)) ?? [];
+	const toRemove = items.fragments.filter((fragment) => !identifiers.next.set.has(fragment.identifier));
 	const { length } = toRemove;
 	for (let index = 0; index < length; index += 1) toRemove[index].remove();
 	return {
@@ -1854,52 +1898,45 @@ function handleArray(identifiers, items, nodes) {
 		nodes: next.flatMap((fragment) => fragment.get())
 	};
 }
-function removeFragments(fragments) {
-	if (fragments != null) {
-		const { length } = fragments;
-		for (let index = 0; index < length; index += 1) fragments[index].remove();
-	}
+function removeArray(item, comment) {
+	const fragments = (item.fragments ?? []).slice();
+	const result = { nodes: setText(item, comment) };
+	removeFragmentsItems(fragments);
+	return result;
 }
-function replaceText(item, comment, isNullable) {
-	let to;
-	if (isNullable) to = [comment];
-	else to = item.text == null ? [] : [item.text];
-	replaceNodes(item.nodes ?? [], to);
+function removeFragmentsItems(fragments) {
+	const { length } = fragments;
+	for (let index = 0; index < length; index += 1) fragments[index].remove();
 }
 function setArray(item, comment, value) {
-	if (value.length === 0) return { nodes: setText(item, comment, value) };
-	let templates = value.filter((item) => isFragment(item) && item.identifier != null);
-	const next = templates.map((fragment) => fragment.identifier);
-	const previous = item.fragments?.map((fragment) => fragment.identifier) ?? [];
-	const nextSet = new Set(next);
-	if (nextSet.size !== templates.length) templates = [];
-	const noTemplates = templates.length === 0;
-	if (noTemplates || item.nodes == null || previous.some((identifier) => identifier == null)) return {
-		fragments: noTemplates ? void 0 : templates,
-		nodes: setNodes(item, comment, noTemplates ? value.flatMap((item) => createNodes(item)) : templates.flatMap((template) => template.get()))
-	};
+	if (value.length === 0) return removeArray(item, comment);
+	const { next, previous, template } = getArrayData(item, value);
+	if (template.empty || item.nodes == null || previous.array.some((identifier) => identifier == null)) {
+		const fragments = (item.fragments ?? []).slice();
+		const result = {
+			fragments: template.empty ? void 0 : template.items,
+			nodes: replaceNodes(item.nodes ?? [comment], template.empty ? value.flatMap((item) => createNodes(item)) : template.items.flatMap((template) => template.get()))
+		};
+		removeFragmentsItems(fragments);
+		return result;
+	}
 	return handleArray({
-		next: nextSet,
-		previous: new Set(previous)
+		next,
+		previous
 	}, {
-		templates,
-		fragments: item.fragments ?? []
+		fragments: item.fragments ?? [],
+		templates: template.items
 	}, item.nodes);
 }
 function setNodes(item, comment, next) {
-	if (item.nodes == null) replaceNodes([comment], next);
-	else replaceNodes(item.nodes, next);
-	removeFragments(item.fragments);
-	return next;
+	return replaceNodes(item.nodes ?? [comment], next);
 }
 function setReactiveValue(data, comment, reactive) {
 	let item = data.items.find((item) => item.nodes?.includes(comment));
 	item ??= {};
-	item.text = new Text();
 	data.mora.subscribers.add(reactive.subscribe((value) => {
 		if (Array.isArray(value)) setReactiveValueForArray(item, comment, value);
 		else setReactiveValueForSingle(item, comment, value);
-		item.nodes ??= [comment];
 	}));
 }
 function setReactiveValueForArray(item, comment, value) {
@@ -1908,25 +1945,20 @@ function setReactiveValueForArray(item, comment, value) {
 	item.nodes = nodes;
 }
 function setReactiveValueForSingle(item, comment, value) {
+	const fragments = (item.fragments ?? []).slice();
 	const valueIsFragment = isFragment(value);
-	item.fragments = valueIsFragment ? [value] : void 0;
 	if (valueIsFragment || isChildNode(value)) item.nodes = setNodes(item, comment, createNodes(value));
 	else item.nodes = setText(item, comment, value);
+	item.fragments = valueIsFragment ? [value] : void 0;
+	removeFragmentsItems(fragments);
 }
 function setText(item, comment, value) {
-	const isNullable = isNullableOrWhitespace(value);
-	if (item.text != null) item.text.textContent = isNullable ? "" : getString(value);
-	let result = false;
-	if (item.nodes != null) {
-		replaceText(item, comment, isNullable);
-		result = !isNullable;
-	} else if (isNullable && comment.parentNode == null) item.text?.replaceWith(comment);
-	else if (!isNullable && item?.text?.parentNode == null) {
-		if (item.text != null) comment.replaceWith(item.text);
-		result = true;
-	}
-	removeFragments(item.fragments);
-	if (result) return item.text == null ? [] : [item.text];
+	const valueIsNullable = isNullableOrWhitespace(value);
+	item.text ??= new Text();
+	item.text.textContent = valueIsNullable ? "" : getString(value);
+	const result = valueIsNullable ? [comment] : [item.text];
+	replaceNodes(item.nodes ?? [comment], result);
+	return result;
 }
 //#endregion
 //#region src/node/index.ts
@@ -1943,42 +1975,29 @@ function mapNodes(data, nodes) {
 			mapNode(data, node);
 			continue;
 		}
-		if (node instanceof HTMLTextAreaElement) mapTextarea(data, node);
-		if (isHTMLOrSVGElement(node)) mapAttributes(data, node);
+		if (isHTMLOrSVGElement(node)) {
+			let ignoreValueAttribute = false;
+			if (node instanceof HTMLTextAreaElement) ignoreValueAttribute = mapTextarea(data, node);
+			mapAttributes(data, node, ignoreValueAttribute);
+		}
 		if (node.hasChildNodes()) mapNodes(data, [...node.childNodes]);
 	}
 }
 function mapTextarea(data, element) {
 	const [, index] = EXPRESSION_TEXTAREA_VALUE.exec(element.textContent) ?? EXPRESSION_TEXTAREA_VALUE.exec(element.value) ?? [];
-	if (index == null) return;
+	if (index == null) return false;
 	element.textContent = "";
 	element.value = "";
-	const value = data.values[Number.parseInt(index, 10)];
-	if (isSignal(value)) {
-		element.value = getString(value.peek());
-		mapEvent(element, "on", () => {
-			value.set(element.value);
-		});
-		data.mora.subscribers.add(value.subscribe((value) => {
-			element.value = getString(value);
-		}));
-		return;
-	}
-	let reactive;
-	if (typeof value === "function") reactive = computed(value);
-	else if (isComputed(value)) reactive = value;
-	if (reactive == null) element.value = "";
-	else data.mora.subscribers.add(reactive.subscribe((value) => {
-		element.value = getString(value);
-	}));
+	mapAttributeValue(data, element, "value", data.values[Number.parseInt(index, 10)]);
+	return true;
 }
 function mapValue(data, comment, value) {
 	switch (true) {
 		case typeof value === "function":
-			setComputedValue(data, comment, value);
+			setComputedNode(data, comment, value);
 			break;
 		case isFragments(value):
-			setFragmentsValue(data, comment, value);
+			setFragmentsNode(data, comment, value);
 			break;
 		case isReactive(value):
 			setReactiveValue(data, comment, value);
@@ -1997,12 +2016,12 @@ function replaceComment(data, comment, value) {
 	}
 	comment.replaceWith(...nodes);
 }
-function setComputedValue(data, comment, callback) {
-	const value = computed(callback);
-	data.mora.values.add(value);
-	setReactiveValue(data, comment, value);
+function setComputedNode(data, comment, callback) {
+	setComputedValue(data, callback, (computation) => {
+		setReactiveValue(data, comment, computation);
+	});
 }
-function setFragmentsValue(data, comment, fragments) {
+function setFragmentsNode(data, comment, fragments) {
 	const state = fragmentsStates.get(fragments);
 	handleFragments(state, false);
 	setReactiveValue(data, comment, state.mapped);
@@ -2048,11 +2067,13 @@ var Fragment = class {
 	/**
 	* Is template caching enabled?
 	*/
-	get caching() {
+	get cache() {
 		return this.#configuration.cache;
 	}
 	/**
-	* Fragment identifier
+	* Identifier for the _Fragment_
+	*
+	* _An identifier can be used to uniquely identify a Fragment, which helps prevent re-rendering in reactive arrays and Fragments_
 	*/
 	get identifier() {
 		return this.#configuration.identifier;
@@ -2071,16 +2092,32 @@ var Fragment = class {
 		};
 	}
 	/**
-	* Append the fragment to the given element
+	* Insert the _Fragment_ after the given element
+	* @param element Element to insert after
+	*/
+	after(element) {
+		element.after(...this.get());
+	}
+	/**
+	* Append the _Fragment_ to the given element
 	* @param element Element to append to
 	*/
 	appendTo(element) {
 		element.append(...this.get());
 	}
 	/**
-	* Configure the fragment
+	* Insert the _Fragment_ before the given element
+	* @param element Element to insert before
+	*/
+	before(element) {
+		element.before(...this.get());
+	}
+	/**
+	* Configure the _Fragment_
+	*
+	* _Returns the Fragment instance for chaining_
 	* @param configuration Configuration options
-	* @returns Fragment
+	* @returns _Fragment_
 	*/
 	configure(configuration) {
 		const actual = isPlainObject(configuration) ? configuration : {};
@@ -2089,7 +2126,7 @@ var Fragment = class {
 		return this;
 	}
 	/**
-	* Get a list of the fragment's nodes
+	* Get a list of the _Fragment_'s nodes
 	* @returns List of nodes
 	*/
 	get() {
@@ -2102,19 +2139,17 @@ var Fragment = class {
 		return data.items.flatMap((item) => item.fragments?.flatMap((fragment) => fragment.get()) ?? item.nodes);
 	}
 	/**
-	* Set an identifier for the fragment
-	*
-	* _An identifier can be used to uniquely identify a fragment,
-	* which helps prevent re-rendering in certain scenarios._
-	* @param identifier Identifier
-	* @returns Fragment
+	* Prepend the _Fragment_ to the given element
+	* @param element Element to prepend to
 	*/
-	identify(identifier) {
-		this.#configuration.identifier = identifier;
-		return this;
+	prependTo(element) {
+		element.prepend(...this.get());
 	}
 	/**
-	* Remove the fragment from the DOM
+	* Remove the _Fragment_ _(and all its descendants)_ from the _DOM_
+	*
+	* - _Any events, reactive values, and Fragments will also be cleaned up and removed_
+	* - _After being removed, the Fragment can be re-inserted into the DOM_
 	*/
 	remove() {
 		removeFragment(this.#data);
@@ -2145,11 +2180,27 @@ function removeMora(data) {
 //#endregion
 //#region src/index.ts
 /**
-* Create a Fragments from a reactive array
+* Create a _Fragments_ instance from a reactive array
+* 
+* _A Fragments instance can be used to efficiently render a list of items that may change over time, using unique identifiers to track each item, only adding, removing, or updating each related Fragment._
+*
+* @example
+* ```ts
+* const fruits = array(['Apple', 'Banana', 'Cherry']);
+* const items = fragments(
+*   fruits,
+*   fruit => fruit,                           // Identifies a unique item
+*   fruit => html`<p>${fruit}</p>`,           // Creates a Fragment from an item
+* );
+* html`${items}`.appendTo(document.body)      // Renders '<p>Apple</p><p>Banana</p><p>Cherry</p>'
+* fruits.push(['Date', 'Elderberry', 'Fig']); // Appends '<p>Date</p><p>Elderberry</p><p>Fig</p>'
+*                                             // without re-rendering the existing Fragments
+* ```
+*
 * @param array Reactive array
-* @param identify Function to identify item
-* @param fragment Function to create fragment from item
-* @returns Fragments
+* @param identify Function to identify item uniquely _(non-nullable)_
+* @param fragment Function to create _Fragment_ from item
+* @returns _Fragments_
 */
 function fragments(array, identify, fragment) {
 	if (!isArray(array)) throw new TypeError("Fragments array must be a reactive array");
@@ -2158,8 +2209,19 @@ function fragments(array, identify, fragment) {
 	return new Fragments(array, identify, fragment);
 }
 /**
-* Create a Fragment from a template
-* @returns Fragment
+* Create a _Fragment_ from a template
+* 
+* _A Fragment can be used to efficiently render a template that may change over time, only updating the necessary parts of the DOM._
+*
+* @example
+* ```ts
+* const name = signal('World');
+* const fragment = html`<p>Hello, ${name}!</p>`;
+* fragment.appendTo(document.body);              // Renders '<p>Hello, World!</p>'
+* name.set('Alice');                             // Replaces 'World' with 'Alice'
+* ```
+*
+* @returns _Fragment_
 */
 function html(template, ...values) {
 	return new Fragment(template, values);