@rusticarcade/palette 0.3.1 → 0.7.0

package/dist/test/index.d.ts

@@ -13,30 +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;
-	private _hasWarned;
-	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.
@@ -66,37 +51,17 @@ 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>;
 	/**
-	* Proxied access to state properties with automatic reconciliation.
-	*
-	* 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;
+	* Live reactive accessor for state data. Deeply nested changes trigger
+	* automatic updates, including array, Map, and Set mutations.
 	*
-	* // 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;
 	/**
-	* 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
@@ -115,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]>;
 	/**
@@ -131,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;
@@ -154,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
@@ -199,87 +122,79 @@ 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 */
+	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"
+}
+declare const enum UpdateType {
+	Conditional = "cond",
+	Tag = "tag",
+	Attribute = "attr",
+	List = "list",
+	Swap = "swap"
+}
+type ConditionalRenderSchemeBranch = {
+	type: Directive.If | Directive.ElseIf;
+	notation: ParsedNotation;
+	branchRootRef: string;
+	branchTemplateHTML: string;
+} | {
+	type: Directive.Else;
+	branchRootRef: string;
+	branchTemplateHTML: string;
+};
+interface ConditionalRenderScheme {
+	type: UpdateType.Conditional;
+	branches: ConditionalRenderSchemeBranch[];
+}
+interface AttributeUpdateScheme {
+	type: UpdateType.Attribute;
+	notation: ParsedNotation;
+	attribute: string;
+	nodeRef: string;
+}
+interface TagChangeScheme {
+	type: UpdateType.Tag;
+	notation: ParsedNotation;
+	nodeRef: string;
+}
+interface ContentSwapScheme {
+	type: UpdateType.Swap;
+	notation: ParsedNotation;
+	nodeRef: string;
+}
+interface ListRenderScheme {
+	type: UpdateType.List;
+	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 = {
@@ -295,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.
 	*
@@ -355,7 +283,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
 	*/
@@ -366,6 +297,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.
 	*/
@@ -373,16 +305,10 @@ 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;
-	};
+declare enum RootMode {
+	Closed = "closed",
+	Open = "open"
 }
-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>);
 /**
 * The **Component** class extends the base HTMLElement class to provide an
 * ergonomic way to design and develop Web Components with reactive state,
@@ -390,181 +316,56 @@ type StateInitializer<Shape extends object = {}> = Shape | State<Shape> | ((this
 */
 declare abstract class Component<StateShape extends object = {}> extends HTMLElement {
 	/**
-	* Register a Component with the browser. Optionally provide an overriding
-	* tag name.
+	* Check if a value is a Component instance
 	*/
-	static register(component: CustomElementConstructor | typeof Component, tagName?: string): void;
+	static isComponent(value: unknown): value is Component;
 	/**
-	* The HTML tag name to use for this Component
+	* 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.
-	*/
+	/** 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
-	*/
-	static styles: ComponentStyles;
-	/**
-	* An array of html attribute names to observe to trigger updates.
-	*
-	* @remarks
-	* If you use the {@link define} factory helper, this value will be
-	* automatically merged with a list of any defined {@link liveAttributes}.
-	*/
+	/** 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.
 	*
-	* - `"open"` allows JS access to the children of this component
-	* - `"closed"` (default) disallows internal JS access
-	*/
-	static shadowRootMode: "closed" | "open";
-	/**
-	* Called immediately before each template update
+	* MDN: https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/mode
 	*/
-	protected beforeUpdate?(): void;
+	static rootMode: RootMode;
+	/** Called immediately before each template update */
+	beforeUpdate?(changedAttributes: Record<string, string | null>): void;
+	/** Called immediately after each template update */
+	afterUpdate?(previousAttributes: Record<string, string | null>): void;
+	/** Final lifecycle method called at the end of the unmounting process. */
+	finalize?(): void;
 	/**
-	* 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.
+	* Handle errors thrown during lifecycle methods of this component or any
+	* unhandled errors from child components.
 	*/
-	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.
-	*
-	* @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);
-	* }
-	* ```
-	*/
-	protected onError?(error: unknown): void;
-	/**
-	* The initial value for this Component's reactive internal state, if any.
-	*
-	* 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.
-	*
-	* 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
-	* host = {
-	*   avatarUrl: "http://...",
-	*   renderTime: () => new Date().toISOString(),
-	* }
-	* ```
-	*
-	* ```html
-	* <img :src="*avatarUrl" />
-	* <span>Rendered at ${"*renderTime"}</span>
-	* ```
 	*/
