domma-js 0.56.0 → 0.58.0

package/assets/types/generated/src/binding-source.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The adapter between Domma's data and the binding engine.
+ *
+ * ── The contract, and the two ways it fails ──────────────────────────────────
+ *
+ * `domma-reactive` resolves every expression - `{{ }}`, `data-bind-*`,
+ * `data-if`, `data-on-*`, `data-model` - against ONE object, and writes back
+ * through that same object. Both halves matter, and getting either wrong fails
+ * SILENTLY, in two specific ways that this module exists to prevent:
+ *
+ *   1. A read-only snapshot swallows every `data-model` write. The control
+ *      still looks correct, because what you see while typing is your own
+ *      keystrokes, but the model never changes and nothing else bound to that
+ *      field moves.
+ *
+ *   2. An object carrying no functions resolves no `data-on-*` handler. Every
+ *      event binding logs "did not resolve to a function" and does nothing,
+ *      while every other binding on the same element works perfectly.
+ *
+ * Both shipped, in `component-factory.js`, and were fixed in v0.37.0. The fix
+ * then existed twice - once there and once in `models.js` for `M.applyBindings`
+ * - in two slightly different shapes. This is that fix, once.
+ *
+ * ── Why a Proxy and not a merged object ──────────────────────────────────────
+ *
+ * Because reads must stay LIVE. A component's data is a snapshot, but
+ * `M.applyBindings` resolves against `model.tracked()`, where every read
+ * registers a dependency and every write routes through `set()`. Copying that
+ * into a plain object would flatten it into a snapshot and lose both halves.
+ *
+ * @module binding-source
+ */
+/**
+ * Build the object the binding engine reads from and writes through.
+ *
+ * @template {object} T
+ * @param {T}        primary            Reads resolve here first; writes land here.
+ *                                      For `M.applyBindings` this is a model's
+ *                                      `tracked()` view, which is what makes a
+ *                                      write reach the model.
+ * @param {object}   [options]
+ * @param {Record<string, any>} [options.fallback] Consulted only when `primary` has no such
+ *                                      key. Event handlers live here, so a data
+ *                                      field of the same name always wins - a
+ *                                      template mostly renders data, and a method
+ *                                      quietly shadowing a rendered value is the
+ *                                      worse failure.
+ * @param {(key: string, value: any) => void} [options.onWrite]  Called `(key, value)` after a write lands
+ *                                      on `primary`. Used where `primary` is a
+ *                                      snapshot that cannot route the write
+ *                                      itself, so the model has to be told.
+ * @returns {T} `primary` itself when there is nothing to layer, otherwise a
+ *                   Proxy over it.
+ */
+export function createBindingSource<T extends unknown>(primary: T, { fallback, onWrite }?: {
+    fallback?: Record<string, any>;
+    onWrite?: (key: string, value: any) => void;
+}): T;

package/assets/types/generated/src/butterfly-drawing.d.ts

@@ -0,0 +1,2 @@
+/** Painted butterfly silhouette; size is the fully open wingspan in pixels. */
+export function drawIllustratedButterfly(ctx: any, b: any): void;

