synstate-dom 0.0.0-stage → 0.2.0

package/src/bind/bind-props.mts

@@ -0,0 +1,174 @@
+import { isObservable, onScopeDispose } from 'synstate';
+import { hasKey, isBoolean, isRecord, unknownToString } from 'ts-data-forge';
+import type { ReadonlyRecord } from 'ts-type-forge';
+import type { Bindable } from '../constant/index.mjs';
+import {
+  attributeNameOf,
+  bindValue,
+  propertyNames,
+  viewTag,
+} from '../internal/index.mjs';
+
+/**
+ * Binds every prop of an intrinsic element except `ref` and `children`
+ * (SPEC.md 7): `class`, `style`, event handlers, the DOM properties of
+ * `propertyNames`, and attributes for the rest. Subscriptions and listeners
+ * are released when the current scope is disposed.
+ */
+export const bindProps = (
+  element: Element,
+  props: ReadonlyRecord<string, unknown>,
+): void => {
+  for (const [key, value] of Object.entries(props)) {
+    bindProp(element, key, value);
+  }
+};
+
+const bindProp = (element: Element, key: string, value: unknown): void => {
+  if (key === 'children' || key === 'ref' || !isBindable(value)) {
+    return;
+  }
+
+  if (key === 'class') {
+    bindClass(element, value);
+
+    return;
+  }
+
+  if (key === 'style') {
+    bindStyle(element, value);
+
+    return;
+  }
+
+  if (isEventKey(key) && isEventHandler(value)) {
+    bindEvent(element, key.slice(2).toLowerCase(), value);
+
+    return;
+  }
+
+  if (propertyNameSet.has(key)) {
+    bindValue(value, (v) => {
+      Reflect.set(element, key, v);
+    });
+
+    return;
+  }
+
+  const name = attributeNameOf[key] ?? key;
+
+  bindValue(value, (v) => {
+    writeAttribute(element, name, v);
+  });
+};
+
+const bindClass = (element: Element, value: Bindable<unknown>): void => {
+  if (!isPlainObject(value)) {
+    bindValue(value, (v) => {
+      writeAttribute(element, 'class', v);
+    });
+
+    return;
+  }
+
+  for (const [name, on] of Object.entries(value)) {
+    if (/\s/u.test(name)) {
+      console.error(
+        `synstate-dom: the class name ${JSON.stringify(name)} contains whitespace; give each class its own key.`,
+      );
+
+      continue;
+    }
+
+    if (isBindable(on)) {
+      bindValue(on, (v) => {
+        element.classList.toggle(name, v === true);
+      });
+    }
+  }
+};
+
+const bindStyle = (element: Element, value: Bindable<unknown>): void => {
+  if (!(element instanceof HTMLElement || element instanceof SVGElement)) {
+    return;
+  }
+
+  const { style } = element;
+
+  if (!isPlainObject(value)) {
+    bindValue(value, (v) => {
+      writeAttribute(element, 'style', v);
+    });
+
+    return;
+  }
+
+  for (const [name, v] of Object.entries(value)) {
+    if (isBindable(v)) {
+      bindValue(v, (current) => {
+        if (current === undefined || current === null) {
+          style.removeProperty(name);
+        } else {
+          style.setProperty(name, unknownToString(current));
+        }
+      });
+    }
+  }
+};
+
+const bindEvent = (
+  element: Element,
+  type: string,
+  handler: EventListener,
+): void => {
+  element.addEventListener(type, handler);
+
+  onScopeDispose(() => {
+    element.removeEventListener(type, handler);
+  });
+};
+
+/**
+ * `true` writes an empty attribute, and `false`, `undefined` and `null`
+ * remove it.
+ */
+const writeAttribute = (
+  element: Element,
+  name: string,
+  value: unknown,
+): void => {
+  if (isBoolean(value)) {
+    element.toggleAttribute(name, value);
+
+    return;
+  }
+
+  if (value === undefined || value === null) {
+    element.removeAttribute(name);
+
+    return;
+  }
+
+  element.setAttribute(name, unknownToString(value));
+};
+
+const propertyNameSet: ReadonlySet<string> = new Set(propertyNames);
+
+/**
+ * Every value is a `Bindable` at run time: what is neither an observable nor
+ * a view is a constant. An omitted prop is `undefined`, which is not.
+ */
+const isBindable = (value: unknown): value is Bindable<unknown> =>
+  value !== undefined && value !== null;
+
+/** `class` and `style` in their object form: neither an observable nor a view. */
+const isPlainObject = (
+  value: unknown,
+): value is ReadonlyRecord<string, unknown> =>
+  isRecord(value) && !isObservable(value) && !hasKey(value, viewTag);
+
+/** `onClick`, `onPointerDown`: `on` and an upper-case letter. */
+const isEventKey = (key: string): boolean => /^on[A-Z]/u.test(key);
+
+const isEventHandler = (value: unknown): value is EventListener =>
+  typeof value === 'function';