-	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.
-	*
-	* @example
-	*
-	* ```typescript
-	* liveAttributes = {
-	*   done: {
-	*     onChange(newValue) {
-	*       this.state.set("done", !!newValue);
-	*     },
-	*     reflect() { return this.state.current.done }
-	*   }
-	* };
-	* ```
-	*
-	* @remarks
-	*
-	* 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 _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
@@ -575,193 +376,113 @@ 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;
+	getState(): State<StateShape>;
 	/**
-	* Directly access and manipulate this Component's reactive state with deep
-	* reactivity enabled.
-	*
-	* @example
-	*
-	* ```typescript
-	* initialState = { values: { count: 1, time: 0 } };
+	* Accessor for live reactive state.
 	*
-	* increment() {
-	*   this.state.values.count = 2;
-	* }
-	* ```
-	*
-	* @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
-	* 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
+	* 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;
 	/**
-	* Create a managed event listener on this Component with an optional query
-	* filter string to specify which elements to listen to events from.
+	* Listen for events on a child element based on the provided query
 	*
-	* Event handlers set up with `listen()` are automatically cleaned up when
-	* the component is unmounted.
+	* @returns A function which removes the listener when called
 	*
-	* Handlers are delegated to a single listener per event on the root of the
-	* Component, which is the closed ShadowRoot by default.
+	* @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.
+	*/
+	listen<E extends EventName>(target: string, eventName: E, eventHandler: EventHandler<E>): VoidFunction;
+	/**
+	* Listen for events on a child element based on the provided component's tag
 	*
-	* @example
+	* @returns A function which removes the listener when called
 	*
-	* Set up an event listener for a click event from a button with ID "submit"
+	* @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.
+	*/
+	listen<E extends EventName>(target: typeof Component<any>, eventName: E, eventHandler: EventHandler<E>): VoidFunction;
+	/**
+	* Listen for events on the host element
 	*
-	* ```typescript
-	* this.listen("#submit", "click", this.handleClick);
-	* ```
+	* @returns A function which removes the listener when called
 	*
-	* @example
+	* @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.
+	*/
+	listen<E extends EventName>(target: typeof this, eventName: E, eventHandler: EventHandler<E>): VoidFunction;
+	/**
+	* Listen for events on the host element
 	*
-	* Set up an event listener on the host element itself (`this`).
+	* @returns A function which removes the listener when called
 	*
-	* ```typescript
-	* // Use ":host" or ":HOST" as the query selector to targe the host element
-	* this.listen(":host", "animationend", this.handler);
-	* ```
+	* @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.
 	*/
-	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: ":host", eventName: E, eventHandler: EventHandler<E>): VoidFunction;
 	/**
-	* Dispatch a {@link CustomEvent} with the specified name and detail
+	* Publish a {@link CustomEvent} with the provided name and options.
 	*
-	* @example Defining custom events
+	* Default options are:
 	*
 	* ```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
-	*  }
+	* {
+	*   bubbles: true,
+	*   cancelable: true,
+	*   composed: true,
+	*   detail: undefined,
 	* }
-	*
-	* // 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;
-		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;
-	/**
-	* Set a value as an attribute, serializing to a string or `null`.
 	*
-	* null values cause the attribute to be removed from this element
+	* @param name The name of the custom event to publish
+	* @param options Options to configure the custom event
 	*/
-	setAttribute(name: string, value: unknown): void;
-	getAttribute(name: string): string | null;
+	dispatchEvent<T>(name: string, options: CustomEventInit<T>): boolean;
+	dispatchEvent(event: Event): boolean;
 	/**
-	* Get an attribute as a number, falling back to a specified default.
+	* Returns a reference to the HTML Element with the provided ID within the
+	* shadow root of this component.
 	*
-	*
-	* `null` attributes are returned as `null`, while string attributes are
-	* parsed using the `Number()` constructor.
-	*
-	* Values which evaluate to NaN are returned as `null`.
-	*/
-	getAttribute(name: string, defaultValue: number): number;
-	/**
-	* Get an attribute as a string, falling back to a specified default
-	*/
-	getAttribute(name: string, defaultValue: string): string;
-	/**
-	* Set the value of an attribute on this element if the provided value
-	* differs from the attribute when serialized
+	* 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
 	*/
-	toString(full?: boolean): string;
+	toString(): string;
 }
 /**
 * Render a Palette Component class as a test element
@@ -789,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
 *