@rasamjs/core 0.1.2 → 0.3.0

package/src/advanced.ts

@@ -11,7 +11,7 @@ export { Namespace } from './dom/namespace.js';
 export { DrawingContext } from './services/context.js';
 export { Scheduler } from './services/scheduler.js';
 export { Registry } from './services/registry.js';
-export type { ElementClass } from './services/types.js';
+export type { ElementClass, ElementVariant } from './services/types.js';
 export { BoundsService } from './services/bounds.js';
 export { DefsManager } from './services/defs-manager.js';
 

package/src/catalog/fragment.ts

@@ -1,6 +1,6 @@
 import { Group } from '../elements/group.js';
 import type { AnyNode } from '../core/types.js';
-import type { ElementClass } from '../services/types.js';
+import type { ElementClass, CreationOptions } from '../services/types.js';
 import type { ParentNode } from '../mixins/types.js';
 import { validateChild, validateIndex } from '../mixins/parent-internals.js';
 import { destroySubtrees } from '../core/destruction.js';
@@ -32,7 +32,7 @@ export class SvgFragment {
   }
   create<Options, Child extends AnyNode>(
     Constructor: ElementClass<Options, Child>,
-    options: Options,
+    options: NoInfer<CreationOptions<Options, Child>>,
   ): Child {
     return this.#host.create(Constructor, options);
   }

package/src/changes/derived.ts

@@ -0,0 +1,19 @@
+import type { AnyNode } from '../core/types.js';
+import type { ModelChange } from './types.js';
+
+/** Marks a class whose children are drawn from its own state, such as a component. */
+export const derivesChildren = Symbol('derivesChildren');
+const derived = new WeakSet<AnyNode>();
+
+export const ownsDerived = (Constructor: unknown): boolean =>
+  !!(Constructor as { [derivesChildren]?: boolean } | undefined)?.[derivesChildren];
+
+/** Records the owner's current descendants as derived. The owner redraws them after replay. */
+export function markDerived(owner: AnyNode): void {
+  for (const node of owner.descendants()) if (node !== owner) derived.add(node);
+}
+
+/** Replay skips derived nodes and their owners' child lists. */
+export const isDerivedChange = (change: ModelChange): boolean =>
+  derived.has(change.target.node) ||
+  (change.domain === 'children' && ownsDerived(change.target.node.constructor));

package/src/changes/restore.ts

@@ -1,9 +1,11 @@
 import type { AnyNode } from '../core/types.js';
 import type { ParentNode } from '../mixins/types.js';
 import { destroySubtrees } from '../core/destruction.js';
-import { validateChild } from '../mixins/parent-internals.js';
+import { validateChild, withInternalStructure } from '../mixins/parent-internals.js';
 import { readTransformState } from '../mixins/transform-state.js';
 import { referenceValue } from '../services/reference-value.js';
+import { initializeNode } from '../services/initialization.js';
+import { isDerivedChange, ownsDerived } from './derived.js';
 import { captureState, sameState, stateAdapter, combineChanges } from './state.js';
 import {
   ChangeConflictError,
@@ -28,6 +30,14 @@ function currentValue(snapshot: ModelSnapshot | null, change: ModelChange): unkn
   return snapshot[change.domain];
 }
 
