@oscarpalmer/abydon 0.23.1 → 0.24.0

package/src/attribute/index.ts

@@ -9,23 +9,25 @@ import {
 	PROPERTY_VALUE,
 } from '../constants';
 import {setComputedValue} from '../helpers';
-import type {FragmentData} from '../models';
+import type {FragmentState} from '../models';
 import {mapEvent} from '../node/event';
 import {setAttribute} from './value';
 import {isNullableOrWhitespace} from '@oscarpalmer/atoms/is';
 
+// #region Functions
+
 function compareAttributes(first: Attr, second: Attr): number {
 	return first.name.localeCompare(second.name);
 }
 
-function getValue(data: FragmentData, original: string): unknown {
+function getValue(data: FragmentState, original: string): unknown {
 	const matches = EXPRESSION_ABYDON_CONTENT.exec(original);
 
 	return matches == null ? original : data.values[+matches[1]];
 }
 
 export function mapAttributeValue(
-	data: FragmentData,
+	data: FragmentState,
 	element: HTMLElement | SVGElement,
 	name: string,
 	value: unknown,
@@ -44,7 +46,7 @@ export function mapAttributeValue(
 }
 
 export function mapAttributes(
-	data: FragmentData,
+	data: FragmentState,
 	element: HTMLElement | SVGElement,
 	ignoreValue: boolean,
 ): void {
@@ -80,7 +82,7 @@ export function mapAttributes(
 }
 
 function setComputedAttribute(
-	data: FragmentData,
+	data: FragmentState,
 	element: HTMLElement | SVGElement,
 	name: string,
 	callback: GenericCallback,
@@ -89,3 +91,5 @@ function setComputedAttribute(
 		setAttribute(data, element, name, computation);
 	});
 }
+
+// #endregion

package/src/attribute/value.ts

@@ -12,7 +12,9 @@ import {
 	EXPRESSION_ATTRIBUTE_STYLE_VARIABLE,
 	VALUE_TRUE,
 } from '../constants';
-import type {FragmentData} from '../models';
+import type {FragmentState} from '../models';
+
+// #region Functions
 
 function getStyleValue(value: unknown, unit: string, isVariable: boolean): string | undefined {
 	if (removeStyleValue(value, unit, isVariable)) {
@@ -31,7 +33,7 @@ function removeStyleValue(value: unknown, unit: unknown, isVariable: boolean): b
 }
 
 export function setAttribute(
-	data: FragmentData,
+	data: FragmentState,
 	element: HTMLElement | SVGElement,
 	name: string,
 	value: unknown,
@@ -52,7 +54,7 @@ export function setAttribute(
 }
 
 function setClassValues(
-	data: FragmentData,
+	data: FragmentState,
 	element: HTMLElement | SVGElement,
 	name: string,
 	value: unknown,
@@ -69,7 +71,7 @@ function setClassValues(
 }
 
 function setStyleValues(
-	data: FragmentData,
+	data: FragmentState,
 	element: HTMLElement | SVGElement,
 	name: string,
 	value: unknown,
@@ -88,7 +90,7 @@ function setStyleValues(
 }
 
 function setValue(
-	data: FragmentData,
+	data: FragmentState,
 	element: HTMLElement | SVGElement,
 	name: string,
 	value: unknown,
@@ -98,10 +100,12 @@ function setValue(
 	});
 }
 
-function updateValue(data: FragmentData, value: unknown, updater: (value: unknown) => void): void {
+function updateValue(data: FragmentState, value: unknown, updater: (value: unknown) => void): void {
 	if (isReactive(value)) {
-		data.mora.subscribers.add(value.subscribe(updater));
+		data.mora.subscriptions.add(value.subscribe(updater));
 	} else {
 		updater(value);
 	}
 }
+
+// #endregion

package/src/constants.ts

@@ -1,3 +1,5 @@
+// #region Variables
+
 export const ARRAY_COMPARISON_ADDED = 'added';
 
 export const ARRAY_COMPARISON_DISSIMILAR = 'dissimilar';
@@ -10,12 +12,6 @@ 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: '<>'";
-
-export const ERROR_IDENTIFIER_TYPE = 'Identifier cannot be null or undefined';
-
 export const EVENT_CHANGE = 'change';
 
 export const EVENT_INPUT = 'input';
@@ -63,16 +59,36 @@ export const EXPRESSION_EVENT_PREFIX = /^@/;
 
 export const EXPRESSION_TEXTAREA_VALUE = /(?:<|&lt;)!--abydon\.(\d+)--(?:>|&gt;)/;
 
-export const NAME_FRAGMENT = '$fragment';
+export const MESSAGE_FRAGMENT_VALUE =
+	'Fragment template must be a string or a template strings array';
+
+export const MESSAGE_FRAGMENTS_FRAGMENT_RESULT =
+	'Fragment function must return a Fragment instance';
+
+export const MESSAGE_FRAGMENTS_FRAGMENT_TYPE = 'Fragment handler must be a function';
+
+export const MESSAGE_FRAGMENTS_IDENTIFIER_RESULT_DUPLICATE = "Duplicate identifier found: '<>'";
 
-export const NAME_FRAGMENTS = '$fragments';
+export const MESSAGE_FRAGMENTS_IDENTIFIER_RESULT_TYPE = 'Identifier cannot be null or undefined';
+
+export const MESSAGE_FRAGMENTS_IDENTIFIER_TYPE = 'Identifier handler must be a function';
+
+export const MESSAGE_FRAGMENTS_VALUE = 'Fragments array must be a reactive array';
+
+export const NAME_FRAGMENT = 'fragment';
+
+export const NAME_FRAGMENTS = 'fragments';
 
 export const PROPERTY_IDENTIFIER = 'identifier';
 
 export const PROPERTY_VALUE = 'value';
 
+export const SYMBOL = Symbol('abydon');
+
 export const TEMPLATE_ITEM = '<>';
 
 export const VALUE_TRUE = 'true';
 
 export const WHITESPACE = /\s+/g;
+
+// #endregion

package/src/fragment.ts

@@ -1,158 +1,174 @@
-import {isPlainObject} from '@oscarpalmer/atoms/is';
+import {isNonTemplateStringsArray, isPlainObject} from '@oscarpalmer/atoms/is';
 import {html} from '@oscarpalmer/toretto/html';
-import {NAME_FRAGMENT, PROPERTY_IDENTIFIER} from './constants';
+import {MESSAGE_FRAGMENT_VALUE, NAME_FRAGMENT, PROPERTY_IDENTIFIER, SYMBOL} from './constants';
 import {handleFragments} from './fragments';
 import {isFragments} from './helpers';
 import {removeNodes} from './helpers/dom';
-import type {FragmentConfiguration, FragmentData} from './models';
+import type {Fragment, FragmentConfiguration, FragmentState, InternalFragment} from './models';
 import {mapNodes} from './node';
 import {parse} from './parse';
 
-export class Fragment {
-	readonly #data: FragmentData;
+// #region Instances
 
-	readonly #configuration: Required<FragmentConfiguration> = {
-		identifier: undefined,
+function Fragment(this: any, strings: TemplateStringsArray, expressions: unknown[]) {
+	this[SYMBOL] = {
+		expressions,
+		strings,
 		cache: true,
+		identifier: undefined,
+		items: [],
+		mora: {
+			subscriptions: new Set(),
+			values: new Set(),
+		},
+		name: NAME_FRAGMENT,
+		values: [],
 	};
+}
 
-	/**
-	 * Is template caching enabled?
-	 */
-	get cache(): boolean {
-		return this.#configuration.cache;
-	}
+Fragment.prototype.after = insertFragmentAfter;
+Fragment.prototype.appendTo = appendFragmentTo;
+Fragment.prototype.before = insertFragmentBefore;
+Fragment.prototype.configure = configureFragment;
+Fragment.prototype.get = getFragmentNodes;
+Fragment.prototype.prependTo = prependFragmentTo;
+Fragment.prototype.remove = removeFragment;
+
+Object.defineProperties(Fragment.prototype, {
+	cache: {
+		enumerable: true,
+		get: getFragmentCache,
+	},
+	identifier: {
+		enumerable: true,
+		get: getFragmentIdentifier,
+	},
+});
+
+// #endregion
+
+// #region Functions
+
+function appendFragmentTo(this: InternalFragment, element: Element): void {
+	element.append(...this.get());
+}
 
-	/**
-	 * 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;
-	}
+function configureFragment(
+	this: InternalFragment,
+	configuration: FragmentConfiguration,
+): InternalFragment {
+	const state = this[SYMBOL];
 
-	constructor(strings: TemplateStringsArray, expressions: unknown[]) {
-		Object.defineProperty(this, NAME_FRAGMENT, {
-			value: true,
-		});
+	const actual = isPlainObject(configuration) ? configuration : {};
 
-		this.#data = {
-			expressions,
-			strings,
-			items: [],
-			mora: {
-				subscribers: new Set(),
-				values: new Set(),
-			},
-			values: [],
-		};
+	if (PROPERTY_IDENTIFIER in actual) {
+		state.identifier = actual.identifier;
 	}
 
-	/**
-	 * Insert the _Fragment_ after the given element
-	 * @param element Element to insert after
-	 */
-	after(element: Element): void {
-		element.after(...this.get());
+	if (typeof actual.cache === 'boolean') {
+		state.cache = actual.cache;
 	}
 
-	/**
-	 * Append the _Fragment_ to the given element
-	 * @param element Element to append to
-	 */
-	appendTo(element: Element): void {
-		element.append(...this.get());
-	}
+	return this;
+}
 
-	/**
-	 * Insert the _Fragment_ before the given element
-	 * @param element Element to insert before
-	 */
-	before(element: Element): void {
-		element.before(...this.get());
+/**
+ * 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 = fragment`<p>Hello, ${name}!</p>`; // or `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 fragment(template: TemplateStringsArray, ...values: unknown[]): Fragment;
+
+/**
+ * Create a _Fragment_ from a simple template
+ *
+ * @example
+ * ```ts
+ * const fragment = fragment('<p>Hello, World!</p>'); // or `html`('<p>Hello, World!</p>')
+ * fragment.appendTo(document.body);                  // Renders '<p>Hello, World!</p>'
+ * ```
+ *
+ * @returns _Fragment_
+ */
+export function fragment(template: string): Fragment;
+
+export function fragment(template: string | TemplateStringsArray, ...values: unknown[]): Fragment {
+	if (typeof template !== 'string' && isNonTemplateStringsArray(template)) {
+		throw new TypeError(MESSAGE_FRAGMENT_VALUE);
 	}
 
-	/**
-	 * Configure the _Fragment_
-	 *
-	 * _Returns the Fragment instance for chaining_
-	 * @param configuration Configuration options
-	 * @returns _Fragment_
-	 */
-	configure(configuration: FragmentConfiguration): Fragment {
-		const actual = isPlainObject(configuration) ? configuration : {};
-
-		if (PROPERTY_IDENTIFIER in actual) {
-			this.#configuration.identifier = actual.identifier;
-		}
+	// @ts-expect-error All good, no worries :-)
+	return new Fragment(template, values);
+}
 
-		if (typeof actual.cache === 'boolean') {
-			this.#configuration.cache = actual.cache;
-		}
+function getFragmentCache(this: InternalFragment): boolean {
+	return this[SYMBOL].cache;
+}
 
-		return this;
-	}
+function getFragmentIdentifier(this: InternalFragment): unknown {
+	return this[SYMBOL].identifier;
+}
 
-	/**
-	 * Get a list of the _Fragment_'s nodes
-	 * @returns List of nodes
-	 */
-	get(): ChildNode[] {
-		const data = this.#data;
-
-		if (data.items.length === 0) {
-			const parsed = parse(data);
-
-			const templated = html(parsed, {
-				cache: this.#configuration.cache,
-			});
-
-			data.items.splice(
-				0,
-				data.items.length,
-				...templated.map(node => ({
-					nodes: [node as ChildNode],
-				})),
-			);
-
-			mapNodes(
-				data,
-				data.items.flatMap(item => item.nodes!),
-			);
-		}
+function getFragmentNodes(this: InternalFragment): ChildNode[] {
+	const state = this[SYMBOL];
+
+	if (state.items.length === 0) {
+		const parsed = parse(state);
 
-		return data.items.flatMap(
-			item => item.fragments?.flatMap(fragment => fragment.get()) ?? item.nodes!,
+		const templated = html(parsed, {
+			cache: state.cache,
+		});
+
+		state.items.splice(
+			0,
+			state.items.length,
+			...templated.map(node => ({
+				nodes: [node as ChildNode],
+			})),
 		);
-	}
 
-	/**
-	 * Prepend the _Fragment_ to the given element
-	 * @param element Element to prepend to
-	 */
-	prependTo(element: Element): void {
-		element.prepend(...this.get());
+		mapNodes(
+			state,
+			state.items.flatMap(item => item.nodes!),
+		);
 	}
 
-	/**
-	 * 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);
-	}
+	return state.items.flatMap(
+		item => item.fragments?.flatMap(fragment => fragment.get()) ?? item.nodes!,
+	);
+}
+
+function insertFragmentAfter(this: InternalFragment, element: Element): void {
+	element.after(...this.get());
+}
+
+function insertFragmentBefore(this: InternalFragment, element: Element): void {
+	element.before(...this.get());
+}
+
+function prependFragmentTo(this: InternalFragment, element: Element): void {
+	element.prepend(...this.get());
 }
 
-function removeFragment(data: FragmentData): void {
-	removeMora(data);
+function removeFragment(this: InternalFragment): void {
+	const state = this[SYMBOL];
+
+	removeMora(state);
 
-	let {length} = data.items;
+	let {length} = state.items;
 
 	for (let index = 0; index < length; index += 1) {
-		const {fragments, nodes} = data.items[index];
+		const {fragments, nodes} = state.items[index];
 		const fragmentsLength = fragments?.length ?? 0;
 
 		for (let fragmentIndex = 0; fragmentIndex < fragmentsLength; fragmentIndex += 1) {
@@ -162,12 +178,12 @@ function removeFragment(data: FragmentData): void {
 		removeNodes(nodes!);
 	}
 
-	data.items.length = 0;
+	state.items.length = 0;
 
-	length = data.values.length;
+	length = state.values.length;
 
 	for (let index = 0; index < length; index += 1) {
-		const value = data.values[index];
+		const value = state.values[index];
 
 		if (isFragments(value)) {
 			handleFragments(value, true);
@@ -175,13 +191,21 @@ function removeFragment(data: FragmentData): void {
 	}
 }
 
-function removeMora(data: FragmentData): void {
-	const unsubscribers = [...data.mora.subscribers];
+function removeMora(state: FragmentState): void {
+	const subscriptions = [...state.mora.subscriptions];
 
-	data.mora.subscribers.clear();
-	data.mora.values.clear();
+	state.mora.subscriptions.clear();
+	state.mora.values.clear();
 
-	for (const unsubscribe of unsubscribers) {
-		unsubscribe();
+	for (const subscription of subscriptions) {
+		subscription.unsubscribe();
 	}
 }
+
+// #endregion
+
+// #region Exports
+
+export {fragment as html};
+
+// #endregion