@tschk/moonshine-svelte 0.0.0-stage → 0.4.4

package/src/binding.ts

@@ -0,0 +1,115 @@
+/** Native binding helpers with Svelte state-proxy identity comparison. */
+import {
+  bindSelectValue as nativeBindSelectValue,
+  bindValue as nativeBindValue,
+  type InputValue,
+  createInputGroup as nativeCreateInputGroup,
+} from "@tschk/moonshine-dom/binding";
+import { stateEquals } from "./state";
+import {
+  createComponentScope,
+  getOwner,
+  getRenderScheduler,
+} from "@tschk/moonshine-dom/reactive";
+import {
+  bindOwnedReference,
+  type ComponentReference,
+  type OwnedReference,
+} from "@tschk/moonshine-dom/component-instance";
+import { captureRuneReferenceCleanup } from "./pre";
+export {
+  bindChecked,
+  bindOpen,
+  setOptionValue,
+  setInputValue,
+  type InputValue,
+} from "@tschk/moonshine-dom/binding";
+
+export function bindSelectValue(
+  select: HTMLSelectElement,
+  read: () => unknown,
+  write: (value: unknown) => void,
+): void {
+  nativeBindSelectValue(select, read, write, stateEquals);
+}
+
+export function createInputGroup(
+  kind: "radio" | "checkbox",
+  read: () => unknown,
+  write: (value: unknown) => void,
+): { bind(input: HTMLInputElement): void } {
+  return nativeCreateInputGroup(kind, read, write, stateEquals);
+}
+
+/** Svelte numeric bindings write null for an empty number/range input. */
+export function bindValue(
+  element: HTMLInputElement | HTMLTextAreaElement,
+  read: () => InputValue,
+  write: (value: string | number | null) => void,
+): void {
+  nativeBindValue(element, read, (value, reset) => {
+    write(
+      value === undefined
+        ? reset && element.defaultValue !== ""
+          ? Number(element.defaultValue)
+          : null
+        : value,
+    );
+  });
+}
+
+/** Compiler-owned element references publish before this element's actions. */
+export function bindThis<
+  T extends Element,
+  Parts extends readonly unknown[] = [],
+>(element: T, reference: ComponentReference<T, Parts, unknown>): void {
+  const owner = getOwner();
+  if (!owner || owner.disposed || owner.disposing)
+    throw new Error("Element references require a live native owner");
+  if (
+    !(element instanceof Element) ||
+    !reference ||
+    typeof reference.get !== "function" ||
+    typeof reference.set !== "function"
+  )
+    throw new TypeError(
+      "Element references require an element and getter/setter functions",
+    );
+  if (reference.cleanup !== undefined && reference.cleanup !== "commit")
+    throw new TypeError(
+      "Element reference cleanup must be commit when provided",
+    );
+  if (reference.publication !== undefined && reference.publication !== "post")
+    throw new TypeError(
+      "Element reference publication must be post when provided",
+    );
+  const scheduler = getRenderScheduler();
+  if (!scheduler)
+    throw new Error("Element references require an opt-in render scheduler");
+  const enqueueClear = captureRuneReferenceCleanup();
+  createComponentScope(() =>
+    scheduler.branch(() => {
+      const scope = getOwner()!;
+      const posts = getRenderScheduler()!;
+      let published = false;
+      let firstPublication: (() => void) | undefined;
+      bindOwnedReference(
+        scope,
+        element,
+        // Tuple callbacks enter the checked internal path protocol here.
+        reference as unknown as OwnedReference<T>,
+        (publish) => {
+          if (published) publish();
+          else
+            posts.post(
+              (firstPublication ??= () => {
+                published = true;
+                publish();
+              }),
+            );
+        },
+        { cleanup: "commit", previousCheck: "after-set", enqueueClear },
+      )();
+    }),
+  );
+}

package/src/class.ts

@@ -0,0 +1,21 @@
+/** Normalize source class expressions; ordinary native h attributes stay unchanged. */
+export function classValue(value: unknown): string | undefined {
+  if (value === null || value === undefined) return undefined;
+  if (typeof value !== "object") return `${value}` || undefined;
+  const tokens: string[] = [];
+  function append(entry: unknown): void {
+    if (!entry) return;
+    if (typeof entry === "string" || typeof entry === "number") {
+      tokens.push(`${entry}`);
+    } else if (Array.isArray(entry)) {
+      const length = entry.length;
+      for (let index = 0; index < length; index++) append(entry[index]);
+    } else if (typeof entry === "object") {
+      // Enumerable inherited class flags are part of Svelte's class expression API.
+      for (const key in entry)
+        if ((entry as Record<string, unknown>)[key]) tokens.push(key);
+    }
+  }
+  append(value);
+  return tokens.join(" ") || undefined;
+}

package/src/const-derived.ts