package/assets/types/generated/src/component-factory.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Build and register a Custom Element class from a component definition.
+ *
+ * @template {Record<string, any>} [TData=Record<string, any>]
+ * @template {Record<string, any>} [TProps=Record<string, any>]
+ * @param {string} tagName     Custom element tag (must contain a hyphen, or `domma-` is prefixed)
+ * @param {ComponentDefinition<TData, TProps>} definition  Component definition object
+ * @returns {typeof DommaElement|undefined} The element class, or undefined when the tag is already registered
+ */
+export function createComponent<TData extends Record<string, any> = Record<string, any>, TProps extends Record<string, any> = Record<string, any>>(tagName: string, definition: ComponentDefinition<TData, TProps>): typeof DommaElement | undefined;
+export namespace components {
+    /**
+     * Define and register a new component.
+     *
+     * @template {Record<string, any>} [TData=Record<string, any>]
+     * @template {Record<string, any>} [TProps=Record<string, any>]
+     * @param {string} tagName     Custom element tag name
+     * @param {ComponentDefinition<TData, TProps>} definition  Component definition
+     * @returns {typeof DommaElement|undefined} The element class, or undefined when the tag is already registered
+     */
+    function define<TData extends Record<string, any> = Record<string, any>, TProps extends Record<string, any> = Record<string, any>>(tagName: string, definition: ComponentDefinition<TData, TProps>): typeof DommaElement | undefined;
+    /**
+     * Returns true if a component with this tag name has been registered.
+     * @param {string} tagName
+     * @returns {boolean}
+     */
+    function has(tagName: string): boolean;
+    /**
+     * Returns a copy of the component registry (for tooling / inspection).
+     * @returns {Map<string, ComponentDefinition>}
+     */
+    function registry(): Map<string, ComponentDefinition>;
+    const templateCache: Map<string, string>;
+}
+/**
+ * Valid primitive type tokens for component props.
+ */
+export type PropType = "string" | "number" | "boolean" | "array" | "object" | "any";
+/**
+ * A declared prop: an HTML attribute coerced to a type. `number` -> Number (NaN -> null),
+ * `boolean` -> '' / 'true' are true, 'false' false; `array` / `object` -> JSON.parse (the raw
+ * string when it is not JSON); anything else stays a string.
+ */
+export type PropDefinition = {
+    /**
+     * - Expected type - a token or an `M.types.*` constant
+     */
+    type?: PropType | ((value: any) => boolean);
+    /**
+     * - Marks the prop as required (documentation only - not enforced)
+     */
+    required?: boolean;
+    /**
+     * - Value used when the attribute is absent; a function is called for it
+     */
+    default?: any;
+};
+/**
+ * `this` inside a component's hooks, computed properties and methods. Computed properties are
+ * also on it as getters (`this.fullName`) and methods as bound functions (`this.save()`).
+ */
+export type ComponentContext<TData extends Record<string, any> = Record<string, any>, TProps extends Record<string, any> = Record<string, any>> = {
+    /**
+     * - Live, read-tracked view of the reactive data; reads inside a computed register a dependency
+     */
+    data: TData;
+    /**
+     * - Resolved prop values after type coercion (a copy)
+     */
+    props: TProps;
+    /**
+     * - The Shadow DOM root of this component
+     */
+    root: ShadowRoot;
+    /**
+     * - The host Custom Element
+     */
+    el: HTMLElement;
+    /**
+     * - Batch-update reactive data fields; bound template text updates surgically, then `onUpdated` runs
+     */
+    set: (updates: Partial<TData>) => void;
+};
+/**
+ * A component definition for `Domma.component(tagName, definition)`.
+ */
+export type ComponentDefinition<TData extends Record<string, any> = Record<string, any>, TProps extends Record<string, any> = Record<string, any>> = {
+    /**
+     * - Inline Mustache template string. Use `templateUrl` for non-trivial templates
+     */
+    template?: string;
+    /**
+     * - URL to an external HTML template file, fetched once and cached across all instances
+     */
+    templateUrl?: string;
+    /**
+     * - Declared HTML attributes (camelCase name, kebab-case attribute) with type coercion and defaults
+     */
+    props?: Record<string, PropDefinition>;
+    /**
+     * - Factory returning the component's initial reactive state; called once per instance. Declare every field here
+     */
+    data?: () => TData;
+    /**
+     * - Derived values, memoised and recalculated when a field they read changes; available in templates and as `this.name`
+     */
+    computed?: Record<string, (this: ComponentContext<TData, TProps>) => any>;
+    /**
+     * - Functions bound to the component context; callable as `this.name()` and from `data-on-*` bindings
+     */
+    methods?: Record<string, (this: ComponentContext<TData, TProps>, ...args: any[]) => any>;
+    /**
+     * - Scoped CSS injected into the component's Shadow DOM `<style>` block
+     */
+    style?: string;
+    /**
+     * - Called before the template is rendered. Data and props are available
+     */
+    onBeforeMount?: (this: ComponentContext<TData, TProps>) => void;
+    /**
+     * - Called after the template is rendered and bindings are established (again when the element is re-connected)
+     */
+    onMount?: (this: ComponentContext<TData, TProps>) => void;
+    /**
+     * - Called once per flush after any data change, and after a prop change re-renders
+     */
+    onUpdated?: (this: ComponentContext<TData, TProps>) => void;
+    /**
+     * - Called when the element is removed from the DOM, before clean-up
+     */
+    onBeforeUnmount?: (this: ComponentContext<TData, TProps>) => void;
+    /**
+     * - Called after the element is removed and cleaned up
+     */
+    onUnmount?: (this: ComponentContext<TData, TProps>) => void;
+    /**
+     * - Called when an observed attribute (prop) changes, with the camelCase prop name and the raw attribute values
+     */
+    onPropsChanged?: (this: ComponentContext<TData, TProps>, name: string, oldValue: string | null, newValue: string | null) => void;
+};
+/**
+ * Binding controller returned by `TemplateCompiler.compile()` (domma-reactive): surgical updates
+ * for bound fields, full re-renders for structural changes.
+ */
+export type TemplateBindings = import("../vendor/domma-reactive.js").BindingController;
+/**
+ * The `components` namespace (`Domma.components`).
+ */
+export type Components = typeof components;
+import { DommaElement } from './web-components/base/domma-element.js';

