synstate-dom 0.3.0 → 0.5.0

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

@@ -1,7 +1,7 @@
 /**
- * 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).
+ * 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[],

package/src/control/match-optional.mts

@@ -13,10 +13,10 @@ 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.
+ * `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,

package/src/control/match-result.mts

@@ -10,13 +10,12 @@ 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).
+ * 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.
+ * 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,

package/src/control/mount-switch.mts

@@ -14,11 +14,11 @@ import { toNodes, type Mountable, type MountedNodes } from '../jsx/index.mjs';
  * 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.
+ * 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.

package/src/control/portal.mts

@@ -3,8 +3,8 @@ 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`.
+ * 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

package/src/index.mts

@@ -2,3 +2,4 @@ export * from './constant/index.mjs';
 export * from './control/index.mjs';
 export * from './jsx/index.mjs';
 export * from './render.mjs';
+export * from './scope/index.mjs';

package/src/internal/bind-value.mts

@@ -1,9 +1,6 @@
-import {
-  isObservable,
-  onScopeDispose,
-  type InitializedObservable,
-} from 'synstate';
+import { isObservable, type InitializedObservable } from 'synstate';
 import type { Bindable } from '../constant/index.mjs';
+import { subscribeInScope } from '../scope/index.mjs';
 import { isView } from './is-view.mjs';
 
 /**
@@ -23,7 +20,7 @@ export const bindValue = <T,>(
 ): void => {
   if (isView(bindable)) {
     bindable.open((source, fn) => {
-      subscribeInScope(source, (value) => {
+      bindObservable(source, (value) => {
         write(fn(value));
       });
     });
@@ -32,7 +29,7 @@ export const bindValue = <T,>(
   }
 
   if (isObservable(bindable)) {
-    subscribeInScope(bindable, write);
+    bindObservable(bindable, write);
 
     return;
   }
@@ -40,7 +37,8 @@ export const bindValue = <T,>(
   write(bindable);
 };
 
-const subscribeInScope = <A,>(
+/** A completed observable is written once and not subscribed to. */
+const bindObservable = <A,>(
   source: InitializedObservable<A>,
   write: (value: A) => void,
 ): void => {
@@ -50,9 +48,5 @@ const subscribeInScope = <A,>(
     return;
   }
 
-  const subscription = source.subscribe(write);
-
-  onScopeDispose(() => {
-    subscription.unsubscribe();
-  });
+  subscribeInScope(source, write);
 };

package/src/jsx/child.mts

@@ -37,8 +37,8 @@ export const toNodes = (nodes: MountedNodes): readonly ChildNode[] =>
   Arr.isArray(nodes) ? nodes : ([nodes] as const);
 
 /**
- * Tells a child from any other value, one level deep: the elements of an
- * array are checked as they are mounted.
+ * Tells a child from any other value, one level deep: the elements of an array
+ * are checked as they are mounted.
  */
 export const isChild = (value: unknown): value is Child =>
   Arr.isArray(value) ||

package/src/jsx/element-props.mts

