@chronocide/hyper 0.6.0 → 1.0.0

package/README.md

@@ -41,25 +41,78 @@ document.body.appendChild(img);
 
 ### List
 
-Keeping track of children within a list can be tedious, especially if using immutable data. `list` caches elements based on keys and compares each data entry, only updating the child i the data has changed. Keys do not need to be unique, duplicate elements are cloned.
+Keeping track of children within a list can be tedious. `list` caches state and compares each entry, only updating children if the data has changed.
+
+**Note**: `list` only supports the following types:
+- `string`
+- `number`
+- `boolean`
+- `null`
+- `array`
+- `object`
+
+Where `array` and `object` can only contain aforementioned types.
 
 ```ts
 import h, { list } from '@chronocide/hyper';
 
+const ul = h('ul')()(); // <ul></ul>
+const li = (x: string) => h('li')()(x);
+const update = list(li)(ul);
+
+/**
+ * <ul>
+ *  <li>a</li> (render)
+ *  <li>b</li> (render)
+ *  <li>c</li> (render)
+ * </ul>
+ */
+update(['a', 'b', 'c']);
+
+/**
+ * <ul>
+ *  <li>a</li>
+ *  <li>b</li>
+ *  <li>c</li>
+ *  <li>d</li> (render)
+ * </ul>
+ */
+update(['a', 'b', 'c', 'd']);
+
+/**
+ * <ul>
+ *  <li>a</li>
+ *  <li>b</li> (render)
+ *  <li>c</li>
+ * </ul>
+ */
+update(['a', 'c', 'c']);
+```
+
+### Virtual
+
+Virtualisation is a technique that improves list performance by limiting the amount of children rendered. By only rendering elements that are visible within a defined viewport, the size of the DOM can be significantly decreased.
+
+`virtual` adds the neccesary inline styles and even listeners to make virtualisation possible, but does not add `aria` properties.
+
+```ts
+import h, { virtual } from '@chronocide/hyper';
+
 type Planet = { id: string; name: string };
 
 const ul = h('ul')()(); // <ul></ul>
 const render = (planet: Planet) => h('li')({ id: planet.id })(planet.name);
-const key = (planet: Planet) => planet.id;
-const update = list<Planet>(render)(key)(ul);
+const { update, scrollTo } = virtual(render)(ul);
 
 const planets: Planet[] = [
   { id: 'jupiter', name: 'Jupiter' },
   { id: 'mars', name: 'Mars' },
-  { id: 'pluto', name: 'Pluto' }
+  { id: 'pluto', name: 'Pluto' },
+  // ...
 ];
 
 update(planets); // <ul><li id="jupiter">Jupiter</li><li id="mars">Mars</li><li id="pluto">Pluto</li></ul>
+scrollTo(30); // Scroll to 30th item
 ```
 
 ## Testing

package/dist/hyper.d.ts

@@ -1,21 +1,43 @@
-type Attributes = Record<string, unknown>;
-type Child = Node | string;
-type HTMLVoidElementTagName = 'area' | 'base' | 'br' | 'col' | 'embed' | 'hr' | 'img' | 'input' | 'link' | 'meta' | 'source' | 'track' | 'wbr';
+type CellOptions<T> = {
+    /** If empty, equal to container width */
+    width?: number | ((data: T, i: number, arr: T[]) => number | null);
+    /** If true, cells do not fill container width */
+    gap?: boolean;
+    height: number | ((data: T, i: number, arr: T[]) => number);
+};
+
+type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
 
 declare class Env {
     private _document;
+    private _window;
     get document(): Document;
     set document(document: Document);
+    get window(): Window;
+    set window(window: Window);
     constructor();
 }
 
+type Attributes = Record<string, unknown>;
+type HTMLAttributes = Attributes & {
+    style?: Record<string, string>;
+};
+type Child = Node | string;
+type HTMLVoidElementTagName = 'area' | 'base' | 'br' | 'col' | 'embed' | 'hr' | 'img' | 'input' | 'link' | 'meta' | 'source' | 'track' | 'wbr';
+
 declare const env: Env;
