@oscarpalmer/abydon 0.21.0 → 0.23.0

package/dist/attribute/index.d.mts

@@ -0,0 +1,7 @@
+import { FragmentData } from "../models.mjs";
+
+//#region src/attribute/index.d.ts
+declare function mapAttributeValue(data: FragmentData, element: HTMLElement | SVGElement, name: string, value: unknown): void;
+declare function mapAttributes(data: FragmentData, element: HTMLElement | SVGElement, ignoreValue: boolean): void;
+//#endregion
+export { mapAttributeValue, mapAttributes };

package/dist/attribute/index.mjs

@@ -0,0 +1,47 @@
+import { EXPRESSION_ABYDON_ATTRIBUTE_PREFIX, EXPRESSION_ABYDON_CONTENT, EXPRESSION_EVENT_PREFIX } from "../constants.mjs";
+import { setComputedValue } from "../helpers/index.mjs";
+import { mapEvent } from "../node/event.mjs";
+import { setAttribute } from "./value.mjs";
+import { isSignal } from "@oscarpalmer/mora";
+import { isInputElement } from "@oscarpalmer/toretto/is";
+//#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 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:
+				mapAttributeValue(data, element, actualName, actualValue);
+				break;
+		}
+	}
+}
+function setComputedAttribute(data, element, name, callback) {
+	setComputedValue(data, callback, (computation) => {
+		setAttribute(data, element, name, computation);
+	});
+}
+//#endregion
+export { mapAttributeValue, mapAttributes };

package/dist/{node/attribute → attribute}/value.d.mts

@@ -1,6 +1,6 @@
-import { FragmentData } from "../../models.mjs";
+import { FragmentData } from "../models.mjs";
 
-//#region src/node/attribute/value.d.ts
+//#region src/attribute/value.d.ts
 declare function setAttribute(data: FragmentData, element: HTMLElement | SVGElement, name: string, value: unknown): void;
 //#endregion
 export { setAttribute };

package/dist/attribute/value.mjs

@@ -0,0 +1,53 @@
+import { EXPRESSION_ATTRIBUTE_CLASS, EXPRESSION_ATTRIBUTE_STYLE_FULL, EXPRESSION_ATTRIBUTE_STYLE_PREFIX, EXPRESSION_ATTRIBUTE_STYLE_VARIABLE } from "../constants.mjs";
+import { isNullableOrWhitespace } from "@oscarpalmer/atoms/is";
+import { getString } from "@oscarpalmer/atoms/string";
+import { isReactive } from "@oscarpalmer/mora";
+import { setAttribute as setAttribute$1 } from "@oscarpalmer/toretto/attribute";
+import { setStyle } from "@oscarpalmer/toretto/style";
+//#region src/attribute/value.ts
+function getStyleValue(value, unit, isVariable) {
+	if (removeStyleValue(value, unit, isVariable)) return;
+	return value === true || value === "true" ? unit : `${getString(value)}${unit ?? ""}`;
+}
+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) {
+	switch (true) {
+		case EXPRESSION_ATTRIBUTE_CLASS.test(name):
+			setClassValues(data, element, name, value);
+			return;
+		case EXPRESSION_ATTRIBUTE_STYLE_PREFIX.test(name):
+			setStyleValues(data, element, name, value);
+			return;
+		default:
+			setValue(data, element, name, value);
+			break;
+	}
+}
+function setClassValues(data, element, name, 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);
+	});
+}
+function setStyleValues(data, element, name, value) {
+	let [, property, unit] = EXPRESSION_ATTRIBUTE_STYLE_FULL.exec(name);
+	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) {
+	updateValue(data, value, (value) => {
+		setAttribute$1(element, name, value);
+	});
+}
+function updateValue(data, value, updater) {
+	if (isReactive(value)) data.mora.subscribers.add(value.subscribe(updater));
+	else updater(value);
+}
+//#endregion
+export { setAttribute };

package/dist/constants.d.mts

@@ -2,16 +2,16 @@
 declare const ARRAY_COMPARISON_ADDED = "added";
 declare const ARRAY_COMPARISON_DISSIMILAR = "dissimilar";
 declare const ARRAY_COMPARISON_REMOVED = "removed";
-declare const ATTRIBUTE_CLASS_PREFIX_LENGTH = 6;
+declare const ATTRIBUTE_CLASS_PREFIX_LENGTH: number;
 declare const ATTRIBUTE_NAME_DELIMITER = ".";
