synstate-dom 0.0.0-stage → 0.2.0

package/src/control/for.mts

@@ -0,0 +1,362 @@
+import {
+  createInitializedSyncChildObservable,
+  createScope,
+  getCurrentScope,
+  map,
+  onScopeDispose,
+  type InitializedObservable,
+  type Observable,
+  type Scope,
+} from 'synstate';
+import { Arr, Optional } from 'ts-data-forge';
+import type { BivariantHack } from 'ts-type-forge';
+import { toObservable, type Bindable } from '../constant/index.mjs';
+import { bindValue } from '../internal/index.mjs';
+import { mountable, toNodes, type JSX } from '../jsx/index.mjs';
+import { longestIncreasingSubsequence } from './longest-increasing-subsequence.mjs';
+
+/**
+ * Mounts one row per element of `items`, matched across updates by `key`
+ * (SPEC.md 8.4).
+ *
+ * `children` is called once per key, inside a scope of the row's own, with
+ * observables of the element and its index. The index is made only for a
+ * `children` that declares a second parameter (`children.length >= 2`); one
+ * that reads it otherwise, through a rest parameter or `arguments`, is given
+ * `undefined`.
+ *
+ * A row whose key stays is not rebuilt: its `item$` and `index$` are derived
+ * from `items`, so they update in the ordinary propagation, and nothing is
+ * written during it. A key that goes disposes its row's scope and removes its
+ * nodes; the rows that stay are moved as little as the longest increasing
+ * subsequence allows.
+ *
+ * `key` is required, as in React; `(_, i) => i` matches rows by position. A
+ * key that appears twice is reported with `console.error`, and its later
+ * occurrences are rebuilt on every update.
+ */
+export const For = <T,>({
+  items,
+  key,
+  children,
+}: Readonly<{
+  items: Bindable<readonly T[]>;
+  key: (item: T, index: number) => unknown;
+  children: (
+    item$: InitializedObservable<T>,
+    index$: InitializedObservable<number>,
+  ) => JSX.Element;
+}>): JSX.Element =>
+  mountable(() => {
+    const parent = getCurrentScope();
+
+    const anchor = document.createComment('');
+
+    const entries$ = toObservable(items).pipe(
+      map((list) => toEntries(list, key)),
+    );
+
+    // `index$` is a node of its own in every row, visited on every update of
+    // `items`; a `children` that declares no second parameter is not given
+    // one, as Solid's `For` does.
+    const usesIndex = children.length >= 2;
+
+    const callChildren: BivariantHack<
+      (
+        item$: InitializedObservable<T>,
+        index$?: InitializedObservable<number>,
+      ) => JSX.Element
+    > = children;
+
+    const mut_rows = new Map<unknown, Row>();
+
+    const rowStarts = new WeakSet<Node>();
+
+    const mut_initial: { nodes: readonly ChildNode[] } = { nodes: [] };
+
+    /** Creates a row in a scope of its own and returns its first nodes. */
+    const createRow = (
+      rowKey: unknown,
+      entry: Entry<T>,
+    ): readonly ChildNode[] => {
+      const scope = createScope(parent);
+
+      const start = document.createComment('');
+
+      rowStarts.add(start);
+
+      const nodes = scope.run(() => {
+        const item$ = rowField(entries$, rowKey, entry.item, (e) => e.item);
+
+        return toNodes(
+          (usesIndex
+            ? callChildren(
+                item$,
+                rowField(entries$, rowKey, entry.index, (e) => e.index),
+              )
+            : callChildren(item$)
+          ).mount(),
+        );
+      });
+
+      const row: Row = { scope, start } as const;
+
+      scope.run(() => {
+        onScopeDispose(() => {
+          for (const node of rowNodes(row)) {
+            node.remove();
+          }
+        });
+      });
+
+      mut_rows.set(rowKey, row);
+
+      return Arr.toUnshifted(start)(nodes);
+    };
+
+    /** The row's current nodes: from its start to the next row or the anchor. */
+    const rowNodes = (row: Row): readonly ChildNode[] => {
+      const mut_nodes: ChildNode[] = [row.start];
+
+      for (
+        let mut_node = row.start.nextSibling;
+        mut_node !== null && mut_node !== anchor && !rowStarts.has(mut_node);
+        mut_node = mut_node.nextSibling
+      ) {
+        mut_nodes.push(mut_node);
+      }
+
+      return mut_nodes;
+    };
+
+    /**
+     * When no key stays, takes every row's nodes out in one range, rather than
+     * one by one as each row's scope is disposed: clearing or replacing the
+     * whole list is then one DOM operation. The scopes are disposed after,
+     * and find their nodes already detached.
+     */
+    const removeAllAtOnceIfEveryKeyGoes = (
+      previousOrder: readonly unknown[],
+      entries: Entries<T>,
+    ): void => {
+      if (
+        !Arr.isNonEmpty(previousOrder) ||
+        previousOrder.some((rowKey) => entries.byKey.has(rowKey))
+      ) {
+        return;
+      }
+
+      const first = mut_rows.get(previousOrder[0]);
+
+      if (first === undefined) {
+        return;
+      }
+
+      const range = document.createRange();
+
+      range.setStartBefore(first.start);
+
+      range.setEndBefore(anchor);
+
+      range.deleteContents();
+    };
+
+    bindValue(entries$, (entries) => {
+      const previousOrder = Array.from(mut_rows.keys());
+
+      if (anchor.parentNode !== null) {
+        removeAllAtOnceIfEveryKeyGoes(previousOrder, entries);
+      }
+
+      for (const [rowKey, row] of mut_rows) {
+        if (entries.byKey.has(rowKey)) {
+          continue;
+        }
+
+        row.scope.dispose();
+
+        mut_rows.delete(rowKey);
+      }
+
+      if (anchor.parentNode === null) {
+        mut_initial.nodes = entries.order.flatMap((rowKey) => {
+          const entry = entries.byKey.get(rowKey);
+
+          return entry === undefined ? [] : createRow(rowKey, entry);
+        });
+
+        return;
+      }
+
+      if (Arr.eq(previousOrder, entries.order)) {
+        return;
+      }
+
+      const previousPosition = new Map(
+        previousOrder
+          .filter((rowKey) => mut_rows.has(rowKey))
+          .map((rowKey, position) => [rowKey, position]),
+      );
+
+      const positions = entries.order.map(
+        (rowKey) => previousPosition.get(rowKey) ?? -1,
+      );
+
+      const stay = longestIncreasingSubsequence(
+        positions.filter((position) => position >= 0),
+      );
+
+      const staying = new Set(
+        positions
+          .filter((position) => position >= 0)
+          .filter((_, k) => stay.has(k)),
+      );
+
+      let mut_next: ChildNode = anchor;
+
+      for (const rowKey of entries.order.toReversed()) {
+        const existing = mut_rows.get(rowKey);
+
+        if (existing === undefined) {
+          const entry = entries.byKey.get(rowKey);
+
+          if (entry === undefined) {
+            continue;
+          }
+
+          const [start, ...rest] = createRow(rowKey, entry);
+
+          if (start !== undefined) {
+            mut_next.before(start, ...rest);
+
+            mut_next = start;
+          }
+
+          continue;
+        }
+
+        if (!staying.has(previousPosition.get(rowKey) ?? -1)) {
+          mut_next.before(...rowNodes(existing));
+        }
+
+        mut_next = existing.start;
+      }
+
+      reorderMap(mut_rows, entries.order);
+    });
+
+    return Arr.toPushed(mut_initial.nodes, anchor);
+  });
+
+type Row = Readonly<{
+  /** The row's own scope, a child of the scope `For` was mounted in. */
+  scope: Scope;
+  /** A comment in front of the row's nodes, which do not otherwise stay put: a switch at the top of the row changes them. */
+  start: Comment;
+}>;
+
+type Entry<T> = Readonly<{ item: T; index: number }>;
+
+type Entries<T> = Readonly<{
+  order: readonly unknown[];
+  byKey: ReadonlyMap<unknown, Entry<T>>;
+}>;
+
+const toEntries = <T,>(
+  list: readonly T[],
+  key: (item: T, index: number) => unknown,
+): Entries<T> => {
+  const mut_byKey = new Map<unknown, Entry<T>>();
+
+  const order = list.map((item, index) => {
+    const itemKey = key(item, index);
+
+    if (!mut_byKey.has(itemKey)) {
+      mut_byKey.set(itemKey, { item, index });
+
+      return itemKey;
+    }
+
+    console.error(
+      'synstate-dom: For found the key',
+      itemKey,
+      'more than once; keys must be unique.',
+    );
+
+    // A fresh key: the duplicate is rebuilt on every update.
+    const duplicateKey = Symbol('duplicate key');
+
+    mut_byKey.set(duplicateKey, { item, index });
+
+    return duplicateKey;
+  });
+
+  return { order, byKey: mut_byKey };
+};
+
+/**
+ * One field of a row's entry, as a single child of `entries$`, where
+ * `map`, `filter`, `withInitialValue` and `skipIfNoChange` would make four:
+ * creating and disposing a row costs roughly its number of nodes.
+ *
+ * A row whose key has gone keeps its last value; its scope is disposed in
+ * the same update.
+ */
+const rowField = <T, A>(
+  entries$: Observable<Entries<T>>,
+  rowKey: unknown,
+  initialValue: A,
+  field: (entry: Entry<T>) => A,
+): InitializedObservable<A> =>
+  createInitializedSyncChildObservable(
+    { parents: [entries$], initialValue: Optional.some(initialValue) },
+    ({ setNext }) => {
+      let mut_previous = initialValue;
+
+      return (updateToken) => {
+        const sn = entries$.getSnapshot();
+
+        if (entries$.updateToken !== updateToken || Optional.isNone(sn)) {
+          return;
+        }
+
+        const entry = sn.value.byKey.get(rowKey);
+
+        if (entry === undefined) {
+          return;
+        }
+
+        const next = field(entry);
+
+        if (Object.is(next, mut_previous)) {
+          return;
+        }
+
+        mut_previous = next;
+
+        setNext(next, updateToken);
+      };
+    },
+  );
+
+/** Re-inserts the rows in the new order, so that iteration follows the DOM. */
+const reorderMap = (
+  mut_rows: Map<unknown, Row>,
+  order: readonly unknown[],
+): void => {
+  const rows = Arr.generate(function* () {
+    for (const rowKey of order) {
+      const row = mut_rows.get(rowKey);
+
+      if (row !== undefined) {
+        yield [rowKey, row] as const;
+      }
+    }
+  });
+
+  mut_rows.clear();
+
+  for (const [rowKey, row] of rows) {
+    mut_rows.set(rowKey, row);
+  }
+};

