@oscarpalmer/abydon 0.21.0 → 0.23.0

package/src/constants.ts

@@ -4,13 +4,15 @@ export const ARRAY_COMPARISON_DISSIMILAR = 'dissimilar';
 
 export const ARRAY_COMPARISON_REMOVED = 'removed';
 
-export const ATTRIBUTE_CLASS_PREFIX_LENGTH = 6;
+export const ATTRIBUTE_CLASS_PREFIX_LENGTH = 'class.'.length;
 
 export const ATTRIBUTE_NAME_DELIMITER = '.';
 
+export const CHANGE_INPUTS = new Set(['checkbox', 'radio']);
+
 export const ERROR_FRAGMENT = 'Fragment function must return a Fragment instance';
 
-export const ERROR_IDENTIFIER_DUPLICATE = "Duplicate identifier found: '<id>'";
+export const ERROR_IDENTIFIER_DUPLICATE = "Duplicate identifier found: '<>'";
 
 export const ERROR_IDENTIFIER_TYPE = 'Identifier cannot be null or undefined';
 
@@ -29,17 +31,15 @@ export const EVENT_DEFAULTS: Record<string, string> = {
 	TEXTAREA: EVENT_INPUT,
 };
 
-export const EVENT_ON_PREFIXED = '@on';
-
 export const EVENT_ON_VALUE = 'on';
 
 export const EVENT_OPTIONS_DELIMITER = ':';
 
-export const EXPRESSION_ABYDON_ATTRIBUTE_FULL = /(@?[\w-]+)="<!--abydon.(\d+)-->"/g;
+export const EXPRESSION_ABYDON_ATTRIBUTE_FULL = /(@?[\w-.]+(?::[a-z:]+)?)="<!--abydon.(\d+)-->"/g;
 
-export const EXPRESSION_ABYDON_ATTRIBUTE_PREFIX = /^_/;
+export const EXPRESSION_ABYDON_ATTRIBUTE_PREFIX = /^abydon-/;
 
-export const EXPRESSION_ABYDON_CONTENT = /^@?abydon\.(\d+)@?$/;
+export const EXPRESSION_ABYDON_CONTENT = /^abydon\.(\d+)$/;
 
 export const EXPRESSION_ATTRIBUTE_CLASS = /^class\./;
 
@@ -47,32 +47,32 @@ export const EXPRESSION_ATTRIBUTE_STYLE_FULL = /^style\.([\w-]+)(?:\.([\w-]+))?$
 
 export const EXPRESSION_ATTRIBUTE_STYLE_PREFIX = /^style\./;
 
-export const EXPRESSION_EVENT_CHANGE_TYPES = /^(checkbox|radio)$/;
+export const EXPRESSION_ATTRIBUTE_STYLE_VARIABLE = /^style\.--/;
 
-export const EXPRESSION_EVENT_NAME = /^@([\w-]+)(?::([a-z:]+))?$/i;
+export const EXPRESSION_EVENT_ATTRIBUTE = /^@([\w-]+)(?::([a-z:]+))?="$/i;
 
-export const EXPRESSION_EVENT_OPTIONS_ACTIVE = /^a(ctive)$/i;
+export const EXPRESSION_EVENT_NAME = /^@?([\w-]+)(?::([a-z:]+))?$/i;
 
-export const EXPRESSION_EVENT_OPTIONS_CAPTURE = /^c(apture)$/i;
+export const EXPRESSION_EVENT_OPTIONS_ACTIVE = /^a(?:ctive)$/i;
 
-export const EXPRESSION_EVENT_OPTIONS_ONCE = /^o(nce)$/i;
-
-export const EXPRESSION_EVENT_PREFIX = /^@/;
+export const EXPRESSION_EVENT_OPTIONS_CAPTURE = /^c(?:apture)$/i;
 
-export const EXPRESSION_PERIOD = /\./;
+export const EXPRESSION_EVENT_OPTIONS_ONCE = /^o(?:nce)$/i;
 
-export const EXPRESSION_TEXTAREA_VALUE = /<!--abydon\.(\d+)-->/;
+export const EXPRESSION_EVENT_PREFIX = /^@/;
 
-export const INPUT_TYPE_CHECKBOX = 'checkbox';
+export const EXPRESSION_TEXTAREA_VALUE = /(?:<|&lt;)!--abydon\.(\d+)--(?:>|&gt;)/;
 
 export const NAME_FRAGMENT = '$fragment';
 
 export const NAME_FRAGMENTS = '$fragments';
 
-export const PROPERTY_CHECKED = 'checked';
-
 export const PROPERTY_IDENTIFIER = 'identifier';
 
 export const PROPERTY_VALUE = 'value';
 
 export const TEMPLATE_ITEM = '<>';
+
+export const VALUE_TRUE = 'true';
+
+export const WHITESPACE = /\s+/g;

package/src/fragment.ts