+declare const CHANGE_INPUTS: Set<string>;
 declare const ERROR_FRAGMENT = "Fragment function must return a Fragment instance";
-declare const ERROR_IDENTIFIER_DUPLICATE = "Duplicate identifier found: '<id>'";
+declare const ERROR_IDENTIFIER_DUPLICATE = "Duplicate identifier found: '<>'";
 declare const ERROR_IDENTIFIER_TYPE = "Identifier cannot be null or undefined";
 declare const EVENT_CHANGE = "change";
 declare const EVENT_INPUT = "input";
 declare const EVENT_SUBMIT = "submit";
 declare const EVENT_DEFAULTS: Record<string, string>;
-declare const EVENT_ON_PREFIXED = "@on";
 declare const EVENT_ON_VALUE = "on";
 declare const EVENT_OPTIONS_DELIMITER = ":";
 declare const EXPRESSION_ABYDON_ATTRIBUTE_FULL: RegExp;
@@ -20,20 +20,20 @@ declare const EXPRESSION_ABYDON_CONTENT: RegExp;
 declare const EXPRESSION_ATTRIBUTE_CLASS: RegExp;
 declare const EXPRESSION_ATTRIBUTE_STYLE_FULL: RegExp;
 declare const EXPRESSION_ATTRIBUTE_STYLE_PREFIX: RegExp;
-declare const EXPRESSION_EVENT_CHANGE_TYPES: RegExp;
+declare const EXPRESSION_ATTRIBUTE_STYLE_VARIABLE: RegExp;
+declare const EXPRESSION_EVENT_ATTRIBUTE: RegExp;
 declare const EXPRESSION_EVENT_NAME: RegExp;
 declare const EXPRESSION_EVENT_OPTIONS_ACTIVE: RegExp;
 declare const EXPRESSION_EVENT_OPTIONS_CAPTURE: RegExp;
 declare const EXPRESSION_EVENT_OPTIONS_ONCE: RegExp;
 declare const EXPRESSION_EVENT_PREFIX: RegExp;
-declare const EXPRESSION_PERIOD: RegExp;
 declare const EXPRESSION_TEXTAREA_VALUE: RegExp;
-declare const INPUT_TYPE_CHECKBOX = "checkbox";
 declare const NAME_FRAGMENT = "$fragment";
 declare const NAME_FRAGMENTS = "$fragments";
-declare const PROPERTY_CHECKED = "checked";
 declare const PROPERTY_IDENTIFIER = "identifier";
 declare const PROPERTY_VALUE = "value";
 declare const TEMPLATE_ITEM = "<>";
+declare const VALUE_TRUE = "true";
+declare const WHITESPACE: RegExp;
 //#endregion
-export { ARRAY_COMPARISON_ADDED, ARRAY_COMPARISON_DISSIMILAR, ARRAY_COMPARISON_REMOVED, ATTRIBUTE_CLASS_PREFIX_LENGTH, ATTRIBUTE_NAME_DELIMITER, ERROR_FRAGMENT, ERROR_IDENTIFIER_DUPLICATE, ERROR_IDENTIFIER_TYPE, EVENT_CHANGE, EVENT_DEFAULTS, EVENT_INPUT, EVENT_ON_PREFIXED, EVENT_ON_VALUE, EVENT_OPTIONS_DELIMITER, EVENT_SUBMIT, EXPRESSION_ABYDON_ATTRIBUTE_FULL, EXPRESSION_ABYDON_ATTRIBUTE_PREFIX, EXPRESSION_ABYDON_CONTENT, EXPRESSION_ATTRIBUTE_CLASS, EXPRESSION_ATTRIBUTE_STYLE_FULL, EXPRESSION_ATTRIBUTE_STYLE_PREFIX, EXPRESSION_EVENT_CHANGE_TYPES, EXPRESSION_EVENT_NAME, EXPRESSION_EVENT_OPTIONS_ACTIVE, EXPRESSION_EVENT_OPTIONS_CAPTURE, EXPRESSION_EVENT_OPTIONS_ONCE, EXPRESSION_EVENT_PREFIX, EXPRESSION_PERIOD, EXPRESSION_TEXTAREA_VALUE, INPUT_TYPE_CHECKBOX, NAME_FRAGMENT, NAME_FRAGMENTS, PROPERTY_CHECKED, PROPERTY_IDENTIFIER, PROPERTY_VALUE, TEMPLATE_ITEM };
+export { ARRAY_COMPARISON_ADDED, ARRAY_COMPARISON_DISSIMILAR, ARRAY_COMPARISON_REMOVED, ATTRIBUTE_CLASS_PREFIX_LENGTH, ATTRIBUTE_NAME_DELIMITER, CHANGE_INPUTS, ERROR_FRAGMENT, ERROR_IDENTIFIER_DUPLICATE, ERROR_IDENTIFIER_TYPE, EVENT_CHANGE, EVENT_DEFAULTS, EVENT_INPUT, EVENT_ON_VALUE, EVENT_OPTIONS_DELIMITER, EVENT_SUBMIT, EXPRESSION_ABYDON_ATTRIBUTE_FULL, EXPRESSION_ABYDON_ATTRIBUTE_PREFIX, EXPRESSION_ABYDON_CONTENT, EXPRESSION_ATTRIBUTE_CLASS, EXPRESSION_ATTRIBUTE_STYLE_FULL, EXPRESSION_ATTRIBUTE_STYLE_PREFIX, EXPRESSION_ATTRIBUTE_STYLE_VARIABLE, EXPRESSION_EVENT_ATTRIBUTE, EXPRESSION_EVENT_NAME, EXPRESSION_EVENT_OPTIONS_ACTIVE, EXPRESSION_EVENT_OPTIONS_CAPTURE, EXPRESSION_EVENT_OPTIONS_ONCE, EXPRESSION_EVENT_PREFIX, EXPRESSION_TEXTAREA_VALUE, NAME_FRAGMENT, NAME_FRAGMENTS, PROPERTY_IDENTIFIER, PROPERTY_VALUE, TEMPLATE_ITEM, VALUE_TRUE, WHITESPACE };

