synstate-dom 0.0.0-stage → 0.2.0

package/src/internal/bind-value.mts

@@ -0,0 +1,58 @@
+import {
+  isObservable,
+  onScopeDispose,
+  type InitializedObservable,
+} from 'synstate';
+import type { Bindable } from '../constant/index.mjs';
+import { isView } from './is-view.mjs';
+
+/**
+ * Writes the value of a {@link Bindable} with `write`, and again on every
+ * update (SPEC.md 7.1).
+ *
+ * - A constant is written once.
+ * - A completed observable has its current value written once.
+ * - Any other observable is subscribed to, and the subscription is released
+ *   when the current scope is disposed.
+ *
+ * A view is the same as its source, with its function applied before `write`.
+ */
+export const bindValue = <T,>(
+  bindable: Bindable<T>,
+  write: (value: T) => void,
+): void => {
+  if (isView(bindable)) {
+    bindable.open((source, fn) => {
+      subscribeInScope(source, (value) => {
+        write(fn(value));
+      });
+    });
+
+    return;
+  }
+
+  if (isObservable(bindable)) {
+    subscribeInScope(bindable, write);
+
+    return;
+  }
+
+  write(bindable);
+};
+
+const subscribeInScope = <A,>(
+  source: InitializedObservable<A>,
+  write: (value: A) => void,
+): void => {
+  if (source.isCompleted) {
+    write(source.getSnapshot().value);
+
+    return;
+  }
+
+  const subscription = source.subscribe(write);
+
+  onScopeDispose(() => {
+    subscription.unsubscribe();
+  });
+};

package/src/internal/dom-tables.mts

@@ -0,0 +1,176 @@
+import type { ReadonlyRecord, RelaxedExclude } from 'ts-type-forge';
+
+/**
+ * The keys written as DOM properties (`element[key] = value`) rather than as
+ * attributes. These are the ones a user's input moves away from the attribute
+ * (`value`, `checked`, …), and the enumerated attributes whose `false` is a
+ * value rather than an absence (`draggable`, `spellcheck`, `translate`).
+ *
+ * The props types and the binding both read this table (SPEC.md 5.2).
+ */
+export const propertyNames = [
+  'checked',
+  'defaultChecked',
+  'defaultValue',
+  'draggable',
+  'indeterminate',
+  'muted',
+  'selected',
+  'spellcheck',
+  'translate',
+  'value',
+] as const;
+
+/**
+ * DOM property names whose attribute is spelt differently. Every other name is
+ * passed to `setAttribute`, which lower-cases it for an HTML element
+ * (`tabIndex` becomes `tabindex`).
+ */
+export const attributeNameOf: ReadonlyRecord<string, string> = {
+  acceptCharset: 'accept-charset',
+  htmlFor: 'for',
+  httpEquiv: 'http-equiv',
+} as const;
+
+/**
+ * The tags created in the SVG namespace: those of `SVGElementTagNameMap` that
+ * HTML does not also have. `a`, `script`, `style` and `title` are created as
+ * HTML elements wherever they appear.
+ */
+export const svgTagNames = [
+  'animate',
+  'animateMotion',
+  'animateTransform',
+  'circle',
+  'clipPath',
+  'defs',
+  'desc',
+  'ellipse',
+  'feBlend',
+  'feColorMatrix',
+  'feComponentTransfer',
+  'feComposite',
+  'feConvolveMatrix',
+  'feDiffuseLighting',
+  'feDisplacementMap',
+  'feDistantLight',
+  'feDropShadow',
+  'feFlood',
+  'feFuncA',
+  'feFuncB',
+  'feFuncG',
+  'feFuncR',
+  'feGaussianBlur',
+  'feImage',
+  'feMerge',
+  'feMergeNode',
+  'feMorphology',
+  'feOffset',
+  'fePointLight',
+  'feSpecularLighting',
+  'feSpotLight',
+  'feTile',
+  'feTurbulence',
+  'filter',
+  'foreignObject',
+  'g',
+  'image',
+  'line',
+  'linearGradient',
+  'marker',
+  'mask',
+  'metadata',
+  'mpath',
+  'path',
+  'pattern',
+  'polygon',
+  'polyline',
+  'radialGradient',
+  'rect',
+  'set',
+  'stop',
+  'svg',
+  'switch',
+  'symbol',
+  'text',
+  'textPath',
+  'tspan',
+  'use',
+  'view',
+] as const satisfies readonly RelaxedExclude<
+  keyof SVGElementTagNameMap,
+  keyof HTMLElementTagNameMap
+>[];
+
+export type SvgTagName = (typeof svgTagNames)[number];
+
+/**
+ * The attributes an SVG element takes. SVG properties are animated values
+ * (`SVGAnimatedLength`), so unlike HTML they cannot be read off the element
+ * types; these are listed by hand and written with `setAttribute` as named.
+ */
+export const svgAttributeNames = [
+  'clip-path',
+  'clip-rule',
+  'cx',
+  'cy',
+  'd',
+  'dominant-baseline',
+  'dx',
+  'dy',
+  'fill',
+  'fill-opacity',
+  'fill-rule',
+  'filter',
+  'font-family',
+  'font-size',
+  'font-weight',
+  'fx',
+  'fy',
+  'gradientTransform',
+  'gradientUnits',
+  'height',
+  'href',
+  'id',
+  'marker-end',
+  'marker-mid',
+  'marker-start',
+  'markerHeight',
+  'markerUnits',
+  'markerWidth',
+  'mask',
+  'offset',
+  'opacity',
+  'orient',
+  'pathLength',
+  'patternUnits',
+  'points',
+  'preserveAspectRatio',
+  'r',
+  'refX',
+  'refY',
+  'role',
+  'rx',
+  'ry',
+  'stop-color',
+  'stop-opacity',
+  'stroke',
+  'stroke-dasharray',
+  'stroke-dashoffset',
+  'stroke-linecap',
+  'stroke-linejoin',
+  'stroke-opacity',
+  'stroke-width',
+  'tabindex',
+  'text-anchor',
+  'transform',
+  'viewBox',
+  'visibility',
+  'width',
+  'x',
+  'x1',
+  'x2',
+  'y',
+  'y1',
+  'y2',
+] as const;

