p-elements-core 1.2.15 → 1.2.16

package/src/{dom.ts → maquette/dom.ts}

@@ -1,133 +1,115 @@
-import {
-  createDom,
-  createProjection,
-  extend,
-  initPropertiesAndChildren,
-} from "./projection";
-
-const missingTransition = () => {
-  throw new Error(
-    "Provide a transitions object to the projectionOptions to do animations"
-  );
-};
-
-const DEFAULT_PROJECTION_OPTIONS: ProjectionOptions = {
-  namespace: undefined,
-  eventHandlerInterceptor: undefined,
-  styleApplyer: (domNode: HTMLElement, styleName: string, value: string) => {
-    // Provides a hook to add vendor prefixes for browsers that still need it.
-    (domNode.style as any)[styleName] = value;
-  },
-  transitions: {
-    enter: missingTransition,
-    exit: missingTransition,
-  },
-};
-
-export const applyDefaultProjectionOptions = (
-  projectorOptions?: ProjectionOptions
-) => {
-  return extend(DEFAULT_PROJECTION_OPTIONS, projectorOptions);
-};
-
-export const dom = {
-  /**
-   * Creates a real DOM tree from `vnode`. The [[Projection]] object returned will contain the resulting DOM Node in
-   * its [[Projection.domNode|domNode]] property.
-   * This is a low-level method. Users will typically use a [[Projector]] instead.
-   * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]]
-   * objects may only be rendered once.
-   * @param projectionOptions - Options to be used to create and update the projection.
-   * @returns The [[Projection]] which also contains the DOM Node that was created.
-   */
-  create: (vnode: VNode, projectionOptions?: ProjectionOptions): Projection => {
-    projectionOptions = applyDefaultProjectionOptions(projectionOptions);
-    createDom(
-      vnode,
-      document.createElement("div"),
-      undefined,
-      projectionOptions
-    );
-    return createProjection(vnode, projectionOptions);
-  },
-
-  /**
-   * Appends a new child node to the DOM which is generated from a [[VNode]].
-   * This is a low-level method. Users will typically use a [[Projector]] instead.
-   * @param parentNode - The parent node for the new child node.
-   * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]]
-   * objects may only be rendered once.
-   * @param projectionOptions - Options to be used to create and update the [[Projection]].
-   * @returns The [[Projection]] that was created.
-   */
-  append: (
-    parentNode: Element,
-    vnode: VNode,
-    projectionOptions?: ProjectionOptions
-  ): Projection => {
-    projectionOptions = applyDefaultProjectionOptions(projectionOptions);
-    createDom(vnode, parentNode, undefined, projectionOptions);
-    return createProjection(vnode, projectionOptions);
-  },
-
-  /**
-   * Inserts a new DOM node which is generated from a [[VNode]].
-   * This is a low-level method. Users wil typically use a [[Projector]] instead.
-   * @param beforeNode - The node that the DOM Node is inserted before.
-   * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function.
-   * NOTE: [[VNode]] objects may only be rendered once.
-   * @param projectionOptions - Options to be used to create and update the projection, see [[createProjector]].
-   * @returns The [[Projection]] that was created.
-   */
-  insertBefore: (
-    beforeNode: Element,
-    vnode: VNode,
-    projectionOptions?: ProjectionOptions
-  ): Projection => {
-    projectionOptions = applyDefaultProjectionOptions(projectionOptions);
-    createDom(vnode, beforeNode.parentNode!, beforeNode, projectionOptions);
-    return createProjection(vnode, projectionOptions);
-  },
-
-  /**
-   * Merges a new DOM node which is generated from a [[VNode]] with an existing DOM Node.
-   * This means that the virtual DOM and the real DOM will have one overlapping element.
-   * Therefore the selector for the root [[VNode]] will be ignored, but its properties and children will be applied to the Element provided.
-   * This is a low-level method. Users wil typically use a [[Projector]] instead.
-   * @param element - The existing element to adopt as the root of the new virtual DOM. Existing attributes and child nodes are preserved.
-   * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]] objects
-   * may only be rendered once.
-   * @param projectionOptions - Options to be used to create and update the projection, see [[createProjector]].
-   * @returns The [[Projection]] that was created.
-   */
-  merge: (
-    element: Element,
-    vnode: VNode,
-    projectionOptions?: ProjectionOptions
-  ): Projection => {
-    projectionOptions = applyDefaultProjectionOptions(projectionOptions);
-    vnode.domNode = element;
-    initPropertiesAndChildren(element, vnode, projectionOptions);
-    return createProjection(vnode, projectionOptions);
-  },
-
-  /**
-   * Replaces an existing DOM node with a node generated from a [[VNode]].
-   * This is a low-level method. Users will typically use a [[Projector]] instead.
-   * @param element - The node for the [[VNode]] to replace.
-   * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]]
-   * objects may only be rendered once.
-   * @param projectionOptions - Options to be used to create and update the [[Projection]].
-   * @returns The [[Projection]] that was created.
-   */
-  replace: (
-    element: Element,
-    vnode: VNode,
-    projectionOptions?: ProjectionOptions
-  ): Projection => {
-    projectionOptions = applyDefaultProjectionOptions(projectionOptions);
-    createDom(vnode, element.parentNode!, element, projectionOptions);
-    element.parentNode!.removeChild(element);
-    return createProjection(vnode, projectionOptions);
-  },
-};
+/**
+ * Contains simple low-level utility functions to manipulate the real DOM.
+ */
+import { Projection, ProjectionOptions, VNode } from "./interfaces";
+import { createDom, createProjection, extend, initPropertiesAndChildren } from "./projection";
+
+const DEFAULT_PROJECTION_OPTIONS: ProjectionOptions = {
+  namespace: undefined,
+  performanceLogger: () => undefined,
+  eventHandlerInterceptor: undefined,
+  styleApplyer: (domNode: HTMLElement, styleName: string, value: string) => {
+    if (styleName.charAt(0) === "-") {
+      // CSS variables must be set using setProperty
+      domNode.style.setProperty(styleName, value);
+    } else {
+      // properties like 'backgroundColor' must be set as a js-property
+      (domNode.style as any)[styleName] = value;
+    }
+  },
+};
+
+export let applyDefaultProjectionOptions = (
+  projectorOptions?: ProjectionOptions
+): ProjectionOptions => {
+  return extend(DEFAULT_PROJECTION_OPTIONS, projectorOptions);
+};
+
+export let dom = {
+  /**
+   * Creates a real DOM tree from `vnode`. The [[Projection]] object returned will contain the resulting DOM Node in
+   * its [[Projection.domNode|domNode]] property.
+   * This is a low-level method. Users will typically use a [[Projector]] instead.
+   * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]]
+   * objects may only be rendered once.
+   * @param projectionOptions - Options to be used to create and update the projection.
+   * @returns The [[Projection]] which also contains the DOM Node that was created.
+   */
+  create: (vnode: VNode, projectionOptions?: ProjectionOptions): Projection => {
+    projectionOptions = applyDefaultProjectionOptions(projectionOptions);
+    createDom(vnode, document.createElement("div"), undefined, projectionOptions);
+    return createProjection(vnode, projectionOptions);
+  },
+
+  /**
+   * Appends a new child node to the DOM which is generated from a [[VNode]].
+   * This is a low-level method. Users will typically use a [[Projector]] instead.
+   * @param parentNode - The parent node for the new child node.
+   * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]]
+   * objects may only be rendered once.
+   * @param projectionOptions - Options to be used to create and update the [[Projection]].
+   * @returns The [[Projection]] that was created.
+   */
+  append: (
+    parentNode: Element,
+    vnode: VNode,
+    projectionOptions?: ProjectionOptions
+  ): Projection => {
+    projectionOptions = applyDefaultProjectionOptions(projectionOptions);
+    createDom(vnode, parentNode, undefined, projectionOptions);
+    return createProjection(vnode, projectionOptions);
+  },
+
+  /**
+   * Inserts a new DOM node which is generated from a [[VNode]].
+   * This is a low-level method. Users wil typically use a [[Projector]] instead.
+   * @param beforeNode - The node that the DOM Node is inserted before.
+   * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function.
+   * NOTE: [[VNode]] objects may only be rendered once.
+   * @param projectionOptions - Options to be used to create and update the projection, see [[createProjector]].
+   * @returns The [[Projection]] that was created.
+   */
+  insertBefore: (
+    beforeNode: Element,
+    vnode: VNode,
+    projectionOptions?: ProjectionOptions
+  ): Projection => {
+    projectionOptions = applyDefaultProjectionOptions(projectionOptions);
+    createDom(vnode, beforeNode.parentNode!, beforeNode, projectionOptions);
+    return createProjection(vnode, projectionOptions);
+  },
+
+  /**
+   * Merges a new DOM node which is generated from a [[VNode]] with an existing DOM Node.
+   * This means that the virtual DOM and the real DOM will have one overlapping element.
+   * Therefore the selector for the root [[VNode]] will be ignored, but its properties and children will be applied to the Element provided.
+   * This is a low-level method. Users wil typically use a [[Projector]] instead.
+   * @param element - The existing element to adopt as the root of the new virtual DOM. Existing attributes and child nodes are preserved.
+   * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]] objects
+   * may only be rendered once.
+   * @param projectionOptions - Options to be used to create and update the projection, see [[createProjector]].
+   * @returns The [[Projection]] that was created.
+   */
+  merge: (element: Element, vnode: VNode, projectionOptions?: ProjectionOptions): Projection => {
+    projectionOptions = applyDefaultProjectionOptions(projectionOptions);
+    vnode.domNode = element;
+    initPropertiesAndChildren(element, vnode, projectionOptions);
+    return createProjection(vnode, projectionOptions);
+  },
+
+  /**
+   * Replaces an existing DOM node with a node generated from a [[VNode]].
+   * This is a low-level method. Users will typically use a [[Projector]] instead.
+   * @param element - The node for the [[VNode]] to replace.
+   * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]]
+   * objects may only be rendered once.
+   * @param projectionOptions - Options to be used to create and update the [[Projection]].
+   * @returns The [[Projection]] that was created.
+   */
+  replace: (element: Element, vnode: VNode, projectionOptions?: ProjectionOptions): Projection => {
+    projectionOptions = applyDefaultProjectionOptions(projectionOptions);
+    createDom(vnode, element.parentNode!, element, projectionOptions);
+    element.parentNode!.removeChild(element);
+    return createProjection(vnode, projectionOptions);
+  },
+};