package/dist/constants.mjs

@@ -4,8 +4,9 @@ const ARRAY_COMPARISON_DISSIMILAR = "dissimilar";
 const ARRAY_COMPARISON_REMOVED = "removed";
 const ATTRIBUTE_CLASS_PREFIX_LENGTH = 6;
 const ATTRIBUTE_NAME_DELIMITER = ".";
+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";
@@ -18,29 +19,28 @@ const EVENT_DEFAULTS = {
 	SELECT: EVENT_CHANGE,
 	TEXTAREA: EVENT_INPUT
 };
-const EVENT_ON_PREFIXED = "@on";
 const EVENT_ON_VALUE = "on";
 const EVENT_OPTIONS_DELIMITER = ":";
-const EXPRESSION_ABYDON_ATTRIBUTE_FULL = /(@?[\w-]+)="<!--abydon.(\d+)-->"/g;
-const EXPRESSION_ABYDON_ATTRIBUTE_PREFIX = /^_/;
-const EXPRESSION_ABYDON_CONTENT = /^@?abydon\.(\d+)@?$/;
+const EXPRESSION_ABYDON_ATTRIBUTE_FULL = /(@?[\w-.]+(?::[a-z:]+)?)="<!--abydon.(\d+)-->"/g;
+const EXPRESSION_ABYDON_ATTRIBUTE_PREFIX = /^abydon-/;
+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_EVENT_CHANGE_TYPES = /^(checkbox|radio)$/;
-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_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_PREFIX = /^@/;
-const EXPRESSION_PERIOD = /\./;
-const EXPRESSION_TEXTAREA_VALUE = /<!--abydon\.(\d+)-->/;
-const INPUT_TYPE_CHECKBOX = "checkbox";
+const EXPRESSION_TEXTAREA_VALUE = /(?:<|&lt;)!--abydon\.(\d+)--(?:>|&gt;)/;
 const NAME_FRAGMENT = "$fragment";
 const NAME_FRAGMENTS = "$fragments";
-const PROPERTY_CHECKED = "checked";
 const PROPERTY_IDENTIFIER = "identifier";
 const PROPERTY_VALUE = "value";
 const TEMPLATE_ITEM = "<>";
+const VALUE_TRUE = "true";
+const WHITESPACE = /\s+/g;
 //#endregion