package/src/control/if.mts

@@ -0,0 +1,28 @@
+import type { Bindable } from '../constant/index.mjs';
+import { mountable, type JSX } from '../jsx/index.mjs';
+import { mountSwitch } from './mount-switch.mjs';
+
+/**
+ * Mounts `then` while `cond` is `true` and `else` while it is `false`
+ * (SPEC.md 8.2). Nothing is mounted for an omitted `else`.
+ *
+ * Both branches are descriptions, so only the one chosen is mounted. A branch
+ * is rebuilt only when `cond` flips; flipping disposes the previous branch's
+ * scope and removes its nodes. A constant `cond` mounts one branch once.
+ */
+export const If = ({
+  cond,
+  then,
+  else: elseBranch,
+}: Readonly<{
+  cond: Bindable<boolean>;
+  then: JSX.Element;
+  else?: JSX.Element;
+}>): JSX.Element =>
+  mountable(() =>
+    mountSwitch(
+      cond,
+      (value) => value,
+      (value) => (value ? then : elseBranch),
+    ),
+  );

package/src/control/index.mts

@@ -0,0 +1,5 @@
+export * from './for.mjs';
+export * from './if.mjs';
+export * from './match-optional.mjs';
+export * from './match-result.mjs';
+export * from './portal.mjs';