package/src/bind/index.mts

@@ -0,0 +1 @@
+export * from './bind-props.mjs';

package/src/constant/bindable.mts

@@ -0,0 +1,19 @@
+import type { InitializedObservable, Observable } from 'synstate';
+import type { Constant } from './constant.mjs';
+import type { View } from './view.mjs';
+
+/**
+ * What a slot that takes data accepts: an observable with an initial value, an
+ * explicit {@link Constant}, or a {@link View}. A plain value is not accepted.
+ */
+export type Bindable<T> = Constant<T> | InitializedObservable<T> | View<T>;
+
+/** The value type a {@link Bindable} carries. */
+export type BindableValue<B> =
+  B extends View<infer T>
+    ? T
+    : B extends Observable<infer T>
+      ? T
+      : B extends Constant<infer T>
+        ? T
+        : never;

package/src/constant/constant.mts

@@ -0,0 +1,24 @@
+import type { Observable } from 'synstate';
+import type { Brand } from 'ts-type-forge';
+import { asConstant } from '../internal/index.mjs';
+
+/**
+ * A value that is written once and never updated. A brand that exists only in
+ * the type system: at run time it is the value itself.
+ *
+ * A slot that takes data accepts a `Constant<T>` but not a plain `T`, so that
+ * a value read once and never updated (`count$.getSnapshot().value`) is a type
+ * error rather than a binding that silently stays stale.
+ */
+export type Constant<T> = Brand<T, 'synstate-dom/Constant'>;
+
+/**
+ * Marks a value as a {@link Constant}. Returns the value unchanged.
+ *
+ * `null` and `undefined` are rejected: an absent attribute is an omitted prop,
+ * and a value that comes and goes is an `InitializedObservable<T | undefined>`.
+ * An observable is rejected too, since wrapping one would bind it once.
+ */
+export const constant = <const T,>(
+  value: T extends Observable<unknown> | null | undefined ? never : T,
+): Constant<T> => asConstant<T>(value);

package/src/constant/constant.test.mts

@@ -0,0 +1,70 @@
+import { createState } from 'synstate';
+import { expectType } from 'ts-data-forge';
+import type { Bindable } from './bindable.mjs';
+import { constant, type Constant } from './constant.mjs';
+
+describe(constant, () => {
+  test('returns the value unchanged', () => {
+    const value = { a: 1 } as const;
+
+    assert.strictEqual(constant(value), value);
+
+    assert.strictEqual(constant('btn'), 'btn');
+  });
+
+  test('keeps the literal type', () => {
+    const c = constant('btn');
+
+    expectType<typeof c, Constant<'btn'>>('=');
+
+    assert.strictEqual<unknown>(c, 'btn');
+  });
+
+  test('a constant can be read as its value', () => {
+    const n: number = constant(1);
+
+    assert.strictEqual(n, 1);
+  });
+
+  test('rejects null, undefined and observables', () => {
+    const [count$] = createState(0);
+
+    // @ts-expect-error null is not a constant: omit the prop instead
+    constant(null);
+
+    // @ts-expect-error undefined is not a constant: omit the prop instead
+    constant(undefined);
+
+    // @ts-expect-error wrapping an observable would bind it once
+    constant(count$);
+
+    const maybe = Math.random() > 2 ? 'a' : undefined;
+
+    // @ts-expect-error a value that may be undefined is an observable of `T | undefined`
+    constant(maybe);
+
+    assert.isTrue(true);
+  });
+
+  test('a plain value is not a Bindable', () => {
+    const [count$] = createState(0);
+
+    // @ts-expect-error a plain value would be written once and never updated
+    const plain: Bindable<string> = 'btn';
+
+    // @ts-expect-error the snapshot is read once
+    const snapshot: Bindable<number> = count$.getSnapshot().value;
+
+    const fromConstant: Bindable<string> = constant('btn');
+
+    const fromObservable: Bindable<number> = count$;
+
+    assert.strictEqual<unknown>(plain, 'btn');
+
+    assert.strictEqual<unknown>(snapshot, 0);
+
+    assert.strictEqual<unknown>(fromConstant, 'btn');
+
+    assert.strictEqual(fromObservable, count$);
+  });
+});

