@rasamjs/core 0.2.0 → 0.3.0

package/src/template/render.ts

@@ -1,73 +1,180 @@
 import { mutation } from '../changes/mutation.js';
 import type { AnyNode } from '../core/types.js';
+import { destroySubtrees } from '../core/destruction.js';
 import type { ParentNode } from '../mixins/types.js';
 import { Guards } from '../mixins/guards.js';
 import { Group } from '../elements/group.js';
 import type { Registry } from '../services/registry.js';
+import type { ElementClass } from '../services/types.js';
 import { BindingPart, TemplateCompiler } from './parts.js';
-import type { TemplateDescription } from './parts.js';
-import type { SvgTemplate } from './svg-tag.js';
+import type { ContentItem, TemplateDescription } from './parts.js';
+import { SvgTemplate } from './svg-tag.js';
+import type { TemplateValue } from './svg-tag.js';
 import { appendTextSlot, type TextBinding } from '../text/internals.js';
 
-export class TemplateInstance {
-  readonly host: Group;
-  readonly nodes: readonly AnyNode[];
-  private readonly parts: BindingPart[] = [];
+type Segment = AnyNode | ChildPart;
+/** The nodes and child holes one template places in one parent, from index `base()`. */
+interface Sequence {
+  parent: ParentNode;
+  readonly segments: Segment[];
+  base(): number;
+}
+
+const size = (segments: readonly Segment[]) =>
+  segments.reduce((total, segment) => total + (segment instanceof ChildPart ? segment.size : 1), 0);
+const flat = (segments: readonly Segment[]): AnyNode[] =>
+  segments.flatMap((segment) => (segment instanceof ChildPart ? segment.nodes : [segment]));
+/** Semantic disposal: unlike `destroy()`, undo can restore it and history isn't cleared. */
+const dispose = (nodes: readonly AnyNode[]) => {
+  const live = nodes.filter((node) => !node.isDestroyed);
+  if (live.length) live[0][destroySubtrees](live);
+};
+
+/** Flattens a child hole's value into templates. */
+function templates(value: TemplateValue, out: SvgTemplate[] = []): SvgTemplate[] {
+  if (value instanceof SvgTemplate) out.push(value);
+  else if (typeof value == 'object' && value && Symbol.iterator in value)
+    for (const item of value) templates(item, out);
+  else if (value != null && typeof value != 'boolean' && value !== '')
+    throw new TypeError('Child bindings take templates, iterables of them, or null');
+  return out;
+}
+
+/**
+ * Validates and builds an update without changing the drawing: new items are built in
+ * detached `stagings` groups. The returned commit applies it.
+ */
+type Prepare = (values: readonly TemplateValue[], stagings: Group[]) => () => void;
+
+/** Prepares and commits, disposing the staging groups whether or not it succeeds. */
+function commit(prepare: Prepare, values: readonly TemplateValue[]): void {
+  const stagings: Group[] = [];
+  try {
+    prepare(values, stagings)();
+  } finally {
+    dispose(stagings);
+  }
+}
+
+/** A hole between elements: the items it renders, reused by index while their literal matches. */
+class ChildPart {
+  private items: Mount[] = [];
+  constructor(
+    private readonly sequence: Sequence,
+    private readonly hole: number,
+    private readonly registry: Registry,
+  ) {}
+
+  get size(): number {
+    return this.items.reduce((total, item) => total + item.size, 0);
+  }
+  get nodes(): AnyNode[] {
+    return this.items.flatMap((item) => item.nodes);
+  }
+  /** The index of this part's first node, or of `item`'s first node. */
+  private start(item?: Mount): number {
+    const { segments } = this.sequence;
+    let index = this.sequence.base() + size(segments.slice(0, segments.indexOf(this)));
+    for (const other of item ? this.items : []) {
+      if (other === item) break;
+      index += other.size;
+    }
+    return index;
+  }
+
+  readonly prepare: Prepare = (values, stagings) => {
+    const parent = this.sequence.parent;
+    const forbidden = new Set<string>();
+    for (let node: AnyNode | null = parent; node; node = node.parent)
+      for (const tag of (node.constructor as ElementClass).forbiddenDescendantTags ?? [])
+        forbidden.add(tag);
+    const plans = templates(values[this.hole]).map((template, index) => {
+      const item = this.items[index];
+      if (item?.template.strings === template.strings)
+        return { item, commit: item.prepare(template.values, stagings) };
+      const content = TemplateCompiler.content(parent.context.dom, template.strings);
+      TemplateCompiler.validate(
+        content,
+        this.registry,
+        forbidden,
+        parent.constructor as ElementClass,
+      );
+      const staging = new Group(parent.context);
+      stagings.push(staging);
+      return { item: new Mount(template, staging, this.registry, content) };
+    });
+    return () => {
+      const items = plans.map((plan) => plan.item);
+      dispose(this.items.filter((item) => !items.includes(item)).flatMap((item) => item.nodes));
+      this.items = items;
+      for (const { item, commit } of plans)
+        if (!commit) {
+          // Detach first, so history records new nodes rather than a move from staging.
+          for (const node of item.nodes) parent.add(node.remove());
+          item.sequence.parent = parent;
+          item.sequence.base = () => this.start(item);
+        }
+      for (const plan of plans) plan.commit?.();
+      let index = this.start();
+      for (const node of this.nodes) parent.add(node, index++);
+    };
+  };
+}
+
+/** One template's nodes and parts, mounted as a sequence inside a parent. */
+class Mount {
+  readonly sequence: Sequence;
+  private readonly parts: (BindingPart | ChildPart)[] = [];
 
   constructor(
-    parent: ParentNode,
     readonly template: SvgTemplate,
-    registry: Registry,
-    descriptions: readonly TemplateDescription[],
+    parent: ParentNode,
+    private readonly registry: Registry,
+    content: readonly ContentItem[],
   ) {
-    this.host = new Group(parent.context);
-    try {
-      this.nodes = descriptions.map((description) =>
-        this.instantiate(description, this.host, registry),
-      );
-    } catch (error) {
-      this.host.destroy();
-      throw error;
-    }
+    this.sequence = { parent, segments: [], base: () => 0 };
+    this.fill(content, this.sequence);
   }
 
-  get isDestroyed(): boolean {
-    return this.host.isDestroyed;
+  get size(): number {
+    return size(this.sequence.segments);
+  }
+  get nodes(): AnyNode[] {
+    return flat(this.sequence.segments);
   }
 
-  update(template: SvgTemplate): this {
-    return mutation(this, () => {
-      this.host.assertLive();
-      if (template.strings !== this.template.strings)
-        throw new TypeError('An instance can only update its original template');
-      const changes = this.parts.map((part) => {
-        const value = part.evaluate(template.values);
-        part.validate(value);
-        return { part, value };
-      });
-      this.host.batch(() => {
-        for (const { part, value } of changes) part.commit(value);
-      });
-      return this;
+  /** Validates every binding first, so an update changes all or nothing. */
+  readonly prepare: Prepare = (values, stagings) => {
+    const commits = this.parts.map((part) => {
+      if (part instanceof ChildPart) return part.prepare(values, stagings);
+      const value = part.evaluate(values);
+      part.validate(value);
+      return () => part.commit(value);
     });
-  }
+    return () => commits.forEach((commit) => commit());
+  };
 
-  destroy(): void {
-    this.host.destroy();
+  private fill(content: readonly ContentItem[], sequence: Sequence): void {
+    for (const item of content) {
+      if ('tag' in item) sequence.segments.push(this.element(item, sequence.parent));
+      else
+        for (const hole of item.parts)
+          if (typeof hole == 'number') {
+            const part = new ChildPart(sequence, hole, this.registry);
+            sequence.segments.push(part);
+            this.parts.push(part);
+            commit(part.prepare, this.template.values);
+          }
+    }
   }
-
-  private instantiate(
-    description: TemplateDescription,
-    parent: ParentNode,
-    registry: Registry,
-  ): AnyNode {
-    const node = registry.createEmpty(description.tag, parent.context);
+  private element(description: TemplateDescription, parent: ParentNode): AnyNode {
+    const node = this.registry.createEmpty(description.tag, parent.context);
     parent.add(node);
     for (const [name, values] of Object.entries(description.attributes))
       this.bind(new BindingPart(node, name, values));
     if (appendTextSlot in node && Guards.isParent(node)) {
       for (const part of description.content) {
-        if ('tag' in part) this.instantiate(part, node, registry);
+        if ('tag' in part) this.element(part, node);
         else {
           const binding = (node[appendTextSlot] as (value: string) => TextBinding)('');
           this.bind(new BindingPart(node, null, part.parts, binding));
@@ -75,22 +182,69 @@ export class TemplateInstance {
       }
       return node;
     }
-    if (description.text.length > 0 && Guards.isTextual(node))
-      this.bind(new BindingPart(node, null, description.text));
+    if (Guards.isTextual(node)) {
+      if (description.text.length > 0) this.bind(new BindingPart(node, null, description.text));
+    } else if (Guards.isParent(node)) {
+      this.fill(description.content, { parent: node, segments: [], base: () => 0 });
+      return node;
+    }
     if (description.children.length > 0 && !Guards.isParent(node))
       throw new TypeError('Children require the Parent mixin');
-    for (const child of description.children) this.instantiate(child, node as ParentNode, registry);
+    for (const child of description.children) this.element(child, node as ParentNode);
     return node;
   }
 
   private bind(part: BindingPart): void {
     const value = part.evaluate(this.template.values);
     part.validate(value);
-    part.commit(value, true);
+    part.commit(value);
     this.parts.push(part);
   }
 }
 
+export class TemplateInstance {
+  readonly host: Group;
+  private readonly mount: Mount;
+
+  constructor(
+    parent: ParentNode,
+    readonly template: SvgTemplate,
+    registry: Registry,
+    content: readonly ContentItem[],
+  ) {
+    this.host = new Group(parent.context);
+    try {
+      this.mount = new Mount(template, this.host, registry, content);
+    } catch (error) {
+      this.host.destroy();
+      throw error;
+    }
+  }
+
+  /** The current top-level nodes, including those that child holes render. */
+  get nodes(): readonly AnyNode[] {
+    return this.mount.nodes;
+  }
+
+  get isDestroyed(): boolean {
+    return this.host.isDestroyed;
+  }
+
+  update(template: SvgTemplate): this {
+    return mutation(this, () => {
+      this.host.assertLive();
+      if (template.strings !== this.template.strings)
+        throw new TypeError('An instance can only update its original template');
+      this.host.batch(() => commit(this.mount.prepare, template.values));
+      return this;
+    });
+  }
+
+  destroy(): void {
+    this.host.destroy();
+  }
+}
+
 export class Renderer {
   private static readonly renderers = new WeakMap<ParentNode, Renderer>();
   private instance: TemplateInstance | null = null;
@@ -126,12 +280,15 @@ export class Renderer {
       this.instance.template.strings === template.strings
     )
       return this.instance.update(template);
-    const descriptions = TemplateCompiler.compile(this.parent.context.dom, template.strings);
-    TemplateCompiler.validate(descriptions, this.registry);
-    const instance = new TemplateInstance(this.parent, template, this.registry, descriptions);
+    const content = TemplateCompiler.content(this.parent.context.dom, template.strings);
+    TemplateCompiler.validate(content, this.registry);
+    const instance = new TemplateInstance(this.parent, template, this.registry, content);
     try {
-      this.instance?.destroy();
-      this.parent.add(instance.host);
+      // Replacing a template disposes the old one semantically, so undo restores it.
+      this.parent.context.changes.run(this.parent, () => {
+        if (this.instance) dispose([this.instance.host]);
+        this.parent.add(instance.host);
+      });
     } catch (error) {
       instance.destroy();
       throw error;

package/src/template/svg-tag.ts

@@ -1,4 +1,9 @@
-export type TemplateValue = string | number | boolean | null | undefined;
+/**
+ * Attribute and text holes take primitives. A hole between elements also takes a nested
+ * template or an iterable of them; `null`, `undefined`, booleans and `''` render nothing.
+ */
+export type TemplateValue =
+  string | number | boolean | null | undefined | SvgTemplate | Iterable<TemplateValue>;
 
 export class SvgTemplate {
   constructor(

package/src/text/internals.ts

@@ -1,6 +1,7 @@
 export const appendTextSlot = Symbol('appendTextSlot');
 
 export interface TextBinding {
+  readonly value: string;
   validate(): void;
   set(value: string): void;
 }

package/src/types/common.ts

@@ -101,3 +101,32 @@ export interface Disposable {
   readonly isDestroyed: boolean;
   destroy(): void;
 }
+
+/**
+ * Per-node editing limits that tools read structurally from `node.editRules`, for
+ * example from a component type. A node without rules edits freely.
+ */
+export interface EditRules {
+  /** `'free'` (default), a positive step in degrees that divides 360, or `false`. */
+  readonly rotate?: 'free' | number | false;
+  /** Whether flips and mirroring resizes are allowed. Defaults to true. */
+  readonly flip?: boolean;
+  /**
+   * `'scale'` (default), `false`, or `'props'`: a resize changes the node's own width and
+   * height through `size()` instead of scaling it. Multi-node resizes don't apply to it.
+   */
+  readonly resize?: 'scale' | 'props' | false;
+}
+
+/**
+ * A named connection point that connectors read structurally from
+ * `node.portDefinitions`, for example from a component. `x` and `y` are in the node's
+ * local coordinates, before its own transform.
+ */
+export interface PortDefinition {
+  readonly name: string;
+  readonly x: number;
+  readonly y: number;
+  /** The side a link leaves from, before the node's transform. Elbow routing uses it. */
+  readonly side?: 'left' | 'right' | 'top' | 'bottom';
+}