package/src/control/longest-increasing-subsequence.mts

@@ -0,0 +1,59 @@
+/**
+ * The positions in `values` of one longest strictly increasing subsequence,
+ * in O(n log n). `For` keeps the rows at these positions in place and moves
+ * only the others (SPEC.md 8.4).
+ */
+export const longestIncreasingSubsequence = (
+  values: readonly number[],
+): ReadonlySet<number> => {
+  /** `tails[k]`: the position of the smallest tail of an increasing run of length k + 1. */
+  const mut_tails: number[] = [];
+
+  /** `previous[i]`: the position before `i` in the run that ends at `i`. */
+  const mut_previous: (number | undefined)[] = [];
+
+  for (const [i, value] of values.entries()) {
+    const k = lowerBound(
+      mut_tails,
+      (position) => (values[position] ?? 0) < value,
+    );
+
+    mut_previous[i] = k > 0 ? mut_tails[k - 1] : undefined;
+
+    mut_tails[k] = i;
+  }
+
+  const mut_result = new Set<number>();
+
+  for (
+    let mut_i = mut_tails.at(-1);
+    mut_i !== undefined;
+    mut_i = mut_previous[mut_i]
+  ) {
+    mut_result.add(mut_i);
+  }
+
+  return mut_result;
+};
+
+/** The first index of `sorted` for which `isBefore` is false. */
+const lowerBound = (
+  sorted: readonly number[],
+  isBefore: (element: number) => boolean,
+): number => {
+  let mut_low = 0;
+
+  let mut_high = sorted.length;
+
+  while (mut_low < mut_high) {
+    const middle = Math.floor((mut_low + mut_high) / 2);
+
+    if (isBefore(sorted[middle] ?? 0)) {
+      mut_low = middle + 1;
+    } else {
+      mut_high = middle;
+    }
+  }
+
+  return mut_low;
+};