package/src/constant/derive.mts

@@ -0,0 +1,51 @@
+import {
+  combine,
+  isObservable,
+  map,
+  type InitializedObservable,
+} from 'synstate';
+import { Arr } from 'ts-data-forge';
+import type { NonEmptyTuple } from 'ts-type-forge';
+import { asConstant, isView } from '../internal/index.mjs';
+import type { Bindable, BindableValue } from './bindable.mjs';
+import { toObservable } from './to-observable.mjs';
+
+/**
+ * Combines several {@link Bindable}s into one.
+ *
+ * When every input is a constant, `fn` runs once and the result is a constant:
+ * a static part of the view never enters the graph. Otherwise the constants
+ * become `just` and the views are turned into observables, and the result is
+ * `combine(...).pipe(map(...))`.
+ */
+export const derive = <const BS extends NonEmptyTuple<Bindable<unknown>>, R>(
+  bindables: BS,
+  fn: (...values: BindableValues<BS>) => R,
+): Bindable<R> => {
+  // `values` holds, position by position, the value of each of `bindables`:
+  // the constants themselves, or what `combine` emits for their observables.
+  // The checker cannot follow a position through `Arr.map` and `combine`,
+  // which carry one element type for the whole tuple.
+  const apply = (values: readonly unknown[]): R =>
+    // eslint-disable-next-line total-functions/no-unsafe-type-assertion -- see above
+    fn(...(values as BindableValues<BS>));
+
+  if (Arr.every(bindables, isConstant)) {
+    return asConstant(apply(bindables));
+  }
+
+  const observables: NonEmptyTuple<InitializedObservable<unknown>> = Arr.map(
+    bindables,
+    toObservable,
+  );
+
+  return combine(observables).pipe(map(apply));
+};
+
+/** The value types of a tuple of {@link Bindable}s, position by position. */
+export type BindableValues<BS extends readonly Bindable<unknown>[]> = Readonly<{
+  [K in keyof BS]: BindableValue<BS[K]>;
+}>;
+
+const isConstant = (bindable: Bindable<unknown>): boolean =>
+  !isView(bindable) && !isObservable(bindable);

package/src/constant/derive.test.mts

@@ -0,0 +1,64 @@
+import { createState, isObservable } from 'synstate';
+import { expectType } from 'ts-data-forge';
+import type { Bindable } from './bindable.mjs';
+import { constant } from './constant.mjs';
+import { derive } from './derive.mjs';
+import { toObservable } from './to-observable.mjs';
+import { view } from './view.mjs';
+
+describe(derive, () => {
+  test('constants only give a constant without creating a node', () => {
+    const fn = vi.fn((a: number, b: string) => `${b}${a}`);
+
+    const result = derive([constant(1), constant('x')], fn);
+
+    expectType<typeof result, Bindable<string>>('=');
+
+    assert.isFalse(isObservable(result));
+
+    assert.strictEqual<unknown>(result, 'x1');
+
+    expect(fn).toHaveBeenCalledExactlyOnceWith(1, 'x');
+  });
+
+  test('passes each value with its own type', () => {
+    const [count$] = createState(0);
+
+    derive([count$, constant('a'), view(count$, (n) => n > 0)], (n, s, b) => {
+      expectType<typeof n, number>('=');
+
+      expectType<typeof s, 'a'>('=');
+
+      expectType<typeof b, boolean>('=');
+
+      return 0;
+    });
+
+    assert.isTrue(true);
+  });
+
+  test('observables, constants and views are combined', () => {
+    const [count$, setCount] = createState(1);
+
+    const [label$, setLabel] = createState('a');
+
+    const result = derive(
+      [count$, constant('-'), view(label$, (s) => s.toUpperCase())],
+      (n, sep, label) => `${n}${sep}${label}`,
+    );
+
+    assert.isTrue(isObservable(result));
+
+    const result$ = toObservable(result);
+
+    assert.strictEqual(result$.getSnapshot().value, '1-A');
+
+    setCount(2);
+
+    assert.strictEqual(result$.getSnapshot().value, '2-A');
+
+    setLabel('b');
+
+    assert.strictEqual(result$.getSnapshot().value, '2-B');
+  });
+});

