@tempots/dom
Version:
Fully-typed frontend framework alternative to React and Angular
306 lines (305 loc) • 12.4 kB
TypeScript
import { Clear, ProviderMark, Providers } from '../types/domain';
import { DOMContext, HandlerOptions } from './dom-context';
import { HeadlessContext } from './headless-context';
/**
* Browser implementation of DOMContext for real DOM manipulation in web browsers.
*
* BrowserContext provides a comprehensive API for creating, manipulating, and managing
* DOM elements in a browser environment. It handles element creation, text nodes,
* event listeners, styling, and provider management while maintaining immutability
* through context chaining.
*
* The context uses a reference system to track insertion points within sibling elements,
* allowing precise control over where new elements are inserted in the DOM tree.
*
* @example
* ```typescript
* // Create a context for the document body
* const ctx = BrowserContext.of(document.body, undefined, {})
*
* // Create child elements
* const divCtx = ctx.makeChildElement('div', undefined)
* const textCtx = divCtx.makeChildText('Hello, World!')
*
* // Add event listeners
* divCtx.on('click', (event, ctx) => {
* console.log('Div clicked!', event.target)
* })
* ```
*
* @example
* ```typescript
* // Working with providers
* const themeProvider = makeProviderMark<string>('theme')
* const ctxWithProvider = ctx.setProvider(themeProvider, 'dark', undefined)
*
* // Later retrieve the provider
* const { value: theme } = ctxWithProvider.getProvider(themeProvider)
* ```
*
* @example
* ```typescript
* // Portal to different DOM location
* const modalCtx = ctx.makePortal('#modal-root')
* const modalContent = modalCtx.makeChildElement('div', undefined)
* ```
*
* @public
*/
export declare class BrowserContext implements DOMContext {
/**
* The `Document` instance associated with this context.
*/
readonly document: Document;
/**
* The `Element` instance associated with this context.
*/
readonly element: HTMLElement;
/**
* An optional `Node` instance that serves as a reference for this context.
*/
readonly reference: Node | undefined;
/**
* The `Providers` instance associated with this context.
*/
readonly providers: Providers;
/**
* Creates a new `DOMContext` instance for the given `Element` and optional reference `Node`.
*
* @param element - The `HTMLElement` to create the `DOMContext` for.
* @param ref - A reference `Node` to associate with the `DOMContext` or undefined .
* @param providers - The providers to associate with the `DOMContext`.
* @returns A new `DOMContext` instance.
*/
static of(element: HTMLElement, ref: Node | undefined, providers: Providers): DOMContext;
/**
* Constructs a new `DOMContext` instance.
*
* @param document - The `Document` instance associated with this context.
* @param element - The `Element` instance associated with this context.
* @param reference - An optional `Node` instance that serves as a reference for this context.
* @param providers - The `Providers` instance associated with this context.
* @param isFirstLevel - A boolean value indicating whether this context is at the first level, meaning the outermost node in the generated DOM.
*/
constructor(
/**
* The `Document` instance associated with this context.
*/
document: Document,
/**
* The `Element` instance associated with this context.
*/
element: HTMLElement,
/**
* An optional `Node` instance that serves as a reference for this context.
*/
reference: Node | undefined,
/**
* The `Providers` instance associated with this context.
*/
providers: Providers);
/**
* Creates a new DOM element (eg: HTML or SVG) with the specified tag name and namespace.
*
* @param tagName - The tag name of the element to create.
* @param namespace - The namespace URI to create the element in, or `undefined` to create a standard HTML element.
* @returns The newly created element.
*/
readonly createElement: (tagName: string, namespace: string | undefined) => HTMLElement;
/**
* Creates a new child element and appends it to the current element, returning a new context.
*
* This method creates a new DOM element with the specified tag name and namespace,
* appends it to the current element, and returns a new DOMContext focused on the
* newly created child element. This is the primary method for building DOM trees.
*
* @example
* ```typescript
* // Create HTML elements
* const divCtx = ctx.makeChildElement('div', undefined)
* const spanCtx = divCtx.makeChildElement('span', undefined)
*
* // Create SVG elements
* const svgCtx = ctx.makeChildElement('svg', 'http://www.w3.org/2000/svg')
* const circleCtx = svgCtx.makeChildElement('circle', 'http://www.w3.org/2000/svg')
* ```
*
* @param tagName - The tag name of the element to create (e.g., 'div', 'span', 'svg')
* @param namespace - The namespace URI for the element, or undefined for HTML elements
* @returns A new DOMContext focused on the newly created child element
*/
readonly makeChildElement: (tagName: string, namespace: string | undefined) => DOMContext;
/**
* Creates a new text node with the specified text content.
* @param text - The text content for the new text node.
* @returns A new `Text` node with the specified text content.
*/
readonly createText: (text: string) => Text;
/**
* Creates a new text node with the specified text content and appends it to the current element.
* @param text - The text content for the new text node.
* @returns A new `DOMContext` with a reference to the new text node.
*/
readonly makeChildText: (text: string) => DOMContext;
/**
* Sets the text content of the current element.
* @param text - The text content to set.
*/
readonly setText: (text: string) => void;
/**
* Gets the text content of the current element or text node.
* @returns The text content of the current element or text node.
*/
readonly getText: () => string;
/**
* Creates a new `DOMContext` with a reference to a newly created text node.
* The text node is appended or inserted to the current `DOMContext`.
* The new `DOMContext` with the reference is returned.
*/
readonly makeRef: () => DOMContext;
/**
* Appends or inserts a child node to the element, depending on whether a reference node is provided.
*
* @param child - The child node to append or insert.
*/
readonly appendOrInsert: (child: Node) => void;
/**
* Creates a new `DOMContext` instance with the provided `element`.
* @param element - The DOM element to use in the new `DOMContext` instance.
* @returns A new `DOMContext` instance with the provided `element`.
*/
readonly withElement: (element: HTMLElement) => BrowserContext;
/**
* Creates a portal to render content in a different part of the DOM tree.
*
* Portals allow you to render child components into a DOM node that exists outside
* the parent component's DOM hierarchy. This is useful for modals, tooltips,
* dropdowns, and other UI elements that need to break out of their container's
* styling or z-index context.
*
* @example
* ```typescript
* // Portal to a modal container
* const modalCtx = ctx.makePortal('#modal-root')
* const modal = modalCtx.makeChildElement('div', undefined)
*
* // Add modal content
* modal.makeChildText('This renders in #modal-root')
* ```
*
* @example
* ```typescript
* // Portal to an existing element reference
* const tooltipContainer = document.getElementById('tooltip-container')!
* const tooltipCtx = ctx.makePortal(tooltipContainer)
*
* // Render tooltip content
* const tooltip = tooltipCtx.makeChildElement('div', undefined)
* tooltip.addClasses(['tooltip', 'tooltip-top'])
* ```
*
* @example
* ```typescript
* // Portal for dropdown menu
* const dropdownCtx = ctx.makePortal('body') // Render at body level
* const dropdown = dropdownCtx.makeChildElement('div', undefined)
* dropdown.addClasses(['dropdown-menu'])
* dropdown.setStyle('position', 'absolute')
* dropdown.setStyle('top', '100px')
* dropdown.setStyle('left', '50px')
* ```
*
* @param selector - CSS selector string or HTMLElement reference for the portal target
* @returns A new DOMContext focused on the portal target element
* @throws {Error} When the selector doesn't match any element in the document
*/
readonly makePortal: (selector: string | HTMLElement) => DOMContext;
/**
* Creates a new `DOMContext` instance with the specified reference.
*
* @param reference - The optional `Text` node to use as the reference for the new `DOMContext`.
* @returns A new `DOMContext` instance with the specified reference.
*/
readonly withReference: (reference: Text | undefined) => DOMContext;
/**
* Sets a provider for the given provider mark.
*
* @param mark - The provider mark to set the provider for.
* @param value - The provider to set for the given mark.
* @returns A new `DOMContext` instance with the specified provider.
*/
readonly setProvider: <T>(mark: ProviderMark<T>, value: T, onUse: undefined | (() => void)) => DOMContext;
/**
* Retrieves a provider for the given provider mark.
*
* @param mark - The provider mark to retrieve the provider for.
* @returns The provider for the given mark.
* @throws Throws `ProviderNotFoundError` if the provider for the given mark is not found.
*/
readonly getProvider: <T>(mark: ProviderMark<T>) => {
value: T;
onUse: (() => void) | undefined;
};
readonly clear: (removeTree: boolean) => void;
/**
* Adds classes to the element.
* @param tokens - The class names to add.
*/
readonly addClasses: (tokens: string[]) => void;
/**
* Removes classes from the element.
* @param tokens - The class names to remove.
*/
readonly removeClasses: (tokens: string[]) => void;
/**
* Gets the classes of the element.
* @returns The classes of the element.
*/
readonly getClasses: () => string[];
/**
* Adds an event listener to the element.
* @param event - The event to listen for.
* @param listener - The listener to call when the event occurs.
* @param options - The options for the event listener.
* @returns A function to remove the event listener.
*/
readonly on: <E>(event: string, listener: (event: E, ctx: BrowserContext) => void, options?: HandlerOptions) => Clear;
/**
* Returns `true` if the context is a browser DOM context.
* @returns `true` if the context is a browser DOM context.
* @deprecated Use `isBrowser()` instead.
*/
readonly isBrowserDOM: () => this is BrowserContext;
/**
* Returns `true` if the context is a browser context.
* @returns `true` if the context is a browser context.
*/
readonly isBrowser: () => this is BrowserContext;
/**
* Returns `true` if the context is a headless DOM context.
* @returns `true` if the context is a headless DOM context.
*/
readonly isHeadlessDOM: () => this is HeadlessContext;
/**
* Returns `true` if the context is a headless context.
* @returns `true` if the context is a headless context.
*/
readonly isHeadless: () => this is HeadlessContext;
/**
* Sets the style of the element.
* @param name - The name of the style to set.
* @param value - The value of the style to set.
*/
readonly setStyle: (name: string, value: string) => void;
/**
* Gets the style of the element.
* @param name - The name of the style to get.
* @returns The value of the style.
*/
readonly getStyle: (name: string) => string;
readonly makeAccessors: (name: string) => {
get: () => any;
set: (value: unknown) => void;
};
readonly getWindow: () => Window & typeof globalThis;
}