@@ -0,0 +1,47 @@
+/** Compiler-owned const evaluation with per-evaluation cleanup and consumer context. */
+import { createDerived } from "./derived";
+import { getRuneConsumer } from "./pre";
+import { isHistoryReading } from "./history";
+import {
+  withComponentConsumer,
+  withComponentCleanupConsumer,
+} from "@tschk/moonshine-dom/component";
+import {
+  createRoot,
+  getOwner,
+  onCleanup,
+  runWithOwner,
+  type Owner,
+} from "@tschk/moonshine-dom/reactive";
+export function createConstDerived<T>(fn: () => T): { readonly value: T } {
+  const frame = getRuneConsumer();
+  const parent = getOwner();
+  if (!parent || parent.disposed || !frame || frame.owner.disposed)
+    throw Error("Const requires a live consumer");
+  let stop: (() => void) | undefined;
+  const release = () => {
+    const previous = stop;
+    stop = undefined;
+    previous?.();
+  };
+  onCleanup(release);
+  return createDerived(() => {
+    if (isHistoryReading()) return withComponentCleanupConsumer(frame, fn);
+    release();
+    let evaluation!: Owner;
+    createRoot((dispose) => {
+      stop = dispose;
+      evaluation = getOwner()!;
+    });
+    try {
+      return runWithOwner(evaluation, () => withComponentConsumer(frame, fn));
+    } catch (error) {
+      try {
+        release();
+      } catch {
+        /* Preserve the computation failure after disposing owned work. */
+      }
+      throw error;
+    }
+  });
+}

package/src/derived.ts