package/src/constant/index.mts

@@ -0,0 +1,6 @@
+export * from './bindable.mjs';
+export * from './constant.mjs';
+export * from './derive.mjs';
+export * from './map-bindable.mjs';
+export * from './to-observable.mjs';
+export * from './view.mjs';

package/src/constant/map-bindable.mts

@@ -0,0 +1,23 @@
+import { isObservable, map } from 'synstate';
+import { asConstant, isView } from '../internal/index.mjs';
+import type { Bindable } from './bindable.mjs';
+import { view } from './view.mjs';
+
+/**
+ * Applies `fn` to the value of a {@link Bindable}, keeping its kind.
+ *
+ * - A constant gives a constant: `fn` runs once and no node is created.
+ * - A view gives a view with the two functions composed: no node is created.
+ * - An observable gives `bindable.pipe(map(fn))`.
+ */
+export const mapBindable = <A, B>(
+  bindable: Bindable<A>,
+  fn: (value: A) => B,
+): Bindable<B> =>
+  isView(bindable)
+    ? bindable.open((source, inner) =>
+        view(source, (value) => fn(inner(value))),
+      )
+    : isObservable(bindable)
+      ? bindable.pipe(map(fn))
+      : asConstant(fn(bindable));

package/src/constant/map-bindable.test.mts

@@ -0,0 +1,63 @@
+import { createState, isObservable } from 'synstate';
+import { expectType } from 'ts-data-forge';
+import { isView } from '../internal/index.mjs';
+import type { Bindable } from './bindable.mjs';
+import { constant } from './constant.mjs';
+import { mapBindable } from './map-bindable.mjs';
+import { toObservable } from './to-observable.mjs';
+import { view } from './view.mjs';
+
+describe(mapBindable, () => {
+  test('a constant gives a constant without creating a node', () => {
+    const fn = vi.fn((n: number) => n * 2);
+
+    const result = mapBindable(constant(3), fn);
+
+    expectType<typeof result, Bindable<number>>('=');
+
+    assert.isFalse(isObservable(result));
+
+    assert.isFalse(isView(result));
+
+    assert.strictEqual<unknown>(result, 6);
+
+    expect(fn).toHaveBeenCalledExactlyOnceWith(3);
+  });
+
+  test('a view gives a view with the functions composed', () => {
+    const [count$, setCount] = createState(1);
+
+    const result = mapBindable(
+      view(count$, (n) => n + 1),
+      String,
+    );
+
+    assert.isTrue(isView(result));
+
+    assert.isFalse(isObservable(result));
+
+    const result$ = toObservable(result);
+
+    assert.strictEqual(result$.getSnapshot().value, '2');
+
+    setCount(5);
+
+    assert.strictEqual(result$.getSnapshot().value, '6');
+  });
+
+  test('an observable gives a mapped observable', () => {
+    const [count$, setCount] = createState(1);
+
+    const result = mapBindable(count$, (n) => n * 10);
+
+    assert.isTrue(isObservable(result));
+
+    const result$ = toObservable(result);
+
+    assert.strictEqual(result$.getSnapshot().value, 10);
+
+    setCount(2);
+
+    assert.strictEqual(result$.getSnapshot().value, 20);
+  });
+});

package/src/constant/to-observable.mts

@@ -0,0 +1,20 @@
+import { isObservable, just, map, type InitializedObservable } from 'synstate';
+import { isView } from '../internal/index.mjs';
+import type { Bindable } from './bindable.mjs';
+
+/**
+ * Turns a {@link Bindable} into an observable: a constant becomes `just(value)`,
+ * a view becomes `source.pipe(map(fn))`, and an observable is returned as is.
+ *
+ * Only for where an observable is really needed, such as the projection of a
+ * `switchMap`: a constant made into an observable joins the graph, which
+ * {@link mapBindable} and {@link derive} avoid.
+ */
+export const toObservable = <T,>(
+  bindable: Bindable<T>,
+): InitializedObservable<T> =>
+  isView(bindable)
+    ? bindable.open((source, fn) => source.pipe(map(fn)))
+    : isObservable(bindable)
+      ? bindable
+      : just(bindable);

