@oscarpalmer/abydon 0.22.0 → 0.23.1

package/src/fragment.ts

@@ -19,12 +19,14 @@ export class Fragment {
 	/**
 	 * Is template caching enabled?
 	 */
-	get caching(): boolean {
+	get cache(): boolean {
 		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(): unknown {
 		return this.#configuration.identifier;
@@ -48,7 +50,15 @@ export class Fragment {
 	}
 
 	/**
-	 * Append the fragment to the given element
+	 * Insert the _Fragment_ after the given element
+	 * @param element Element to insert after
+	 */
+	after(element: Element): void {
+		element.after(...this.get());
+	}
+
+	/**
+	 * Append the _Fragment_ to the given element
 	 * @param element Element to append to
 	 */
 	appendTo(element: Element): void {
@@ -56,9 +66,19 @@ export class Fragment {
 	}
 
 	/**
-	 * Configure the fragment
+	 * Insert the _Fragment_ before the given element
+	 * @param element Element to insert before
+	 */
+	before(element: Element): void {
+		element.before(...this.get());
+	}
+
+	/**
+	 * Configure the _Fragment_
+	 *
+	 * _Returns the Fragment instance for chaining_
 	 * @param configuration Configuration options
-	 * @returns Fragment
+	 * @returns _Fragment_
 	 */
 	configure(configuration: FragmentConfiguration): Fragment {
 		const actual = isPlainObject(configuration) ? configuration : {};
@@ -75,7 +95,7 @@ export class Fragment {
 	}
 
 	/**
-	 * Get a list of the fragment's nodes
+	 * Get a list of the _Fragment_'s nodes
 	 * @returns List of nodes
 	 */
 	get(): ChildNode[] {
@@ -108,21 +128,18 @@ export class Fragment {
 	}
 
 	/**
-	 * 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 {
-		this.#configuration.identifier = identifier;
-
-		return this;
+	prependTo(element: Element): void {
+		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(): void {
 		removeFragment(this.#data);

package/src/fragments.ts

@@ -74,7 +74,9 @@ function handleItems(state: FragmentsState, items: unknown[]): void {
 			}
 		}
 
-		instance.identify(key);
+		instance.configure({
+			identifier: key,
+		});
 
 		state.instances[key] = instance;
 
@@ -88,7 +90,7 @@ function handleItems(state: FragmentsState, items: unknown[]): void {
 	updateFragments(state, keys);
 }
 
-export function initializeFragments(state: FragmentsState): void {
+function initializeFragments(state: FragmentsState): void {
 	state.subscriber ??= state.array.subscribe(items => {
 		handleItems(state, items);
 	});

package/src/helpers/dom.ts

@@ -14,10 +14,6 @@ export function createNodes(value: unknown): ChildNode[] {
 	return [new Text(getString(value))];
 }
 
-export function isInputElement(node: Node): node is HTMLInputElement | HTMLSelectElement {
-	return node instanceof HTMLInputElement || node instanceof HTMLSelectElement;
-}
-
 export function removeNodes(nodes: ChildNode[]): void {
 	const {length} = nodes;
 
@@ -26,7 +22,7 @@ export function removeNodes(nodes: ChildNode[]): void {
 	}
 }
 
-export function replaceNodes(from: ChildNode[], to: ChildNode[]): void {
+export function replaceNodes(from: ChildNode[], to: ChildNode[]): ChildNode[] {
 	from[0]?.replaceWith(...to);
 
 	const {length} = from;
@@ -34,4 +30,6 @@ export function replaceNodes(from: ChildNode[], to: ChildNode[]): void {
 	for (let index = 1; index < length; index += 1) {
 		from[index].remove();
 	}
+
+	return to;
 }

package/src/helpers/index.ts

@@ -1,4 +1,5 @@
-import type {PlainObject} from '@oscarpalmer/atoms/models';
+import type {GenericCallback, PlainObject} from '@oscarpalmer/atoms/models';
+import {computed, type Computed} from '@oscarpalmer/mora';
 import {
 	ARRAY_COMPARISON_ADDED,
 	ARRAY_COMPARISON_DISSIMILAR,
@@ -8,6 +9,7 @@ import {
 } from '../constants';
 import type {Fragment} from '../fragment';
 import type {Fragments} from '../fragments';
+import type {FragmentData} from '../models';
 
 export function compareArrays(
 	first: unknown[],
@@ -28,18 +30,18 @@ export function compareArrays(
 }
 
 /**
- * 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`
  */
 export function isFragment(value: unknown): value is Fragment {
 	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`
  */
 export function isFragments(value: unknown): value is Fragments {
 	return isNamed(value, NAME_FRAGMENTS);
@@ -53,3 +55,15 @@ function isNamed(value: unknown, name: string): boolean {
 		(value as PlainObject)[name] === true
 	);
 }
+
+export function setComputedValue(
+	data: FragmentData,
+	callback: GenericCallback,
+	after: (computation: Computed<unknown>) => void,
+): void {
+	const computation = computed(callback);
+
+	data.mora.values.add(computation);
+
+	after(computation);
+}

package/src/index.ts

@@ -4,11 +4,27 @@ import {Fragment} from './fragment';
 import {Fragments} from './fragments';
 
 /**
- * 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_
  */
 export function fragments<Item>(
 	array: ReactiveArray<Item>,
@@ -31,8 +47,19 @@ export function fragments<Item>(
 }
 
 /**
- * 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_
  */
 export function html(template: TemplateStringsArray, ...values: unknown[]): Fragment {
 	return new Fragment(template, values);

package/src/models.ts

@@ -1,16 +1,18 @@
 import type {Reactive, ReactiveArray, Unsubscribe} from '@oscarpalmer/mora';
 import type {Fragment} from './fragment';
 
+/**
+ * Configuration for a _Fragment_
+ */
 export type FragmentConfiguration = {
 	/**
 	 * Should the template be cached? _(defaults to `true`)_
 	 */
 	cache?: boolean;
 	/**
-	 * Identifier for the fragment
+	 * Identifier for the _Fragment_
 	 *
-	 * _(An identifier can be used to uniquely identify a fragment,
-	 * which helps prevent re-rendering in certain scenarios)_
+	 * _An identifier can be used to uniquely identify a Fragment, which helps prevent re-rendering in reactive arrays and Fragments_
 	 */
 	identifier?: unknown;
 };
@@ -19,7 +21,7 @@ export type FragmentData = {
 	expressions: unknown[];
 	items: FragmentItem[];
 	mora: MoraData;
-	strings: TemplateStringsArray;
+	strings: TemplateStringsArray | string[];
 	template?: string;
 	values: unknown[];
 };

package/src/node/index.ts

@@ -1,21 +1,12 @@
 import type {GenericCallback} from '@oscarpalmer/atoms/models';
-import {getString} from '@oscarpalmer/atoms/string';
-import {
-	computed,
-	isComputed,
-	isReactive,
-	isSignal,
-	type Computed,
-	type ReactiveArray,
-} from '@oscarpalmer/mora';
+import {isReactive, type ReactiveArray} from '@oscarpalmer/mora';
 import {isHTMLOrSVGElement} from '@oscarpalmer/toretto/is';
-import {mapAttributes} from '../attribute/index';
-import {EVENT_ON_VALUE, EXPRESSION_ABYDON_CONTENT, EXPRESSION_TEXTAREA_VALUE} from '../constants';
+import {mapAttributes, mapAttributeValue} from '../attribute/index';
+import {EXPRESSION_ABYDON_CONTENT, EXPRESSION_TEXTAREA_VALUE} from '../constants';
 import {Fragments, fragmentsStates, handleFragments} from '../fragments';
-import {isFragment, isFragments} from '../helpers';
+import {isFragment, isFragments, setComputedValue} from '../helpers';
 import {createNodes} from '../helpers/dom';
 import type {FragmentData} from '../models';
-import {mapEvent} from './event';
 import {setReactiveValue} from './value';
 
 function mapNode(data: FragmentData, comment: Comment): void {
@@ -39,12 +30,17 @@ export function mapNodes(data: FragmentData, nodes: ChildNode[]): void {
 			continue;
 		}
 
-		if (node instanceof HTMLTextAreaElement) {
-			mapTextarea(data, node);
-		}
-
 		if (isHTMLOrSVGElement(node)) {
-			mapAttributes(data, node);
+			let ignoreValueAttribute = false;
+
+			if (node instanceof HTMLTextAreaElement) {
+				// Textareas are a special case because their value can be set via the `value` property
+				// or the text content. In order to support both, we need to check for the presence of
+				// the expression in both places and map it accordingly.
+				ignoreValueAttribute = mapTextarea(data, node);
+			}
+
+			mapAttributes(data, node, ignoreValueAttribute);
 		}
 
 		if (node.hasChildNodes()) {
@@ -53,64 +49,32 @@ export function mapNodes(data: FragmentData, nodes: ChildNode[]): void {
 	}
 }
 
-function mapTextarea(data: FragmentData, element: HTMLTextAreaElement): void {
+function mapTextarea(data: FragmentData, element: HTMLTextAreaElement): boolean {
 	const [, index] =
 		EXPRESSION_TEXTAREA_VALUE.exec(element.textContent) ??
 		EXPRESSION_TEXTAREA_VALUE.exec(element.value) ??
 		[];
 
 	if (index == null) {
-		return;
+		return false;
 	}
 
 	element.textContent = '';
 	element.value = '';
 
-	const value = data.values[Number.parseInt(index, 10)];
+	mapAttributeValue(data, element, 'value', data.values[Number.parseInt(index, 10)]);
 
-	if (isSignal(value)) {
-		element.value = getString(value.peek());
-
-		mapEvent(element, EVENT_ON_VALUE, () => {
-			value.set(element.value);
-		});
-
-		data.mora.subscribers.add(
-			value.subscribe(value => {
-				element.value = getString(value);
-			}),
-		);
-
-		return;
-	}
-
-	let reactive: Computed<unknown> | undefined;
-
-	if (typeof value === 'function') {
-		reactive = computed(value as GenericCallback);
-	} else if (isComputed(value)) {
-		reactive = value;
-	}
-
-	if (reactive == null) {
-		element.value = '';
-	} else {
-		data.mora.subscribers.add(
-			reactive.subscribe(value => {
-				element.value = getString(value);
-			}),
-		);
-	}
+	return true;
 }
 
 function mapValue(data: FragmentData, comment: Comment, value: unknown): void {
 	switch (true) {
 		case typeof value === 'function':
-			setComputedValue(data, comment, value as GenericCallback);
+			setComputedNode(data, comment, value as GenericCallback);
 			break;
 
 		case isFragments(value):
-			setFragmentsValue(data, comment, value);
+			setFragmentsNode(data, comment, value);
 			break;
 
 		case isReactive(value):
@@ -135,15 +99,13 @@ function replaceComment(data: FragmentData, comment: Comment, value: unknown): v
 	comment.replaceWith(...nodes);
 }
 
-function setComputedValue(data: FragmentData, comment: Comment, callback: GenericCallback): void {
-	const value = computed(callback);
-
-	data.mora.values.add(value);
-
-	setReactiveValue(data, comment, value);
+function setComputedNode(data: FragmentData, comment: Comment, callback: GenericCallback): void {
+	setComputedValue(data, callback, computation => {
+		setReactiveValue(data, comment, computation);
+	});
 }
 
-function setFragmentsValue(data: FragmentData, comment: Comment, fragments: Fragments): void {
+function setFragmentsNode(data: FragmentData, comment: Comment, fragments: Fragments): void {
 	const state = fragmentsStates.get(fragments)!;
 
 	handleFragments(state, false);