@@ -17,7 +17,16 @@ export class Fragment {
 	};
 
 	/**
-	 * Fragment identifier
+	 * Is template caching enabled?
+	 */
+	get cache(): boolean {
+		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(): unknown {
 		return this.#configuration.identifier;
@@ -41,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 {
@@ -49,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 : {};
@@ -68,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[] {
@@ -91,33 +118,28 @@ export class Fragment {
 
 			mapNodes(
 				data,
-				data.items.flatMap(
-					item => item.fragments?.flatMap(fragment => fragment.get()) ?? item.nodes ?? [],
-				),
+				data.items.flatMap(item => item.nodes!),
 			);
 		}
 
 		return data.items.flatMap(
-			item => item.fragments?.flatMap(fragment => fragment.get()) ?? item.nodes ?? [],
+			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: 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);
@@ -137,7 +159,7 @@ function removeFragment(data: FragmentData): void {
 			fragments?.[fragmentIndex]?.remove();
 		}
 
-		removeNodes(nodes ?? []);
+		removeNodes(nodes!);
 	}
 
 	data.items.length = 0;

package/src/fragments.ts

@@ -14,13 +14,6 @@ import type {FragmentsState} from './models';
 export class Fragments {
 	readonly #state: FragmentsState;
 
-	/**
-	 * Fragment items
-	 */
-	get items(): ReactiveArray<Fragment> {
-		return this.#state.mapped;
-	}
-
 	constructor(
 		items: ReactiveArray<unknown>,
 		identify: (item: unknown) => unknown,
@@ -39,18 +32,16 @@ export class Fragments {
 			subscriber: undefined,
 		};
 
-		states.set(this, this.#state);
+		fragmentsStates.set(this, this.#state);
 
 		initializeFragments(this.#state);
 	}
 }
 
 export function handleFragments(item: Fragments | FragmentsState, remove: boolean): void {
-	const state = isFragments(item) ? states.get(item) : item;
+	const state = isFragments(item) ? fragmentsStates.get(item) : item;
 
-	if (state != null) {
-		(remove ? removeFragments : initializeFragments)(state);
-	}
+	(remove ? removeFragments : initializeFragments)(state!);
 }
 
 function handleItems(state: FragmentsState, items: unknown[]): void {
@@ -83,7 +74,9 @@ function handleItems(state: FragmentsState, items: unknown[]): void {
 			}
 		}
 
-		instance.identify(key);
+		instance.configure({
+			identifier: key,
+		});
 
 		state.instances[key] = instance;
 
@@ -97,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);
 	});
@@ -135,4 +128,4 @@ function updateFragments(state: FragmentsState, active?: Set<string>): void {
 
 //
 
-const states: WeakMap<Fragments, FragmentsState> = new WeakMap();
+export const fragmentsStates: WeakMap<Fragments, FragmentsState> = new WeakMap();

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[],
@@ -27,10 +29,20 @@ export function compareArrays(
 	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`
+ */
 export function isFragment(value: unknown): value is Fragment {
 	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`
+ */
 export function isFragments(value: unknown): value is Fragments {
 	return isNamed(value, NAME_FRAGMENTS);
 }
@@ -43,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

@@ -1,26 +1,65 @@
 import '@oscarpalmer/mora';
-import type {ReactiveArray} from '@oscarpalmer/mora';
+import {isArray, type ReactiveArray} from '@oscarpalmer/mora';
 import {Fragment} from './fragment';
 import {Fragments} from './fragments';
 
 /**
- * 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_
  */
 export function fragments<Item>(
 	array: ReactiveArray<Item>,
 	identify: (item: Item) => unknown,
 	fragment: (item: Item) => Fragment,
 ): Fragments {
+	if (!isArray(array)) {
+		throw new TypeError('Fragments array must be a reactive array');
+	}
+
+	if (typeof identify !== 'function') {
+		throw new TypeError('Fragments identify must be a function');
+	}
+
+	if (typeof fragment !== 'function') {
+		throw new TypeError('Fragments fragment must be a function');
+	}
+
 	return new Fragments(array as ReactiveArray<unknown>, identify as never, fragment as never);
 }
 
 /**
- * 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_
  */
 export function html(template: TemplateStringsArray, ...values: unknown[]): Fragment {
 	return new Fragment(template, values);
@@ -29,3 +68,4 @@ export function html(template: TemplateStringsArray, ...values: unknown[]): Frag
 export * from '@oscarpalmer/mora';
 export type {Fragment} from './fragment';
 export type {Fragments} from './fragments';
+export {isFragment, isFragments} from './helpers';

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/event.ts

@@ -1,12 +1,12 @@
 import {on} from '@oscarpalmer/toretto/event';
 import {
+	CHANGE_INPUTS,
 	EVENT_CHANGE,
 	EVENT_DEFAULTS,
 	EVENT_INPUT,
 	EVENT_ON_VALUE,
 	EVENT_OPTIONS_DELIMITER,
 	EVENT_SUBMIT,
-	EXPRESSION_EVENT_CHANGE_TYPES,
 	EXPRESSION_EVENT_NAME,
 	EXPRESSION_EVENT_OPTIONS_ACTIVE,
 	EXPRESSION_EVENT_OPTIONS_CAPTURE,
@@ -29,7 +29,7 @@ function getType(element: HTMLElement | SVGElement, type: string): string {
 	}
 
 	if (element instanceof HTMLInputElement) {
-		if (EXPRESSION_EVENT_CHANGE_TYPES.test(element.type)) {
+		if (CHANGE_INPUTS.has(element.type)) {
 			return EVENT_CHANGE;
 		}
 
@@ -40,9 +40,16 @@ function getType(element: HTMLElement | SVGElement, type: string): string {
 }
 
 export function mapEvent(element: HTMLElement | SVGElement, name: string, value: unknown): void {
-	const [, type, options] = EXPRESSION_EVENT_NAME.exec(name) ?? [];
+	const [, type, options] = EXPRESSION_EVENT_NAME.exec(name)!;
 
-	if (type != null && typeof value === 'function') {
-		on(element, getType(element, type), value as EventListener, getOptions(options ?? ''));
+	const values = Array.isArray(value) ? value : [value];
+	const {length} = values;
+
+	for (let index = 0; index < length; index += 1) {
+		const item = values[index];
+
+		if (typeof item === 'function') {
+			on(element, getType(element, type), item as EventListener, getOptions(options ?? ''));
+		}
 	}
 }

package/src/node/index.ts

@@ -1,24 +1,16 @@
 import type {GenericCallback} from '@oscarpalmer/atoms/models';
-import {
-	computed,
-	isComputed,
-	isReactive,
-	isSignal,
-	type Computed,
-	type Reactive,
-} from '@oscarpalmer/mora';
+import {isReactive, type ReactiveArray} from '@oscarpalmer/mora';
 import {isHTMLOrSVGElement} from '@oscarpalmer/toretto/is';
+import {mapAttributes, mapAttributeValue} from '../attribute/index';
 import {EXPRESSION_ABYDON_CONTENT, EXPRESSION_TEXTAREA_VALUE} from '../constants';
-import {handleFragments} from '../fragments';
-import {isFragment, isFragments} from '../helpers';
+import {Fragments, fragmentsStates, handleFragments} from '../fragments';
+import {isFragment, isFragments, setComputedValue} from '../helpers';
 import {createNodes} from '../helpers/dom';
 import type {FragmentData} from '../models';
-import {mapAttributes} from './attribute';
 import {setReactiveValue} from './value';
-import {mapEvent} from './event';
 
 function mapNode(data: FragmentData, comment: Comment): void {
-	const matches = EXPRESSION_ABYDON_CONTENT.exec(comment.textContent ?? '');
+	const matches = EXPRESSION_ABYDON_CONTENT.exec(comment.textContent);
 	const value = matches == null ? null : data.values[+matches[1]];
 
 	if (value != null) {
@@ -38,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()) {
@@ -52,55 +49,32 @@ export function mapNodes(data: FragmentData, nodes: ChildNode[]): void {
 	}
 }
 
-function mapTextarea(data: FragmentData, element: HTMLTextAreaElement): void {
-	const [, index] = EXPRESSION_TEXTAREA_VALUE.exec(element.value) ?? [];
+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)];
-
-	if (isSignal(value)) {
-		element.value = String(value.peek());
-
-		mapEvent(element, '@on', () => {
-			value.set(element.value);
-		});
-
-		return;
-	}
-
-	let reactive: Computed<unknown> | undefined;
-
-	if (typeof value === 'function') {
-		reactive = computed(value as GenericCallback);
-	} else if (isComputed(value)) {
-		reactive = value;
-	}
+	mapAttributeValue(data, element, 'value', data.values[Number.parseInt(index, 10)]);
 
-	if (reactive == null) {
-		element.value = String(value);
-	} else {
-		data.mora.subscribers.add(
-			reactive.subscribe(value => {
-				element.value = String(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):
-			handleFragments(value, false);
-			setReactiveValue(data, comment, value.items as Reactive<unknown[], unknown>);
+			setFragmentsNode(data, comment, value);
 			break;
 
 		case isReactive(value):
@@ -125,10 +99,16 @@ 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);
+function setComputedNode(data: FragmentData, comment: Comment, callback: GenericCallback): void {
+	setComputedValue(data, callback, computation => {
+		setReactiveValue(data, comment, computation);
+	});
+}
+
+function setFragmentsNode(data: FragmentData, comment: Comment, fragments: Fragments): void {
+	const state = fragmentsStates.get(fragments)!;
 
-	data.mora.values.add(value);
+	handleFragments(state, false);
 
-	setReactiveValue(data, comment, value);
+	setReactiveValue(data, comment, state.mapped as ReactiveArray<unknown>);
 }