package/src/control/longest-increasing-subsequence.test.mts

@@ -0,0 +1,26 @@
+import { longestIncreasingSubsequence } from './longest-increasing-subsequence.mjs';
+
+describe(longestIncreasingSubsequence, () => {
+  test.each([
+    { values: [], expected: [] },
+    { values: [0, 1, 2], expected: [0, 1, 2] },
+    { values: [2, 1, 0], expected: [2] },
+    { values: [1, 2, 0], expected: [0, 1] },
+    { values: [3, 0, 1, 2], expected: [1, 2, 3] },
+    { values: [0, 8, 4, 12, 2, 10, 6, 14, 1, 9], expected: [0, 2, 5, 9] },
+  ])('$values', ({ values, expected }) => {
+    const result = longestIncreasingSubsequence(values);
+
+    assert.strictEqual(result.size, expected.length);
+
+    const picked = Array.from(result).toSorted((a, b) => a - b);
+
+    assert.isTrue(
+      picked.every(
+        (position, k) =>
+          k === 0 ||
+          (values[position] ?? 0) > (values[picked[k - 1] ?? 0] ?? 0),
+      ),
+    );
+  });
+});

package/src/control/match-optional.mts

@@ -0,0 +1,41 @@
+import {
+  filter,
+  map,
+  withInitialValue,
+  type InitializedObservable,
+} from 'synstate';
+import { Optional } from 'ts-data-forge';
+import { toObservable, type Bindable } from '../constant/index.mjs';
+import { mountable, type JSX } from '../jsx/index.mjs';
+import { mountSwitch } from './mount-switch.mjs';
+
+/**
+ * Mounts `some` while `value` holds a value and `none` while it is empty
+ * (SPEC.md 8.3).
+ *
+ * `some` is called once per change from empty to present, with an observable
+ * of the value narrowed to `T`. While the value stays present, new values flow
+ * through that observable rather than rebuilding the branch. It is derived
+ * from `value`, not written to, so nothing is written during propagation.
+ */
+export const MatchOptional = <T,>({
+  value,
+  some,
+  none,
+}: Readonly<{
+  value: Bindable<Optional<T>>;
+  some: (value$: InitializedObservable<T>) => JSX.Element;
+  none?: JSX.Element;
+}>): JSX.Element =>
+  mountable(() =>
+    mountSwitch(value, Optional.isSome, (isSome, current) =>
+      isSome && Optional.isSome(current)
+        ? some(
+            toObservable(value)
+              .pipe(filter(Optional.isSome))
+              .pipe(map((o) => o.value))
+              .pipe(withInitialValue(current.value)),
+          )
+        : none,
+    ),
+  );

package/src/control/match-result.mts

@@ -0,0 +1,48 @@
+import {
+  filter,
+  map,
+  withInitialValue,
+  type InitializedObservable,
+} from 'synstate';
+import { Result } from 'ts-data-forge';
+import { toObservable, type Bindable } from '../constant/index.mjs';
+import { mountable, type JSX } from '../jsx/index.mjs';
+import { mountSwitch } from './mount-switch.mjs';
+
+/**
+ * Mounts `ok` while `value` is `Ok` and `err` while it is `Err`
+ * (SPEC.md 8.3).
+ *
+ * Each branch is called once per change of tag, with an observable of the
+ * value narrowed to `S` or `E`; while the tag stays the same, new values flow
+ * through that observable rather than rebuilding the branch. It is derived
+ * from `value`, not written to, so nothing is written during propagation.
+ */
+export const MatchResult = <S, E>({
+  value,
+  ok,
+  err,
+}: Readonly<{
+  value: Bindable<Result<S, E>>;
+  ok: (value$: InitializedObservable<S>) => JSX.Element;
+  err: (error$: InitializedObservable<E>) => JSX.Element;
+}>): JSX.Element =>
+  mountable(() =>
+    mountSwitch(value, Result.isOk, (_isOk, current) => {
+      const value$ = toObservable(value);
+
+      return Result.isOk(current)
+        ? ok(
+            value$
+              .pipe(filter(Result.isOk))
+              .pipe(map((r) => r.value))
+              .pipe(withInitialValue(current.value)),
+          )
+        : err(
+            value$
+              .pipe(filter(Result.isErr))
+              .pipe(map((r) => r.value))
+              .pipe(withInitialValue(current.value)),
+          );
+    }),
+  );