+/** An owner's derived child list is redrawn, not restored, so conflicts ignore it. */
+function comparable(value: unknown, change: ModelChange): unknown {
+  const snapshot = value as ModelSnapshot | null;
+  return change.domain === 'existence' && snapshot && ownsDerived(snapshot.constructor)
+    ? { ...snapshot, children: undefined }
+    : value;
+}
+
 function contentFeatures(content: ContentState): ModelFeatures['content'] {
   return {
     parts: content.parts.map((part) => (typeof part === 'string' ? part : part.node)),
@@ -80,7 +90,8 @@ function applyChanges(
   direction: 'undo' | 'redo',
 ): void {
   const service = owner.context.changes;
-  changes = combineChanges(changes);
+  // An owner redraws its derived children after replay, from the state replay restored.
+  changes = combineChanges(changes).filter((change) => !isDerivedChange(change));
   service.resetOrders();
   service.configure(stateAdapter);
   try {
@@ -97,7 +108,8 @@ function applyChanges(
         domains.set(change.target, new Set());
       }
       const expected = direction === 'undo' ? change.after : change.before;
-      if (!sameState(currentValue(before.get(change.target)!, change), expected))
+      const current = currentValue(before.get(change.target)!, change);
+      if (!sameState(comparable(current, change), comparable(expected, change)))
         throw new ChangeConflictError(
           `Conflicting ${change.domain} state on node ${change.target.id}`,
         );
@@ -176,7 +188,7 @@ function validateGraph(
   const removed = new Set([...states].filter(([, state]) => !state).map(([target]) => target.node));
   for (const [target, state] of states) {
     if (!state) continue;
-    if (context.registry.get(state.constructor.tag) !== state.constructor)
+    if (context.registry.registered(state.constructor) !== state.constructor)
       throw new ChangeConflictError(`Constructor is not registered: ${state.constructor.tag}`);
     const id = state.properties.id?.value;
     if (
@@ -258,10 +270,19 @@ function validateGraph(
       throw new ChangeConflictError('A removed node would retain live typed references');
 }
 
+/** Replay restores exact prior trees, including children that their class owns. */
 function applyPrepared(
   owner: AnyNode,
   states: Map<NodeHandle, ModelSnapshot | null>,
   domains: Map<NodeHandle, Set<string>>,
+): void {
+  withInternalStructure(() => applyStates(owner, states, domains));
+}
+
+function applyStates(
+  owner: AnyNode,
+  states: Map<NodeHandle, ModelSnapshot | null>,
+  domains: Map<NodeHandle, Set<string>>,
 ): void {
   const context = owner.context;
   const recreated = new Set<NodeHandle>();
@@ -343,6 +364,7 @@ function applyPrepared(
   for (const [target, state] of states)
     if (
       state?.children &&
+      !ownsDerived(state.constructor) &&
       (recreated.has(target) ||
         domains.get(target)!.has('children') ||
         domains.get(target)!.has('existence'))
@@ -371,5 +393,6 @@ function applyPrepared(
   );
   const roots = [...retired].filter((node) => !node.parent || !retired.has(node.parent));
   if (roots.length) owner[destroySubtrees](roots);
+  for (const target of recreated) initializeNode(target.node);
   context.bounds.invalidate();
 }

package/src/changes/service.ts

@@ -4,6 +4,7 @@ import type {
   ChangeEvent,
   ChangeGroup,
   ChangeMetadata,
+  ChangeDerivation,
   ModelChange,
   ModelSnapshot,
   NodeHandle,
@@ -15,9 +16,14 @@ interface ChangeAdapter {
   diff(target: NodeHandle, before: ModelSnapshot, after: ModelSnapshot): ModelChange[];
   immutable<Value>(value: Value): Value;
 }
+interface ChildOrder {
+  readonly nodes: readonly AnyNode[];
+  readonly indices: ReadonlyMap<AnyNode, number>;
+}
 
 export class ChangeService {
   private readonly listeners = new Set<(event: ChangeEvent) => void>();
+  readonly derivations = new Set<(event: ChangeDerivation) => void>();
   private readonly identities = new WeakMap<AnyNode, NodeHandle>();
   private readonly retained = new WeakSet<AnyNode>();
   private readonly queue: ChangeEvent[] = [];
@@ -39,26 +45,32 @@ export class ChangeService {
   }[] = [];
   private adapter?: ChangeAdapter;
   private validationCounts?: ReadonlyMap<AnyNode, number>;
-  private childOrders = new Map<
-    AnyNode,
-    { nodes: readonly AnyNode[]; indices: ReadonlyMap<AnyNode, number> }
-  >();
+  private childOrders = new Map<AnyNode, ChildOrder>();
+  private liveOrders = new WeakMap<AnyNode, ChildOrder>();
 
   constructor(private readonly context: DrawingContext) {}
 
   get observed(): boolean {
-    return this.listeners.size > 0;
+    return this.listeners.size > 0 || this.derivations.size > 0;
   }
   get replaying(): boolean {
     return this.replayDepth > 0;
   }
+  /** The surrounding synchronous edit, if one is already grouping model writes. */
+  get currentGroup(): number | undefined {
+    return this.metadata.group;
+  }
 
   children(node: AnyNode): readonly AnyNode[] | undefined {
     if (!('children' in node)) return undefined;
     let order = this.childOrders.get(node);
     if (!order) {
-      const nodes = [...(node as AnyNode & { children: readonly AnyNode[] }).children];
-      order = { nodes, indices: new Map(nodes.map((child, index) => [child, index])) };
+      order = this.liveOrders.get(node);
+      if (!order) {
+        const nodes = [...(node as AnyNode & { children: readonly AnyNode[] }).children];
+        order = { nodes, indices: new Map(nodes.map((child, index) => [child, index])) };
+        this.liveOrders.set(node, order);
+      }
       this.childOrders.set(node, order);
     }
     return order.nodes;
@@ -73,6 +85,10 @@ export class ChangeService {
   resetOrders(): void {
     this.childOrders = new Map();
   }
+  /** Keep the operation's original order, but invalidate the live order after a tree edit. */
+  invalidateOrder(node: AnyNode): void {
+    this.liveOrders.delete(node);
+  }
 
   reading<Result>(callback: () => Result): Result {
     const previous = this.capturing;
@@ -194,6 +210,20 @@ export class ChangeService {
     try {
       if (node) this.touch(node);
       result = callback();
+      if (this.before.size && this.derivations.size) {
+        const nodes = [...this.before]
+          .filter(
+            ([target, previous]) =>
+              target.node.isDestroyed ||
+              this.adapter!.diff(target, previous, this.adapter!.capture(target.node)).length,
+          )
+          .map(([target]) => target.node);
+        if (nodes.length) {
+          const event = { ...this.metadata, nodes };
+          for (const derive of [...this.derivations])
+            if (this.derivations.has(derive)) derive(event);
+        }
+      }
     } catch (error) {
       failure = { error };
     }
@@ -266,13 +296,22 @@ export class ChangeService {
     }
   }
 
-  group(metadata: ChangeMetadata = {}): ChangeGroup {
+  group(metadata: ChangeMetadata = {}): Omit<ChangeGroup, 'cancel'> & {
+    end(cancelled?: boolean, restored?: boolean): void;
+  } {
     const id = ++this.nextGroup,
       source = metadata.source ?? 'application';
     let active = true;
     this.groups.add(id);
     try {
-      this.publish(Object.freeze({ type: 'groupstart', group: id, source }));
+      this.publish(
+        Object.freeze({
+          type: 'groupstart',
+          group: id,
+          source,
+          ...(metadata.label === undefined ? {} : { label: metadata.label }),
+        }),
+      );
     } catch (error) {
       this.groups.delete(id);
       this.publish(Object.freeze({ type: 'groupend', group: id, source, cancelled: true }));
@@ -284,11 +323,19 @@ export class ChangeService {
         if (!active) throw new Error('Change group has ended');
         return this.scope({ ...metadata, group: id }, callback, null);
       },
-      end: (cancelled = false) => {
+      end: (cancelled = false, restored = false) => {
         if (!active) return;
         active = false;
         this.groups.delete(id);
-        this.publish(Object.freeze({ type: 'groupend', group: id, source, cancelled }));
+        this.publish(
+          Object.freeze({
+            type: 'groupend',
+            group: id,
+            source,
+            cancelled,
+            ...(restored ? { restored: true } : {}),
+          }),
+        );
       },
     });
   }
@@ -378,11 +425,13 @@ export class ChangeService {
 
   destroy(): void {
     this.listeners.clear();
+    this.derivations.clear();
     this.queue.length = 0;
     this.notifications.length = 0;
     this.replacements.length = 0;
     this.groups.clear();
     this.owner = null;
     this.childOrders.clear();
+    this.liveOrders = new WeakMap();
   }
 }

package/src/changes/types.ts

@@ -104,9 +104,14 @@ export type ModelChange =
 
 export interface ChangeMetadata {
   readonly source?: string;
+  readonly label?: string;
   readonly temporary?: boolean;
   readonly group?: number;
 }
+/** Runs synchronously after an operation's writes, before its final change snapshot. */
+export interface ChangeDerivation extends ChangeMetadata {
+  readonly nodes: readonly AnyNode[];
+}
 export interface ChangeBatch {
   readonly type: 'change';
   readonly id: number;
@@ -126,7 +131,9 @@ export type ChangeEvent =
       readonly type: 'groupstart' | 'groupend';
       readonly group: number;
       readonly source: string;
+      readonly label?: string;
       readonly cancelled?: boolean;
+      readonly restored?: boolean;
     }
   | {
       readonly type: 'dispose' | 'willdispose';
@@ -136,6 +143,8 @@ export interface ChangeGroup {
   readonly id: number;
   run<Result>(callback: () => Result): Result;
   end(cancelled?: boolean): void;
+  /** Restore this group's own non-temporary changes, then end it as cancelled. */
+  cancel(): void;
 }
 
 export class ChangeConflictError extends Error {

package/src/changes.ts

@@ -1,12 +1,15 @@
 import type { AnyNode } from './core/types.js';
-import type { ChangeEvent, ChangeMetadata } from './changes/types.js';
-import { stateAdapter } from './changes/state.js';
+import type { ChangeEvent, ChangeGroup, ChangeMetadata, ModelChange } from './changes/types.js';
+import { ChangeConflictError, ChangeObserverError } from './changes/types.js';
+import { combineChanges, stateAdapter } from './changes/state.js';
+import { restoreChanges } from './changes/restore.js';
 
 export type {
   ChangeBatch,
   ChangeEvent,
   ChangeGroup,
   ChangeMetadata,
+  ChangeDerivation,
   ModelChange,
   ModelSnapshot,
   ModelFeatures,
@@ -35,6 +38,20 @@ export function observeChanges(
   drawing.assertLive();
   return drawing.context.changes.observe(listener, stateAdapter);
 }
+/** Derived writes join the same operation and group. Callbacks never run during restoration. */
+export function deriveChanges(
+  drawing: AnyNode,
+  derive: (event: import('./changes/types.js').ChangeDerivation) => void,
+): () => void {
+  drawing.assertLive();
+  if (typeof derive !== 'function') throw new TypeError('Change derivation must be a function');
+  drawing.context.changes.configure(stateAdapter);
+  const callbacks = drawing.context.changes.derivations;
+  callbacks.add(derive);
+  return () => {
+    callbacks.delete(derive);
+  };
+}
 export function withChanges<Result>(
   drawing: AnyNode,
   metadata: ChangeMetadata,
@@ -43,9 +60,81 @@ export function withChanges<Result>(
   drawing.assertLive();
   return drawing.context.changes.scope(metadata, callback, drawing);
 }
-export function beginChangeGroup(drawing: AnyNode, metadata: ChangeMetadata = {}) {
+export function beginChangeGroup(drawing: AnyNode, metadata: ChangeMetadata = {}): ChangeGroup {
   drawing.assertLive();
-  return drawing.context.changes.group(metadata);
+  const owner = drawing.context.root!;
+  let id: number | undefined;
+  let changes: readonly ModelChange[] = [];
+  let invalidated = false;
+  // Subscribe before groupstart so edits made by start observers are captured too.
+  const unsubscribe = observeChanges(drawing, (event) => {
+    if (event.type === 'dispose') invalidated = true;
+    if (id === undefined && event.type === 'groupstart') id = event.group;
+    if (event.type === 'change' && event.group === id && !event.temporary)
+      changes = combineChanges([...changes, ...event.changes]);
+  });
+  let group: ReturnType<typeof drawing.context.changes.group>;
+  try {
+    group = drawing.context.changes.group(metadata);
+    id = group.id;
+  } catch (error) {
+    unsubscribe();
+    throw error;
+  }
+  let active = true;
+  let cancelling = false;
+  let depth = 0;
+  const assertNotDisposed = () => {
+    if (invalidated)
+      throw new ChangeConflictError('Permanent disposal invalidated the change group');
+  };
+  const finish = (cancelled: boolean, restored = false) => {
+    active = false;
+    changes = [];
+    unsubscribe();
+    group.end(cancelled, restored);
+  };
+  return Object.freeze({
+    id: group.id,
+    run<Result>(callback: () => Result): Result {
+      if (!active || cancelling) throw new Error('Change group has ended or is cancelling');
+      assertNotDisposed();
+      depth++;
+      try {
+        return group.run(callback);
+      } finally {
+        depth--;
+      }
+    },
+    end(cancelled = false) {
+      if (active && !cancelling) finish(cancelled);
+    },
+    cancel() {
+      if (!active || cancelling) return;
+      if (depth) throw new Error('Finish the change callback before cancelling its group');
+      assertNotDisposed();
+      cancelling = true;
+      const failures: unknown[] = [];
+      try {
+        try {
+          if (changes.length) restoreChanges(owner, changes, 'undo');
+        } catch (error) {
+          if (error instanceof ChangeObserverError) failures.push(error);
+          else throw error;
+        }
+        try {
+          finish(true, true);
+        } catch (error) {
+          failures.push(error);
+        }
+      } finally {
+        cancelling = false;
+      }
+      if (failures.length === 1) throw failures[0];
+      if (failures.length)
+        throw new AggregateError(failures, 'Change group cancellation observers failed');
+    },
+  });
 }
 
 /** One recorder per context; ordinary change observers are unrestricted. */

package/src/components/changes.ts

@@ -0,0 +1,131 @@
+import type { AnyNode } from '../core/types.js';
+import type { DrawingContext } from '../services/context.js';
+import { deriveChanges, observeChanges, withChanges, type ChangeBatch } from '../changes.js';
+
+export interface Binding {
+  readonly node: AnyNode;
+  derive(): void;
+  replay(): void;
+  paint(): void;
+}
+interface Discovery {
+  added(node: AnyNode): void;
+  identityChanged(node: AnyNode): void;
+}
+const drawings = new WeakMap<DrawingContext, ComponentChanges>();
+
+/** Routes work by changed node, independent of the number of components in a drawing. */
+export class ComponentChanges {
+  private readonly bindings = new WeakMap<AnyNode, Binding>();
+  private readonly discovery = new Set<Discovery>();
+  private bindingCount = 0;
+  private readonly dirty = new Set<Binding>();
+  private cancelFrame?: () => void;
+  private readonly stopDerive: () => void;
+  private readonly stopObserve: () => void;
+  private readonly context: DrawingContext;
+
+  static for(node: AnyNode): ComponentChanges {
+    let changes = drawings.get(node.context);
+    if (!changes) {
+      changes = new ComponentChanges(node);
+      drawings.set(node.context, changes);
+    }
+    return changes;
+  }
+
+  private constructor(drawing: AnyNode) {
+    this.context = drawing.context;
+    this.stopDerive = deriveChanges(drawing, ({ nodes }) => {
+      for (const node of nodes) this.bindings.get(node)?.derive();
+    });
+    this.stopObserve = observeChanges(drawing, (event) => {
+      if (event.type === 'change') this.dispatch(event);
+    });
+  }
+
+  bind(binding: Binding): () => void {
+    if (this.bindings.has(binding.node)) throw new Error('Component is already observing changes');
+    this.bindings.set(binding.node, binding);
+    this.bindingCount++;
+    return this.release(() => {
+      this.bindings.delete(binding.node);
+      this.dirty.delete(binding);
+      this.bindingCount--;
+    });
+  }
+
+  discover(discovery: Discovery): () => void {
+    this.discovery.add(discovery);
+    return this.release(() => this.discovery.delete(discovery));
+  }
+
+  private release(cleanup: () => void): () => void {
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      cleanup();
+      if (!this.bindingCount && !this.discovery.size) {
+        this.cancelFrame?.();
+        this.stopDerive();
+        this.stopObserve();
+        drawings.delete(this.context);
+      }
+    };
+  }
+
+  /** Live state from every instance renders in one shared frame, as one temporary change. */
+  schedule(binding: Binding): void {
+    this.dirty.add(binding);
+    this.cancelFrame ??= this.context.dom.requestFrame(() => {
+      this.cancelFrame = undefined;
+      this.paint(this.dirty);
+    });
+  }
+
+  /** Renders without an undo step; failures surface after every other instance rendered. */
+  paint(bindings: Iterable<Binding>): void {
+    const list = [...bindings].filter((binding) => !binding.node.isDestroyed);
+    for (const binding of list) this.dirty.delete(binding);
+    if (!list.length) return;
+    const failures: unknown[] = [];
+    withChanges(list[0].node, { source: 'components', temporary: true }, () => {
+      for (const binding of list)
+        try {
+          binding.paint();
+        } catch (error) {
+          failures.push(error);
+        }
+    });
+    if (failures.length > 1) throw new AggregateError(failures, 'Component renders failed');
+    if (failures.length) throw failures[0];
+  }
+
+  private dispatch(event: ChangeBatch): void {
+    // Replay skips rendered children, so restored and recreated instances redraw together.
+    const replayed = new Set<Binding>();
+    for (const change of event.changes) {
+      const node = change.target.node,
+        binding = this.bindings.get(node);
+      if (
+        binding &&
+        event.source === 'replay' &&
+        ((change.domain === 'property' && change.attribute === 'data-rasam-props') ||
+          (change.domain === 'existence' && change.after))
+      )
+        replayed.add(binding);
+      if (!this.discovery.size) continue;
+      if (
+        (change.domain === 'placement' && change.after.parent && !change.before.parent) ||
+        (change.domain === 'existence' && change.after)
+      )
+        for (const subscriber of this.discovery) subscriber.added(node);
+      else if (change.domain === 'property' && change.attribute === 'data-rasam-component')
+        for (const subscriber of this.discovery) subscriber.identityChanged(node);
+    }
+    if (!replayed.size) return;
+    for (const binding of replayed) binding.replay();
+    this.paint(replayed);
+  }
+}