-export { ARRAY_COMPARISON_ADDED, ARRAY_COMPARISON_DISSIMILAR, ARRAY_COMPARISON_REMOVED, ATTRIBUTE_CLASS_PREFIX_LENGTH, ATTRIBUTE_NAME_DELIMITER, ERROR_FRAGMENT, ERROR_IDENTIFIER_DUPLICATE, ERROR_IDENTIFIER_TYPE, EVENT_CHANGE, EVENT_DEFAULTS, EVENT_INPUT, EVENT_ON_PREFIXED, EVENT_ON_VALUE, EVENT_OPTIONS_DELIMITER, EVENT_SUBMIT, EXPRESSION_ABYDON_ATTRIBUTE_FULL, EXPRESSION_ABYDON_ATTRIBUTE_PREFIX, EXPRESSION_ABYDON_CONTENT, EXPRESSION_ATTRIBUTE_CLASS, EXPRESSION_ATTRIBUTE_STYLE_FULL, EXPRESSION_ATTRIBUTE_STYLE_PREFIX, EXPRESSION_EVENT_CHANGE_TYPES, EXPRESSION_EVENT_NAME, EXPRESSION_EVENT_OPTIONS_ACTIVE, EXPRESSION_EVENT_OPTIONS_CAPTURE, EXPRESSION_EVENT_OPTIONS_ONCE, EXPRESSION_EVENT_PREFIX, EXPRESSION_PERIOD, EXPRESSION_TEXTAREA_VALUE, INPUT_TYPE_CHECKBOX, NAME_FRAGMENT, NAME_FRAGMENTS, PROPERTY_CHECKED, PROPERTY_IDENTIFIER, PROPERTY_VALUE, TEMPLATE_ITEM };
+export { ARRAY_COMPARISON_ADDED, ARRAY_COMPARISON_DISSIMILAR, ARRAY_COMPARISON_REMOVED, ATTRIBUTE_CLASS_PREFIX_LENGTH, ATTRIBUTE_NAME_DELIMITER, CHANGE_INPUTS, ERROR_FRAGMENT, ERROR_IDENTIFIER_DUPLICATE, ERROR_IDENTIFIER_TYPE, EVENT_CHANGE, EVENT_DEFAULTS, EVENT_INPUT, EVENT_ON_VALUE, EVENT_OPTIONS_DELIMITER, EVENT_SUBMIT, EXPRESSION_ABYDON_ATTRIBUTE_FULL, EXPRESSION_ABYDON_ATTRIBUTE_PREFIX, EXPRESSION_ABYDON_CONTENT, EXPRESSION_ATTRIBUTE_CLASS, EXPRESSION_ATTRIBUTE_STYLE_FULL, EXPRESSION_ATTRIBUTE_STYLE_PREFIX, EXPRESSION_ATTRIBUTE_STYLE_VARIABLE, EXPRESSION_EVENT_ATTRIBUTE, EXPRESSION_EVENT_NAME, EXPRESSION_EVENT_OPTIONS_ACTIVE, EXPRESSION_EVENT_OPTIONS_CAPTURE, EXPRESSION_EVENT_OPTIONS_ONCE, EXPRESSION_EVENT_PREFIX, EXPRESSION_TEXTAREA_VALUE, NAME_FRAGMENT, NAME_FRAGMENTS, PROPERTY_IDENTIFIER, PROPERTY_VALUE, TEMPLATE_ITEM, VALUE_TRUE, WHITESPACE };

package/dist/fragment.d.mts