@@ -0,0 +1,276 @@
+/** Lazy native derived values with writable optimistic overrides. */
+import { createMemo, createSignal, untrack } from "@tschk/moonshine";
+import {
+  collectDeps,
+  subscribeInvalidation,
+  trackDependency,
+  hasValueDemand,
+  type Trackable,
+} from "@tschk/moonshine/tracking";
+import {
+  getOwner,
+  onCleanup,
+  runWithOwner,
+} from "@tschk/moonshine-dom/reactive";
+
+import {
+  collectHistoryReads,
+  hasHistory,
+  historicalValue,
+  isHistoryReading,
+  readHistory,
+  recordHistory,
+  trackHistoryRead,
+  withHistoryCleanup,
+  withHistoryMutation,
+  type HistoryRead,
+} from "./history";
+
+export function createDerived<T>(fn: () => T): {
+  get value(): T;
+  set value(value: T);
+} {
+  const owner = getOwner();
+  if (owner?.disposed)
+    throw new Error("Cannot create a derived value in a disposed owner");
+  const invalidation = createSignal(0);
+  const token = {};
+  let reads: HistoryRead[] = [];
+  let baseValue!: T;
+  type Snapshot = { value: T } | undefined;
+  function snapshot(): Snapshot {
+    return overridden
+      ? { value: override }
+      : returned
+        ? { value: last }
+        : undefined;
+  }
+  let initialized = false,
+    overridden = false,
+    disposed = false,
+    returned = false,
+    overrideInvalidated = false;
+  let inputRevision = 0;
+  let memoDependency: Trackable | undefined;
+  let overrideVersions = new Map<Trackable, number>();
+  let override!: T, last!: T;
+  let subscriptions = new Map<Trackable, () => void>();
+  function invalidate(): void {
+    if (disposed) return;
+    // Invalidating a committed override restores the previous computed inputs.
+    // A same-flush assignment already recorded its earlier value, which wins.
+    if (overridden) recordHistory(token, "override", undefined, undefined);
+    overrideInvalidated = true;
+    inputRevision++;
+  }
+  // Preserve the kernel dependency graph for pull validation and diamond updates.
+  // Side observers mark input changes without turning observation into value demand.
+  // Only a changed base computation resets an optimistic override.
+  const base = createMemo(() => {
+    let next!: T,
+      failed = false,
+      failure: unknown;
+    const versions = new Map<Trackable, number>();
+    const dependencies = collectDeps(
+      () => {
+        try {
+          const collected = collectHistoryReads(() => runWithOwner(owner, fn));
+          next = collected.value;
+          reads = collected.reads;
+        } catch (error) {
+          failed = true;
+          failure = error;
+        }
+      },
+      (dependency) => versions.set(dependency, dependency.version),
+      true,
+    );
+    const nextSubscriptions = new Map<Trackable, () => void>();
+    try {
+      untrack(() => {
+        for (const dependency of dependencies)
+          nextSubscriptions.set(
+            dependency,
+            subscriptions.get(dependency) ??
+              subscribeInvalidation(dependency, {
+                demand: false,
+                invalidate,
+                notify() {
+                  if (!disposed) invalidation.set((previous) => previous + 1);
+                },
+              }),
+          );
+        for (const [dependency, unsubscribe] of subscriptions)
+          if (!nextSubscriptions.has(dependency)) unsubscribe();
+      });
+    } catch (error) {
+      for (const [dependency, unsubscribe] of nextSubscriptions)
+        if (!subscriptions.has(dependency)) unsubscribe();
+      if (!failed) failure = error;
+      failed = true;
+    }
+    subscriptions = nextSubscriptions;
+    if (failed) throw failure;
+    if (
+      dependencies.some(
+        (dependency) => dependency.version !== versions.get(dependency),
+      )
+    )
+      throw new Error("Derived computations must not write their dependencies");
+    // Pull validation can run before this dependency's queued notification.
+    // Reset here too so optimistic siblings cannot expose a stale override.
+    if (initialized) {
+      if (hasHistory(reads))
+        recordHistory(token, "override", undefined, undefined);
+      overridden = false;
+    }
+    initialized = true;
+    baseValue = next;
+    return next;
+  });
+  let baseDependency: Parameters<typeof trackDependency>[0] | undefined;
+  const baseView: Parameters<typeof trackDependency>[0] = {
+    get version() {
+      return inputRevision;
+    },
+    validate() {},
+    subscribe: (
+      ...args: Parameters<Parameters<typeof trackDependency>[0]["subscribe"]>
+    ) => baseDependency!.subscribe(...args),
+  };
+  const memo = createMemo(() => {
+    invalidation();
+    let computed!: T;
+    if (overridden && initialized && !overrideInvalidated && baseDependency) {
+      computed = override;
+    } else if (baseDependency) computed = untrack(base);
+    else {
+      const dependencies = collectDeps(() => {
+        computed = base();
+      });
+      baseDependency = dependencies[0] as Parameters<typeof trackDependency>[0];
+    }
+    trackDependency(baseView);
+    overrideInvalidated = false;
+    last = overridden ? override : computed;
+    returned = true;
+    return last;
+  });
+  if (owner)
+    onCleanup(() => {
+      disposed = true;
+      for (const unsubscribe of subscriptions.values()) untrack(unsubscribe);
+      subscriptions.clear();
+    });
+  let frozenFailure = false,
+    frozenError: unknown;
+  return {
+    get value() {
+      trackHistoryRead(token, "override");
+      for (const read of reads) trackHistoryRead(read.target, read.key);
+      if (isHistoryReading())
+        return historicalValue(token, () =>
+          untrack(() => {
+            let recorded = true;
+            const previous = readHistory<Snapshot>(token, "override", () => {
+              recorded = false;
+              return undefined;
+            });
+            if (previous) return previous.value;
+            if (initialized && !hasHistory(reads))
+              return !recorded && overridden ? override : baseValue;
+            return runWithOwner(owner, () => withHistoryCleanup(fn));
+          }),
+        );
+      if (disposed) {
+        if (frozenFailure) throw frozenError;
+        if (returned) return last;
+        if (overridden) return override;
+        // A never-read value may finish once after its owner has stopped, without
+        // reconnecting the disposed memo or retaining dependency subscriptions.
+        frozenFailure = true;
+        frozenError = new Error(
+          "Derived value read during its disposed evaluation",
+        );
+        const versions = new Map<Trackable, number>();
+        let next!: T;
+        try {
+          const dependencies = untrack(() =>
+            collectDeps(
+              () => {
+                next = runWithOwner(owner, fn);
+              },
+              (dependency) => versions.set(dependency, dependency.version),
+            ),
+          );
+          if (
+            dependencies.some(
+              (dependency) => dependency.version !== versions.get(dependency),
+            )
+          )
+            throw new Error(
+              "Derived computations must not write their dependencies",
+            );
+          frozenFailure = false;
+          last = baseValue = next;
+          returned = initialized = true;
+          return next;
+        } catch (error) {
+          frozenFailure = true;
+          frozenError = error;
+          throw error;
+        }
+      }
+      if (
+        overridden &&
+        initialized &&
+        memoDependency &&
+        !hasValueDemand(memoDependency)
+      ) {
+        let changed = false;
+        untrack(() => {
+          for (const [dependency, version] of overrideVersions) {
+            dependency.validate?.();
+            if (dependency.version !== version) changed = true;
+          }
+        });
+        if (changed && !overrideInvalidated) {
+          overrideInvalidated = true;
+          inputRevision++;
+          invalidation.set((previous) => previous + 1);
+        }
+      }
+      if (!memoDependency) {
+        let value!: T;
+        collectDeps(
+          () => {
+            value = memo();
+          },
+          (dependency) => {
+            memoDependency = dependency;
+          },
+          true,
+        );
+        return value;
+      }
+      return memo();
+    },
+    set value(value: T) {
+      if (disposed) throw new Error("Cannot override a disposed derived value");
+      withHistoryMutation(() => {
+        if (!initialized) untrack(base);
+        recordHistory(token, "override", snapshot(), { value });
+        overrideVersions = new Map(
+          [...subscriptions.keys()].map((dependency) => [
+            dependency,
+            dependency.version,
+          ]),
+        );
+        overrideInvalidated = false;
+        override = value;
+        overridden = true;
+        invalidation.set((previous) => previous + 1);
+      });
+    },
+  };
+}