package/assets/types/generated/src/component.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Instances on an element, newest last.
+ * @param {Element} element
+ * @returns {Component[]}
+ */
+export function instancesOf(element: Element): Component[];
+/**
+ * The kind of an instance: a Component's `static componentName`, or a `componentName`
+ * on a plain handle (skeleton, avatar) that registered itself.
+ * @param {Object} instance
+ * @returns {string|undefined}
+ */
+export function componentNameOf(instance: any): string | undefined;
+/**
+ * The newest instance on an element, optionally of one component kind.
+ * @param {Element} element
+ * @param {string} [name] - componentName, e.g. 'slideover'
+ * @returns {Component|null}
+ */
+export function instanceOf(element: Element, name?: string): Component | null;
+/**
+ * Add an instance to the registry. Component does this itself; factories whose objects
+ * are not Components (wrappers, handles) call it so E.get finds them too.
+ * @param {Element} element
+ * @param {Object} instance
+ */
+export function register(element: Element, instance: any): void;
+/**
+ * @param {Element} element
+ * @param {Object} instance
+ */
+export function unregister(element: Element, instance: any): void;
+export default Component;
+/**
+ * A component event handler: gets the same arguments as the matching `onX` option.
+ * Returning false from a handler of a `before...` event cancels it.
+ */
+export type ComponentEventHandler = (...args: any[]) => any;
+/**
+ * The instance type every component shares (the Component base class).
+ */
+export type ComponentInstance = Component;
+/**
+ * A component event handler: gets the same arguments as the matching `onX` option.
+ * Returning false from a handler of a `before...` event cancels it.
+ * @typedef {(...args: any[]) => any} ComponentEventHandler
+ */
+/**
+ * The instance type every component shares (the Component base class).
+ * @typedef {Component} ComponentInstance
+ */
+declare class Component {
+    /** Used in `dm:<componentName>:<event>`. Subclasses set it - class names do not survive minification. */
+    static componentName: string;
+    /**
+     * @param {string|Element|null} [selector] - CSS selector or the host element
+     * @param {Record<string, any>} [options]
+     */
+    constructor(selector?: string | Element | null, options?: Record<string, any>);
+    /** The DOM element this component is attached to. @type {HTMLElement|null} */
+    element: HTMLElement | null;
+    /** Component options (defaults merged with what was passed). @type {Record<string, any>} */
+    options: Record<string, any>;
+    /** @protected @type {{element: EventTarget, event: string, handler: EventListenerOrEventListenerObject}[]} */
+    protected _eventHandlers: {
+        element: EventTarget;
+        event: string;
+        handler: EventListenerOrEventListenerObject;
+    }[];
+    /** @protected @type {Record<string, ComponentEventHandler[]>} */
+    protected _listeners: Record<string, ComponentEventHandler[]>;
+    /**
+     * Listen for a component event. The handler gets the same arguments as the matching
+     * `onX` option. Returning false from a handler of a `before...` event cancels it.
+     * @param {string} event - Event name, e.g. 'open', 'change', 'beforeclose'
+     * @param {ComponentEventHandler} handler
+     * @returns {this}
+     */
+    on(event: string, handler: ComponentEventHandler): this;
+    /**
+     * Listen once.
+     * @param {string} event
+     * @param {ComponentEventHandler} handler
+     * @returns {this}
+     */
+    once(event: string, handler: ComponentEventHandler): this;
+    /**
+     * Stop listening. Without a handler, removes every listener for the event.
+     * @param {string} event
+     * @param {ComponentEventHandler} [handler]
+     * @returns {this}
+     */
+    off(event: string, handler?: ComponentEventHandler): this;
+    /**
+     * Call the .on() listeners for an event.
+     * @param {string} event
+     * @param {...*} args
+     * @returns {boolean} false if a listener returned false
+     * @protected
+     */
+    protected _notify(event: string, ...args: any[]): boolean;
+    /**
+     * .on() listeners plus the `dm:<component>:<event>` DOM event - not the onX option.
+     * @param {string} event
+     * @param {...*} args
+     * @returns {boolean} false if a listener returned false or a DOM listener called preventDefault()
+     * @protected
+     */
+    protected _emit(event: string, ...args: any[]): boolean;
+    /**
+     * Fire an event the whole way: the `onX` option (called as `this.options.onX(...)` has
+     * always been called), then .on() listeners and the DOM event.
+     * @param {string} event - e.g. 'change' for onChange, 'beforeClose' or 'beforeclose' for onBeforeClose
+     * @param {...*} args
+     * @returns {*} the option's return value, or false when anything cancelled
+     * @protected
+     */
+    protected _fire(event: string, ...args: any[]): any;
+    /**
+     * The onX option for a lower-case event name ('beforeclose' -> onBeforeClose).
+     * @protected
+     * @param {string} key
+     * @returns {*}
+     */
+    protected _optionFor(key: string): any;
+    /**
+     * close() without the cancelable `beforeclose` - for destroy() and teardown that must
+     * not be refused. Still calls `this.close()` by name, so a patched close runs too.
+     * @param {...*} args - passed to close()
+     * @returns {*} close()'s return value
+     * @protected
+     */
+    protected _forcedClose(...args: any[]): any;
+    _forceClose: boolean;
+    /**
+     * The cancelable `beforeclose` an overlay's close() asks first. Skipped (true) while
+     * `_forcedClose()` runs.
+     * @param {...*} args - the same arguments onClose gets
+     * @returns {boolean} false when a handler refused
+     * @protected
+     */
+    protected _mayClose(...args: any[]): boolean;
+    /**
+     * Update component options at runtime
+     * @param {Record<string, any>} newOptions - New options to merge
+     * @returns {this} The component instance for chaining
+     */
+    setOptions(newOptions: Record<string, any>): this;
+    /**
+     * addEventListener that destroy() undoes.
+     * @protected
+     * @param {EventTarget} element
+     * @param {string} event
+     * @param {EventListenerOrEventListenerObject} handler
+     */
+    protected _addEventListener(element: EventTarget, event: string, handler: EventListenerOrEventListenerObject): void;
+    /**
+     * Destroy the component and clean up its event listeners.
+     * @returns {void}
+     */
+    destroy(): void;
+}