@@ -4,37 +4,54 @@ import { FragmentConfiguration } from "./models.mjs";
 declare class Fragment {
   #private;
   /**
-   * Fragment identifier
+   * Is template caching enabled?
+   */
+  get cache(): boolean;
+  /**
+   * 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(): unknown;
   constructor(strings: TemplateStringsArray, expressions: unknown[]);
   /**
-   * Append the fragment to the given element
+   * Insert the _Fragment_ after the given element
+   * @param element Element to insert after
+   */
+  after(element: Element): void;
+  /**
+   * Append the _Fragment_ to the given element
    * @param element Element to append to
    */
   appendTo(element: Element): void;
   /**
-   * Configure the fragment
+   * Insert the _Fragment_ before the given element
+   * @param element Element to insert before
+   */
+  before(element: Element): void;
+  /**
+   * Configure the _Fragment_
+   *
+   * _Returns the Fragment instance for chaining_
    * @param configuration Configuration options
-   * @returns Fragment
+   * @returns _Fragment_
    */
   configure(configuration: FragmentConfiguration): Fragment;
   /**
-   * Get a list of the fragment's nodes
+   * Get a list of the _Fragment_'s nodes
    * @returns List of nodes
    */
   get(): ChildNode[];
   /**
-   * 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: unknown): Fragment;
+  prependTo(element: Element): void;
   /**
-   * 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(): void;
 }

package/dist/fragment.mjs

@@ -14,7 +14,15 @@ var Fragment = class {
 		cache: true
 	};
 	/**
-	* Fragment identifier
+	* Is template caching enabled?
+	*/
+	get cache() {
+		return this.#configuration.cache;
+	}
+	/**
+	* 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;
@@ -33,16 +41,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 : {};
@@ -51,7 +75,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() {
@@ -59,24 +83,22 @@ var Fragment = class {
 		if (data.items.length === 0) {
 			const templated = html(parse(data), { cache: this.#configuration.cache });
 			data.items.splice(0, data.items.length, ...templated.map((node) => ({ nodes: [node] })));
-			mapNodes(data, data.items.flatMap((item) => item.fragments?.flatMap((fragment) => fragment.get()) ?? item.nodes ?? []));
+			mapNodes(data, data.items.flatMap((item) => item.nodes));
 		}
-		return data.items.flatMap((item) => item.fragments?.flatMap((fragment) => fragment.get()) ?? item.nodes ?? []);
+		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);
@@ -89,7 +111,7 @@ function removeFragment(data) {
 		const { fragments, nodes } = data.items[index];
 		const fragmentsLength = fragments?.length ?? 0;
 		for (let fragmentIndex = 0; fragmentIndex < fragmentsLength; fragmentIndex += 1) fragments?.[fragmentIndex]?.remove();
-		removeNodes(nodes ?? []);
+		removeNodes(nodes);
 	}
 	data.items.length = 0;
 	length = data.values.length;

package/dist/fragments.d.mts

@@ -1,17 +1,13 @@
-import { FragmentsState } from "./models.mjs";
 import { Fragment } from "./fragment.mjs";
+import { FragmentsState } from "./models.mjs";
 import { ReactiveArray } from "@oscarpalmer/mora";
 
 //#region src/fragments.d.ts
 declare class Fragments {
   #private;
-  /**
-   * Fragment items
-   */
-  get items(): ReactiveArray<Fragment>;
   constructor(items: ReactiveArray<unknown>, identify: (item: unknown) => unknown, fragment: (item: unknown) => Fragment);
 }
 declare function handleFragments(item: Fragments | FragmentsState, remove: boolean): void;
-declare function initializeFragments(state: FragmentsState): void;
+declare const fragmentsStates: WeakMap<Fragments, FragmentsState>;
 //#endregion
-export { Fragments, handleFragments, initializeFragments };
+export { Fragments, fragmentsStates, handleFragments };

package/dist/fragments.mjs