package/src/constant/to-observable.test.mts

@@ -0,0 +1,37 @@
+import { createState, isObservable } from 'synstate';
+import { expectType } from 'ts-data-forge';
+import { constant } from './constant.mjs';
+import { toObservable } from './to-observable.mjs';
+import { view } from './view.mjs';
+
+describe(toObservable, () => {
+  test('a constant becomes a completed observable holding it', () => {
+    const result$ = toObservable(constant('a'));
+
+    assert.isTrue(isObservable(result$));
+
+    assert.isTrue(result$.isCompleted);
+
+    assert.strictEqual(result$.getSnapshot().value, 'a');
+  });
+
+  test('an observable is returned as is', () => {
+    const [count$] = createState(0);
+
+    assert.strictEqual(toObservable(count$), count$);
+  });
+
+  test('a view becomes the source mapped by its function', () => {
+    const [count$, setCount] = createState(1);
+
+    const result$ = toObservable(view(count$, (n) => n > 1));
+
+    expectType<ReturnType<typeof result$.getSnapshot>['value'], boolean>('<=');
+
+    assert.isFalse(result$.getSnapshot().value);
+
+    setCount(2);
+
+    assert.isTrue(result$.getSnapshot().value);
+  });
+});

package/src/constant/view.mts

@@ -0,0 +1,35 @@
+import type { InitializedObservable } from 'synstate';
+import { viewTag } from '../internal/index.mjs';
+
+/**
+ * An observable and a function to apply to each of its values, bound without
+ * creating a node in the graph. Made by {@link view}.
+ *
+ * The source's value type is hidden behind `open`, which hands the pair back
+ * to a callback that is generic in it: whoever opens a view sees a source and
+ * a function that agree with each other, with no assertion on either side.
+ */
+export type View<T> = Readonly<{
+  [viewTag]: true;
+  open: <R>(
+    use: <A>(source: InitializedObservable<A>, fn: (value: A) => T) => R,
+  ) => R;
+}>;
+
+/**
+ * Pairs an observable with a light transformation, for a slot that takes a
+ * `Bindable`. The transformation runs in the binding's subscriber, so no node
+ * is added to the graph.
+ *
+ * `fn` runs once per value per binding: a view passed to two slots runs it
+ * twice. A heavy transformation, or one shared by several bindings, belongs in
+ * `source.pipe(map(fn))`.
+ */
+export const view = <A, T>(
+  source: InitializedObservable<A>,
+  fn: (value: A) => T,
+): View<T> =>
+  ({
+    [viewTag]: true,
+    open: (use) => use(source, fn),
+  }) as const;

package/src/constant/view.test.mts

@@ -0,0 +1,40 @@
+import { createState } from 'synstate';
+import { expectType } from 'ts-data-forge';
+import { isView } from '../internal/index.mjs';
+import type { Bindable } from './bindable.mjs';
+import { view, type View } from './view.mjs';
+
+const fn = (n: number): string => `${n} items` as const;
+
+describe(view, () => {
+  test('opens to the source and the function it was made from', () => {
+    const [count$] = createState(2);
+
+    const v = view(count$, fn);
+
+    expectType<typeof v, View<string>>('=');
+
+    v.open((source, f) => {
+      assert.strictEqual<unknown>(source, count$);
+
+      assert.strictEqual<unknown>(f, fn);
+    });
+  });
+
+  test('ties the function parameter to the source value type', () => {
+    const [count$] = createState(0);
+
+    // @ts-expect-error a `string` parameter does not take the `number` values of `count$`
+    view(count$, (s: string) => s.length);
+
+    assert.isTrue(true);
+  });
+
+  test('is accepted where a Bindable is', () => {
+    const [count$] = createState(0);
+
+    const b: Bindable<boolean> = view(count$, (n) => n === 0);
+
+    assert.isTrue(isView(b));
+  });
+});