synstate-dom 0.4.0 → 0.6.0

package/src/control/for.mts

@@ -31,8 +31,8 @@ import { longestIncreasingSubsequence } from './longest-increasing-subsequence.m
  * 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
+ * `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,>({
@@ -57,8 +57,8 @@ export const For = <T,>({
     );
 
     // `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.
+    // `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<
@@ -132,8 +132,8 @@ export const For = <T,>({
     /**
      * 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.
+     * whole list is then one DOM operation. The scopes are disposed after, and
+     * find their nodes already detached.
      */
     const removeAllAtOnceIfEveryKeyGoes = (
       previousOrder: readonly unknown[],
@@ -295,12 +295,12 @@ const toEntries = <T,>(
 };
 
 /**
- * One field of a row's entry, as a single child of `entries$`, where
- * `map`, `filter`, `withInitialValue` and `skipIfNoChange` would make four:
+ * 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.
+ * 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>>,

package/src/control/if.mts

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

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

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

package/src/internal/as-constant.mts

@@ -1,10 +1,10 @@
 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.
+ * The one type assertion that brands a value. `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

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/internal/dom-tables.mts

@@ -28,6 +28,9 @@ export const propertyNames = [
  */
 export const attributeNameOf: ReadonlyRecord<string, string> = {
   acceptCharset: 'accept-charset',
+  defaultMuted: 'muted',
+  defaultSelected: 'selected',
+  encoding: 'enctype',
   htmlFor: 'for',
   httpEquiv: 'http-equiv',
 } as const;

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`
@@ -118,7 +118,20 @@ type IsWritable<E, K extends keyof E> =
 
 /**
  * Writable primitive properties that are not attributes, or that are props of
- * their own (`class`, `style`).
+ * their own (`class`, `style`). The binding would pass them to `setAttribute`,
+ * which makes an attribute nothing reads (#2934): the parts of `<a>`'s `href`
+ * (`hash` … `username`), the text of `<a>`, `<option>`, `<script>` and
+ * `<title>` (`text`), media playback state (`currentTime` … `volume`), and form
+ * control state (`returnValue` … `length`), and the obsolete `ch` and `chOff`
+ * of table cells, whose attributes are `char` and `charoff`. A property written as a property is
+ * in `propertyNames`, and one whose attribute is spelt differently in
+ * `attributeNameOf`. Checked in Chromium by setting the attribute and reading
+ * the property back.
+ *
+ * The keys are left out of every element, so a name that is an attribute on one
+ * element and not on another goes by the common case: `<body>`'s obsolete
+ * `text` attribute is left out with the rest, and `<style>`'s `disabled`, which
+ * has no attribute, stays in with every other `disabled`.
  */
 type ExcludedKey =
   | 'className'
@@ -129,4 +142,28 @@ type ExcludedKey =
   | 'outerText'
   | 'scrollLeft'
   | 'scrollTop'
-  | 'textContent';
+  | 'textContent'
+  | 'hash'
+  | 'host'
+  | 'hostname'
+  | 'password'
+  | 'pathname'
+  | 'port'
+  | 'protocol'
+  | 'search'
+  | 'username'
+  | 'text'
+  | 'currentTime'
+  | 'defaultPlaybackRate'
+  | 'playbackRate'
+  | 'preservesPitch'
+  | 'volume'
+  | 'returnValue'
+  | 'selectedIndex'
+  | 'selectionDirection'
+  | 'selectionEnd'
+  | 'selectionStart'
+  | 'valueAsNumber'
+  | 'length'
+  | 'ch'
+  | 'chOff';

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/keyboard/index.mts

@@ -0,0 +1 @@
+export * from './is-ime-key-down.mjs';

package/src/keyboard/is-ime-key-down.mts

@@ -0,0 +1,20 @@
+import type { StrictPick } from 'ts-type-forge';
+
+/**
+ * Whether a key down is an input method's rather than the field's: one sent
+ * while a composition is going on, or the Enter or Escape that confirmed or
+ * cancelled one, which Safari sends after `compositionend`, told from the
+ * field's by its key code alone. Other keys with that key code are the field's:
+ * a virtual keyboard on Android sends it for the keys that type text, and its
+ * arrow keys may carry it too.
+ */
+export const isImeKeyDown = (
+  event: StrictPick<KeyboardEvent, 'isComposing' | 'key' | 'keyCode'>,
+): boolean =>
+  event.isComposing ||
+  ((event.key === 'Enter' || event.key === 'Escape') &&
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- the key code is all that tells Safari's apart
+    event.keyCode === imeKeyCode);
+
+/** The key code of a key down that an input method takes. */
+const imeKeyCode = 229;

package/src/keyboard/is-ime-key-down.test.mts

@@ -0,0 +1,42 @@
+import { isImeKeyDown } from './is-ime-key-down.mjs';
+
+// Plain objects stand in for `KeyboardEvent`s: it reads only these fields, and
+// Node.js has no `KeyboardEvent`.
+describe(isImeKeyDown, () => {
+  test('is a key down sent while an input method is composing', () => {
+    assert.isTrue(isImeKeyDown(keyDown('a', 229, true)));
+
+    assert.isTrue(isImeKeyDown(keyDown('ArrowUp', 229, true)));
+  });
+
+  test.each(['Enter', 'Escape'])(
+    'is %s with key code 229, which Safari sends after compositionend',
+    (key) => {
+      assert.isTrue(isImeKeyDown(keyDown(key, 229)));
+    },
+  );
+
+  test('is not another key with key code 229, as an Android virtual keyboard sends every key', () => {
+    assert.isFalse(isImeKeyDown(keyDown('ArrowUp', 229)));
+  });
+
+  test.each([
+    ['Enter', 13],
+    ['Escape', 27],
+    ['a', 65],
+  ] as const)('is not a plain %s', (key, code) => {
+    assert.isFalse(isImeKeyDown(keyDown(key, code)));
+  });
+});
+
+/** The fields of a key down that `isImeKeyDown` reads. */
+const keyDown = (
+  key: string,
+  code: number,
+  isComposing: boolean = false,
+): Readonly<{ key: string; keyCode: number; isComposing: boolean }> =>
+  ({
+    key,
+    keyCode: code,
+    isComposing,
+  }) as const;

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