rvx/dist/rvx.element.d.ts

A signal based rendering library

/*!
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.
*/
import { Signal } from './rvx.js';
import { Content } from './rvx.js';

type StartTrigger = "on-connect" | "manual";
type DisposeTrigger = "on-disconnect" | "manual";
interface RvxElementOptions {
	/**
	 * Shadow root options to use or false to attach content to the element directly.
	 *
	 * By default and when `true`, an open shadow root is attached immediately.
	 */
	shadow?: boolean | ShadowRootInit;
	/**
	 * When to render this element's content.
	 *
	 * + `on-connect` - Default. Render when this element is connected.
	 * + `manual` - Render only when `.start()` is called.
	 */
	start?: StartTrigger;
	/**
	 * When to dispose this element's content.
	 *
	 * + `on-disconnect` - Default. Dispose when this element is disconnected or when `.dispose()` is called.
	 * + `manual` - Dispose only when `.dispose()` is called.
	 */
	dispose?: DisposeTrigger;
}
declare const moduleEnv: typeof globalThis;
declare abstract class RvxElement extends moduleEnv.HTMLElement {
	#private;
	static observedAttributes?: string[];
	constructor(options?: RvxElementOptions);
	/**
	 * Called to render the content of this element.
	 *
	 * @returns The content to attach to this element or the shadow root if it exists.
	 */
	abstract render(): Content;
	/**
	 * Get a signal that reflects an attribute value.
	 *
	 * + `null` represents a missing attribute.
	 * + This signal is only updated if the name is part of the static `observedAttributes` array.
	 * + Updating the signal value will also update or remove the attribute.
	 * + This signal will be kept alive until neither this element nor the signal is referenced anymore.
	 *
	 * @param name The attribute name.
	 * @returns The signal.
	 */
	reflect(name: string): Signal<string | null>;
	/**
	 * Manually initialize this element.
	 *
	 * This has no effect if the element is already initialized.
	 */
	start(): void;
	/**
	 * Manually dispose this element.
	 *
	 * This will leave rendered content as is.
	 */
	dispose(): void;
	connectedCallback(): void;
	disconnectedCallback(): void;
	attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
}

export { RvxElement };
export type { DisposeTrigger, RvxElementOptions, StartTrigger };