synstate-dom 0.4.0 → 0.5.0

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']);
+  });
+});