-declare const _default: <T extends keyof HTMLElementTagNameMap>(tag: T) => <P extends Attributes>(attributes?: P | undefined) => (...children: T extends HTMLVoidElementTagName ? never[] : Child[]) => HTMLElementTagNameMap[T];
+declare const _default: <T extends keyof HTMLElementTagNameMap>(tag: T) => <P extends HTMLAttributes>(attributes?: P) => (...children: T extends HTMLVoidElementTagName ? never[] : Child[]) => HTMLElementTagNameMap[T];
 
-declare const svg: <T extends keyof SVGElementTagNameMap>(tag: T) => <P extends Attributes>(attributes?: P | undefined) => (...children: Child[]) => SVGElementTagNameMap[T];
-declare const mathml: <T extends keyof MathMLElementEventMap>(tag: T) => <P extends Attributes>(attributes?: P | undefined) => (...children: Child[]) => MathMLElement;
+declare const svg: <T extends keyof SVGElementTagNameMap>(tag: T) => <P extends Attributes>(attributes?: P) => (...children: Child[]) => SVGElementTagNameMap[T];
+declare const mathml: <T extends keyof MathMLElementEventMap>(tag: T) => <P extends Attributes>(attributes?: P) => (...children: Child[]) => MathMLElement;
 declare const xml: (tag: string) => <P extends Attributes>(attributes?: P) => (...children: Child[]) => HTMLElement;
-declare const list: <T>(render: (x: T, i: number, arr: T[]) => Element) => (key: (x: T) => string) => (root: Element) => (next: T[]) => void;
+declare const list: <T extends Json>(render: (x: T, i: number, arr: T[]) => Element) => (root: Element) => (next: T[]) => void;
+declare const virtual: <T>(cell: CellOptions<T>) => (render: (i: number) => HTMLElement) => (root: HTMLElement) => {
+    update: (next: T[]) => void;
+    scrollTo: (i: number) => void;
+};
 
-export { _default as default, env, list, mathml, svg, xml };
-export type { Attributes, Child, HTMLVoidElementTagName };
+export { _default as default, env, list, mathml, svg, virtual, xml };
+export type { Attributes, CellOptions, Child, HTMLVoidElementTagName, Json };

package/dist/hyper.js

@@ -1,69 +1,227 @@
+class Env {
+  _document;
+  _window;
+  get document() {
+    if (!this._document) throw new Error("Missing document");
+    return this._document;
+  }
+  set document(document2) {
+    this._document = document2;
+  }
+  get window() {
+    if (!this._window) throw new Error("Missing window");
+    return this._window;
+  }
+  set window(window2) {
+    this._window = window2;
+  }
+  constructor() {
+    this._document = typeof document === "undefined" ? null : document;
+    this._window = typeof window === "undefined" ? null : window;
+  }
+}
+
 const maybe = (fn) => (x) => {
   if (x === null || x === void 0) return null;
   return fn(x);
 };
