@oscarpalmer/abydon 0.23.1 → 0.24.0

package/src/fragments.ts

@@ -1,47 +1,92 @@
 import {getString} from '@oscarpalmer/atoms/string';
-import {array, type ReactiveArray} from '@oscarpalmer/mora';
+import {array, isReactiveArray, type ReactiveArray} from '@oscarpalmer/mora';
 import {
-	ERROR_FRAGMENT,
-	ERROR_IDENTIFIER_DUPLICATE,
-	ERROR_IDENTIFIER_TYPE,
+	MESSAGE_FRAGMENTS_FRAGMENT_RESULT,
+	MESSAGE_FRAGMENTS_FRAGMENT_TYPE,
+	MESSAGE_FRAGMENTS_IDENTIFIER_RESULT_DUPLICATE,
+	MESSAGE_FRAGMENTS_IDENTIFIER_RESULT_TYPE,
+	MESSAGE_FRAGMENTS_IDENTIFIER_TYPE,
+	MESSAGE_FRAGMENTS_VALUE,
 	NAME_FRAGMENTS,
+	SYMBOL,
 	TEMPLATE_ITEM,
 } from './constants';
-import type {Fragment} from './fragment';
-import {isFragment, isFragments} from './helpers';
-import type {FragmentsState} from './models';
-
-export class Fragments {
-	readonly #state: FragmentsState;
-
-	constructor(
-		items: ReactiveArray<unknown>,
-		identify: (item: unknown) => unknown,
-		fragment: (item: unknown) => Fragment,
-	) {
-		Object.defineProperty(this, NAME_FRAGMENTS, {
-			value: true,
-		});
+import {isFragment} from './helpers';
+import type {Fragment, Fragments, FragmentsState, InternalFragments} from './models';
+
+// #region Instances
+
+function Fragments(
+	this: any,
+	items: ReactiveArray<unknown>,
+	identify: (item: unknown) => unknown,
+	fragment: (item: unknown) => Fragment,
+) {
+	this[SYMBOL] = {
+		fragment,
+		identify,
+		array: items,
+		instances: {},
+		mapped: array<Fragment>([]),
+		name: NAME_FRAGMENTS,
+		subscription: undefined,
+	};
+
+	initializeFragments.call(this);
+}
 
-		this.#state = {
-			fragment,
-			identify,
-			array: items,
-			instances: {},
-			mapped: array<Fragment>([]),
-			subscriber: undefined,
-		};
+Fragments.prototype.remove = removeFragments;
+
+// #endregion
+
+// #region Functions
+
+/**
+ * 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 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 (!isReactiveArray(array)) {
+		throw new TypeError(MESSAGE_FRAGMENTS_VALUE);
+	}
 
-		fragmentsStates.set(this, this.#state);
+	if (typeof identify !== 'function') {
+		throw new TypeError(MESSAGE_FRAGMENTS_IDENTIFIER_TYPE);
+	}
 
-		initializeFragments(this.#state);
+	if (typeof fragment !== 'function') {
+		throw new TypeError(MESSAGE_FRAGMENTS_FRAGMENT_TYPE);
 	}
-}
 
-export function handleFragments(item: Fragments | FragmentsState, remove: boolean): void {
-	const state = isFragments(item) ? fragmentsStates.get(item) : item;
+	// @ts-expect-error All good, no worries :-)
+	return new Fragments(array as ReactiveArray<unknown>, identify as never, fragment as never);
+}
 
-	(remove ? removeFragments : initializeFragments)(state!);
+export function handleFragments(instance: Fragments, remove: boolean): void {
+	(remove ? removeFragments : initializeFragments).call(instance as InternalFragments);
 }
 
 function handleItems(state: FragmentsState, items: unknown[]): void {
@@ -55,13 +100,13 @@ function handleItems(state: FragmentsState, items: unknown[]): void {
 		const identifier = state.identify(item);
 
 		if (identifier == null) {
-			throw new TypeError(ERROR_IDENTIFIER_TYPE);
+			throw new TypeError(MESSAGE_FRAGMENTS_IDENTIFIER_RESULT_TYPE);
 		}
 
 		const key = getString(identifier);
 
 		if (keys.has(key)) {
-			throw new Error(ERROR_IDENTIFIER_DUPLICATE.replace(TEMPLATE_ITEM, key));
+			throw new Error(MESSAGE_FRAGMENTS_IDENTIFIER_RESULT_DUPLICATE.replace(TEMPLATE_ITEM, key));
 		}
 
 		let instance = state.instances[key];
@@ -70,7 +115,7 @@ function handleItems(state: FragmentsState, items: unknown[]): void {
 			instance = state.fragment(item);
 
 			if (!isFragment(instance)) {
-				throw new Error(ERROR_FRAGMENT);
+				throw new Error(MESSAGE_FRAGMENTS_FRAGMENT_RESULT);
 			}
 		}
 
@@ -90,18 +135,24 @@ function handleItems(state: FragmentsState, items: unknown[]): void {
 	updateFragments(state, keys);
 }
 
-function initializeFragments(state: FragmentsState): void {
-	state.subscriber ??= state.array.subscribe(items => {
+function initializeFragments(this: InternalFragments): void {
+	const state = this[SYMBOL];
+
+	state.subscription ??= state.array.subscribe(items => {
 		handleItems(state, items);
 	});
 }
 
-function removeFragments(state: FragmentsState): void {
-	state.subscriber?.();
+function removeFragments(this: InternalFragments): void {
+	const state = this[SYMBOL];
+
+	state.subscription?.unsubscribe();
+
+	state.mapped.set([]);
 
 	updateFragments(state);
 
-	state.subscriber = undefined;
+	state.subscription = undefined;
 }
 
 function updateFragments(state: FragmentsState, active?: Set<string>): void {
@@ -116,7 +167,7 @@ function updateFragments(state: FragmentsState, active?: Set<string>): void {
 
 		if (active?.has(key)) {
 			next[key] = previous[key];
-		} else {
+		} else if (active == null) {
 			previous[key].remove();
 		}
 	}
@@ -126,6 +177,4 @@ function updateFragments(state: FragmentsState, active?: Set<string>): void {
 	active?.clear();
 }
 
-//
-
-export const fragmentsStates: WeakMap<Fragments, FragmentsState> = new WeakMap();
+// #endregion

package/src/helpers/dom.ts

@@ -2,6 +2,8 @@ import {getString} from '@oscarpalmer/atoms/string';
 import {isChildNode} from '@oscarpalmer/toretto/is';
 import {isFragment} from './index';
 
+// #region Functions
+
 export function createNodes(value: unknown): ChildNode[] {
 	if (isFragment(value)) {
 		return value.get() as ChildNode[];
@@ -33,3 +35,5 @@ export function replaceNodes(from: ChildNode[], to: ChildNode[]): ChildNode[] {
 
 	return to;
 }
+
+// #endregion

package/src/helpers/index.ts

@@ -6,10 +6,11 @@ import {
 	ARRAY_COMPARISON_REMOVED,
 	NAME_FRAGMENT,
 	NAME_FRAGMENTS,
+	SYMBOL,
 } from '../constants';
-import type {Fragment} from '../fragment';
-import type {Fragments} from '../fragments';
-import type {FragmentData} from '../models';
+import type {Fragment, Fragments, FragmentState} from '../models';
+
+// #region Functions
 
 export function compareArrays(
 	first: unknown[],
@@ -31,6 +32,7 @@ export function compareArrays(
 
 /**
  * Is the value a _Fragment_?
+ *
  * @param value Value to check
  * @returns `true` if the value is a _Fragment_, otherwise `false`
  */
@@ -40,6 +42,7 @@ export 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`
  */
@@ -50,14 +53,14 @@ export function isFragments(value: unknown): value is Fragments {
 function isNamed(value: unknown, name: string): boolean {
 	return (
 		typeof value === 'object' &&
-		value != null &&
-		name in value &&
-		(value as PlainObject)[name] === true
+		value !== null &&
+		SYMBOL in value &&
+		(value[SYMBOL] as PlainObject).name === name
 	);
 }
 
 export function setComputedValue(
-	data: FragmentData,
+	data: FragmentState,
 	callback: GenericCallback,
 	after: (computation: Computed<unknown>) => void,
 ): void {
@@ -67,3 +70,5 @@ export function setComputedValue(
 
 	after(computation);
 }
+
+// #endregion

package/src/index.ts

@@ -1,71 +1,7 @@
 import '@oscarpalmer/mora';
-import {isArray, type ReactiveArray} from '@oscarpalmer/mora';
-import {Fragment} from './fragment';
-import {Fragments} from './fragments';
-
-/**
- * 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 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 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);
-}
 
 export * from '@oscarpalmer/mora';
-export type {Fragment} from './fragment';
-export type {Fragments} from './fragments';
+export {fragment, html} from './fragment';
+export {fragments} from './fragments';
 export {isFragment, isFragments} from './helpers';
+export type {Fragment, Fragments} from './models';

package/src/models.ts

@@ -1,5 +1,80 @@
-import type {Reactive, ReactiveArray, Unsubscribe} from '@oscarpalmer/mora';
-import type {Fragment} from './fragment';
+import type {Reactive, ReactiveArray, Subscription} from '@oscarpalmer/mora';
+import type {SYMBOL} from './constants';
+
+// #region Types
+
+export type InternalFragment = {
+	[SYMBOL]: FragmentState;
+} & Fragment;
+
+export type InternalFragments = {
+	[SYMBOL]: FragmentsState;
+} & Fragments;
+
+export type Fragment = {
+	/**
+	 * 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;
+
+	/**
+	 * 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;
+
+	/**
+	 * Insert the _Fragment_ before the given element
+	 *
+	 * @param element Element to insert before
+	 */
+	before(element: Element): void;
+
+	/**
+	 * Configure the _Fragment_
+	 *
+	 * @param configuration Configuration options
+	 * @returns _Fragment_
+	 */
+	configure(configuration: FragmentConfiguration): Fragment;
+
+	/**
+	 * Get a list of the _Fragment_'s nodes
+	 *
+	 * @returns List of nodes
+	 */
+	get(): ChildNode[];
+
+	/**
+	 * Prepend the _Fragment_ to the given element
+	 *
+	 * @param element Element to prepend to
+	 */
+	prependTo(element: Element): void;
+
+	/**
+	 * 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;
+};
 
 /**
  * Configuration for a _Fragment_
@@ -17,19 +92,29 @@ export type FragmentConfiguration = {
 	identifier?: unknown;
 };
 
-export type FragmentData = {
+export type FragmentItem = {
+	fragments?: Fragment[];
+	nodes?: ChildNode[];
+	text?: Text;
+};
+
+export type FragmentState = {
+	cache: boolean;
 	expressions: unknown[];
+	identifier: unknown;
 	items: FragmentItem[];
 	mora: MoraData;
+	name: string;
 	strings: TemplateStringsArray | string[];
 	template?: string;
 	values: unknown[];
 };
 
-export type FragmentItem = {
-	fragments?: Fragment[];
-	nodes?: ChildNode[];
-	text?: Text;
+export type Fragments = {
+	/**
+	 * Remove the _Fragments_ _(and all its descendants)_ from the _DOM_, including any events, reactive values, and Fragments
+	 */
+	remove(): void;
 };
 
 export type FragmentsState = {
@@ -38,10 +123,13 @@ export type FragmentsState = {
 	identify: (item: unknown) => unknown;
 	instances: Record<string, Fragment>;
 	mapped: ReactiveArray<Fragment>;
-	subscriber: Unsubscribe | undefined;
+	name: string;
+	subscription: Subscription | undefined;
 };
 
 type MoraData = {
-	subscribers: Set<() => void>;
+	subscriptions: Set<Subscription>;
 	values: Set<Reactive<unknown>>;
 };
+
+// #endregion

package/src/node/event.ts

@@ -13,6 +13,8 @@ import {
 	EXPRESSION_EVENT_OPTIONS_ONCE,
 } from '../constants';
 
+// #region Functions
+
 function getOptions(options: string): AddEventListenerOptions {
 	const parts = options.split(EVENT_OPTIONS_DELIMITER);
 
@@ -53,3 +55,5 @@ export function mapEvent(element: HTMLElement | SVGElement, name: string, value:
 		}
 	}
 }
+
+// #endregion

package/src/node/index.ts

@@ -1,15 +1,17 @@
 import type {GenericCallback} from '@oscarpalmer/atoms/models';
-import {isReactive, type ReactiveArray} from '@oscarpalmer/mora';
+import {isReactive} 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 {Fragments, fragmentsStates, handleFragments} from '../fragments';
+import {EXPRESSION_ABYDON_CONTENT, EXPRESSION_TEXTAREA_VALUE, SYMBOL} from '../constants';
+import {handleFragments} from '../fragments';
 import {isFragment, isFragments, setComputedValue} from '../helpers';
 import {createNodes} from '../helpers/dom';
-import type {FragmentData} from '../models';
+import type {Fragments, FragmentState, InternalFragments} from '../models';
 import {setReactiveValue} from './value';
 
-function mapNode(data: FragmentData, comment: Comment): void {
+// #region Functions
+
+function mapNode(data: FragmentState, comment: Comment): void {
 	const matches = EXPRESSION_ABYDON_CONTENT.exec(comment.textContent);
 	const value = matches == null ? null : data.values[+matches[1]];
 
@@ -18,7 +20,7 @@ function mapNode(data: FragmentData, comment: Comment): void {
 	}
 }
 
-export function mapNodes(data: FragmentData, nodes: ChildNode[]): void {
+export function mapNodes(data: FragmentState, nodes: ChildNode[]): void {
 	const {length} = nodes;
 
 	for (let index = 0; index < length; index += 1) {
@@ -49,7 +51,7 @@ export function mapNodes(data: FragmentData, nodes: ChildNode[]): void {
 	}
 }
 
-function mapTextarea(data: FragmentData, element: HTMLTextAreaElement): boolean {
+function mapTextarea(data: FragmentState, element: HTMLTextAreaElement): boolean {
 	const [, index] =
 		EXPRESSION_TEXTAREA_VALUE.exec(element.textContent) ??
 		EXPRESSION_TEXTAREA_VALUE.exec(element.value) ??
@@ -67,7 +69,7 @@ function mapTextarea(data: FragmentData, element: HTMLTextAreaElement): boolean
 	return true;
 }
 
-function mapValue(data: FragmentData, comment: Comment, value: unknown): void {
+function mapValue(data: FragmentState, comment: Comment, value: unknown): void {
 	switch (true) {
 		case typeof value === 'function':
 			setComputedNode(data, comment, value as GenericCallback);
@@ -87,7 +89,7 @@ function mapValue(data: FragmentData, comment: Comment, value: unknown): void {
 	}
 }
 
-function replaceComment(data: FragmentData, comment: Comment, value: unknown): void {
+function replaceComment(data: FragmentState, comment: Comment, value: unknown): void {
 	const item = data.items.find(item => item.nodes?.includes(comment));
 	const nodes = createNodes(value);
 
@@ -99,16 +101,16 @@ function replaceComment(data: FragmentData, comment: Comment, value: unknown): v
 	comment.replaceWith(...nodes);
 }
 
-function setComputedNode(data: FragmentData, comment: Comment, callback: GenericCallback): void {
+function setComputedNode(data: FragmentState, 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)!;
-
-	handleFragments(state, false);
+function setFragmentsNode(data: FragmentState, comment: Comment, fragments: Fragments): void {
+	handleFragments(fragments, false);
 
-	setReactiveValue(data, comment, state.mapped as ReactiveArray<unknown>);
+	setReactiveValue(data, comment, (fragments as InternalFragments)[SYMBOL].mapped);
 }
+
+// #endregion

package/src/node/value.ts

@@ -3,12 +3,11 @@ import {getString} from '@oscarpalmer/atoms/string';
 import type {Reactive} from '@oscarpalmer/mora';
 import {isChildNode} from '@oscarpalmer/toretto/is';
 import {ARRAY_COMPARISON_ADDED, ARRAY_COMPARISON_REMOVED} from '../constants';
-import type {Fragment} from '../fragment';
 import {compareArrays, isFragment} from '../helpers';
 import {createNodes, replaceNodes} from '../helpers/dom';
-import type {FragmentData, FragmentItem} from '../models';
+import type {Fragment, FragmentItem, FragmentState} from '../models';
 
-//
+// #region Types
 
 type ArrayData = {
 	next: ArrayDataIdentifiers;
@@ -45,7 +44,9 @@ type ExtendedItems = {
 	next: Fragment[];
 } & BaseItems;
 
-//
+// #endregion
+
+// #region Functions
 
 function addToArray(
 	identifiers: Identifiers,
@@ -183,6 +184,7 @@ function setArray(item: FragmentItem, comment: Comment, value: unknown[]): Parti
 	if (
 		template.empty ||
 		item.nodes == null ||
+		item.fragments == null ||
 		previous.array.some(identifier => identifier == null)
 	) {
 		const fragments = (item.fragments ?? []).slice();
@@ -208,7 +210,7 @@ function setArray(item: FragmentItem, comment: Comment, value: unknown[]): Parti
 			previous,
 		},
 		{
-			fragments: item.fragments ?? [],
+			fragments: item.fragments,
 			templates: template.items,
 		},
 		item.nodes,
@@ -220,7 +222,7 @@ function setNodes(item: FragmentItem, comment: Comment, next: ChildNode[]): Chil
 }
 
 export function setReactiveValue(
-	data: FragmentData,
+	data: FragmentState,
 	comment: Comment,
 	reactive: Reactive<unknown>,
 ): void {
@@ -228,7 +230,7 @@ export function setReactiveValue(
 
 	item ??= {};
 
-	data.mora.subscribers.add(
+	data.mora.subscriptions.add(
 		reactive.subscribe(value => {
 			if (Array.isArray(value)) {
 				setReactiveValueForArray(item, comment, value);
@@ -271,7 +273,7 @@ function setText(item: FragmentItem, comment: Comment, value?: unknown): ChildNo
 
 	const result = valueIsNullable ? [comment] : [item.text];
 
-	replaceNodes(item.nodes ?? [comment], result);
-
-	return result;
+	return replaceNodes(item.nodes ?? [comment], result);
 }
+
+// #endregion

package/src/parse.ts

@@ -4,9 +4,11 @@ import {
 	EXPRESSION_EVENT_ATTRIBUTE,
 	WHITESPACE,
 } from './constants';
-import type {FragmentData} from './models';
+import type {FragmentState} from './models';
 
-function handleExpression(data: FragmentData, prefix: string, expression: unknown): string {
+// #region Functions
+
+function handleExpression(data: FragmentState, prefix: string, expression: unknown): string {
 	if (Array.isArray(expression)) {
 		if (EXPRESSION_EVENT_ATTRIBUTE.test(prefix.split(WHITESPACE).at(-1)!)) {
 			return transformExpression(prefix, data.values.push(expression) - 1);
@@ -32,7 +34,7 @@ function handleExpression(data: FragmentData, prefix: string, expression: unknow
 	return asString.trim().length === 0 ? prefix : `${prefix}${asString}`;
 }
 
-export function parse(data: FragmentData): string {
+export function parse(data: FragmentState): string {
 	if (data.template != null) {
 		return data.template;
 	}
@@ -60,3 +62,5 @@ function transformAttribute(_: string, name: string, index: string): string {
 function transformExpression(prefix: string, index: number): string {
 	return `${prefix}<!--abydon.${index}-->`;
 }
+
+// #endregion