@rusticarcade/palette 0.3.0 → 0.4.0

package/dist/prod/index.d.ts

@@ -27,7 +27,6 @@ declare class State<Shape extends object> {
 	private _proxyCache;
 	private _reverseProxyCache;
 	private _isLocked;
-	private _hasWarned;
 	constructor(initialData: Shape, onChange?: StateListener<Shape>);
 	/**
 	* Lazily create and cache proxies into the state for reactive updates on
@@ -60,28 +59,12 @@ declare class State<Shape extends object> {
 	*/
 	get current(): Readonly<Shape>;
 	/**
-	* Proxied access to state properties with automatic reconciliation.
+	* Live reactive accessor for state data. Deeply nested changes trigger
+	* automatic updates, including array, Map, and Set mutations.
 	*
-	* Allows direct property access for both reading and writing state values.
-	*
-	* @example
-	*
-	* Deep reactivity with the `.live` accessor
-	*
-	* ```typescript
-	* const state = new State({
-	*   nested: {
-	*     values: [1, 2, 3],
-	*   }
-	* });
-	*
-	* // Deep value assignment triggers state updates
-	* state.live.nested.values[1] = 5;
-	*
-	* // Array mutators are automatically reactive as well
-	* state.live.nested.values.push(4);
-	* state.live.nested.values.reverse();
-	* ```
+	* @remarks
+	* For deeply nested values, the `.live` accessor may add performance overhead
+	* compared to directly accessing the value via `.current`
 	*/
 	get live(): Shape;
 	/**
@@ -273,6 +256,72 @@ declare class State<Shape extends object> {
 	*/
 	transactionAsync: (fn: (state: State<Shape>) => Promise<void>) => Promise<boolean>;
 }
