@oscarpalmer/abydon 0.22.0 → 0.23.0

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);

package/src/node/value.ts

@@ -10,9 +10,30 @@ import type {FragmentData, FragmentItem} from '../models';
 
 //
 
+type ArrayData = {
+	next: ArrayDataIdentifiers;
+	previous: ArrayDataIdentifiers;
+	template: ArrayDataTemplate;
+};
+
+type ArrayDataIdentifiers = {
+	array: unknown[];
+	set: Set<unknown>;
+};
+
+type ArrayDataTemplate = {
+	empty: boolean;
+	items: Fragment[];
+};
+
 type Identifiers = {
-	next: Set<unknown>;
-	previous: Set<unknown>;
+	next: IdentifiersValues;
+	previous: IdentifiersValues;
+};
+
+type IdentifiersValues = {
+	array: unknown[];
+	set: Set<unknown>;
 };
 
 type BaseItems = {
@@ -34,7 +55,7 @@ function addToArray(
 ): void {
 	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 => ({
@@ -48,7 +69,7 @@ function addToArray(
 	for (let index = 0; index < length; index += 1) {
 		const node = next[index];
 
-		if (!(added && identifiers.previous.has(node.identifier))) {
+		if (!(added && identifiers.previous.set.has(node.identifier))) {
 			if (index === 0 && before) {
 				position.before(node.value);
 			} else {
@@ -60,6 +81,46 @@ function addToArray(
 	}
 }
 
+function getArrayData(item: FragmentItem, values: unknown[]): ArrayData {
+	const {length} = values;
+
+	const next: unknown[] = [];
+
+	let templates: Fragment[] = [];
+
+	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: Identifiers,
 	items: BaseItems,
@@ -67,17 +128,18 @@ function handleArray(
 ): Partial<FragmentItem> {
 	const next = items.templates.map(
 		template =>
-			items.fragments?.find(fragment => fragment.identifier === template.identifier) ?? template,
+			items.fragments.find(fragment => fragment.identifier === template.identifier) ?? template,
 	);
 
-	const comparison = compareArrays(items.fragments ?? [], items.templates);
+	const comparison = compareArrays(identifiers.previous.array, identifiers.next.array);
 
 	if (comparison !== ARRAY_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;
 
@@ -91,84 +153,70 @@ function handleArray(
 	};
 }
 
-function removeFragments(fragments: Fragment[] | undefined): void {
-	if (fragments != null) {
-		const {length} = fragments;
+function removeArray(item: FragmentItem, comment: Comment): Partial<FragmentItem> {
+	const fragments = (item.fragments ?? []).slice();
 
-		for (let index = 0; index < length; index += 1) {
-			fragments[index].remove();
-		}
-	}
+	const result = {
+		nodes: setText(item, comment),
+	};
+
+	removeFragmentsItems(fragments);
+
+	return result;
 }
 
-function replaceText(item: FragmentItem, comment: Comment, isNullable: boolean): void {
-	let to: ChildNode[];
+function removeFragmentsItems(fragments: Fragment[]): void {
+	const {length} = fragments;
 
-	if (isNullable) {
-		to = [comment];
-	} else {
-		to = item.text == null ? [] : [item.text];
+	for (let index = 0; index < length; index += 1) {
+		fragments[index].remove();
 	}
-
-	replaceNodes(item.nodes ?? [], to);
 }
 
 function setArray(item: FragmentItem, comment: Comment, value: unknown[]): Partial<FragmentItem> {
 	if (value.length === 0) {
-		return {
-			nodes: setText(item, comment, value),
-		};
+		return removeArray(item, comment);
 	}
 
-	let templates = value.filter(item => isFragment(item) && item.identifier != null) as Fragment[];
+	const {next, previous, template} = getArrayData(item, value);
 
-	const next = templates.map(fragment => fragment.identifier) as unknown[];
-	const previous = item.fragments?.map(fragment => fragment.identifier) ?? [];
+	if (
+		template.empty ||
+		item.nodes == null ||
+		previous.array.some(identifier => identifier == null)
+	) {
+		const fragments = (item.fragments ?? []).slice();
 
-	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 ? undefined : templates,
-			nodes: setNodes(
-				item,
-				comment,
-				noTemplates
+		const result = {
+			fragments: template.empty ? undefined : template.items,
+			nodes: replaceNodes(
+				item.nodes ?? [comment],
+				template.empty
 					? value.flatMap(item => createNodes(item))
-					: templates.flatMap(template => template.get()),
+					: template.items.flatMap(template => template.get()),
 			),
 		};
+
+		removeFragmentsItems(fragments);
+
+		return result;
 	}
 
 	return handleArray(
 		{
-			next: nextSet,
-			previous: new Set(previous),
+			next,
+			previous,
 		},
 		{
-			templates,
 			fragments: item.fragments ?? [],
+			templates: template.items,
 		},
 		item.nodes,
 	);
 }
 
 function setNodes(item: FragmentItem, comment: Comment, next: ChildNode[]): ChildNode[] {
-	if (item.nodes == null) {
-		replaceNodes([comment], next);
-	} else {
-		replaceNodes(item.nodes, next);
-	}
-
-	removeFragments(item.fragments);
-
-	return next;
+	return replaceNodes(item.nodes ?? [comment], next);
 }
 
 export function setReactiveValue(
@@ -180,8 +228,6 @@ export function setReactiveValue(
 
 	item ??= {};
 
-	item.text = new Text();
-
 	data.mora.subscribers.add(
 		reactive.subscribe(value => {
 			if (Array.isArray(value)) {
@@ -189,8 +235,6 @@ export function setReactiveValue(
 			} else {
 				setReactiveValueForSingle(item, comment, value);
 			}
-
-			item.nodes ??= [comment];
 		}),
 	);
 }
@@ -203,43 +247,31 @@ function setReactiveValueForArray(item: FragmentItem, comment: Comment, value: u
 }
 
 function setReactiveValueForSingle(item: FragmentItem, comment: Comment, value: unknown): void {
-	const valueIsFragment = isFragment(value);
+	const fragments = (item.fragments ?? []).slice();
 
-	item.fragments = valueIsFragment ? [value] : undefined;
+	const valueIsFragment = isFragment(value);
 
 	if (valueIsFragment || isChildNode(value)) {
 		item.nodes = setNodes(item, comment, createNodes(value));
 	} else {
 		item.nodes = setText(item, comment, value);
 	}
-}
 
-function setText(item: FragmentItem, comment: Comment, value: unknown): ChildNode[] | undefined {
-	const isNullable = isNullableOrWhitespace(value);
+	item.fragments = valueIsFragment ? [value] : undefined;
 
-	if (item.text != null) {
-		item.text.textContent = isNullable ? '' : getString(value);
-	}
+	removeFragmentsItems(fragments);
+}
 
-	let result = false;
+function setText(item: FragmentItem, comment: Comment, value?: unknown): ChildNode[] {
+	const valueIsNullable = isNullableOrWhitespace(value);
 
-	if (item.nodes != null) {
-		replaceText(item, comment, isNullable);
+	item.text ??= new Text();
 
-		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);
-		}
+	item.text.textContent = valueIsNullable ? '' : getString(value);
 
-		result = true;
-	}
+	const result = valueIsNullable ? [comment] : [item.text];
 
-	removeFragments(item.fragments);
+	replaceNodes(item.nodes ?? [comment], result);
 
-	if (result) {
-		return item.text == null ? [] : [item.text];
-	}
+	return result;
 }

package/src/parse.ts

@@ -48,7 +48,7 @@ export function parse(data: FragmentData): string {
 	data.template = data.template.replaceAll(EXPRESSION_ABYDON_ATTRIBUTE_FULL, transformAttribute);
 
 	data.expressions = [];
-	data.strings = [] as never;
+	data.strings = [];
 
 	return data.template;
 }