package/src/maquette/h.ts

@@ -0,0 +1,100 @@
+import { VNode, VNodeChild, VNodeProperties } from "./interfaces";
+
+let toTextVNode = (data: string): VNode => {
+  return {
+    vnodeSelector: "",
+    properties: undefined,
+    children: undefined,
+    text: data.toString(),
+    domNode: null,
+  };
+};
+
+let appendChildren = (parentSelector: string, insertions: VNodeChild[], main: VNode[]) => {
+  for (let i = 0, length = insertions.length; i < length; i++) {
+    let item = insertions[i];
+    if (Array.isArray(item)) {
+      appendChildren(parentSelector, item, main);
+    } else {
+      if (item !== null && item !== undefined && item !== false) {
+        if (typeof item === "string") {
+          item = toTextVNode(item);
+        }
+        main.push(item);
+      }
+    }
+  }
+};
+
+/**
+ * The `h` function is used to create a virtual DOM node.
+ * This function is largely inspired by the mercuryjs and mithril frameworks.
+ * The `h` stands for (virtual) hyperscript.
+ *
+ * @param selector    Contains the tagName, id and fixed css classnames in CSS selector format.
+ *                    It is formatted as follows: `tagname.cssclass1.cssclass2#id`.
+ * @param properties  An object literal containing properties that will be placed on the DOM node.
+ * @param children    Virtual DOM nodes and strings to add as child nodes.
+ *                    `children` may contain [[VNode]]s, `string`s, nested arrays, `null` and `undefined`.
+ *                    Nested arrays are flattened, `null` and `undefined` are removed.
+ *
+ * @returns           A VNode object, used to render a real DOM later.
+ *
+ * NOTE: There are {@link http://maquettejs.org/docs/rules.html two basic rules} you should be aware of when updating the virtual DOM.
+ */
+export function h(
+  selector: string,
+  properties?: VNodeProperties,
+  children?: VNodeChild[] | null
+): VNode;
+/**
+ * The `h` function is used to create a virtual DOM node.
+ * This function is largely inspired by the mercuryjs and mithril frameworks.
+ * The `h` stands for (virtual) hyperscript.
+ *
+ * @param selector    Contains the tagName, id and fixed css classnames in CSS selector format.
+ *                    It is formatted as follows: `tagname.cssclass1.cssclass2#id`.
+ * @param children    Virtual DOM nodes and strings to add as child nodes.
+ *                    `children` may contain [[VNode]]s, `string`s, nested arrays, `null` and `undefined`.
+ *                    Nested arrays are flattened, `null` and `undefined` are removed.
+ *
+ * @returns           A VNode object, used to render a real DOM later.
+ *
+ * NOTE: There are {@link http://maquettejs.org/docs/rules.html two basic rules} you should be aware of when updating the virtual DOM.
+ */
+export function h(selector: string, children: VNodeChild[]): VNode;
+
+export function h(
+  selector: string,
+  properties?: VNodeProperties,
+  children?: VNodeChild[] | null
+): VNode {
+  if (Array.isArray(properties)) {
+    children = properties;
+    properties = undefined;
+  } else if (
+    (properties && (typeof (properties as any) === "string" || properties.vnodeSelector)) ||
+    (children && (typeof (children as any) === "string" || (children as any).vnodeSelector))
+  ) {
+    throw new Error("h called with invalid arguments");
+  }
+  let text: string | undefined;
+  let flattenedChildren: VNode[] | undefined;
+  // Recognize a common special case where there is only a single text node
+  if (children && children.length === 1 && typeof children[0] === "string") {
+    text = children[0];
+  } else if (children) {
+    flattenedChildren = [];
+    appendChildren(selector, children, flattenedChildren);
+    if (flattenedChildren.length === 0) {
+      flattenedChildren = undefined;
+    }
+  }
+  return {
+    vnodeSelector: selector,
+    properties: properties,
+    children: flattenedChildren,
+    text: text === "" ? undefined : text,
+    domNode: null,
+  };
+}

package/src/maquette/index.ts

@@ -0,0 +1,12 @@
+// Comment that is displayed in the API documentation for the maquette module:
+/**
+ * Welcome to the API documentation of the **maquette** library.
+ *
+ * [[https://maquettejs.org/|To the maquette homepage]]
+ */
+export * from "./interfaces";
+export { dom } from "./dom";
+export { h } from "./h";
+export { createProjector } from "./projector";
+export { createCache } from "./cache";
+export { createMapping } from "./mapping";