package/assets/types/generated/src/components/back-to-top.d.ts

@@ -0,0 +1,150 @@
+/**
+ * @typedef {object} BackToTopOptions
+ * @property {number|null} [showAfter] - Px scrolled before it shows (null: one viewport / container height)
+ * @property {number} [duration=300] - Scroll animation duration in ms (0 under reduced motion)
+ * @property {import('../elements.js').BackToTopPosition} [position='bottom-right'] - Button position
+ * @property {number|{bottom?: number, right?: number, left?: number}|null} [offset] - Px from the edges (null: the stylesheet's)
+ * @property {string|HTMLElement|null} [target] - Scroll container to watch (null: the window)
+ * @property {number|null} [zIndex] - z-index for the button
+ * @property {string} [label='Scroll back to top'] - aria-label when the button has none
+ * @property {((backToTop: BackToTopInstance) => void)|null} [onShow] - When the button shows
+ * @property {((backToTop: BackToTopInstance) => void)|null} [onHide] - When the button hides
+ * @property {((backToTop: BackToTopInstance) => void)|null} [onScroll] - When a scroll to the top starts
+ */
+/** @typedef {BackToTop} BackToTopInstance */
+export class BackToTop extends Component {
+    static defaults: {
+        showAfter: any;
+        duration: number;
+        position: string;
+        offset: any;
+        target: any;
+        zIndex: any;
+        label: string;
+        onShow: any;
+        onHide: any;
+        onScroll: any;
+    };
+    /**
+     * @param {import('./shared.js').ComponentTarget} selector - A button / link / `.dm-back-to-top` to use; anything else adds a button to the body
+     * @param {BackToTopOptions} [options]
+     */
+    constructor(selector: import("./shared.js").ComponentTarget, options?: BackToTopOptions);
+    _made: boolean;
+    _visible: boolean;
+    _scrolling: boolean;
+    /** The button element. @type {HTMLElement} */
+    button: HTMLElement;
+    _place(): void;
+    _container(): any;
+    _watch(): void;
+    _box: any;
+    _scrollTarget: any;
+    _onScroll: () => void;
+    _check(): void;
+    /**
+     * Scroll to the top; `duration` overrides the option for this call.
+     * @param {number} [duration] - ms
+     * @returns {this}
+     */
+    scroll(duration?: number): this;
+    /**
+     * Show the button.
+     * @returns {this}
+     */
+    show(): this;
+    /**
+     * Hide the button.
+     * @returns {this}
+     */
+    hide(): this;
+    /**
+     * Alias of show(), by name.
+     * @returns {this}
+     */
+    open(...args: any[]): this;
+    /**
+     * Alias of hide(), by name.
+     * @returns {this}
+     */
+    close(...args: any[]): this;
+    /**
+     * Toggle button visibility.
+     * @returns {this}
+     */
+    toggle(): this;
+    /** @returns {boolean} */
+    isVisible(): boolean;
+    /** @returns {boolean} */
+    isOpen(): boolean;
+    /**
+     * The button element.
+     * @returns {HTMLElement}
+     */
+    getButton(): HTMLElement;
+    /**
+     * @param {number|string|null} value - Px; null or '' for one viewport / container height
+     * @returns {this}
+     */
+    setShowAfter(value: number | string | null): this;
+    /**
+     * @param {import('../elements.js').BackToTopPosition} position
+     * @returns {this}
+     */
+    setPosition(position: import("../elements.js").BackToTopPosition): this;
+    /**
+     * @param {BackToTopOptions['offset']} offset
+     * @returns {this}
+     */
+    setOffset(offset: BackToTopOptions["offset"]): this;
+    _applyOptions(): void;
+}
+export default BackToTop;
+export type BackToTopOptions = {
+    /**
+     * - Px scrolled before it shows (null: one viewport / container height)
+     */
+    showAfter?: number | null;
+    /**
+     * - Scroll animation duration in ms (0 under reduced motion)
+     */
+    duration?: number;
+    /**
+     * - Button position
+     */
+    position?: import("../elements.js").BackToTopPosition;
+    /**
+     * - Px from the edges (null: the stylesheet's)
+     */
+    offset?: number | {
+        bottom?: number;
+        right?: number;
+        left?: number;
+    } | null;
+    /**
+     * - Scroll container to watch (null: the window)
+     */
+    target?: string | HTMLElement | null;
+    /**
+     * - z-index for the button
+     */
+    zIndex?: number | null;
+    /**
+     * - aria-label when the button has none
+     */
+    label?: string;
+    /**
+     * - When the button shows
+     */
+    onShow?: ((backToTop: BackToTopInstance) => void) | null;
+    /**
+     * - When the button hides
+     */
+    onHide?: ((backToTop: BackToTopInstance) => void) | null;
+    /**
+     * - When a scroll to the top starts
+     */
+    onScroll?: ((backToTop: BackToTopInstance) => void) | null;
+};
+export type BackToTopInstance = BackToTop;
+import Component from '../component.js';