@rasamjs/core 0.1.2 → 0.3.0

package/src/services/viewport.ts

@@ -17,7 +17,8 @@ export function unresolved(error: unknown): Bounds {
   throw error;
 }
 
-function length(node: AnyNode, name: string, axis: Axis, fallback: unknown): number {
+/** Resolve an authored viewport length against its original ancestor viewport. */
+export function viewportLength(node: AnyNode, name: string, axis: Axis, fallback: unknown): number {
   return userLength(node.getAttributeValue(name) ?? fallback, () => {
     // Percentages use the nearest ancestor viewport's viewBox, or its size without one.
     let viewport = node === node.context.root ? null : node.parent;
@@ -30,15 +31,15 @@ function length(node: AnyNode, name: string, axis: Axis, fallback: unknown): num
 
 /** A viewport's width or height in its parent's user units; omitted sizes are 100%. */
 export function viewportSize(node: AnyNode, axis: Axis): number {
-  const size = length(node, axis, axis, '100%');
+  const size = viewportLength(node, axis, axis, '100%');
   if (size < 0) throw new ViewportError('Negative viewport size');
   return size;
 }
 
 /** Placement and viewBox transform from a nested viewport's user space to its parent's. */
 export function viewportMapping(node: AnyNode): Matrix {
-  const x = length(node, 'x', 'width', 0),
-    y = length(node, 'y', 'height', 0),
+  const x = viewportLength(node, 'x', 'width', 0),
+    y = viewportLength(node, 'y', 'height', 0),
     viewBox = node.getAttributeValue('viewBox');
   return viewBox === undefined
     ? Matrix.translation(x, y)

package/src/template/parts.ts

@@ -1,9 +1,10 @@
 import type { AnyNode } from '../core/types.js';
 import { Attributes } from '../dom/attributes.js';
 import type { DomFactory } from '../dom/create.js';
-import type { MarkupNode } from '../dom/types.js';
+import type { MarkupElement } from '../dom/types.js';
 import { Guards } from '../mixins/guards.js';
 import type { Registry } from '../services/registry.js';
+import type { ElementClass } from '../services/types.js';
 import type { TemplateValue } from './svg-tag.js';
 import type { TextBinding } from '../text/internals.js';
 import { classifyReference } from '../resources/references.js';
@@ -15,21 +16,36 @@ export interface TemplateDescription {
   readonly attributes: Readonly<Record<string, readonly PartValue[]>>;
   readonly children: readonly TemplateDescription[];
   readonly text: readonly PartValue[];
-  readonly content: readonly (TemplateDescription | { readonly parts: readonly PartValue[] })[];
+  readonly content: readonly ContentItem[];
 }
 
+/** An element, or a text run whose number parts are hole indexes (child holes outside text). */
+export type ContentItem = TemplateDescription | { readonly parts: readonly PartValue[] };
+
 export class TemplateCompiler {
-  private static readonly cache = new WeakMap<
-    TemplateStringsArray,
-    readonly TemplateDescription[]
-  >();
+  private static readonly cache = new WeakMap<TemplateStringsArray, readonly ContentItem[]>();
   private readonly counts: number[];
 
   private constructor(strings: TemplateStringsArray) {
     this.counts = new Array<number>(strings.length - 1).fill(0);
   }
 
+  /** Top-level elements; templates with top-level child holes need `content()`. */
   static compile(dom: DomFactory, strings: TemplateStringsArray): readonly TemplateDescription[] {
+    const content = TemplateCompiler.content(dom, strings);
+    if (
+      content.some(
+        (item) =>
+          !('tag' in item) &&
+          item.parts.some((part) => part !== '' && (typeof part == 'number' || part.trim())),
+      )
+    )
+      throw new TypeError('Template text must be inside a text element');
+    return content.filter((item): item is TemplateDescription => 'tag' in item);
+  }
+
+  /** Top-level content in order: elements and text runs that may hold child holes. */
+  static content(dom: DomFactory, strings: TemplateStringsArray): readonly ContentItem[] {
     const cached = TemplateCompiler.cache.get(strings);
     if (cached) return cached;
     if (strings.some((part) => /rasamHole\d+End/.test(part)))
@@ -38,51 +54,55 @@ export class TemplateCompiler {
     const source = strings
       .map((part, index) => part + (index < strings.length - 1 ? `rasamHole${index}End` : ''))
       .join('');
-    const result: TemplateDescription[] = [];
-    for (const node of dom.parse(source)) {
-      const description = compiler.describe(node);
-      if (description) result.push(description);
-    }
+    const result: ContentItem[] = [];
+    for (const node of dom.parse(source))
+      result.push('text' in node ? { parts: compiler.split(node.text) } : compiler.describe(node));
     if (compiler.counts.some((count) => count !== 1))
       throw new TypeError('Bindings must appear in attribute values or text elements');
     TemplateCompiler.cache.set(strings, result);
     return result;
   }
 
+  /** `parent` is the container class that receives `content`, for its child rules. */
   static validate(
-    descriptions: readonly TemplateDescription[],
+    content: readonly ContentItem[],
     registry: Registry,
     forbidden: ReadonlySet<string> = new Set(),
+    parent?: ElementClass,
   ): void {
-    for (const description of descriptions) {
+    for (const description of content) {
+      if (!('tag' in description)) {
+        if (description.parts.some((part) => typeof part == 'string' && part.trim()))
+          throw new TypeError('Template text must be inside a text element');
+        continue;
+      }
       const Constructor = registry.get(description.tag);
       if (forbidden.has(description.tag))
         throw new TypeError('Nested links or forbidden descendants are unsupported');
       if (!Constructor) throw new TypeError(`Unsupported template tag: ${description.tag}`);
+      if (parent?.childTags && !parent.childTags.includes(description.tag))
+        throw new TypeError(`${parent.tag} only accepts ${parent.childTags.join(', ')} children`);
       for (const name of Object.keys(description.attributes)) {
         if (!Constructor.attributeNames.includes(name) && !/^(?:data|aria)-[\w-]+$/.test(name))
           throw new TypeError(`Unsupported template attribute: ${name}`);
       }
       if (description.children.length > 0 && !Constructor.isContainer)
         throw new TypeError('Only containers may have element children');
+      // Outside text elements, holes between children are child holes, so only containers take them.
       if (
-        Constructor.childTags &&
-        description.children.some((child) => !Constructor.childTags.includes(child.tag))
-      )
-        throw new TypeError(
-          `${description.tag} only accepts ${Constructor.childTags.join(', ')} children`,
-        );
-      if (
-        description.text.some((part) => typeof part === 'number' || part.trim()) &&
-        !Constructor.isText
+        !Constructor.isText &&
+        description.text.some((part) =>
+          typeof part == 'number' ? !Constructor.isContainer : part.trim(),
+        )
       )
         throw new TypeError('Text bindings require a text element');
       TemplateCompiler.validate(
-        description.children,
+        Constructor.isText ? description.children : description.content,
         registry,
         Constructor.forbiddenDescendantTags
           ? new Set([...forbidden, ...Constructor.forbiddenDescendantTags])
           : forbidden,
+        Constructor,
       );
     }
   }
@@ -101,11 +121,7 @@ export class TemplateCompiler {
     return parts;
   }
 
-  private describe(node: MarkupNode): TemplateDescription | null {
-    if ('text' in node) {
-      if (node.text.trim()) throw new TypeError('Template text must be inside a text element');
-      return null;
-    }
+  private describe(node: MarkupElement): TemplateDescription {
     if (/rasamHole\d+End/.test(node.tag)) throw new TypeError('Dynamic tag names are unsupported');
     const attributes: Record<string, readonly PartValue[]> = {};
     for (const [rawName, value] of Object.entries(node.attributes)) {
@@ -121,7 +137,7 @@ export class TemplateCompiler {
     }
     const text: PartValue[] = [];
     const children: TemplateDescription[] = [];
-    const content: (TemplateDescription | { readonly parts: readonly PartValue[] })[] = [];
+    const content: ContentItem[] = [];
     for (const child of node.children) {
       if ('text' in child) {
         const parts = this.split(child.text);
@@ -129,10 +145,8 @@ export class TemplateCompiler {
         content.push({ parts });
       } else {
         const description = this.describe(child);
-        if (description) {
-          children.push(description);
-          content.push(description);
-        }
+        children.push(description);
+        content.push(description);
       }
     }
     return { tag: node.tag, attributes, children, text, content };
@@ -140,8 +154,6 @@ export class TemplateCompiler {
 }
 
 export class BindingPart {
-  private previous: string | undefined;
-
   constructor(
     private readonly node: AnyNode,
     private readonly name: string | null,
@@ -183,15 +195,18 @@ export class BindingPart {
     }
   }
 
-  commit(value: string | undefined, initial = false): void {
-    if (!initial && value === this.previous) return;
+  commit(value: string | undefined): void {
     if (this.name === null) {
       if (!Guards.isTextual(this.node))
         throw new TypeError('Text binding requires the Textual mixin');
+      if ((this.textBinding ? this.textBinding.value : this.node.text()) === (value ?? '')) return;
       if (this.textBinding) this.textBinding.set(value ?? '');
       else this.node.text(value ?? '');
-    } else this.node.setAttributeValue(this.name, value);
-    this.previous = value;
+    } else {
+      const current = this.node.getAttributeValue(this.name);
+      if ((current === undefined ? undefined : String(current)) === value) return;
+      this.node.setAttributeValue(this.name, value);
+    }
   }
 
   private static primitive(value: TemplateValue): string {

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/content.ts

@@ -7,6 +7,7 @@ import { assertCanAddChildren, validateChild } from '../mixins/parent-internals.
 import { destroySubtrees } from '../core/destruction.js';
 import { TextDom } from '../dom/text.js';
 import type { TextPolicies } from '../changes/types.js';
+import { textContents } from './policies.js';
 
 class TextSlot implements TextBinding {
   active = true;
@@ -275,25 +276,14 @@ export class TextContent {
   }
 }
 
-const contents = new WeakMap<AnyNode, TextContent>();
 export function contentFor(host: ParentNode): TextContent {
-  let content = contents.get(host);
+  let content = textContents.get(host);
   if (!content) {
     content = new TextContent(host);
-    contents.set(host, content);
+    textContents.set(host, content);
   }
   return content;
 }
 export function refreshLines(host: AnyNode): void {
-  contents.get(host)?.refreshLines();
-}
-
-/** Internal reconstruction bridge; copies policies onto fresh children, never callback closures. */
-export function copyTextPolicies(
-  source: AnyNode,
-  target: ParentNode,
-  copies: ReadonlyMap<AnyNode, AnyNode>,
-): void {
-  const content = contents.get(source);
-  if (content) content.copyLinesTo(contentFor(target), copies);
+  textContents.get(host)?.refreshLines();
 }

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/text/policies.ts

@@ -0,0 +1,18 @@
+import type { AnyNode } from '../core/types.js';
+import type { TextContent } from './content.js';
+
+/** Shared state without retaining the rich-text implementation in interchange bundles. */
+export const textContents = new WeakMap<AnyNode, TextContent>();
+
+/** Copies policies onto reconstructed text children, never callback closures. */
+export function copyTextPolicies(
+  source: AnyNode,
+  target: AnyNode,
+  copies: ReadonlyMap<AnyNode, AnyNode>,
+): void {
+  const content = textContents.get(source);
+  if (!content) return;
+  const destination = textContents.get(target);
+  if (!destination) throw new TypeError('Clone target must support the source text content');
+  content.copyLinesTo(destination, copies);
+}

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';
+}