package/src/internal/index.mts

@@ -0,0 +1,6 @@
+export * from './as-constant.mjs';
+export * from './bind-value.mjs';
+export * from './dom-tables.mjs';
+export * from './is-view.mjs';
+export * from './mountable-tag.mjs';
+export * from './view-tag.mjs';

package/src/internal/is-view.mts

@@ -0,0 +1,6 @@
+import { hasKey, isRecord } from 'ts-data-forge';
+import type { Bindable, View } from '../constant/index.mjs';
+import { viewTag } from './view-tag.mjs';
+
+export const isView = <T,>(bindable: Bindable<T>): bindable is View<T> =>
+  isRecord(bindable) && hasKey(bindable, viewTag);

package/src/internal/mountable-tag.mts

@@ -0,0 +1,5 @@
+/**
+ * The key a {@link Mountable} carries, so that mounting a child can tell a
+ * description from a `Bindable` at run time.
+ */
+export const mountableTag: unique symbol = Symbol.for('synstate-dom/mountable');

package/src/internal/view-tag.mts

@@ -0,0 +1,6 @@
+/**
+ * The key a {@link View} carries, so that binding can tell it from a constant
+ * at run time. `Symbol.for` rather than `Symbol`, matching the mark synstate
+ * puts on its observables: two copies of the module still agree.
+ */
+export const viewTag: unique symbol = Symbol.for('synstate-dom/view');

package/src/jsx/child.mts

@@ -0,0 +1,51 @@
+import { isObservable } from 'synstate';
+import { Arr, hasKey, isNumber, isRecord, isString } from 'ts-data-forge';
+import type { Bindable } from '../constant/index.mjs';
+import { bindValue, mountableTag, viewTag } from '../internal/index.mjs';
+import type { Mountable, MountedNodes } from './mountable.mjs';
+
+/**
+ * What a JSX element accepts as a child. Text must be a `Bindable` like any
+ * other data: `<p>{constant('big')}</p>`, never `<p>big</p>` (SPEC.md 5.1).
+ */
+export type Child = Bindable<number | string> | Mountable | readonly Child[];
+
+/**
+ * Mounts a child in the current scope and returns its nodes in order: a
+ * description is mounted, a `Bindable` becomes a text node bound to it, and an
+ * array is flattened.
+ */
+export const mountChild = (child: Child): readonly ChildNode[] => {
+  if (Arr.isArray(child)) {
+    return child.flatMap(mountChild);
+  }
+
+  if (isMountable(child)) {
+    return toNodes(child.mount());
+  }
+
+  const mut_text = document.createTextNode('');
+
+  bindValue(child, (value) => {
+    mut_text.data = value.toString();
+  });
+
+  return [mut_text];
+};
+
+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.
+ */
+export const isChild = (value: unknown): value is Child =>
+  Arr.isArray(value) ||
+  isString(value) ||
+  isNumber(value) ||
+  isObservable(value) ||
+  (isRecord(value) && (hasKey(value, mountableTag) || hasKey(value, viewTag)));
+
+const isMountable = (child: Child): child is Mountable =>
+  isRecord(child) && hasKey(child, mountableTag);

