| 1 | {"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"","sourcesContent":["export interface ProjectorService {\n /**\n * Instructs the projector to re-render to the DOM at the next animation-frame using the registered `render` functions.\n * This method is automatically called for you when event-handlers that are registered in the [[VNode]]s are invoked.\n *\n * You need to call this method when timeouts expire, when AJAX responses arrive or other asynchronous actions happen.\n */\n scheduleRender(): void;\n /**\n * Synchronously re-renders to the DOM. You should normally call the `scheduleRender()` function to keep the\n * user interface more performant. There is however one good reason to call renderNow(),\n * when you want to put the focus into a newly created element in iOS.\n * This is only allowed when triggered by a user-event, not during requestAnimationFrame.\n */\n renderNow(): void;\n}\n\nexport interface Projector extends ProjectorService {\n /**\n * Appends a new child node to the DOM using the result from the provided `renderFunction`.\n * The `renderFunction` will be invoked again to update the DOM when needed.\n * @param parentNode - The parent node for the new child node.\n * @param renderFunction - Function with zero arguments that returns a [[VNode]] tree.\n */\n append(parentNode: Element, renderFunction: () => VNode): void;\n /**\n * Inserts a new DOM node using the result from the provided `renderFunction`.\n * The `renderFunction` will be invoked again to update the DOM when needed.\n * @param beforeNode - The node that the DOM Node is inserted before.\n * @param renderFunction - Function with zero arguments that returns a [[VNode]] tree.\n */\n insertBefore(beforeNode: Element, renderFunction: () => VNode): void;\n /**\n * Merges a new DOM node using the result from the provided `renderFunction` with an existing DOM Node.\n * This means that the virtual DOM and real DOM have one overlapping element.\n * Therefore the selector for the root [[VNode]] will be ignored, but its properties and children will be applied to the Element provided\n * The `renderFunction` will be invoked again to update the DOM when needed.\n * @param domNode - The existing element to adopt as the root of the new virtual DOM. Existing attributes and child nodes are preserved.\n * @param renderFunction - Function with zero arguments that returns a [[VNode]] tree.\n */\n merge(domNode: Element, renderFunction: () => VNode): void;\n /**\n * Replaces an existing DOM node with the result from the provided `renderFunction`.\n * The `renderFunction` will be invoked again to update the DOM when needed.\n * @param domNode - The DOM node to replace.\n * @param renderFunction - Function with zero arguments that returns a [[VNode]] tree.\n */\n replace(domNode: Element, renderFunction: () => VNode): void;\n /**\n * Resumes the projector. Use this method to resume rendering after [[stop]] was called or an error occurred during rendering.\n */\n resume(): void;\n /**\n * Stops running the `renderFunction` to update the DOM. The `renderFunction` must have been\n * registered using [[append]], [[merge]], [[insertBefore]] or [[replace]].\n *\n * @returns The [[Projection]] which was created using this `renderFunction`.\n * The [[Projection]] contains a reference to the DOM Node that was rendered.\n */\n detach(renderFunction: () => VNode): Projection;\n /**\n * Stops the projector. This means that the registered `render` functions will not be called anymore.\n *\n * Note that calling [[stop]] is not mandatory. A projector is a passive object that will get garbage collected\n * as usual if it is no longer in scope.\n */\n stop(): void;\n}\n\n/**\n * A virtual representation of a DOM Node. Maquette assumes that [[VNode]] objects are never modified externally.\n * Instances of [[VNode]] can be created using [[h]].\n */\nexport interface VNode {\n /**\n * The CSS selector containing tagname, css classnames and id. An empty string is used to denote a text node.\n */\n readonly vnodeSelector: string;\n /**\n * Object containing attributes, properties, event handlers and more, see [[h]].\n */\n readonly properties: VNodeProperties | undefined;\n /**\n * Array of [[VNode]]s to be used as children. This array is already flattened.\n */\n readonly children: VNode[] | undefined;\n /**\n * Used in a special case when a [[VNode]] only has one child node which is a text node. Only used in combination with children === undefined.\n */\n readonly text: string | undefined;\n /**\n * Used by maquette to store the domNode that was produced from this [[VNode]].\n */\n domNode: Node | null;\n}\n\n/**\n * Object containing attributes, properties, event handlers and more that can be put on DOM nodes.\n *\n * For your convenience, all common attributes, properties and event handlers are listed here and are\n * type-checked when using Typescript.\n */\nexport interface VNodeProperties {\n /**\n * The animation to perform when this node is added to an already existing parent.\n * {@link http://maquettejs.org/docs/animations.html|More about animations}.\n * @param element - Element that was just added to the DOM.\n * @param properties - The properties object that was supplied to the [[h]] method\n */\n enterAnimation?: (element: Element, properties?: VNodeProperties) => void;\n /**\n * The animation to perform when this node is removed while its parent remains.\n * @param element - Element that ought to be removed from to the DOM.\n * @param removeElement - Function that removes the element from the DOM.\n * This argument is provided purely for convenience.\n * You may use this function to remove the element when the animation is done.\n * @param properties - The properties object that was supplied to the [[h]] method that rendered this [[VNode]] the previous time.\n */\n exitAnimation?(element: Element, removeElement: () => void, properties?: VNodeProperties): void;\n /**\n * The animation to perform when the properties of this node change.\n * This also includes attributes, styles, css classes. This callback is also invoked when node contains only text and that text changes.\n * {@link http://maquettejs.org/docs/animations.html|More about animations}.\n * @param element - Element that was modified in the DOM.\n * @param properties - The last properties object that was supplied to the [[h]] method\n * @param previousProperties - The previous properties object that was supplied to the [[h]] method\n */\n updateAnimation?(\n element: Element,\n properties?: VNodeProperties,\n previousProperties?: VNodeProperties\n ): void;\n /**\n * Callback that is executed after this node is added to the DOM. Child nodes and properties have\n * already been applied.\n * @param element - The element that was added to the DOM.\n * @param projectionOptions - The projection options that were used, see [[createProjector]].\n * @param vnodeSelector - The selector passed to the [[h]] function.\n * @param properties - The properties passed to the [[h]] function.\n * @param children - The children that were created.\n */\n afterCreate?(\n element: Element,\n projectionOptions: ProjectionOptions,\n vnodeSelector: string,\n properties: VNodeProperties,\n children: VNode[] | undefined\n ): void;\n /**\n * Callback that is executed every time this node may have been updated. Child nodes and properties\n * have already been updated.\n * @param element - The element that may have been updated in the DOM.\n * @param projectionOptions - The projection options that were used, see [[createProjector]].\n * @param vnodeSelector - The selector passed to the [[h]] function.\n * @param properties - The properties passed to the [[h]] function.\n * @param children - The children for this node.\n */\n afterUpdate?(\n element: Element,\n projectionOptions: ProjectionOptions,\n vnodeSelector: string,\n properties: VNodeProperties,\n children: VNode[] | undefined\n ): void;\n\n /**\n * Callback that is called when a node has been removed from the tree.\n * The callback is called during idle state or after a timeout (fallback).\n * {@link https://maquettejs.org/docs/dom-node-removal.html|More info}\n * @param element - The element that has been removed from the DOM.\n */\n afterRemoved?(element: Element): void;\n /**\n * When specified, the event handlers will be invoked with 'this' pointing to the value.\n * This is useful when using the prototype/class based implementation of MaquetteComponents.\n *\n * When no [[key]] is present, this object is also used to uniquely identify a DOM node.\n */\n readonly bind?: unknown;\n /**\n * Used to uniquely identify a DOM node among siblings.\n * A key is required when there are more children with the same selector and these children are added or removed dynamically.\n * NOTE: this does not have to be a string or number, a [[MaquetteComponent]] Object for instance is also common.\n */\n readonly key?: unknown;\n /**\n * An object literal like `{important:true}` which allows css classes, like `important` to be added and removed\n * dynamically.\n */\n readonly classes?: { [index: string]: boolean | null | undefined };\n /**\n * An object literal like `{height:'100px'}` which allows styles to be changed dynamically. All values must be strings.\n */\n readonly styles?: Partial<CSSStyleDeclaration> | { [cssVariable: string]: string };\n\n // From Element\n ontouchcancel?(ev: TouchEvent): boolean | void;\n ontouchend?(ev: TouchEvent): boolean | void;\n ontouchmove?(ev: TouchEvent): boolean | void;\n ontouchstart?(ev: TouchEvent): boolean | void;\n // From HTMLFormElement\n readonly action?: string;\n readonly encoding?: string;\n readonly enctype?: string;\n readonly method?: string;\n readonly name?: string;\n readonly target?: string;\n // From HTMLAnchorElement\n readonly href?: string;\n readonly rel?: string;\n // From HTMLElement\n onblur?(ev: FocusEvent): boolean | void;\n onchange?(ev: Event): boolean | void;\n onclick?(ev: MouseEvent): boolean | void;\n ondblclick?(ev: MouseEvent): boolean | void;\n ondrag?(ev: DragEvent): boolean | void;\n ondragend?(ev: DragEvent): boolean | void;\n ondragenter?(ev: DragEvent): boolean | void;\n ondragleave?(ev: DragEvent): boolean | void;\n ondragover?(ev: DragEvent): boolean | void;\n ondragstart?(ev: DragEvent): boolean | void;\n ondrop?(ev: DragEvent): boolean | void;\n onfocus?(ev: FocusEvent): boolean | void;\n oninput?(ev: Event): boolean | void;\n onkeydown?(ev: KeyboardEvent): boolean | void;\n onkeypress?(ev: KeyboardEvent): boolean | void;\n onkeyup?(ev: KeyboardEvent): boolean | void;\n onload?(ev: Event): boolean | void;\n onmousedown?(ev: MouseEvent): boolean | void;\n onmouseenter?(ev: MouseEvent): boolean | void;\n onmouseleave?(ev: MouseEvent): boolean | void;\n onmousemove?(ev: MouseEvent): boolean | void;\n onmouseout?(ev: MouseEvent): boolean | void;\n onmouseover?(ev: MouseEvent): boolean | void;\n onmouseup?(ev: MouseEvent): boolean | void;\n onmousewheel?(ev: WheelEvent): boolean | void;\n onscroll?(ev: UIEvent): boolean | void;\n onsubmit?(ev: Event): boolean | void;\n readonly spellcheck?: boolean;\n readonly tabIndex?: number;\n readonly disabled?: boolean;\n readonly title?: string;\n readonly accessKey?: string;\n readonly class?: string;\n readonly id?: string;\n readonly draggable?: boolean;\n // From HTMLInputElement\n readonly type?: string;\n readonly autocomplete?: string;\n readonly checked?: boolean;\n readonly placeholder?: string;\n readonly readOnly?: boolean;\n readonly src?: string;\n readonly value?: string;\n // From HTMLImageElement\n readonly alt?: string;\n readonly srcset?: string;\n /**\n * Puts a non-interactive string of html inside the DOM node.\n *\n * Note: if you use innerHTML, maquette cannot protect you from XSS vulnerabilities and you must make sure that the innerHTML value is safe.\n */\n readonly innerHTML?: string;\n\n /**\n * Do not use className, use class instead\n */\n readonly className?: never | \"Hint: do not use `className`, use `class` instead\";\n\n /**\n * Everything that is not explicitly listed (properties and attributes that are either uncommon or custom).\n */\n readonly [index: string]: any;\n}\n\n/**\n * Only needed for the definition of [[VNodeChild]].\n */\nexport interface VNodeChildren extends Array<VNodeChild> {}\n/**\n * These are valid values for the children parameter of the [[h]] function.\n */\nexport type VNodeChild = string | VNode | VNodeChildren | false | null | undefined;\n\n/**\n * Represents a [[VNode]] tree that has been rendered to a real DOM tree.\n */\nexport interface Projection {\n /**\n * The DOM node that is used as the root of this [[Projection]].\n */\n readonly domNode: Element;\n /**\n * Updates the real DOM to match the new virtual DOM tree.\n * @param updatedVnode The updated virtual DOM tree. Note: The selector for the root of the [[VNode]] tree may not change.\n */\n update(updatedVnode: VNode): void;\n getLastRender(): VNode;\n}\n\nexport type EventHandler = (this: Node, event: Event) => boolean | undefined | void;\n\n/**\n * Options that influence how the DOM is rendered and updated.\n */\nexport type EventHandlerInterceptor = (\n propertyName: string,\n eventHandler: EventHandler,\n domNode: Node,\n properties: VNodeProperties\n) => undefined | EventHandler;\n\nexport type PerformanceLoggerEvent =\n | \"domEvent\"\n | \"domEventProcessed\"\n | \"renderStart\"\n | \"rendered\"\n | \"patched\"\n | \"renderDone\";\nexport type ProjectorPerformanceLogger = (\n eventType: PerformanceLoggerEvent,\n trigger: Event | undefined\n) => void;\n/**\n * Options that may be passed when creating the [[Projector]]\n */\nexport interface ProjectorOptions {\n /**\n * Can be used to log performance metrics\n */\n performanceLogger?: ProjectorPerformanceLogger;\n\n /**\n * May be used to add vendor prefixes when applying inline styles when needed.\n * This function is called when [[styles]] is used.\n * This function should execute `domNode.style[styleName] = value` or do something smarter.\n *\n * @param domNode The DOM Node that needs to receive the style\n * @param styleName The name of the style that should be applied, for example `transform`.\n * @param value The value of this style, for example `rotate(45deg)`.\n */\n styleApplyer?(domNode: HTMLElement, styleName: string, value: string): void;\n}\n\nexport interface ProjectionOptions extends ProjectorOptions {\n /**\n * Only for internal use. Used for rendering SVG Nodes.\n */\n readonly namespace?: string;\n /**\n * May be used to intercept registration of event-handlers.\n *\n * Used by the [[Projector]] to wrap eventHandler-calls to call [[scheduleRender]] as well.\n *\n * @param propertyName The name of the property to be assigned, for example onclick\n * @param eventHandler The function that was registered on the [[VNode]]\n * @param domNode The real DOM element\n * @param properties The whole set of properties that was put on the VNode\n * @returns The function that is to be placed on the DOM node as the event handler, instead of `eventHandler`.\n */\n eventHandlerInterceptor?: EventHandlerInterceptor;\n}\n\n/**\n * Keeps an array of result objects synchronized with an array of source objects.\n * See {@link http://maquettejs.org/docs/arrays.html|Working with arrays}.\n *\n * Mapping provides a [[map]] function that updates its [[results]].\n * The [[map]] function can be called multiple times and the results will get created, removed and updated accordingly.\n * A Mapping can be used to keep an array of components (objects with a `render` method) synchronized with an array of data.\n * Instances of Mapping can be created using [[createMapping]].\n *\n * @param <Source> The type of source elements. Usually the data type.\n * @param <Target> The type of target elements. Usually the component type.\n */\nexport interface Mapping<Source, Target> {\n /**\n * The array of results. These results will be synchronized with the latest array of sources that were provided using [[map]].\n */\n results: Target[];\n /**\n * Maps a new array of sources and updates [[results]].\n *\n * @param newSources The new array of sources.\n */\n map(newSources: Source[]): void;\n}\n\n/**\n * A CalculationCache object remembers the previous outcome of a calculation along with the inputs.\n * On subsequent calls the previous outcome is returned if the inputs are identical.\n * This object can be used to bypass both rendering and diffing of a virtual DOM subtree.\n * Instances of CalculationCache can be created using [[createCache]].\n *\n * @param <Result> The type of the value that is cached.\n */\nexport interface CalculationCache<Result> {\n /**\n * Manually invalidates the cached outcome.\n */\n invalidate(): void;\n /**\n * If the inputs array matches the inputs array from the previous invocation, this method returns the result of the previous invocation.\n * Otherwise, the calculation function is invoked and its result is cached and returned.\n * Objects in the inputs array are compared using ===.\n * @param inputs - Array of objects that are to be compared using === with the inputs from the previous invocation.\n * These objects are assumed to be immutable primitive values.\n * @param calculation - Function that takes zero arguments and returns an object (A [[VNode]] presumably) that can be cached.\n */\n result(inputs: unknown[], calculation: () => Result): Result;\n}\n\n/**\n * @deprecated Use [[MaquetteComponent]] instead.\n * @since 3.0\n */\nexport interface Component {\n renderMaquette(): VNode | null | undefined;\n}\n\n/**\n * A component is a pattern with which you can split up your web application into self-contained parts.\n *\n * A component may contain other components.\n * This can be achieved by calling the subcomponents `render` functions during the [[render]] function and by using the\n * resulting [[VNode]]s in the return value.\n *\n * This interface is not used anywhere in the maquette sourcecode, but this is a widely used pattern.\n */\nexport interface MaquetteComponent {\n /**\n * A function that returns the DOM representation of the component.\n */\n render(): VNode | null | undefined;\n}\n\nexport interface Dom {\n /**\n * Creates a real DOM tree from `vnode`. The [[Projection]] object returned will contain the resulting DOM Node in\n * its [[Projection.domNode|domNode]] property.\n * This is a low-level method. Users will typically use a [[Projector]] instead.\n * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]]\n * objects may only be rendered once.\n * @param projectionOptions - Options to be used to create and update the projection.\n * @returns The [[Projection]] which also contains the DOM Node that was created.\n */\n create(vnode: VNode, projectionOptions?: ProjectionOptions): Projection;\n\n /**\n * Appends a new child node to the DOM which is generated from a [[VNode]].\n * This is a low-level method. Users will typically use a [[Projector]] instead.\n * @param parentNode - The parent node for the new child node.\n * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]]\n * objects may only be rendered once.\n * @param projectionOptions - Options to be used to create and update the [[Projection]].\n * @returns The [[Projection]] that was created.\n */\n append(parentNode: Element, vnode: VNode, projectionOptions?: ProjectionOptions): Projection;\n\n /**\n * Inserts a new DOM node which is generated from a [[VNode]].\n * This is a low-level method. Users wil typically use a [[Projector]] instead.\n * @param beforeNode - The node that the DOM Node is inserted before.\n * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function.\n * NOTE: [[VNode]] objects may only be rendered once.\n * @param projectionOptions - Options to be used to create and update the projection, see [[createProjector]].\n * @returns The [[Projection]] that was created.\n */\n insertBefore(\n beforeNode: Element,\n vnode: VNode,\n projectionOptions?: ProjectionOptions\n ): Projection;\n\n /**\n * Merges a new DOM node which is generated from a [[VNode]] with an existing DOM Node.\n * This means that the virtual DOM and the real DOM will have one overlapping element.\n * Therefore the selector for the root [[VNode]] will be ignored, but its properties and children will be applied to the Element provided.\n * This is a low-level method. Users wil typically use a [[Projector]] instead.\n * @param element - The existing element to adopt as the root of the new virtual DOM. Existing attributes and child nodes are preserved.\n * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]] objects\n * may only be rendered once.\n * @param projectionOptions - Options to be used to create and update the projection, see [[createProjector]].\n * @returns The [[Projection]] that was created.\n */\n merge(element: Element, vnode: VNode, projectionOptions?: ProjectionOptions): Projection;\n\n /**\n * Replaces an existing DOM node with a node generated from a [[VNode]].\n * This is a low-level method. Users will typically use a [[Projector]] instead.\n * @param element - The node for the [[VNode]] to replace.\n * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]]\n * objects may only be rendered once.\n * @param projectionOptions - Options to be used to create and update the [[Projection]].\n * @returns The [[Projection]] that was created.\n */\n replace(element: Element, vnode: VNode, projectionOptions?: ProjectionOptions): Projection;\n}\n"]} |