+const debounce = (env) => (fn) => {
+  let id;
+  return (...x) => {
+    if (id) env.window.cancelAnimationFrame(id);
+    id = env.window.requestAnimationFrame(() => fn(...x));
+  };
+};
+
+const get = (arr) => (i) => arr[i] ?? null;
+const fill = (n) => (fn) => {
+  const arr = Array.from({ length: n });
+  for (let i = 0; i < arr.length; i += 1) {
+    arr[i] = fn(i, arr);
+  }
+  return arr;
+};
+const bisectLeft = (arr) => (n) => {
+  let l = 0;
+  let r = arr.length;
+  while (l < r) {
+    const m = l + Math.floor((r - l) / 2);
+    if (arr[m] < n) {
+      l = m + 1;
+    } else {
+      r = m;
+    }
+  }
+  while (l > 0 && (arr[l] > n || arr[l - 1] === arr[l])) l -= 1;
+  return Math.min(arr.length - 1, l);
+};
+const bisectRight = (arr) => (n) => {
+  let l = 0;
+  let r = arr.length;
+  while (l < r) {
+    const m = l + Math.floor((r - l) / 2);
+    if (arr[m] > n) {
+      r = m;
+    } else {
+      l = m + 1;
+    }
+  }
+  while (r < arr.length && (arr[r - 1] < n || arr[r] === arr[r - 1])) r += 1;
+  return Math.max(0, r - 1);
+};
+
+const cells = (cell) => (container) => (data) => fill(data.length)((i, arr) => {
+  const prev = get(arr)(i - 1);
+  const height2 = typeof cell.height === "number" ? cell.height : cell.height(data[i], i, data);
+  let width = typeof cell.width === "number" ? cell.width : cell.width?.(data[i], i, data) ?? container.width;
+  if (!cell.gap) {
+    const rows = Math.max(1, Math.floor(container.width / width));
+    width = Math.floor(container.width / rows);
+  }
+  let x = (prev?.x ?? 0) + (prev?.width ?? 0);
+  let y = prev?.y ?? 0;
+  if (x + width > container.width) {
+    x = 0;
+    y += prev?.height ?? 0;
+  }
+  return { i, x, y, width, height: height2 };
+});
+const height = (cells2) => (get(cells2)(cells2.length - 1)?.y ?? 0) + (get(cells2)(cells2.length - 1)?.height ?? 0);
+const view = (container) => (cells2) => {
+  const ly = cells2.map((cell) => cell.y);
+  const min = bisectLeft(ly)(Math.max(0, container.y - container.height));
+  const max = bisectRight(ly)(Math.min(height(cells2), container.y + container.height));
+  return [min, max];
+};
+
+const equals = (a) => (b) => {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((v, i) => equals(v)(b[i]));
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    if (a === null || b === null) return false;
+    if (Array.isArray(a) || Array.isArray(b)) return false;
+    if (Object.keys(a).length !== Object.keys(b).length) return false;
+    return Object.entries(a).every(([k, v]) => {
+      if (!(k in b)) return false;
+      return equals(b[k])(v);
+    });
+  }
+  return false;
+};
+const clone = (a) => {
+  if (a == null || typeof a !== "object") return a;
+  if (Array.isArray(a)) {
+    const b = [];
+    a.forEach((x, i) => {
+      b[i] = clone(x);
+    });
+    return b;
+  }
+  if (typeof a === "object") {
+    const b = {};
+    Object.keys(a).forEach((k) => {
+      b[k] = clone(a[k]);
+    });
+    return b;
+  }
+  throw new Error("Failed to clone, invalid type");
+};
 