+type ParsedNotation = {
+	/** The raw string representation of the parsed notation */
+	base: string;
+	/** An array of property names forming a path to the notation value */
+	path: string[];
+	modifiers?: {
+		not?: boolean;
+	};
+};
+type NotationAccessor = (source: unknown) => unknown;
+declare const enum Directive {
+	Each = "::each",
+	Key = "::key",
+	Tag = "::tag",
+	Swap = "::swap",
+	If = "::if",
+	ElseIf = "::else-if",
+	Else = "::else"
+}
+type ConditionalRenderSchemeBranch = {
+	type: Directive.If | Directive.ElseIf;
+	notation: ParsedNotation;
+	branchRootRef: string;
+	branchTemplateHTML: string;
+} | {
+	type: Directive.Else;
+	branchRootRef: string;
+	branchTemplateHTML: string;
+};
+interface ConditionalRenderScheme {
+	type: "cond";
+	branches: ConditionalRenderSchemeBranch[];
+}
+interface AttributeUpdateScheme {
+	type: "attr";
+	notation: ParsedNotation;
+	attribute: string;
+	nodeRef: string;
+}
+interface TagChangeScheme {
+	type: "tag";
+	notation: ParsedNotation;
+	nodeRef: string;
+}
+interface ContentSwapScheme {
+	type: "swap";
+	notation: ParsedNotation;
+	nodeRef: string;
+}
+interface ListRenderScheme {
+	type: "each";
+	notation: ParsedNotation;
+	keyNotation: ParsedNotation;
+	nodeRef: string;
+	listContentHtml: string;
+}
+type AnyScheme = AttributeUpdateScheme | TagChangeScheme | ContentSwapScheme | ListRenderScheme | ConditionalRenderScheme;
+/**
+* A JSON-serializable representation of a {@link Template} instance, including
+* everything needed to recreate the template.
+*/
+interface CompiledTemplate {
+	html: string;
+	schemes: AnyScheme[];
+	notations: Record<string, ParsedNotation>;
+}
 type TemplateRoot = HTMLElement | ShadowRoot;
 type TemplateContext = {
 	attr?: Record<string, string | null>;
@@ -347,7 +396,10 @@ declare class Template {
 	private _plansByNotation;
 	/** Value Notations -> Accessor functions */
 	private _notationAccessors;
+	private _subtemplates;
 	constructor(template: HTMLTemplateElement);
+	get compiled(): CompiledTemplate;
+	get notationMap(): Map<string, NotationAccessor>;
 	/**
 	* Create a full copy of this template for use in rendering to another root
 	*/
@@ -358,6 +410,7 @@ declare class Template {
 	element: () => HTMLTemplateElement;
 	private _collectUpdatedValues;
 	private _update;
+	renderWithValues: (root: TemplateRoot, values: Map<string, unknown>) => void;
 	/**
 	* Render this template into a target host element.
 	*/
@@ -375,31 +428,26 @@ type ComputedProperties<StateShape extends object = {}> = 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"
+}
 /**
 * The **Component** class extends the base HTMLElement class to provide an
 * ergonomic way to design and develop Web Components with reactive state,
 * managed attributes, and dynamic templating.
 */
 declare abstract class Component<StateShape extends object = {}> extends HTMLElement {
-	/**
-	* Register a Component with the browser. Optionally provide an overriding
-	* tag name.
-	*/
-	static register(component: CustomElementConstructor | typeof Component, tagName?: string): void;
-	/**
-	* The HTML tag name to use for this Component
-	*/
+	/** The HTML tag name to use for this Component */
 	static tagName: string;
-	/**
-	* An HTML Template element for this element to use.
-	*/
+	/** An HTML Template element for this element to use. */
 	static template: HTMLTemplateElement | Template;
 	/**
-	* A {@link CSSStyleSheet} array or string to adopt as the component's scoped styles
+	* Styles for this Component
 	*/
 	static styles: ComponentStyles;
 	/**
-	* An array of html attribute names to observe to trigger updates.
+	* A list of attribute names to track changes for
 	*
 	* @remarks
 	* If you use the {@link define} factory helper, this value will be
@@ -407,39 +455,23 @@ declare abstract class Component<StateShape extends object = {}> extends HTMLEle
 	*/
 	static observedAttributes: string[];
 	/**
-	* The mode for this Component's ShadowRoot.
-	*
-	* - `"open"` allows JS access to the children of this component
-	* - `"closed"` (default) disallows internal JS access
+	* The mode for this Component's ShadowRoot. Must be a {@link RootMode}
 	*/
-	static shadowRootMode: "closed" | "open";
+	static rootMode: RootMode;
 	/**
-	* Called immediately before each template update
+	* 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;
-	/**
-	* Called immediately after each template update
-	*/
+	/** Called immediately after each template update */
 	protected afterUpdate?(previousAttributes: AttributeMap): void;
-	/**
-	* Called as the final lifecycle method at the end of the unmounting process.
-	*
-	* Content has been removed from the DOM and the component is no longer
-	* considered mounted when this function runs.
-	*
-	* Use this for final cleanup tasks and freeing resources.
-	*/
+	/** Final lifecycle method called at the end of the unmounting process. */
 	protected finalize?(): void;
 	/**
-	* If defined, receives errors caught during the lifecycle methods of this
-	* component and it's children. If not defined, this component will instead
-	* throw errors as they are found.
-	*
-	* If the error cannot be handled, `onError()` should re-throw it for a higher
-	* up component to evaluate.
-	*
-	* To display an error message while removing an erroring component from the
-	* DOM, use `this.replaceWith()` and a newly constructed placeholder element.
+	* When defined, catches any errors thrown during lifecycle mthods of this
+	* component as well as any uncaught errors from child components.
 	*
 	* @example
 	*
@@ -447,16 +479,12 @@ declare abstract class Component<StateShape extends object = {}> extends HTMLEle
 	*
 	* ```typescript
 	* onError(error) {
-	*   // Handle known errors
-	*   if (error.message = "Invalid Input") {
-	*     this.state.input = "";
+	*   if (error.canRecover) {
+	*     this.recover();
 	*     return;
 	*   }
 	*
-	*   // Display a fallback banner
-	*   const banner = document.createElement("div");
-	*   banner.textContent = "An unexpected error done did";
-	*   this.replaceWith(banner);
+	*   this.replaceWith("Oh dear, an error happened real bad");
 	* }
 	* ```
 	*/
@@ -464,6 +492,7 @@ declare abstract class Component<StateShape extends object = {}> extends HTMLEle
 	/**
 	* 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.
 	*/
@@ -472,20 +501,6 @@ declare abstract class Component<StateShape extends object = {}> extends HTMLEle
 	* An object or function returning an object which populates the `data` values
 	* in the templating engine. Such values are accessed using the `*` notation.
 	*
-	* When a hosted value is accessed, it's value is coerced based on the way it
-	* is being used. For attributes, values are serialized to a string or null,
-	* which will set the attribute (string) or remove it (null).
-	*
-	* For content swaps, strings, numbers and booleans are rendered as strings
-	* and set as textContent. null and undefined values render nothing (with a
-	* comment placeholder), an HTMLElement will be swapped in as a cloned node.
-	*
-	* Functions are evaluated at render/update time, and their return value is
-	* used instead. Functions are passed the current target node accessing the
-	* property as its first and only argument.
-	*
-	* Other types are unsupported.
-	*
 	* @example
 	*
 	* ```typescript
@@ -502,17 +517,8 @@ declare abstract class Component<StateShape extends object = {}> extends HTMLEle
 	*/
 	protected computedProperties?: ComputedProperties<StateShape>;
 	/**
-	* Declaration of attribute behaviors during updates.
-	*
-	* Each key is the name of an attribute. Values are an object with two
-	* optional function definitions:
-	*
-	* `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.
+	* Define attribute update and reflection behaviors as a record of attribute
+	* name keys to objects with optionally defined behaviors.
 	*
 	* @example
 	*
@@ -528,22 +534,24 @@ declare abstract class Component<StateShape extends object = {}> extends HTMLEle
 	* ```
 	*
 	* @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}.
-	*
-	* If you are directly extending the class, `observedAttributes` must be
-	* explicitly defined with any attributes that should be monitored, regardless
-	* of if they're defined here.
 	*/
 	protected liveAttributes?: LiveAttributes<StateShape>;
-	private _isComponentMounted;
 	private _template;
 	private _root;
 	private _state?;
 	private _delegator?;
-	private _ownListeners;
-	private _liveAttributeConfigs;
+	private _ownListeners?;
 	private _cleanupFn?;
 	private _renderInternals;
 	constructor();
@@ -574,86 +582,29 @@ declare abstract class Component<StateShape extends object = {}> extends HTMLEle
 	* The ShadowRoot node of this element
 	*/
 	get root(): ShadowRoot;
+	get isMounted(): boolean;
 	/**
-	* Directly access and manipulate this Component's reactive state with deep
-	* reactivity enabled.
-	*
-	* @example
-	*
-	* ```typescript
-	* initialState = { values: { count: 1, time: 0 } };
-	*
-	* increment() {
-	*   this.state.values.count = 2;
-	* }
-	* ```
+	* Accessor for live reactive state.
 	*
-	* @remarks
-	* This is a shorthand getter for `this.getState().live`
+	* For the full state manipulation API, use {@link getState}
 	*/
 	get state(): StateShape;
 	/**
 	* Replace the current state with a new value or adopt a whole different State
 	* instance
-	*
-	* @example
-	*
-	* State replacement
-	*
-	* ```typescript
-	* // Always triggers a render
-	* this.state = { some: "newState" }
-	*
-	* // Adopt a new state instance altogether
-	* const otherState = new State({some: "newState"});
-	* this.state = otherState;
-	*
-	* // Causes a render
-	* otherState.set("some", "value");
-	* ```
 	*/
 	set state(newState: StateShape | State<StateShape>);
 	/**
 	* Access the full {@link State} instance for this Component.
 	*
-	* Using this method on a component which is not using reactive state
+	* @remarks
+	* Calling this method on a component which is not using reactive state
 	* will result in an error being thrown.
-	*
-	* @example
-	*
-	* Retrieve stateful value
-	*
-	* ```typescript
-	* class Example extends Component {
-	*   initialState = { count: 1 };
-	*
-	*   script() {
-	*     const state = this.getState();
-	*     console.log(`The count is ${state.get("count")}`);
-	*   }
-	*
-	* }
-	* ```
-	*
-	* @example
-	*
-	* Set a stateful value
-	*
-	* ```typescript
-	* class Example extends Component {
-	*   initialState = { count: 1 };
-	*
-	*   increment() {
-	*     const state = this.getState();
-	*     const current = state.get("count");
-	*     state.set("count", current + 1);
-	*   }
-	* }
-	* ```
 	*/
 	getState(): State<StateShape>;
 	/**
-	* Manually schedule a render to occur
+	* 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
@@ -662,57 +613,19 @@ declare abstract class Component<StateShape extends object = {}> extends HTMLEle
 	*/
 	requestRender(callback?: VoidFunction): void;
 	/**
-	* Create a managed event listener on this Component with an optional query
-	* filter string to specify which elements to listen to events from.
-	*
-	* Event handlers set up with `listen()` are automatically cleaned up when
-	* the component is unmounted.
-	*
-	* Handlers are delegated to a single listener per event on the root of the
-	* Component, which is the closed ShadowRoot by default.
-	*
-	* @example
-	*
-	* Set up an event listener for a click event from a button with ID "submit"
-	*
-	* ```typescript
-	* this.listen("#submit", "click", this.handleClick);
-	* ```
-	*
-	* @example
+	* Listen for events from within this Component.
 	*
-	* Set up an event listener on the host element itself (`this`).
+	* Provide a query string to target specific element events, or use `:host`
+	* to create listeners on the host element itself.
 	*
-	* ```typescript
-	* // Use ":host" or ":HOST" as the query selector to targe the host element
-	* this.listen(":host", "animationend", this.handler);
-	* ```
+	* Event listeners created with this method are automatically cleaned up when
+	* the component unmounts.
 	*/
 	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;
 	/**
 	* Dispatch a {@link CustomEvent} with the specified name and detail
-	*
-	* @example Defining custom events
-	*
-	* ```typescript
-	* // Define types. This can happen in the same file or elsewhere for common
-	* // and shared events.
-	* type MyEvent = CustomEvent<T> // Set `T` to the event detail type
-	*
-	* declare global {
-	*  interface GlobalEventHandlersEventMap {
-	*    "my-event-name": MyEvent
-	*  }
-	* }
-	*
-	* // Dispatch a custom event
-	* this.dispatchEvent("my-event-name", T);
-	*
-	* // Listen to a custom event
-	* $el.addEventListener("my-event-name", ...);
-	* ```
 	*/
 	dispatchEvent<T>(event: string, detail?: T, options?: {
 		bubbles: boolean;
@@ -734,11 +647,8 @@ declare abstract class Component<StateShape extends object = {}> extends HTMLEle
 	/**
 	* Get an attribute as a number, falling back to a specified default.
 	*
-	*
 	* `null` attributes are returned as `null`, while string attributes are
-	* parsed using the `Number()` constructor.
-	*
-	* Values which evaluate to NaN are returned as `null`.
+	* parsed using the `Number()` constructor. NaN is coerced to `null`.
 	*/
 	getAttribute(name: string, defaultValue: number): number;
 	/**
@@ -753,7 +663,7 @@ declare abstract class Component<StateShape extends object = {}> extends HTMLEle
 	/**
 	* Serialize this element to a string
 	*/
-	toString(full?: boolean): string;
+	toString(): string;
 }
 interface ComponentShorthand<StateShape extends object = {}> {
 	/**
@@ -798,46 +708,40 @@ interface ComponentShorthand<StateShape extends object = {}> {
 	afterUpdate?: (this: Component<StateShape>, previousAttributes: AttributeMap) => void;
 	/**
 	* Called as the final lifecycle method at the end of the unmounting process.
-	*
-	* Content has been removed from the DOM and the component is no longer
-	* considered mounted when this function runs.
-	*
-	* Use this for final cleanup tasks and freeing resources.
 	*/
 	finalize?: (this: Component<StateShape>) => void;
 	/**
 	* If defined, receives errors caught during the lifecycle methods of this
 	* component and it's children. If not defined, this component will instead
 	* throw errors as they are found.
-	*
-	* If the error cannot be handled, `onError()` should re-throw it for a higher
-	* up component to evaluate.
-	*
-	* To display an error message while removing an erroring component from the
-	* DOM, use `this.replaceWith()` and a newly constructed placeholder element.
-	*
-	* @example
-	*
-	* Recovering from errors or displaying a fallback
-	*
-	* ```typescript
-	* onError(error) {
-	*   // Handle known errors
-	*   if (error.message = "Invalid Input") {
-	*     this.state.input = "";
-	*     return;
-	*   }
-	*
-	*   // Display a fallback banner
-	*   const banner = document.createElement("div");
-	*   banner.textContent = "An unexpected error done did";
-	*   this.replaceWith(banner);
-	* }
-	* ```
 	*/
 	onError?: (this: Component<StateShape>, error: unknown) => void;
 }
-declare function define<StateShape extends object = {}>(tagname: string, definition: ComponentShorthand<StateShape>): typeof Component<StateShape>;
+/**
+* Register a Palette Component as a custom element
+*/
+declare function define<Cls extends typeof Component<any>>(definition: Cls): Cls;
+/**
+* Register a Palette Component as a custom element
+*/
+declare function define<Cls extends typeof Component<any>>(tagName: string, definition: Cls): Cls;
+/**
+* Define a Palette Component using the shorthand syntax
+*
+* @example
+*
+* ```typescript
+* define("my-component", {
+*   template: html`...`,
+*   styles: css`...`,
+*   initialState: { ... },
+*   computedProperties() { ... },
+*   script() { ... },
+*   // and any other lifecycle methods
+* });
+* ```
+*/
+declare function define<StateShape extends object = {}>(tagName: string, definition: ComponentShorthand<StateShape>): typeof Component<StateShape>;
 /**
 * An error originating from within a Palette subsystem.
 *
@@ -862,7 +766,7 @@ declare class PaletteError extends Error {
 /**
 * @returns An array of {@link CSSStyleSheet}s containing the provided CSS
 */
-declare function css(strings: TemplateStringsArray, ...values: unknown[]): CSSStyleSheet;
+declare function css(strings: TemplateStringsArray, ...values: (string | typeof Component<any>)[]): CSSStyleSheet;
 type ClassValue = string | number | boolean | undefined | null | ClassArray | ClassObject;
 type ClassArray = ClassValue[];
 type ClassObject = Record<string, any>;
@@ -914,4 +818,4 @@ declare function classify(...args: ClassValue[]): string;
 * ```
 */
 declare function html(strings: TemplateStringsArray, ...values: (`@${string}` | `$${string}` | `#${string}` | `*${string}` | HTMLTemplateElement | typeof Component<any>)[]): HTMLTemplateElement;
-export { html, define, css, classify, TemplateRoot, TemplateContext, Template, StateListener, StateInitializer, State, PaletteError, LiveAttributes, EventName, EventHandler, ComputedProperties, ComponentStyles, ComponentShorthand, Component, AttributeMap };
+export { html, define, css, classify, TemplateRoot, TemplateContext, Template, StateListener, StateInitializer, State, RootMode, PaletteError, LiveAttributes, EventName, EventHandler, ComputedProperties, ComponentStyles, ComponentShorthand, Component, AttributeMap };