/** * Custom Element Implementation for Woby Framework * * This module provides functionality to create custom HTML elements with reactive properties * that integrate seamlessly with the Woby framework's observable system. Custom elements * created with this API can be used both in JSX/TSX and directly in HTML. * * Features: * - Automatic attribute to prop mapping * - Type conversion for observable props * - Nested property support (e.g., 'nested$prop$value' or 'nested.prop.value' in HTML, 'nested$prop$value' in JSX) * - Style property support (e.g., 'style$font-size' or 'style.font-size' in HTML, 'style$font-size' in JSX) * - Automatic kebab-case to camelCase conversion for all property names * - Automatic exclusion of properties with { toHtml: () => undefined } from HTML attributes * - Shadow DOM encapsulation with optional stylesheet adoption * - Context support for custom elements * - Custom serialization using toHtml and fromHtml options * * Style Encapsulation Options: * - ignoreStyle: Set to true to prevent adoption of global stylesheets in shadow DOM * * @module customElement */ import { Observable } from "soby"; import { ObservableMaybe } from "../types"; /** * ElementAttributes type helper * * Simplified type to prevent excessive type instantiation depth when working with custom elements. * Combines HTML attributes with component-specific props. * * @template T - Component function type */ export type ElementAttributesPattern

= (keyof P extends string ? keyof P : never) | (keyof JSX.HTMLAttributes extends string ? keyof JSX.HTMLAttributes : never) | `style.${keyof JSX.StyleProperties extends string ? keyof JSX.StyleProperties : never}` | `style$${keyof JSX.StyleProperties extends string ? keyof JSX.StyleProperties : never}`; export type ExtractProps = T extends (props: infer P) => any ? P : never; export type ElementAttributes1 any> = (T extends (props: infer P) => any ? Partial<(JSX.HTMLAttributes & ElementAttributesPattern

)> : Partial>); export type ElementAttributes any> = Partial> & Partial>, any>>; export declare const useAttached: (ref?: ObservableMaybe, match?: (parent: Node | null) => boolean) => { parent: Observable; mount: import("..").JSX.Child; ref: ObservableMaybe; }; /** * Creates a custom HTML element with reactive properties * * Defines a custom element that integrates with the Woby framework's observable system. * The element can observe attribute changes and update corresponding props automatically. * All props defined in the component's defaults are automatically observed as attributes. * * Requirements: * - Component must have default props defined using the `defaults` helper * - Component props that are observables will be updated with type conversion * - Component can be used in both JSX/TSX and HTML * * @template P - Component props type * @param tagName - The HTML tag name for the custom element (must contain a hyphen) * @param component - The component function that renders the element's content * @returns The custom element class * * @example * ```tsx * // Define a component with default props * const Counter = defaults(() => ({ * value: $(0, { type: 'number' } as const), * title: $('Counter') * }), ({ value, title }: { value: Observable, title: Observable }) => ( *

*

{title}

*

Count: {value}

* *
* )) * * // Register as a custom element * customElement('counter-element', Counter) * * // Usage in JSX: * // * * // Usage in HTML: * // * ``` * * @example * ```tsx * // Component with nested properties * const UserCard = defaults(() => ({ * user: { * name: $('John'), * details: { * age: $(30, { type: 'number' } as const) * } * } * }), ({ user }: { user: { name: Observable, details: { age: Observable } } }) => ( *
*

{user.name}

*

Age: {user.details.age}

*
* )) * * customElement('user-card', UserCard) * * // Usage with nested attributes: * // (both HTML and JSX) * ``` * * @example * ```tsx * // Component with custom serialization * const DateComponent = defaults(() => ({ * date: $(new Date(), { * toHtml: o => o.toISOString(), * fromHtml: o => new Date(o) * }) * }), ({ date }: { date: Observable }) => ( *
Date: {() => $$(date).toString()}
* )) * * customElement('date-component', DateComponent) * * // Usage: * // * ``` * * @example * ```tsx * // Component with hidden functions * const Counter = defaults(() => { * const value = $(0, { type: 'number' } as const) * return { * value, * increment: $([() => { value($$(value) + 10) }], { toHtml: o => undefined }) // Hide from HTML attributes * } * }), ({ value, increment }: { value: Observable, increment: Observable<(() => void)[]> }) => ( *
*

Count: {value}

* *
* )) * * customElement('counter-element', Counter) * ``` */ export declare const customElement:

; }>(tagName: string, component: JSX.Component

) => { new (props?: P): { /** Component props */ props: P; propDict: Record; childs: Node[]; slots: HTMLSlotElement; placeHolder: Comment; /** * Called when the element is added to the document * * Sets up attribute observation and initializes the element. */ connectedCallback(): void; /** * Called when the element is removed from the document * * Cleans up observers and resources. */ disconnectedCallback(): void; /** * Called when an observed attribute changes * * Updates the corresponding prop and handles nested properties. * * @param name - The name of the changed attribute * @param oldValue - The previous value of the attribute * @param newValue - The new value of the attribute */ attributeChangedCallback1(name: any, oldValue: any, newValue: any): void; accessKey: string; readonly accessKeyLabel: string; autocapitalize: string; autocorrect: boolean; dir: string; draggable: boolean; hidden: boolean; inert: boolean; innerText: string; lang: string; readonly offsetHeight: number; readonly offsetLeft: number; readonly offsetParent: Element | null; readonly offsetTop: number; readonly offsetWidth: number; outerText: string; popover: string | null; spellcheck: boolean; title: string; translate: boolean; writingSuggestions: string; attachInternals(): ElementInternals; click(): void; hidePopover(): void; showPopover(): void; togglePopover(options?: boolean): boolean; addEventListener(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; removeEventListener(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void; removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void; readonly attributes: NamedNodeMap; get classList(): DOMTokenList; set classList(value: string); className: string; readonly clientHeight: number; readonly clientLeft: number; readonly clientTop: number; readonly clientWidth: number; readonly currentCSSZoom: number; id: string; innerHTML: string; readonly localName: string; readonly namespaceURI: string | null; onfullscreenchange: ((this: Element, ev: Event) => any) | null; onfullscreenerror: ((this: Element, ev: Event) => any) | null; outerHTML: string; readonly ownerDocument: Document; get part(): DOMTokenList; set part(value: string); readonly prefix: string | null; readonly scrollHeight: number; scrollLeft: number; scrollTop: number; readonly scrollWidth: number; readonly shadowRoot: ShadowRoot | null; slot: string; readonly tagName: string; attachShadow(init: ShadowRootInit): ShadowRoot; checkVisibility(options?: CheckVisibilityOptions): boolean; closest(selector: K): HTMLElementTagNameMap[K] | null; closest(selector: K): SVGElementTagNameMap[K] | null; closest(selector: K): MathMLElementTagNameMap[K] | null; closest(selectors: string): E | null; computedStyleMap(): StylePropertyMapReadOnly; getAttribute(qualifiedName: string): string | null; getAttributeNS(namespace: string | null, localName: string): string | null; getAttributeNames(): string[]; getAttributeNode(qualifiedName: string): Attr | null; getAttributeNodeNS(namespace: string | null, localName: string): Attr | null; getBoundingClientRect(): DOMRect; getClientRects(): DOMRectList; getElementsByClassName(classNames: string): HTMLCollectionOf; getElementsByTagName(qualifiedName: K): HTMLCollectionOf; getElementsByTagName(qualifiedName: K): HTMLCollectionOf; getElementsByTagName(qualifiedName: K): HTMLCollectionOf; getElementsByTagName(qualifiedName: K): HTMLCollectionOf; getElementsByTagName(qualifiedName: string): HTMLCollectionOf; getElementsByTagNameNS(namespaceURI: "http://www.w3.org/1999/xhtml", localName: string): HTMLCollectionOf; getElementsByTagNameNS(namespaceURI: "http://www.w3.org/2000/svg", localName: string): HTMLCollectionOf; getElementsByTagNameNS(namespaceURI: "http://www.w3.org/1998/Math/MathML", localName: string): HTMLCollectionOf; getElementsByTagNameNS(namespace: string | null, localName: string): HTMLCollectionOf; getHTML(options?: GetHTMLOptions): string; hasAttribute(qualifiedName: string): boolean; hasAttributeNS(namespace: string | null, localName: string): boolean; hasAttributes(): boolean; hasPointerCapture(pointerId: number): boolean; insertAdjacentElement(where: InsertPosition, element: Element): Element | null; insertAdjacentHTML(position: InsertPosition, string: string): void; insertAdjacentText(where: InsertPosition, data: string): void; matches(selectors: string): boolean; releasePointerCapture(pointerId: number): void; removeAttribute(qualifiedName: string): void; removeAttributeNS(namespace: string | null, localName: string): void; removeAttributeNode(attr: Attr): Attr; requestFullscreen(options?: FullscreenOptions): Promise; requestPointerLock(options?: PointerLockOptions): Promise; scroll(options?: ScrollToOptions): void; scroll(x: number, y: number): void; scrollBy(options?: ScrollToOptions): void; scrollBy(x: number, y: number): void; scrollIntoView(arg?: boolean | ScrollIntoViewOptions): void; scrollTo(options?: ScrollToOptions): void; scrollTo(x: number, y: number): void; setAttribute(qualifiedName: string, value: string): void; setAttributeNS(namespace: string | null, qualifiedName: string, value: string): void; setAttributeNode(attr: Attr): Attr | null; setAttributeNodeNS(attr: Attr): Attr | null; setHTMLUnsafe(html: string): void; setPointerCapture(pointerId: number): void; toggleAttribute(qualifiedName: string, force?: boolean): boolean; webkitMatchesSelector(selectors: string): boolean; textContent: string; readonly baseURI: string; readonly childNodes: NodeListOf; readonly firstChild: ChildNode | null; readonly isConnected: boolean; readonly lastChild: ChildNode | null; readonly nextSibling: ChildNode | null; readonly nodeName: string; readonly nodeType: number; nodeValue: string | null; readonly parentElement: HTMLElement | null; readonly parentNode: ParentNode | null; readonly previousSibling: ChildNode | null; appendChild(node: T): T; cloneNode(subtree?: boolean): Node; compareDocumentPosition(other: Node): number; contains(other: Node | null): boolean; getRootNode(options?: GetRootNodeOptions): Node; hasChildNodes(): boolean; insertBefore(node: T, child: Node | null): T; isDefaultNamespace(namespace: string | null): boolean; isEqualNode(otherNode: Node | null): boolean; isSameNode(otherNode: Node | null): boolean; lookupNamespaceURI(prefix: string | null): string | null; lookupPrefix(namespace: string | null): string | null; normalize(): void; removeChild(child: T): T; replaceChild(node: Node, child: T): T; readonly ELEMENT_NODE: 1; readonly ATTRIBUTE_NODE: 2; readonly TEXT_NODE: 3; readonly CDATA_SECTION_NODE: 4; readonly ENTITY_REFERENCE_NODE: 5; readonly ENTITY_NODE: 6; readonly PROCESSING_INSTRUCTION_NODE: 7; readonly COMMENT_NODE: 8; readonly DOCUMENT_NODE: 9; readonly DOCUMENT_TYPE_NODE: 10; readonly DOCUMENT_FRAGMENT_NODE: 11; readonly NOTATION_NODE: 12; readonly DOCUMENT_POSITION_DISCONNECTED: 1; readonly DOCUMENT_POSITION_PRECEDING: 2; readonly DOCUMENT_POSITION_FOLLOWING: 4; readonly DOCUMENT_POSITION_CONTAINS: 8; readonly DOCUMENT_POSITION_CONTAINED_BY: 16; readonly DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC: 32; dispatchEvent(event: Event): boolean; dispatchEvent(event: Event): boolean; ariaActiveDescendantElement: Element | null; ariaAtomic: string | null; ariaAutoComplete: string | null; ariaBrailleLabel: string | null; ariaBrailleRoleDescription: string | null; ariaBusy: string | null; ariaChecked: string | null; ariaColCount: string | null; ariaColIndex: string | null; ariaColIndexText: string | null; ariaColSpan: string | null; ariaControlsElements: ReadonlyArray | null; ariaCurrent: string | null; ariaDescribedByElements: ReadonlyArray | null; ariaDescription: string | null; ariaDetailsElements: ReadonlyArray | null; ariaDisabled: string | null; ariaErrorMessageElements: ReadonlyArray | null; ariaExpanded: string | null; ariaFlowToElements: ReadonlyArray | null; ariaHasPopup: string | null; ariaHidden: string | null; ariaInvalid: string | null; ariaKeyShortcuts: string | null; ariaLabel: string | null; ariaLabelledByElements: ReadonlyArray | null; ariaLevel: string | null; ariaLive: string | null; ariaModal: string | null; ariaMultiLine: string | null; ariaMultiSelectable: string | null; ariaOrientation: string | null; ariaOwnsElements: ReadonlyArray | null; ariaPlaceholder: string | null; ariaPosInSet: string | null; ariaPressed: string | null; ariaReadOnly: string | null; ariaRelevant: string | null; ariaRequired: string | null; ariaRoleDescription: string | null; ariaRowCount: string | null; ariaRowIndex: string | null; ariaRowIndexText: string | null; ariaRowSpan: string | null; ariaSelected: string | null; ariaSetSize: string | null; ariaSort: string | null; ariaValueMax: string | null; ariaValueMin: string | null; ariaValueNow: string | null; ariaValueText: string | null; role: string | null; animate(keyframes: Keyframe[] | PropertyIndexedKeyframes | null, options?: number | KeyframeAnimationOptions): Animation; getAnimations(options?: GetAnimationsOptions): Animation[]; after(...nodes: (Node | string)[]): void; before(...nodes: (Node | string)[]): void; remove(): void; replaceWith(...nodes: (Node | string)[]): void; readonly nextElementSibling: Element | null; readonly previousElementSibling: Element | null; readonly childElementCount: number; readonly children: HTMLCollection; readonly firstElementChild: Element | null; readonly lastElementChild: Element | null; append(...nodes: (Node | string)[]): void; prepend(...nodes: (Node | string)[]): void; querySelector(selectors: K): HTMLElementTagNameMap[K] | null; querySelector(selectors: K): SVGElementTagNameMap[K] | null; querySelector(selectors: K): MathMLElementTagNameMap[K] | null; querySelector(selectors: K): HTMLElementDeprecatedTagNameMap[K] | null; querySelector(selectors: string): E | null; querySelectorAll(selectors: K): NodeListOf; querySelectorAll(selectors: K): NodeListOf; querySelectorAll(selectors: K): NodeListOf; querySelectorAll(selectors: K): NodeListOf; querySelectorAll(selectors: string): NodeListOf; replaceChildren(...nodes: (Node | string)[]): void; readonly assignedSlot: HTMLSlotElement | null; readonly attributeStyleMap: StylePropertyMap; get style(): CSSStyleDeclaration; set style(cssText: string); contentEditable: string; enterKeyHint: string; inputMode: string; readonly isContentEditable: boolean; onabort: ((this: GlobalEventHandlers, ev: UIEvent) => any) | null; onanimationcancel: ((this: GlobalEventHandlers, ev: AnimationEvent) => any) | null; onanimationend: ((this: GlobalEventHandlers, ev: AnimationEvent) => any) | null; onanimationiteration: ((this: GlobalEventHandlers, ev: AnimationEvent) => any) | null; onanimationstart: ((this: GlobalEventHandlers, ev: AnimationEvent) => any) | null; onauxclick: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; onbeforeinput: ((this: GlobalEventHandlers, ev: InputEvent) => any) | null; onbeforematch: ((this: GlobalEventHandlers, ev: Event) => any) | null; onbeforetoggle: ((this: GlobalEventHandlers, ev: ToggleEvent) => any) | null; onblur: ((this: GlobalEventHandlers, ev: FocusEvent) => any) | null; oncancel: ((this: GlobalEventHandlers, ev: Event) => any) | null; oncanplay: ((this: GlobalEventHandlers, ev: Event) => any) | null; oncanplaythrough: ((this: GlobalEventHandlers, ev: Event) => any) | null; onchange: ((this: GlobalEventHandlers, ev: Event) => any) | null; onclick: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; onclose: ((this: GlobalEventHandlers, ev: Event) => any) | null; oncontextlost: ((this: GlobalEventHandlers, ev: Event) => any) | null; oncontextmenu: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; oncontextrestored: ((this: GlobalEventHandlers, ev: Event) => any) | null; oncopy: ((this: GlobalEventHandlers, ev: ClipboardEvent) => any) | null; oncuechange: ((this: GlobalEventHandlers, ev: Event) => any) | null; oncut: ((this: GlobalEventHandlers, ev: ClipboardEvent) => any) | null; ondblclick: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; ondrag: ((this: GlobalEventHandlers, ev: DragEvent) => any) | null; ondragend: ((this: GlobalEventHandlers, ev: DragEvent) => any) | null; ondragenter: ((this: GlobalEventHandlers, ev: DragEvent) => any) | null; ondragleave: ((this: GlobalEventHandlers, ev: DragEvent) => any) | null; ondragover: ((this: GlobalEventHandlers, ev: DragEvent) => any) | null; ondragstart: ((this: GlobalEventHandlers, ev: DragEvent) => any) | null; ondrop: ((this: GlobalEventHandlers, ev: DragEvent) => any) | null; ondurationchange: ((this: GlobalEventHandlers, ev: Event) => any) | null; onemptied: ((this: GlobalEventHandlers, ev: Event) => any) | null; onended: ((this: GlobalEventHandlers, ev: Event) => any) | null; onerror: OnErrorEventHandler; onfocus: ((this: GlobalEventHandlers, ev: FocusEvent) => any) | null; onformdata: ((this: GlobalEventHandlers, ev: FormDataEvent) => any) | null; ongotpointercapture: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; oninput: ((this: GlobalEventHandlers, ev: Event) => any) | null; oninvalid: ((this: GlobalEventHandlers, ev: Event) => any) | null; onkeydown: ((this: GlobalEventHandlers, ev: KeyboardEvent) => any) | null; onkeypress: ((this: GlobalEventHandlers, ev: KeyboardEvent) => any) | null; onkeyup: ((this: GlobalEventHandlers, ev: KeyboardEvent) => any) | null; onload: ((this: GlobalEventHandlers, ev: Event) => any) | null; onloadeddata: ((this: GlobalEventHandlers, ev: Event) => any) | null; onloadedmetadata: ((this: GlobalEventHandlers, ev: Event) => any) | null; onloadstart: ((this: GlobalEventHandlers, ev: Event) => any) | null; onlostpointercapture: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; onmousedown: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; onmouseenter: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; onmouseleave: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; onmousemove: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; onmouseout: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; onmouseover: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; onmouseup: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; onpaste: ((this: GlobalEventHandlers, ev: ClipboardEvent) => any) | null; onpause: ((this: GlobalEventHandlers, ev: Event) => any) | null; onplay: ((this: GlobalEventHandlers, ev: Event) => any) | null; onplaying: ((this: GlobalEventHandlers, ev: Event) => any) | null; onpointercancel: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; onpointerdown: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; onpointerenter: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; onpointerleave: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; onpointermove: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; onpointerout: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; onpointerover: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; onpointerrawupdate: ((this: GlobalEventHandlers, ev: Event) => any) | null; onpointerup: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; onprogress: ((this: GlobalEventHandlers, ev: ProgressEvent) => any) | null; onratechange: ((this: GlobalEventHandlers, ev: Event) => any) | null; onreset: ((this: GlobalEventHandlers, ev: Event) => any) | null; onresize: ((this: GlobalEventHandlers, ev: UIEvent) => any) | null; onscroll: ((this: GlobalEventHandlers, ev: Event) => any) | null; onscrollend: ((this: GlobalEventHandlers, ev: Event) => any) | null; onsecuritypolicyviolation: ((this: GlobalEventHandlers, ev: SecurityPolicyViolationEvent) => any) | null; onseeked: ((this: GlobalEventHandlers, ev: Event) => any) | null; onseeking: ((this: GlobalEventHandlers, ev: Event) => any) | null; onselect: ((this: GlobalEventHandlers, ev: Event) => any) | null; onselectionchange: ((this: GlobalEventHandlers, ev: Event) => any) | null; onselectstart: ((this: GlobalEventHandlers, ev: Event) => any) | null; onslotchange: ((this: GlobalEventHandlers, ev: Event) => any) | null; onstalled: ((this: GlobalEventHandlers, ev: Event) => any) | null; onsubmit: ((this: GlobalEventHandlers, ev: SubmitEvent) => any) | null; onsuspend: ((this: GlobalEventHandlers, ev: Event) => any) | null; ontimeupdate: ((this: GlobalEventHandlers, ev: Event) => any) | null; ontoggle: ((this: GlobalEventHandlers, ev: ToggleEvent) => any) | null; ontouchcancel?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined; ontouchend?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined; ontouchmove?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined; ontouchstart?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined; ontransitioncancel: ((this: GlobalEventHandlers, ev: TransitionEvent) => any) | null; ontransitionend: ((this: GlobalEventHandlers, ev: TransitionEvent) => any) | null; ontransitionrun: ((this: GlobalEventHandlers, ev: TransitionEvent) => any) | null; ontransitionstart: ((this: GlobalEventHandlers, ev: TransitionEvent) => any) | null; onvolumechange: ((this: GlobalEventHandlers, ev: Event) => any) | null; onwaiting: ((this: GlobalEventHandlers, ev: Event) => any) | null; onwebkitanimationend: ((this: GlobalEventHandlers, ev: Event) => any) | null; onwebkitanimationiteration: ((this: GlobalEventHandlers, ev: Event) => any) | null; onwebkitanimationstart: ((this: GlobalEventHandlers, ev: Event) => any) | null; onwebkittransitionend: ((this: GlobalEventHandlers, ev: Event) => any) | null; onwheel: ((this: GlobalEventHandlers, ev: WheelEvent) => any) | null; autofocus: boolean; readonly dataset: DOMStringMap; nonce?: string; tabIndex: number; blur(): void; focus(options?: FocusOptions): void; }; /** Reference to the children component function */ __component__: JSX.Component

; observedAttributes: string[]; }; //# sourceMappingURL=custom_element.d.ts.map