domma-js 0.55.0 → 0.57.0

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

@@ -0,0 +1,270 @@
+/**
+ * Initials for a name.
+ *
+ *   'Jane Smith'             -> 'JS'   first and last word
+ *   'Jane Q. Public'         -> 'JP'
+ *   'Madonna'                -> 'M'    one word, one letter
+ *   'jane.smith@example.com' -> 'JS'   the part before the @, split on . _ - +
+ *   'Jean-Luc Picard'        -> 'JP'
+ *   'Łukasz Żuk'             -> 'ŁŻ'
+ *   '王小明'                  -> '王'
+ *   '', null, '  !! '        -> ''     nothing to go on: callers show an icon
+ *
+ * Words are split on spaces, dots, underscores, hyphens and plus signs;
+ * anything that is not a letter or digit at the start of a word (quotes,
+ * brackets, emoji) is skipped, and bracketed notes like "(Admin)" are dropped.
+ * @param {string|null|undefined} name
+ * @returns {string}
+ */
+export function avatarInitials(name: string | null | undefined): string;
+/**
+ * The tone (0-7) for a name: FNV-1a over the trimmed, lower-cased, single-spaced
+ * name. Stable across pages, sessions and machines; case and spacing do not
+ * change it, so 'jane smith' and 'Jane  Smith' match.
+ * @param {string} key
+ * @returns {number}
+ */
+export function avatarTone(key: string): number;
+/**
+ * Render one avatar.
+ * @overload
+ * @param {string|Element|ArrayLike<Element>|null} target
+ * @param {AvatarOptions} [options]
+ * @returns {AvatarHandle|null}
+ */
+export function avatar(target: string | Element | ArrayLike<Element> | null, options?: AvatarOptions): AvatarHandle | null;
+/**
+ * Render one avatar into a detached <span> for you to insert.
+ * @overload
+ * @param {AvatarOptions} options
+ * @returns {AvatarHandle}
+ */
+export function avatar(options: AvatarOptions): AvatarHandle;
+export namespace avatar {
+    export { avatarInitials as initials };
+    export { avatarTone as tone };
+    /**
+     * The live handle on an element, if any - the same answer as E.get(target, 'avatar').
+     * @param {string|Element|ArrayLike<Element>} target
+     * @returns {AvatarHandle|null}
+     */
+    export function get(target: string | Element | ArrayLike<Element>): AvatarHandle | null;
+    /**
+     * Turn every `[data-avatar]` under `root` (and `root` itself) into an avatar,
+     * once. Options come from `data-avatar-*`. Returns the new handles.
+     * @param {string|Element|Document} [root]
+     * @returns {AvatarHandle[]}
+     */
+    export function scan(root?: string | Element | Document): AvatarHandle[];
+}
+/**
+ * Render a stack of avatars with a "+N" overflow bubble.
+ *
+ * @param {string|Element|ArrayLike<Element>} target - a <ul>/<ol> to fill, or any element
+ *   to put a new <ul> into (its content comes back on destroy())
+ * @param {AvatarGroupOptions} [options] - see GROUP_DEFAULTS
+ * @returns {AvatarGroupHandle|null} null if nothing matched
+ */
+export function avatarGroup(target: string | Element | ArrayLike<Element>, options?: AvatarGroupOptions): AvatarGroupHandle | null;
+export namespace avatarGroup {
+    /**
+     * The live group handle on a host element (or its list), if any - the same answer as E.get(target, 'avatar-group').
+     * @param {string|Element|ArrayLike<Element>} target
+     * @returns {AvatarGroupHandle|null}
+     */
+    function get(target: string | Element | ArrayLike<Element>): AvatarGroupHandle | null;
+}
+/** @type {AvatarSize[]} */
+export const AVATAR_SIZES: AvatarSize[];
+/** @type {AvatarShape[]} */
+export const AVATAR_SHAPES: AvatarShape[];
+/** @type {AvatarStatus[]} */
+export const AVATAR_STATUSES: AvatarStatus[];
+/** How many `.avatar-tone-*` classes elements.css defines. */
+export const AVATAR_TONES: 8;
+export default avatar;
+export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
+export type AvatarShape = "circle" | "rounded" | "square";
+export type AvatarStatus = "online" | "away" | "busy" | "offline";
+export type AvatarOptions = {
+    /**
+     * - The person: initials, tone and accessible name come from it
+     */
+    name?: string | null;
+    /**
+     * - Picture URL; falls back to the initials (or icon) if it fails to load
+     */
+    src?: string | null;
+    /**
+     * - Accessible name when it should differ from name
+     */
+    alt?: string | null;
+    /**
+     * - Size (default 'md')
+     */
+    size?: AvatarSize;
+    /**
+     * - Shape (default 'circle')
+     */
+    shape?: AvatarShape;
+    /**
+     * - Status dot; the word goes into the accessible name
+     */
+    status?: AvatarStatus | null;
+    /**
+     * - Words for the statuses in the accessible name, e.g. {busy: 'in a meeting'}
+     */
+    statusLabels?: Partial<Record<AvatarStatus, string>> | null;
+    /**
+     * - Icon name shown instead of initials ('user' when there is no name)
+     */
+    icon?: string | null;
+    /**
+     * - Hover text; true = the accessible name
+     */
+    title?: string | true | null;
+    /**
+     * - A primary-coloured ring (default false)
+     */
+    ring?: boolean;
+    /**
+     * - 0-7 to choose the tint; default is a hash of the name
+     */
+    tone?: number | null;
+    /**
+     * - aria-hidden: the name is written next to it (default false)
+     */
+    decorative?: boolean;
+};
+/**
+ * The handle E.avatar() returns. `options`, `initials`, `tone` and `label` are read only.
+ */
+export type AvatarHandle = {
+    /**
+     * - The avatar element
+     */
+    element: HTMLElement;
+    /**
+     * - The options in force
+     */
+    options: AvatarOptions;
+    /**
+     * - The initials drawn ('' when an icon is shown)
+     */
+    initials: string;
+    /**
+     * - The tone 0-7, or null with nothing to hash
+     */
+    tone: number | null;
+    /**
+     * - The accessible name, e.g. 'Jane Smith (online)'
+     */
+    label: string;
+    /**
+     * - Merge options and redraw
+     */
+    update: (options?: AvatarOptions) => AvatarHandle;
+    /**
+     * - Restore the element's previous children, classes and attributes
+     */
+    destroy: () => HTMLElement;
+};
+/**
+ * `E.avatar` - the factory with `initials`, `tone`, `get` and `scan`.
+ */
+export type AvatarStatic = typeof avatar;
+/**
+ * One person in an avatar group.
+ */
+export type AvatarPerson = {
+    name?: string;
+    src?: string;
+    status?: AvatarStatus;
+    /**
+     * - Makes the avatar a link
+     */
+    href?: string;
+    alt?: string;
+    icon?: string;
+    tone?: number;
+    /**
+     * - Hover text (default: the accessible name)
+     */
+    title?: string | true;
+};
+export type AvatarGroupOptions = {
+    /**
+     * - People, or plain names
+     */
+    people?: Array<AvatarPerson | string>;
+    /**
+     * - Show this many, then "+N"; null = everyone
+     */
+    max?: number | null;
+    /**
+     * - Size (default 'md')
+     */
+    size?: AvatarSize;
+    /**
+     * - Shape (default 'circle')
+     */
+    shape?: AvatarShape;
+    /**
+     * - 'none' | 'sm' | 'md' | 'lg', pixels, or any CSS length; null = the stylesheet's 25%
+     */
+    overlap?: "none" | "sm" | "md" | "lg" | number | string | null;
+    /**
+     * - Accessible name for the list
+     */
+    label?: string | null;
+    statusLabels?: Partial<Record<AvatarStatus, string>> | null;
+    /**
+     * - Called when "+N" is pressed, instead of the popover
+     */
+    onMore?: ((hidden: AvatarPerson[], event: MouseEvent) => void) | null;
+    /**
+     * - false: no popover, the hidden names go in the button's title (default true)
+     */
+    popover?: boolean;
+    /**
+     * - The "+N" button's accessible name (default '3 more: A, B and C')
+     */
+    moreLabel?: ((count: number, names: string[]) => string) | null;
+};
+/**
+ * The handle E.avatarGroup() returns. Everything but the methods is read only.
+ */
+export type AvatarGroupHandle = {
+    /**
+     * - The <ul>
+     */
+    element: HTMLUListElement | HTMLOListElement;
+    options: AvatarGroupOptions;
+    people: AvatarPerson[];
+    /**
+     * - Drawn as avatars
+     */
+    shown: AvatarPerson[];
+    /**
+     * - Folded into "+N"
+     */
+    hidden: AvatarPerson[];
+    /**
+     * - The "+N" button, or null
+     */
+    more: HTMLButtonElement | null;
+    /**
+     * - The "+N" popover, or null
+     */
+    popover: import("./popover.js").PopoverInstance | null;
+    update: (options?: AvatarGroupOptions) => AvatarGroupHandle;
+    setPeople: (people: Array<AvatarPerson | string>) => AvatarGroupHandle;
+    /**
+     * - Remove everything and restore the host
+     */
+    destroy: () => HTMLElement;
+};
+/**
+ * `E.avatarGroup` - the factory with `get`.
+ */
+export type AvatarGroupStatic = typeof avatarGroup;

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;
+}