package/src/jsx/element-props.mts

@@ -0,0 +1,132 @@
+import type { ReadonlyRecord, StrictPick, TypeEq } from 'ts-type-forge';
+import type { Bindable } from '../constant/index.mjs';
+import type {
+  propertyNames,
+  svgAttributeNames,
+  SvgTagName,
+} from '../internal/index.mjs';
+import type { Child } from './child.mjs';
+import type { EventPropNames } from './event-prop-names.mjs';
+
+/**
+ * The props every intrinsic element takes.
+ *
+ * - `ref` is called once with the element, right after it is created and
+ *   before its children are mounted or anything is bound.
+ * - `class` is either a string or an object of `Bindable<boolean>`s, one per
+ *   class name, never both (SPEC.md 7.2).
+ * - `style` is either a `cssText` string or an object of CSS properties, each
+ *   bound with `style.setProperty`, so the keys are the hyphenated names
+ *   (`'background-color'`, `'--accent'`).
+ */
+export type CommonElementProps<E extends Element> = Readonly<{
+  ref?: (element: E) => void;
+  children?: Child;
+  class?: Bindable<string> | ClassObject;
+  style?: Bindable<string> | StyleObject;
+}> &
+  Partial<
+    ReadonlyRecord<
+      `aria-${string}` | `data-${string}`,
+      Bindable<string | undefined>
+    >
+  >;
+
+/** `class` as one `Bindable<boolean>` per class name. */
+export type ClassObject = ReadonlyRecord<string, Bindable<boolean>>;
+
+/**
+ * `style` as one `Bindable<string | undefined>` per hyphenated CSS property
+ * name; `undefined` removes the property.
+ */
+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`.
+ *
+ * An attribute, `aria-*` and `data-*` included, also takes `undefined`, which
+ * removes it: a value that comes and goes is an observable of `T | undefined`
+ * (SPEC.md 4.1). A DOM property of `propertyNames` (`value`, `checked`, …) has
+ * no absent state and does not.
+ */
+export type HtmlElementProps<E extends HTMLElement> = CommonElementProps<E> &
+  ReflectedProps<E> &
+  EventProps<E, HTMLElementEventMap>;
+
+/**
+ * The props of an SVG element: the common ones, the attributes of
+ * `svgAttributeNames`, and one handler per event of `SVGElementEventMap`.
+ */
+export type SvgElementProps<E extends SVGElement> = CommonElementProps<E> &
+  Partial<
+    ReadonlyRecord<
+      (typeof svgAttributeNames)[number],
+      Bindable<number | string | undefined>
+    >
+  > &
+  EventProps<E, SVGElementEventMap>;
+
+/**
+ * One handler per event, named `on` followed by the event's name in
+ * PascalCase (`onClick`, `onPointerDown`). `currentTarget` is narrowed to the
+ * element. A handler is a function, never an observable.
+ */
+export type EventProps<E extends Element, M> = Readonly<{
+  [K in keyof M & keyof EventPropNames as EventPropNames[K]]?: (
+    event: M[K] & Readonly<{ currentTarget: E }>,
+  ) => void;
+}>;
+
+export type GeneratedIntrinsicElements = Readonly<{
+  [K in keyof HTMLElementTagNameMap]: HtmlElementProps<
+    HTMLElementTagNameMap[K]
+  >;
+}> &
+  Readonly<{ [K in SvgTagName]: SvgElementProps<SVGElementTagNameMap[K]> }>;
+
+type ReflectedProps<E> = Readonly<{
+  [K in keyof E as ReflectedKey<E, K>]?: Bindable<
+    K extends PropertyName ? NonNullable<E[K]> : NonNullable<E[K]> | undefined
+  >;
+}>;
+
+type PropertyName = (typeof propertyNames)[number];
+
+/**
+ * `K` if it is a writable primitive property of `E`, and `never` otherwise.
+ * An index signature is dropped: `HTMLFormElement` has one for its named
+ * controls, which would otherwise swallow every other key.
+ */
+type ReflectedKey<E, K extends keyof E> = string extends K
+  ? never
+  : number extends K
+    ? never
+    : K extends ExcludedKey | `aria${string}` | `on${string}`
+      ? never
+      : NonNullable<E[K]> extends boolean | number | string
+        ? IsWritable<E, K> extends true
+          ? K
+          : never
+        : never;
+
+type IsWritable<E, K extends keyof E> =
+  TypeEq<StrictPick<E, K>, Readonly<StrictPick<E, K>>> extends true
+    ? false
+    : true;
+
+/**
+ * Writable primitive properties that are not attributes, or that are props of
+ * their own (`class`, `style`).
+ */
+type ExcludedKey =
+  | 'className'
+  | 'innerHTML'
+  | 'innerText'
+  | 'nodeValue'
+  | 'outerHTML'
+  | 'outerText'
+  | 'scrollLeft'
+  | 'scrollTop'
+  | 'textContent';

package/src/jsx/element-props.test.mts

@@ -0,0 +1,28 @@
+import { expectType } from 'ts-data-forge';
+import type { EventPropNames } from './event-prop-names.mjs';
+
+describe('EventPropNames', () => {
+  test('names every event of HTML and SVG elements', () => {
+    expectType<
+      keyof EventPropNames,
+      keyof HTMLElementEventMap | keyof SVGElementEventMap
+    >('=');
+
+    assert.isTrue(true);
+  });
+
+  test('lower-casing a prop name gives its event name back', () => {
+    expectType<
+      {
+        [K in keyof EventPropNames]: Lowercase<
+          EventPropNames[K]
+        > extends `on${K}`
+          ? true
+          : false;
+      }[keyof EventPropNames],
+      true
+    >('=');
+
+    assert.isTrue(true);
+  });
+});

package/src/jsx/event-prop-names.mts

@@ -0,0 +1,119 @@
+/**
+ * The prop name of each DOM event, in the PascalCase React uses
+ * (`pointerdown` → `onPointerDown`). The event names are single lower-case
+ * words, so the word boundaries have to be written down; binding needs no
+ * table, since lower-casing the prop name gives the event name back.
+ *
+ * Covers every key of `HTMLElementEventMap` and `SVGElementEventMap`, which
+ * `element-props.test.mts` asserts.
+ */
+export type EventPropNames = Readonly<{
+  abort: 'onAbort';
+  animationcancel: 'onAnimationCancel';
+  animationend: 'onAnimationEnd';
+  animationiteration: 'onAnimationIteration';
+  animationstart: 'onAnimationStart';
+  auxclick: 'onAuxClick';
+  beforeinput: 'onBeforeInput';
+  beforematch: 'onBeforeMatch';
+  beforetoggle: 'onBeforeToggle';
+  blur: 'onBlur';
+  cancel: 'onCancel';
+  canplay: 'onCanPlay';
+  canplaythrough: 'onCanPlayThrough';
+  change: 'onChange';
+  click: 'onClick';
+  close: 'onClose';
+  command: 'onCommand';
+  compositionend: 'onCompositionEnd';
+  compositionstart: 'onCompositionStart';
+  compositionupdate: 'onCompositionUpdate';
+  contextlost: 'onContextLost';
+  contextmenu: 'onContextMenu';
+  contextrestored: 'onContextRestored';
+  copy: 'onCopy';
+  cuechange: 'onCueChange';
+  cut: 'onCut';
+  dblclick: 'onDblClick';
+  drag: 'onDrag';
+  dragend: 'onDragEnd';
+  dragenter: 'onDragEnter';
+  dragleave: 'onDragLeave';
+  dragover: 'onDragOver';
+  dragstart: 'onDragStart';
+  drop: 'onDrop';
+  durationchange: 'onDurationChange';
+  emptied: 'onEmptied';
+  ended: 'onEnded';
+  error: 'onError';
+  focus: 'onFocus';
+  focusin: 'onFocusIn';
+  focusout: 'onFocusOut';
+  formdata: 'onFormData';
+  fullscreenchange: 'onFullscreenChange';
+  fullscreenerror: 'onFullscreenError';
+  gotpointercapture: 'onGotPointerCapture';
+  input: 'onInput';
+  invalid: 'onInvalid';
+  keydown: 'onKeyDown';
+  keypress: 'onKeyPress';
+  keyup: 'onKeyUp';
+  load: 'onLoad';
+  loadeddata: 'onLoadedData';
+  loadedmetadata: 'onLoadedMetadata';
+  loadstart: 'onLoadStart';
+  lostpointercapture: 'onLostPointerCapture';
+  mousedown: 'onMouseDown';
+  mouseenter: 'onMouseEnter';
+  mouseleave: 'onMouseLeave';
+  mousemove: 'onMouseMove';
+  mouseout: 'onMouseOut';
+  mouseover: 'onMouseOver';
+  mouseup: 'onMouseUp';
+  paste: 'onPaste';
+  pause: 'onPause';
+  play: 'onPlay';
+  playing: 'onPlaying';
+  pointercancel: 'onPointerCancel';
+  pointerdown: 'onPointerDown';
+  pointerenter: 'onPointerEnter';
+  pointerleave: 'onPointerLeave';
+  pointermove: 'onPointerMove';
+  pointerout: 'onPointerOut';
+  pointerover: 'onPointerOver';
+  pointerrawupdate: 'onPointerRawUpdate';
+  pointerup: 'onPointerUp';
+  progress: 'onProgress';
+  ratechange: 'onRateChange';
+  reset: 'onReset';
+  resize: 'onResize';
+  scroll: 'onScroll';
+  scrollend: 'onScrollEnd';
+  securitypolicyviolation: 'onSecurityPolicyViolation';
+  seeked: 'onSeeked';
+  seeking: 'onSeeking';
+  select: 'onSelect';
+  selectionchange: 'onSelectionChange';
+  selectstart: 'onSelectStart';
+  slotchange: 'onSlotChange';
+  stalled: 'onStalled';
+  submit: 'onSubmit';
+  suspend: 'onSuspend';
+  timeupdate: 'onTimeUpdate';
+  toggle: 'onToggle';
+  touchcancel: 'onTouchCancel';
+  touchend: 'onTouchEnd';
+  touchmove: 'onTouchMove';
+  touchstart: 'onTouchStart';
+  transitioncancel: 'onTransitionCancel';
+  transitionend: 'onTransitionEnd';
+  transitionrun: 'onTransitionRun';
+  transitionstart: 'onTransitionStart';
+  volumechange: 'onVolumeChange';
+  waiting: 'onWaiting';
+  webkitanimationend: 'onWebkitAnimationEnd';
+  webkitanimationiteration: 'onWebkitAnimationIteration';
+  webkitanimationstart: 'onWebkitAnimationStart';
+  webkittransitionend: 'onWebkitTransitionEnd';
+  wheel: 'onWheel';
+}>;

package/src/jsx/index.mts

@@ -0,0 +1,6 @@
+export * from './child.mjs';
+export * from './element-props.mjs';
+export * from './event-prop-names.mjs';
+export * from './jsx-namespace.mjs';
+export * from './jsx.mjs';
+export * from './mountable.mjs';

package/src/jsx/jsx-namespace.mts

@@ -0,0 +1,11 @@
+import type { GeneratedIntrinsicElements } from './element-props.mjs';
+import type { Mountable } from './mountable.mjs';
+
+/** The `JSX` namespace TypeScript reads through `jsxImportSource`. */
+export declare namespace JSX {
+  type Element = Mountable;
+
+  type ElementChildrenAttribute = Readonly<{ children: unknown }>;
+
+  type IntrinsicElements = GeneratedIntrinsicElements;
+}

package/src/jsx/jsx.mts

@@ -0,0 +1,63 @@
+import { hasKey, isRecord } from 'ts-data-forge';
+import { bindProps } from '../bind/index.mjs';
+import { svgTagNames } from '../internal/index.mjs';
+import { isChild, mountChild, type Child } from './child.mjs';
+import { mountable, type Mountable } from './mountable.mjs';
+
+/**
+ * The JSX factory (SPEC.md 6.2), exported from `synstate-dom/jsx-runtime` as
+ * `jsx` and `jsxs`. Returns a description and does nothing else:
+ * no DOM is created and no component is called until it is mounted.
+ *
+ * TypeScript checks a JSX expression against the `JSX` namespace, not against
+ * this signature, so the props of an intrinsic element arrive as `P` and are
+ * read with run-time checks.
+ *
+ */
+export const createMountable = <P,>(
+  type: string | ((componentProps: P) => Mountable),
+  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.
+  const propsWithKey = key === undefined ? props : ({ ...props, key } as const);
+
+  return typeof type === 'string'
+    ? mountable(() => mountElement(type, props))
+    : mountable(() => type(propsWithKey).mount());
+};
+
+/** Mounts its children in order, with no element around them. */
+export const Fragment = (props: Readonly<{ children?: Child }>): Mountable =>
+  mountable(() => mountChild(props.children ?? []));
+
+const mountElement = (tag: string, props: unknown): Element => {
+  const element = svgTagNameSet.has(tag)
+    ? document.createElementNS(svgNamespace, tag)
+    : document.createElement(tag);
+
+  if (!isRecord(props)) {
+    return element;
+  }
+
+  if (hasKey(props, 'ref') && isRefCallback(props.ref)) {
+    props.ref(element);
+  }
+
+  // Children first, so that a `<select>`'s `value` finds its `<option>`s.
+  if (hasKey(props, 'children') && isChild(props.children)) {
+    element.append(...mountChild(props.children));
+  }
+
+  bindProps(element, props);
+
+  return 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';