-const setAttributes = (element) => (attributes) => Object.entries(attributes).forEach(([k, v]) => {
+const set = (element) => (attributes) => Object.entries(attributes).forEach(([k, v]) => {
   if (typeof v === "string") element.setAttribute(k, v);
   if (typeof v === "number") element.setAttribute(k, `${v}`);
   if (v === true) element.toggleAttribute(k, v);
 });
+const style = (element) => (style2) => Object.entries(style2).forEach(([k, v]) => {
+  element.style.setProperty(k, v);
+});
 const create = (element) => (attributes) => (children) => {
-  maybe(setAttributes(element))(attributes);
+  maybe(set(element))(attributes);
   element.append(...children);
   return element;
 };
-const html = (document) => (tag) => (attributes) => (...children) => create(document.createElement(tag))(attributes)(children);
-const svg$1 = (document) => (tag) => (attributes) => (...children) => create(document.createElementNS("http://www.w3.org/2000/svg", tag))(attributes)(children);
-const mathml$1 = (document) => (tag) => (attributes) => (...children) => create(document.createElementNS("http://www.w3.org/1998/Math/MathML", tag))(attributes)(children);
-const xml$1 = (document) => (tag) => (attributes) => (...children) => create(document.createElementNS("http://www.w3.org/1999/xhtml", tag))(attributes)(children);
-const list$1 = (render) => (key) => (root) => {
-  const cache = /* @__PURE__ */ new Map();
+const html = (env) => (tag) => (attributes) => (...children) => {
+  const root = create(env.document.createElement(tag))(attributes)(children);
+  maybe(style(root))(attributes?.style);
+  return root;
+};
+const svg$1 = (env) => (tag) => (attributes) => (...children) => create(env.document.createElementNS("http://www.w3.org/2000/svg", tag))(attributes)(children);
+const mathml$1 = (env) => (tag) => (attributes) => (...children) => create(env.document.createElementNS("http://www.w3.org/1998/Math/MathML", tag))(attributes)(children);
+const xml$1 = (env) => (tag) => (attributes) => (...children) => create(env.document.createElementNS("http://www.w3.org/1999/xhtml", tag))(attributes)(children);
+const list$1 = (render) => (root) => {
+  let cache = [];
   return (next) => {
-    const refs = /* @__PURE__ */ new WeakSet();
     while (root.children.length > next.length) root.lastChild?.remove();
     next.forEach((x, i) => {
-      const k = key(x);
+      if (i < cache.length && equals(x)(cache[i])) return;
+      const element = render(x, i, next);
       const child = root.children.item(i);
-      let element = cache.get(k);
-      if (element === child) return;
-      if (!element) {
-        element = render(x, i, next);
-        cache.set(k, element);
-      }
-      if (refs.has(element)) {
-        element = element.cloneNode(true);
-      } else {
-        refs.add(element);
-      }
       if (child) {
         root.replaceChild(element, child);
       } else {
         root.appendChild(element);
       }
     });
+    cache = clone(next);
+  };
+};
+const virtual$1 = (env) => (cell) => (render) => (root) => {
+  style(root)({
+    "position": "relative",
+    "max-height": "100%",
+    "overflow-y": "scroll"
+  });
+  let cache = [];
+  let state = [];
+  const update = debounce(env)((full) => {
+    if (full) cache = cells(cell)({ width: root.scrollWidth })(state);
+    const [min, max] = view({
+      height: root.getBoundingClientRect().height,
+      y: Math.floor(root.scrollTop)
+    })(cache);
+    const spacer = html(env)("div")({
+      "aria-hidden": "true",
+      "style": {
+        "width": "100%",
+        "height": `${height(cache)}px`,
+        "z-index": "-1"
+      }
+    })();
+    root.replaceChildren(...cache.slice(min, max + 1).map((cell2) => {
+      const child = render(cell2.i);
+      style(child)({
+        position: "absolute",
+        transform: `translate(${cell2.x}px, ${cell2.y}px)`,
+        width: `${cell2.width}px`,
+        height: `${cell2.height}px`
+      });
+      return child;
+    }), spacer);
+  });
+  root.addEventListener("scroll", () => update(false), { passive: true });
+  root.addEventListener("resize", () => update(true), { passive: true });
+  return {
+    update: (next) => {
+      state = next;
+      update(true);
+    },
+    scrollTo: (i) => {
+      const y = get(cache)(i)?.y;
+      if (typeof y !== "number") return;
+      root.scrollTop = y;
+    }
   };
 };
-
-class Env {
-  _document;
-  get document() {
-    if (!this._document) throw new Error("Missing document");
-    return this._document;
-  }
-  set document(document2) {
-    this._document = document2;
-  }
-  constructor() {
-    this._document = typeof document === "undefined" ? null : document;
-  }
-}
 
 const env = new Env();
-var hyper = (tag) => html(env.document)(tag);
-const svg = (tag) => svg$1(env.document)(tag);
-const mathml = (tag) => mathml$1(env.document)(tag);
-const xml = (tag) => xml$1(env.document)(tag);
+var hyper = html(env);
+const svg = svg$1(env);
+const mathml = mathml$1(env);
+const xml = xml$1(env);
 const list = list$1;
+const virtual = virtual$1(env);
 
-export { hyper as default, env, list, mathml, svg, xml };
+export { hyper as default, env, list, mathml, svg, virtual, xml };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronocide/hyper",
-  "version": "0.6.0",
+  "version": "1.0.0",
   "type": "module",
   "types": "dist/hyper.d.ts",
   "exports": {