package/src/directives.ts

@@ -0,0 +1,129 @@
+/** Explicit native directive installation; source syntax remains compiler-owned. */
+import {
+  createComponentScope,
+  templateRetentionKey,
+  createRenderEffect,
+  getOwner,
+  getRenderScheduler,
+  onAfterDispose,
+  onCleanup,
+  runWithOwner,
+  untrack,
+} from "@tschk/moonshine-dom/reactive";
+import { isSSRRendering } from "@tschk/moonshine-dom/ssr-owner";
+import { peekComponentContext } from "@tschk/moonshine-dom/component";
+import { mapArray } from "@tschk/moonshine-dom/control";
+import { createRuneEffect } from "./effect";
+import { trackActionState } from "./state";
+import { withHistoryCleanup } from "./history";
+
+/** Type-only authored Svelte action contract. */
+export interface ActionReturn<
+  Parameter = undefined,
+  Attributes extends object = Record<never, never>,
+> {
+  update?: (parameter: Parameter) => void;
+  destroy?: () => void;
+  $$_attributes?: Attributes;
+}
+export interface Action<
+  Element = HTMLElement,
+  Parameter = undefined,
+  Attributes extends object = Record<never, never>,
+> {
+  <Node extends Element>(
+    ...args: undefined extends Parameter
+      ? [node: Node, parameter?: Parameter]
+      : [node: Node, parameter: Parameter]
+  ): void | ActionReturn<Parameter, Attributes>;
+}
+
+export type ActionPayload<T> = { update?(value: T): void; destroy?(): void };
+export type Attachment<E extends Element = Element> = (
+  element: E,
+) => void | (() => void);
+function install(fn: () => void): void {
+  if (isSSRRendering() || peekComponentContext()?.mode === "ssr") return;
+  const owner = getOwner(),
+    scheduler = getRenderScheduler();
+  if (!owner || owner.disposed || !scheduler)
+    throw Error("Native directives require a live owner and withRuneScheduler");
+  createComponentScope(() => scheduler.branch(fn));
+}
+function cleanup(fn: () => void): void {
+  const finish = () => withHistoryCleanup(() => untrack(fn));
+  const owner = getOwner();
+  if (owner?.disposed) finish();
+  else if (owner?.context?.has(templateRetentionKey))
+    onCleanup(() => runWithOwner(owner, finish));
+  else onAfterDispose(finish);
+}
+function different(previous: unknown, next: unknown): boolean {
+  return previous !== previous
+    ? next === next
+    : previous !== next ||
+        (previous !== null && typeof previous === "object") ||
+        typeof previous === "function";
+}
+/** invoke is a closure: resolve a mutable action reference only when the post factory runs. */
+export function installAction<E extends Element, T>(
+  element: E,
+  invoke: (element: E, value: T) => ActionPayload<T> | void | false | null,
+  read: () => T,
+): void;
+export function installAction<E extends Element, T>(
+  element: E,
+  invoke: (element: E) => ActionPayload<T> | void | false | null,
+): void;
+export function installAction<E extends Element, T>(
+  element: E,
+  invoke: (element: E, value: T) => ActionPayload<T> | void | false | null,
+  read?: () => T,
+): void {
+  install(() =>
+    createRuneEffect(() => {
+      const payload = untrack(
+        () =>
+          (read
+            ? invoke(element, read())
+            : (invoke as (element: E) => ReturnType<typeof invoke>)(element)) ||
+          {},
+      );
+      // Register before updater setup so a failing parameter traversal still releases the action.
+      if (payload.destroy) cleanup(() => payload.destroy!());
+      if (read && payload.update) {
+        let initialized = false;
+        let previous: unknown = {};
+        createRenderEffect(() => {
+          const next = read();
+          trackActionState(next);
+          if (initialized && different(previous, next)) {
+            previous = next;
+            payload.update!(next);
+          }
+        });
+        initialized = true;
+      }
+    }),
+  );
+}
+export function installAttachment<E extends Element>(
+  element: E,
+  read: () => Attachment<E> | false | null | undefined,
+): void {
+  install(() => {
+    mapArray(
+      () => {
+        const fn = read();
+        return fn ? [fn] : [];
+      },
+      (fn) => {
+        createRuneEffect(() => {
+          const stop = fn(element);
+          if (typeof stop === "function") cleanup(stop);
+        });
+        return undefined;
+      },
+    );
+  });
+}