@@ -43,8 +43,8 @@ export type StyleObject = ReadonlyRecord<string, Bindable<string | undefined>>;
 
 /**
  * The props of an HTML element: the common ones, one `Bindable` per writable
- * primitive DOM property of `E` (`id`, `disabled`, `value`, `tabIndex`, …),
- * and one handler per event of `HTMLElementEventMap`.
+ * primitive DOM property of `E` (`id`, `disabled`, `value`, `tabIndex`, …), and
+ * one handler per event of `HTMLElementEventMap`.
  *
  * An attribute, `aria-*` and `data-*` included, also takes `undefined`, which
  * removes it: a value that comes and goes is an observable of `T | undefined`

package/src/jsx/jsx.mts

@@ -19,8 +19,8 @@ export const createMountable = <P,>(
   props: P,
   key?: unknown,
 ): Mountable => {
-  // The transform takes `key` out of the props and passes it on its own. It
-  // is put back for a component: `For` takes its `key` function as a prop.
+  // The transform takes `key` out of the props and passes it on its own. It is
+  // put back for a component: `For` takes its `key` function as a prop.
   const propsWithKey = key === undefined ? props : ({ ...props, key } as const);
 
   return typeof type === 'string'
@@ -32,6 +32,9 @@ export const createMountable = <P,>(
 export const Fragment = (props: Readonly<{ children?: Child }>): Mountable =>
   mountable(() => mountChild(props.children ?? []));
 
+const isRefCallback = (value: unknown): value is (element: Element) => void =>
+  typeof value === 'function';
+
 const mountElement = (tag: string, props: unknown): Element => {
   const element = svgTagNameSet.has(tag)
     ? document.createElementNS(svgNamespace, tag)
@@ -58,6 +61,3 @@ const mountElement = (tag: string, props: unknown): Element => {
 const svgNamespace = 'http://www.w3.org/2000/svg';
 
 const svgTagNameSet: ReadonlySet<string> = new Set(svgTagNames);
-
-const isRefCallback = (value: unknown): value is (element: Element) => void =>
-  typeof value === 'function';

package/src/jsx/mountable.mts

@@ -1,8 +1,8 @@
 import { mountableTag } from '../internal/index.mjs';
 
 /**
- * What a JSX expression evaluates to: a description that creates DOM nodes
- * when mounted, not the nodes themselves (SPEC.md 6.1).
+ * What a JSX expression evaluates to: a description that creates DOM nodes when
+ * mounted, not the nodes themselves (SPEC.md 6.1).
  *
  * The children of a JSX element are evaluated before the element, so a
  * description that created its nodes at once would create both branches of
@@ -11,8 +11,8 @@ import { mountableTag } from '../internal/index.mjs';
  * It is an object rather than a function: a props object with a `then` prop
  * holding a function would be taken for a thenable.
  *
- * The same description may be mounted any number of times; each mount
- * creates new nodes.
+ * The same description may be mounted any number of times; each mount creates
+ * new nodes.
  */
 export type Mountable = Readonly<{
   [mountableTag]: true;

package/src/jsx-dev-runtime.mts

@@ -1,6 +1,6 @@
 /**
  * The module `"jsxImportSource": "synstate-dom"` makes TypeScript import for
- * `"jsx": "react-jsxdev"`. The extra arguments (`key`, source location) are
- * not used.
+ * `"jsx": "react-jsxdev"`. The extra arguments (`key`, source location) are not
+ * used.
  */
 export { Fragment, createMountable as jsxDEV, type JSX } from './jsx/index.mjs';

package/src/scope/index.mts

@@ -0,0 +1 @@
+export * from './scope-effects.mjs';

package/src/scope/scope-effects.mts

@@ -0,0 +1,60 @@
+import { onScopeDispose, type Observable } from 'synstate';
+import type { StrictPick } from 'ts-type-forge';
+
+/**
+ * Calls `next` with every value of `source`, the current one first, until the
+ * current scope is disposed — what a component that is called once does in
+ * place of an effect.
+ */
+export const subscribeInScope = <A,>(
+  source: Observable<A>,
+  next: (value: A) => void,
+): void => {
+  const subscription = source.subscribe(next);
+
+  onScopeDispose(() => {
+    subscription.unsubscribe();
+  });
+};
+
+/** Listens to `type` on `target` until the current scope is disposed. */
+export const listenInScope = (
+  target: Readonly<
+    StrictPick<EventTarget, 'addEventListener' | 'removeEventListener'>
+  >,
+  type: string,
+  listener: (event: Event) => void,
+  options?: Readonly<{ capture?: boolean; passive?: boolean }>,
+): void => {
+  target.addEventListener(type, listener, options);
+
+  onScopeDispose(() => {
+    target.removeEventListener(type, listener, options);
+  });
+};
+
+/**
+ * Makes the function that runs work once the update under way has finished:
+ * in a microtask, so before the next paint, with the DOM bound to the update
+ * already written — and nothing written to a state while another is still
+ * propagating, which synstate warns of. Work for a scope disposed by then is
+ * dropped.
+ *
+ * Also what runs after the first mount: a component's nodes are attached to the
+ * document only once the whole description they are in is mounted.
+ */
+export const createAfterUpdate = (): ((work: () => void) => void) => {
+  let mut_alive = true;
+
+  onScopeDispose(() => {
+    mut_alive = false;
+  });
+
+  return (work) => {
+    queueMicrotask(() => {
+      if (mut_alive) {
+        work();
+      }
+    });
+  };
+};

package/src/scope/scope-effects.test.mts

@@ -0,0 +1,89 @@
+import { createScope, createState } from 'synstate';
+import {
+  createAfterUpdate,
+  listenInScope,
+  subscribeInScope,
+} from './scope-effects.mjs';
+
+describe(subscribeInScope, () => {
+  test('follows the source, the current value first, until the scope is disposed', () => {
+    const scope = createScope(undefined);
+
+    const [source, setSource] = createState(0);
+
+    const mut_received: number[] = [];
+
+    scope.run(() => {
+      subscribeInScope(source, (value) => {
+        mut_received.push(value);
+      });
+    });
+
+    setSource(1);
+
+    scope.dispose();
+
+    setSource(2);
+
+    assert.deepStrictEqual(mut_received, [0, 1]);
+  });
+});
+
+describe(createAfterUpdate, () => {
+  test('runs the work in a microtask, and drops it once the scope is disposed', async () => {
+    const scope = createScope(undefined);
+
+    const afterUpdate = scope.run(createAfterUpdate);
+
+    const mut_log: string[] = [];
+
+    afterUpdate(() => {
+      mut_log.push('first');
+    });
+
+    assert.deepStrictEqual(mut_log, []);
+
+    await Promise.resolve();
+
+    assert.deepStrictEqual(mut_log, ['first']);
+
+    afterUpdate(() => {
+      mut_log.push('second');
+    });
+
+    scope.dispose();
+
+    await Promise.resolve();
+
+    assert.deepStrictEqual(mut_log, ['first']);
+  });
+});
+
+describe(listenInScope, () => {
+  test('listens, with the options it is given, until the scope is disposed', () => {
+    const scope = createScope(undefined);
+
+    const target = new EventTarget();
+
+    const mut_received: string[] = [];
+
+    scope.run(() => {
+      listenInScope(
+        target,
+        'ping',
+        (event) => {
+          mut_received.push(event.type);
+        },
+        { capture: true },
+      );
+    });
+
+    target.dispatchEvent(new Event('ping'));
+
+    scope.dispose();
+
+    target.dispatchEvent(new Event('ping'));
+
+    assert.deepStrictEqual(mut_received, ['ping']);
+  });
+});