@@ -5,12 +5,6 @@ import { array } from "@oscarpalmer/mora";
 //#region src/fragments.ts
 var Fragments = class {
 	#state;
-	/**
-	* Fragment items
-	*/
-	get items() {
-		return this.#state.mapped;
-	}
 	constructor(items, identify, fragment) {
 		Object.defineProperty(this, NAME_FRAGMENTS, { value: true });
 		this.#state = {
@@ -21,13 +15,13 @@ var Fragments = class {
 			mapped: array([]),
 			subscriber: void 0
 		};
-		states.set(this, this.#state);
+		fragmentsStates.set(this, this.#state);
 		initializeFragments(this.#state);
 	}
 };
 function handleFragments(item, remove) {
-	const state = isFragments(item) ? states.get(item) : item;
-	if (state != null) (remove ? removeFragments : initializeFragments)(state);
+	const state = isFragments(item) ? fragmentsStates.get(item) : item;
+	(remove ? removeFragments : initializeFragments)(state);
 }
 function handleItems(state, items) {
 	const keys = /* @__PURE__ */ new Set();
@@ -44,7 +38,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);
@@ -75,6 +69,6 @@ function updateFragments(state, active) {
 	state.instances = next;
 	active?.clear();
 }
-const states = /* @__PURE__ */ new WeakMap();
+const fragmentsStates = /* @__PURE__ */ new WeakMap();
 //#endregion
-export { Fragments, handleFragments, initializeFragments };
+export { Fragments, fragmentsStates, handleFragments };

package/dist/helpers/dom.d.mts

@@ -1,7 +1,6 @@
 //#region src/helpers/dom.d.ts
 declare function createNodes(value: unknown): ChildNode[];
-declare function isInputElement(node: Node): node is HTMLInputElement | HTMLSelectElement;
 declare function removeNodes(nodes: ChildNode[]): void;
-declare function replaceNodes(from: ChildNode[], to: ChildNode[]): void;
+declare function replaceNodes(from: ChildNode[], to: ChildNode[]): ChildNode[];
 //#endregion
-export { createNodes, isInputElement, removeNodes, replaceNodes };
+export { createNodes, removeNodes, replaceNodes };

package/dist/helpers/dom.mjs

@@ -7,9 +7,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();
@@ -18,6 +15,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
-export { createNodes, isInputElement, removeNodes, replaceNodes };
+export { createNodes, removeNodes, replaceNodes };

package/dist/helpers/index.d.mts

@@ -1,10 +1,24 @@
-import { ARRAY_COMPARISON_ADDED, ARRAY_COMPARISON_DISSIMILAR, ARRAY_COMPARISON_REMOVED } from "../constants.mjs";
 import { Fragment } from "../fragment.mjs";
+import { FragmentData } from "../models.mjs";
+import { ARRAY_COMPARISON_ADDED, ARRAY_COMPARISON_DISSIMILAR, ARRAY_COMPARISON_REMOVED } from "../constants.mjs";
 import { Fragments } from "../fragments.mjs";
+import { Computed } from "@oscarpalmer/mora";
+import { GenericCallback } from "@oscarpalmer/atoms/models";
 
 //#region src/helpers/index.d.ts
 declare function compareArrays(first: unknown[], second: unknown[]): typeof ARRAY_COMPARISON_ADDED | typeof ARRAY_COMPARISON_DISSIMILAR | typeof ARRAY_COMPARISON_REMOVED;
+/**
+ * Is the value a _Fragment_?
+ * @param value Value to check
+ * @returns `true` if the value is a _Fragment_, otherwise `false`
+ */
 declare function isFragment(value: unknown): value is Fragment;
+/**
+ * Is the value a _Fragments_ instance?
+ * @param value Value to check
+ * @returns `true` if the value is a _Fragments_ instance, otherwise `false`
+ */
 declare function isFragments(value: unknown): value is Fragments;
+declare function setComputedValue(data: FragmentData, callback: GenericCallback, after: (computation: Computed<unknown>) => void): void;
 //#endregion
-export { compareArrays, isFragment, isFragments };
+export { compareArrays, isFragment, isFragments, setComputedValue };

package/dist/helpers/index.mjs

@@ -1,4 +1,5 @@
 import { ARRAY_COMPARISON_ADDED, ARRAY_COMPARISON_DISSIMILAR, ARRAY_COMPARISON_REMOVED, NAME_FRAGMENT, NAME_FRAGMENTS } from "../constants.mjs";
+import { computed } from "@oscarpalmer/mora";
 //#region src/helpers/index.ts
 function compareArrays(first, second) {
 	const firstIsLarger = first.length > second.length;
@@ -7,14 +8,29 @@ function compareArrays(first, second) {
 	if (!from.filter((key) => to.includes(key)).every((key, index) => to[index] === key)) return ARRAY_COMPARISON_DISSIMILAR;
 	return firstIsLarger ? ARRAY_COMPARISON_REMOVED : ARRAY_COMPARISON_ADDED;
 }
+/**
+* Is the value a _Fragment_?
+* @param value Value to check
+* @returns `true` if the value is a _Fragment_, otherwise `false`
+*/
 function isFragment(value) {
 	return isNamed(value, NAME_FRAGMENT);
 }
+/**
+* Is the value a _Fragments_ instance?
+* @param value Value to check
+* @returns `true` if the value is a _Fragments_ instance, otherwise `false`
+*/
 function isFragments(value) {
 	return isNamed(value, NAME_FRAGMENTS);
 }
 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
-export { compareArrays, isFragment, isFragments };
+export { compareArrays, isFragment, isFragments, setComputedValue };

package/dist/index.d.mts

@@ -1,21 +1,49 @@
 import { Fragment } from "./fragment.mjs";
 import { Fragments } from "./fragments.mjs";
+import { isFragment, isFragments } from "./helpers/index.mjs";
 import { ReactiveArray } from "@oscarpalmer/mora";
 export * from "@oscarpalmer/mora";
 
 //#region src/index.d.ts
 /**
- * Create 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_
  */
 declare function fragments<Item>(array: ReactiveArray<Item>, identify: (item: Item) => unknown, fragment: (item: Item) => Fragment): Fragments;
 /**
- * Create 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_
  */
 declare function html(template: TemplateStringsArray, ...values: unknown[]): Fragment;
 //#endregion
-export { type Fragment, type Fragments, fragments, html };
+export { type Fragment, type Fragments, fragments, html, isFragment, isFragments };