@rusticarcade/palette 0.4.0 → 0.7.0

package/dist/test/index.d.ts

@@ -13,29 +13,15 @@ type StateListener<Shape> = (state: Shape) => void;
 *
 * The State class wraps stateful data and provides an API for mutating the data
 * while listeners subscribe to meaningful updates.
-*
-* Modify state with setters, mutators, transactions, or proxied updates with
-* deep reactivity and array mutation support built in.
-*
-* @example
-*
-* ```typescript
-* const state = new State({count: 1});
-* state.addListener(data => console.log(data))
-*
-* state.set("count", 2); // Prints "2"
-* state.set("count", 2); // Nothing happens, no change
-* state.live.count = 3; // Prints "3"
-* ```
 */
 declare class State<Shape extends object> {
+	static isState<T extends object>(value: unknown): value is State<T>;
 	private _data;
 	private _listeners;
 	private _proxy?;
 	private _proxyCache;
 	private _reverseProxyCache;
-	private _isLocked;
-	constructor(initialData: Shape, onChange?: StateListener<Shape>);
+	constructor(initialData: Shape, listener?: StateListener<Shape>);
 	/**
 	* Lazily create and cache proxies into the state for reactive updates on
 	* nested values.
@@ -65,7 +51,7 @@ declare class State<Shape extends object> {
 	* This is a direct reference to the internal state. It is marked as Readonly
 	* to help prevent accidental changes. Never edit this value directly.
 	*/
-	get current(): Readonly<Shape>;
+	get raw(): Readonly<Shape>;
 	/**
 	* Live reactive accessor for state data. Deeply nested changes trigger
 	* automatic updates, including array, Map, and Set mutations.
@@ -76,10 +62,6 @@ declare class State<Shape extends object> {
 	*/
 	get live(): Shape;
 	/**
-	* Indicates if this state is currently locked (true) or not (false)
-	*/
-	get isLocked(): boolean;
-	/**
 	* Add a handler function for when this state changes.
 	*
 	* Listeners are invoked in the order they are registered and are passed a
@@ -98,14 +80,6 @@ declare class State<Shape extends object> {
 	*
 	* The value is returned as Readonly to prevent accidental state mutations.
 	* To mutate stateful properties, use {@link set} or {@link patch} instead.
-	*
-	* @example
-	*
-	* ```typescript
-	* const state = new State({ count: 1 });
-	* console.log(state.get("count")); // 1
-	* ```
-	*
 	*/
 	get: <K extends keyof Shape>(key: K) => Readonly<Shape[K]>;
 	/**
@@ -114,13 +88,6 @@ declare class State<Shape extends object> {
 	*
 	* The object returned from this function can be edited without modifying the
 	* actual internal state.
-	*
-	* @example
-	*
-	* ```typescript
-	* const snap = state.snapshot();
-	* snap.count += 1;
-	* state.patch(snap);
 	* ```
 	*/
 	snapshot: () => Shape;
@@ -137,44 +104,17 @@ declare class State<Shape extends object> {
 	* state.set("count", 2); // State is now { count: 2, color: "red" }
 	* ```
 	*/
-	set: <K extends keyof Shape>(key: K, value: Shape[K]) => void;
+	set: <K extends keyof Shape>(key: K, value: Shape[K]) => State<Shape>;
 	/**
 	* Set multiple stateful properties at once, leaving omitted properties
 	* unchanged.
-	*
-	* @example
-	*
-	* Patch a partial state, updating all listed properties at once
-	*
-	* ```typescript
-	* const state = new State({
-	*   weather: "sunny",
-	*   temperature: 30,
-	*   humidity: 70,
-	* });
-	*
-	* // Leaves `temperature` unchanged
-	* state.patch({
-	*   weather: "cloudy",
-	*   humidity: 50,
-	* });
-	* ```
 	*/
 	patch: (patch: Partial<Shape>) => State<Shape>;
 	/**
-	* Fully replace the current state data and force listeners to receive the
-	* updated data immediately.
+	* Fully replace the current state data and force an update
 	*/
 	replace: (state: Shape) => State<Shape>;
 	/**
-	* Lock this State instance, preventing further external changes
-	*/
-	lock: () => State<Shape>;
-	/**
-	* Unlock this State instance, allowing further external changes
-	*/
-	unlock: () => State<Shape>;
-	/**
 	* Apply complex updates to the state using a mutator function.
 	*
 	* The mutator function takes one parameter which is a structuredClone copy of
@@ -182,87 +122,6 @@ declare class State<Shape extends object> {
 	* patched in to the state.
 	*/
 	mutate: (mutator: (current: Shape) => Shape) => State<Shape>;
-	/**
-	* Perform an async mutation of the state, optionally locking the state during
-	* the process.
-	* @param mutator A function to mutate and return the new state
-	* @param lock If `true`, lock the state until the mutator completes
-	*/
-	mutateAsync: (mutator: (current: Shape) => Promise<Shape>, lock?: boolean) => Promise<State<Shape>>;
-	/**
-	* Perform a transaction-style set of actions defined within a function.
-	*
-	* The provided function can do anything, beyond just setting state. Any
-	* uncaught errors thrown from within the function will cause the transaction
-	* to fail and the state to automatically roll back to the last valid state.
-	*
-	* During a transaction, this state instance will be locked, preventing other
-	* changes.
-	*
-	* Transactions will always result in a state update when successful.
-	*
-	* @example
-	*
-	* Transactions with locking and rollback support
-	*
-	* ```typescript
-	* const state = new State({count: 1});
-	*
-	* state.transaction(async (s) => {
-	*   // `s` is a full State object you can safely manipulate
-	*   s.set("count", 10);
-	* });
-	* state.get("count"); // => 10;
-	*
-	* // Errors inside the transaction roll back the state
-	* state.transaction(async (s) => {
-	*   s.set("count", 100);
-	*   throw new Error();
-	* });
-	* state.get("count"); // => 10;
-	*/
-	transaction: (fn: (state: State<Shape>) => void) => boolean;
-	/**
-	* Perform a transaction-style set of actions defined within an async function
-	*
-	* The provided function can do anything, beyond just setting state. Any
-	* uncaught errors thrown from within the function will cause the transaction
-	* to fail and the state to automatically roll back to the last valid state.
-	*
-	* During a transaction, this state instance will be locked, preventing other
-	* changes.
-	*
-	* Transactions will always result in a state update when successful.
-	*
-	* @example
-	*
-	* Transactions with locking and rollback support
-	*
-	* ```typescript
-	* const state = new State({count: 1});
-	*
-	* // Awaiting the result of a transaction
-	* await state.transactionAsync(async (s) => {
-	*   // `s` is a full State object you can safely manipulate
-	*   s.set("count", 10);
-	* });
-	* state.get("count"); // => 10;
-	*
-	* // Errors inside the transaction roll back the state
-	* await state.transactionAsync(async (s) => {
-	*   s.set("count", 100);
-	*   throw new Error();
-	* });
-	* state.get("count"); // => 10;
-	*
-	* // If you forget to await the transaction, its still locked
-	* state.transactionAsync(async (s) => {
-	*   await waitSeconds(1);
-	* });
-	* state.set("count", 1); // Error: State is locked!
-	* ```
-	*/
-	transactionAsync: (fn: (state: State<Shape>) => Promise<void>) => Promise<boolean>;
 }
 type ParsedNotation = {
 	/** The raw string representation of the parsed notation */
@@ -283,6 +142,13 @@ declare const enum Directive {
 	ElseIf = "::else-if",
 	Else = "::else"
 }
+declare const enum UpdateType {
+	Conditional = "cond",
+	Tag = "tag",
+	Attribute = "attr",
+	List = "list",
+	Swap = "swap"
+}
 type ConditionalRenderSchemeBranch = {
 	type: Directive.If | Directive.ElseIf;
 	notation: ParsedNotation;
@@ -294,27 +160,27 @@ type ConditionalRenderSchemeBranch = {
 	branchTemplateHTML: string;
 };
 interface ConditionalRenderScheme {
-	type: "cond";
+	type: UpdateType.Conditional;
 	branches: ConditionalRenderSchemeBranch[];
 }
 interface AttributeUpdateScheme {
-	type: "attr";
+	type: UpdateType.Attribute;
 	notation: ParsedNotation;
 	attribute: string;
 	nodeRef: string;
 }
 interface TagChangeScheme {
-	type: "tag";
+	type: UpdateType.Tag;
 	notation: ParsedNotation;
 	nodeRef: string;
 }
 interface ContentSwapScheme {
-	type: "swap";
+	type: UpdateType.Swap;
 	notation: ParsedNotation;
 	nodeRef: string;
 }
 interface ListRenderScheme {
-	type: "each";
+	type: UpdateType.List;
 	notation: ParsedNotation;
 	keyNotation: ParsedNotation;
 	nodeRef: string;
@@ -344,20 +210,33 @@ type TemplateContext = {
 * Leverages a simple syntax to provide accessors to template data from one of
 * four categories, based on use case:
 *
-* ```
-* `@` -> The `attr` namespace (the host element's attributes)
-* `$` -> The `state` namespace (the host element's reactive state)
-* `*` -> The `data` namespace (the host element's computed data)
-* `#` -> The `item` namespace (list item access with ::each)
-* ```
+* | Prefix | Namespace                                        |
+* | ------ | ------------------------------------------------ |
+* | `@`    | The `attr` namespace (host element attributes)   |
+* | `$`    | The `state` namespace (component reactive state) |
+* | `*`    | The `data` namespace (component computed props)  |
+* | `#`    | The `item` namespace (list item context)         |
 *
 * Bind attributes to a value using the `:attribute` syntax:
 *
 * ```html
 * <div :id="$id" :class="@classname"></div>
 * ```
+*
+* Or use directives with notations for advanced templating:
+*
+* ```html
+* <div ::if="*showList">
+*   <ul>
+*     <li ::each="$items" ::key="#id">
+*       <span ::swap="#content"></span>
+*     </li>
+*   </ul>
+* </div>
+* ```
 */
 declare class Template {
+	static isTemplate(value: unknown): value is Template;
 	/**
 	* Properties related to the global Template build cache.
 	*
@@ -426,16 +305,6 @@ declare class Template {
 }
 type EventName = keyof GlobalEventHandlersEventMap;
 type EventHandler<K extends EventName = EventName> = (event: GlobalEventHandlersEventMap[K]) => void;
-interface LiveAttributes<State extends object = {}> {
-	[name: string]: {
-		onChange?: (this: Component<State>, current: string | null, previous: string | null) => void;
-		reflect?: (this: Component<State>) => unknown;
-	};
-}
-type ComputedProperties<StateShape extends object = {}> = Record<string, unknown> | ((this: Component<StateShape>) => Record<string, unknown>);
-type ComponentStyles = CSSStyleSheet | CSSStyleSheet[] | string;
-type AttributeMap = Map<string, string | null>;
-type StateInitializer<Shape extends object = {}> = Shape | State<Shape> | ((this: Component<Shape>) => Shape | State<Shape>);
 declare enum RootMode {
 	Closed = "closed",
 	Open = "open"
@@ -446,133 +315,57 @@ declare enum RootMode {
 * managed attributes, and dynamic templating.
 */
 declare abstract class Component<StateShape extends object = {}> extends HTMLElement {
-	/** The HTML tag name to use for this Component */
-	static tagName: string;
-	/** An HTML Template element for this element to use. */
-	static template: HTMLTemplateElement | Template;
 	/**
-	* Styles for this Component
+	* Check if a value is a Component instance
 	*/
-	static styles: ComponentStyles;
+	static isComponent(value: unknown): value is Component;
 	/**
-	* A list of attribute names to track changes for
-	*
-	* @remarks
-	* If you use the {@link define} factory helper, this value will be
-	* automatically merged with a list of any defined {@link liveAttributes}.
+	* Check if a value is a Component class
 	*/
+	static isComponentClass(value: unknown): value is typeof Component;
+	static readComponentTagName(componentClass: typeof Component): string;
+	/** The HTML tag name to use for this Component */
+	static tagName: string;
+	/** An HTML Template element for this element to use. */
+	static template: HTMLTemplateElement | Template;
+	/** Styles to encapsulate to this component's root. */
+	static style: CSSStyleSheet | CSSStyleSheet[] | string;
+	/** Attributes to watch for changes for updates. */
 	static observedAttributes: string[];
 	/**
-	* The mode for this Component's ShadowRoot. Must be a {@link RootMode}
+	* The mode for this Component's ShadowRoot.
+	*
+	* MDN: https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/mode
 	*/
 	static rootMode: RootMode;
-	/**
-	* Initialization lifecycle method. Main scripting and event listeners.
-	* @returns a function to handle cleanup tasks when the component unmounts
-	*/
-	protected script?(): VoidFunction | void;
 	/** Called immediately before each template update */
-	protected beforeUpdate?(): void;
+	beforeUpdate?(changedAttributes: Record<string, string | null>): void;
 	/** Called immediately after each template update */
-	protected afterUpdate?(previousAttributes: AttributeMap): void;
+	afterUpdate?(previousAttributes: Record<string, string | null>): void;
 	/** Final lifecycle method called at the end of the unmounting process. */
-	protected finalize?(): void;
+	finalize?(): void;
 	/**
-	* When defined, catches any errors thrown during lifecycle mthods of this
-	* component as well as any uncaught errors from child components.
-	*
-	* @example
-	*
-	* Recovering from errors or displaying a fallback
-	*
-	* ```typescript
-	* onError(error) {
-	*   if (error.canRecover) {
-	*     this.recover();
-	*     return;
-	*   }
-	*
-	*   this.replaceWith("Oh dear, an error happened real bad");
-	* }
-	* ```
+	* Handle errors thrown during lifecycle methods of this component or any
+	* unhandled errors from child components.
 	*/
-	protected onError?(error: unknown): void;
-	/**
-	* The initial value for this Component's reactive internal state, if any.
-	*
-	* @remarks
-	* If `initialState` is defined as a function, the function is evaluated at
-	* mounting time and the return value is used as the initial state.
-	*/
-	protected initialState?: StateInitializer<StateShape>;
+	onError?(error: unknown): void;
+	/** The initial state for this Component */
+	initialState?(): State<StateShape> | StateShape;
 	/**
 	* An object or function returning an object which populates the `data` values
 	* in the templating engine. Such values are accessed using the `*` notation.
-	*
-	* @example
-	*
-	* ```typescript
-	* host = {
-	*   avatarUrl: "http://...",
-	*   renderTime: () => new Date().toISOString(),
-	* }
-	* ```
-	*
-	* ```html
-	* <img :src="*avatarUrl" />
-	* <span>Rendered at ${"*renderTime"}</span>
-	* ```
 	*/
-	protected computedProperties?: ComputedProperties<StateShape>;
-	/**
-	* Define attribute update and reflection behaviors as a record of attribute
-	* name keys to objects with optionally defined behaviors.
-	*
-	* @example
-	*
-	* ```typescript
-	* liveAttributes = {
-	*   done: {
-	*     onChange(newValue) {
-	*       this.state.set("done", !!newValue);
-	*     },
-	*     reflect() { return this.state.current.done }
-	*   }
-	* };
-	* ```
-	*
-	* @remarks
-	* The optional functions are:
-	*
-	* `onChange(newValue, oldValue): void`, a handler function for when the value
-	* of this attribute has changed. Runs once per update cycle, *before* the
-	* update occurs.
-	*
-	* `reflect(): unknown`, a function which returns a value to serialize and set
-	* as this attribute *after* an update completes.
-	*
-	* If using the {@link define} helper, the keys of this property are
-	* automatically merged with any defined {@link observedAttributes}.
-	*/
-	protected liveAttributes?: LiveAttributes<StateShape>;
-	private _template;
-	private _root;
-	private _state?;
-	private _delegator?;
-	private _ownListeners?;
-	private _cleanupFn?;
-	private _renderInternals;
+	computedProperties?(this: Component<StateShape>, attributes: Record<string, string | null>, state: StateShape): Record<string, unknown>;
+	readonly root: ShadowRoot;
+	readonly template: Template;
+	private _cmp;
 	constructor();
 	/** Produce the data object to pass to the template's render function */
 	private _getRenderContext;
 	private _escalateError;
 	private _reportError;
-	private _executeAttributeChangeHandlers;
-	private _reflectLiveAttributes;
 	/** The actual update behavior */
-	private _performUpdate;
-	/** Safely request for an update to run on the next frame */
-	private _scheduleUpdate;
+	private _render;
 	private _adoptState;
 	/**
 	* @deprecated Use {@link script} instead
@@ -583,14 +376,18 @@ declare abstract class Component<StateShape extends object = {}> extends HTMLEle
 	*/
 	protected disconnectedCallback(): void;
 	/**
-	* @deprecated Use {@link liveAttributes} instead
+	* @deprecated Use {@link beforeUpdate} and {@link afterUpdate} instead
 	*/
 	protected attributeChangedCallback(name: string, _: string | null, newValue: string | null): void;
+	get isMounted(): boolean;
 	/**
-	* The ShadowRoot node of this element
+	* Access the full {@link State} instance for this Component.
+	*
+	* @remarks
+	* Calling this method on a component which is not using reactive state
+	* will result in an error being thrown.
 	*/
-	get root(): ShadowRoot;
-	get isMounted(): boolean;
+	getState(): State<StateShape>;
 	/**
 	* Accessor for live reactive state.
 	*
@@ -603,71 +400,85 @@ declare abstract class Component<StateShape extends object = {}> extends HTMLEle
 	*/
 	set state(newState: StateShape | State<StateShape>);
 	/**
-	* Access the full {@link State} instance for this Component.
-	*
-	* @remarks
-	* Calling this method on a component which is not using reactive state
-	* will result in an error being thrown.
-	*/
-	getState(): State<StateShape>;
-	/**
 	* Manually schedule a render to occur, optionally providing a callback to
 	* invoke after the render completes.
 	*
 	* @remarks
-	* Calling {@link requestRender} multiple times in the same event loop won't
+	* Calling {@link render} multiple times in the same event loop won't
 	* schedule multiple renders. Renders are scheduled to occur on the next
 	* animation frame.
 	*/
-	requestRender(callback?: VoidFunction): void;
+	render: () => void;
 	/**
-	* Listen for events from within this Component.
+	* Listen for events on a child element based on the provided query
 	*
-	* Provide a query string to target specific element events, or use `:host`
-	* to create listeners on the host element itself.
+	* @returns A function which removes the listener when called
 	*
+	* @remarks
 	* Event listeners created with this method are automatically cleaned up when
-	* the component unmounts.
+	* the component unmounts. You can manually remove the listener during the
+	* component's lifecycle by calling the returned function if need be.
 	*/
-	listen<E extends EventName>(targetDescriptor: string | typeof Component<any> | HTMLElement, eventName: E, eventHandler: EventHandler<E>): void;
-	stopListening<E extends EventName>(targetDescriptor: string | typeof Component<any> | HTMLElement, eventName: E, eventHandler: EventHandler<E>): void;
-	dispatchEvent(event: Event): boolean;
+	listen<E extends EventName>(target: string, eventName: E, eventHandler: EventHandler<E>): VoidFunction;
 	/**
-	* Dispatch a {@link CustomEvent} with the specified name and detail
+	* Listen for events on a child element based on the provided component's tag
+	*
+	* @returns A function which removes the listener when called
+	*
+	* @remarks
+	* Event listeners created with this method are automatically cleaned up when
+	* the component unmounts. You can manually remove the listener during the
+	* component's lifecycle by calling the returned function if need be.
 	*/
-	dispatchEvent<T>(event: string, detail?: T, options?: {
-		bubbles: boolean;
-		cancelable: boolean;
-		composed: boolean;
-	}): boolean;
-	querySelector<E extends HTMLElement>(query: string): E | null;
-	querySelectorAll<E extends HTMLElement>(query: string): NodeListOf<E>;
-	getElementById<E extends HTMLElement>(id: string): E | null;
-	requireElementById<E extends HTMLElement>(id: string): E;
-	setAttribute(name: string, value: string): void;
+	listen<E extends EventName>(target: typeof Component<any>, eventName: E, eventHandler: EventHandler<E>): VoidFunction;
 	/**
-	* Set a value as an attribute, serializing to a string or `null`.
+	* Listen for events on the host element
+	*
+	* @returns A function which removes the listener when called
 	*
-	* null values cause the attribute to be removed from this element
+	* @remarks
+	* Event listeners created with this method are automatically cleaned up when
+	* the component unmounts. You can manually remove the listener during the
+	* component's lifecycle by calling the returned function if need be.
 	*/
-	setAttribute(name: string, value: unknown): void;
-	getAttribute(name: string): string | null;
+	listen<E extends EventName>(target: typeof this, eventName: E, eventHandler: EventHandler<E>): VoidFunction;
 	/**
-	* Get an attribute as a number, falling back to a specified default.
+	* Listen for events on the host element
 	*
-	* `null` attributes are returned as `null`, while string attributes are
-	* parsed using the `Number()` constructor. NaN is coerced to `null`.
+	* @returns A function which removes the listener when called
+	*
+	* @remarks
+	* Event listeners created with this method are automatically cleaned up when
+	* the component unmounts. You can manually remove the listener during the
+	* component's lifecycle by calling the returned function if need be.
 	*/
-	getAttribute(name: string, defaultValue: number): number;
+	listen<E extends EventName>(target: ":host", eventName: E, eventHandler: EventHandler<E>): VoidFunction;
 	/**
-	* Get an attribute as a string, falling back to a specified default
+	* Publish a {@link CustomEvent} with the provided name and options.
+	*
+	* Default options are:
+	*
+	* ```typescript
+	* {
+	*   bubbles: true,
+	*   cancelable: true,
+	*   composed: true,
+	*   detail: undefined,
+	* }
+	* ```
+	*
+	* @param name The name of the custom event to publish
+	* @param options Options to configure the custom event
 	*/
-	getAttribute(name: string, defaultValue: string): string;
+	dispatchEvent<T>(name: string, options: CustomEventInit<T>): boolean;
+	dispatchEvent(event: Event): boolean;
 	/**
-	* Set the value of an attribute on this element if the provided value
-	* differs from the attribute when serialized
+	* Returns a reference to the HTML Element with the provided ID within the
+	* shadow root of this component.
+	*
+	* Throws an error if no element with the provided ID is found
 	*/
-	reflectAttribute(name: string, value: unknown): void;
+	ref<E extends HTMLElement>(id: string): E;
 	/**
 	* Serialize this element to a string
 	*/
@@ -699,7 +510,7 @@ declare abstract class Component<StateShape extends object = {}> extends HTMLEle
 * @param attributes A record of attributes to apply
 * @returns A reference to the rendered Component
 */
-declare function renderTestComponent<E extends typeof Component<any>>(component: E, attributes?: Record<string, unknown>): Promise<InstanceType<E>>;
+declare function renderTestComponent<E extends typeof Component<any>>(component: E, attributes?: Record<string, string | null>): Promise<InstanceType<E>>;
 /**
 * Force a render on the target element
 *