package/src/control/mount-switch.mts

@@ -0,0 +1,75 @@
+import {
+  createScope,
+  getCurrentScope,
+  onScopeDispose,
+  type Scope,
+} from 'synstate';
+import { Arr } from 'ts-data-forge';
+import type { Bindable } from '../constant/index.mjs';
+import { bindValue } from '../internal/index.mjs';
+import { toNodes, type Mountable, type MountedNodes } from '../jsx/index.mjs';
+
+/**
+ * Mounts one branch at a time in front of an anchor comment, choosing it from
+ * the value of `value` (SPEC.md 8.1–8.3).
+ *
+ * The branch is rebuilt only when `keyOf` gives a different key: within the
+ * same key the branch keeps its nodes and its scope, and it is up to the
+ * branch to follow the value (`MatchOptional` hands it an observable derived
+ * from `value`). Each branch is mounted in a scope of its own, a child of the
+ * scope the switch was mounted in; disposing the branch's scope removes its
+ * nodes, so the switch's own nodes stay accurate however often it switches.
+ *
+ * `branch` runs inside the new scope, so whatever it creates belongs to the
+ * branch.
+ */
+export const mountSwitch = <V, K>(
+  value: Bindable<V>,
+  keyOf: (current: V) => K,
+  branch: (key: K, current: V) => Mountable | undefined,
+): MountedNodes => {
+  const parent = getCurrentScope();
+
+  const anchor = document.createComment('');
+
+  const mut_state: {
+    current: Readonly<{ key: K; scope: Scope }> | undefined;
+    initialNodes: readonly ChildNode[];
+  } = { current: undefined, initialNodes: [] };
+
+  bindValue(value, (v) => {
+    const key = keyOf(v);
+
+    if (mut_state.current !== undefined) {
+      if (Object.is(mut_state.current.key, key)) {
+        return;
+      }
+
+      mut_state.current.scope.dispose();
+    }
+
+    const scope = createScope(parent);
+
+    const nodes = scope.run(() => {
+      const mounted = toNodes(branch(key, v)?.mount() ?? []);
+
+      onScopeDispose(() => {
+        for (const node of mounted) {
+          node.remove();
+        }
+      });
+
+      return mounted;
+    });
+
+    mut_state.current = { key, scope };
+
+    if (anchor.parentNode === null) {
+      mut_state.initialNodes = nodes;
+    } else {
+      anchor.before(...nodes);
+    }
+  });
+
+  return Arr.toPushed(mut_state.initialNodes, anchor);
+};

package/src/control/portal.mts

@@ -0,0 +1,32 @@
+import { onScopeDispose } from 'synstate';
+import { mountChild, mountable, type Child, type JSX } from '../jsx/index.mjs';
+
+/**
+ * Mounts `children` into `target` (`document.body` when omitted) rather than
+ * where it is written (SPEC.md 8.6): for a modal, a tooltip or a toast that
+ * has to escape an ancestor's `overflow: hidden` or `z-index`.
+ *
+ * The children belong to the scope where `Portal` is written, so closing the
+ * enclosing `If` branch removes them too. Nothing is left in the place it is
+ * written.
+ */
+export const Portal = ({
+  target,
+  children,
+}: Readonly<{
+  target?: Element;
+  children: Child;
+}>): JSX.Element =>
+  mountable(() => {
+    const nodes = mountChild(children);
+
+    (target ?? document.body).append(...nodes);
+
+    onScopeDispose(() => {
+      for (const node of nodes) {
+        node.remove();
+      }
+    });
+
+    return [];
+  });

package/src/index.mts

@@ -0,0 +1,4 @@
+export * from './constant/index.mjs';
+export * from './control/index.mjs';
+export * from './jsx/index.mjs';
+export * from './render.mjs';

package/src/internal/as-constant.mts

@@ -0,0 +1,11 @@
+import type { Constant } from '../constant/index.mjs';
+
+/**
+ * The one type assertion in the library. `Constant<T>` is a brand that exists
+ * only in the type system, so marking a value as one changes nothing at run
+ * time; this is what {@link constant} and the helpers that derive one constant
+ * from another call.
+ */
+export const asConstant = <T,>(value: T): Constant<T> =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion -- a brand has no run-time part to check
+  value as Constant<T>;