@phin-tech/dottie 0.5.4 → 0.6.1

package/dist/dottie.js

@@ -1,4 +1,4 @@
-/*! dottie.js 0.5.4 | Apache-2.0 | https://github.com/phin-tech/dottie */
+/*! dottie.js 0.6.1 | Apache-2.0 | https://github.com/phin-tech/dottie */
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value2) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value: value2 }) : obj[key] = value2;
 var __publicField = (obj, key, value2) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value2);
@@ -33,6 +33,7 @@ var KNOWN_FIELDS = {
     "evenOdd",
     "rotation",
     "link",
+    "url",
     "anchor",
     "click",
     "hover",
@@ -41,12 +42,18 @@ var KNOWN_FIELDS = {
     "offset",
     "args",
     "image",
-    "reveal"
+    "reveal",
+    "ports",
+    "labelRect",
+    "extension"
   ],
   strokePoint: ["x", "y"],
   subpath: ["closed", "coords"],
   inlineImage: ["data", "format"],
-  endpoint: ["elementID", "port", "x", "y"],
+  endpoint: ["elementID", "port", "portIndex", "x", "y"],
+  extensionRef: ["id", "shape", "version", "params"],
+  normalizedPoint: ["x", "y"],
+  normalizedRect: ["x", "y", "width", "height"],
   connector: ["start", "end", "routing", "startHead", "endHead"],
   timeline: ["fps", "duration", "boil", "settle", "poster", "tracks", "camera", "markers"],
   track: ["element", "keys", "boil", "follow", "repeats", "march"],
@@ -85,6 +92,9 @@ function allowedURL(url) {
   if (!/^(https?:\/\/|mailto:)/i.test(u) || [...u].length <= 7 || /[\u0000-\u001f\u007f-\u009f]/.test(u)) return null;
   return u;
 }
+function webLink(url) {
+  return url ? allowedURL(url) : null;
+}
 function rgba(v) {
   if (!isObj(v)) return void 0;
   const r = num(v.r), g = num(v.g), b = num(v.b);
@@ -131,9 +141,11 @@ var Reader = class {
   endpoint(v) {
     const e = isObj(v) ? v : {};
     const port = str(e.port);
+    const portIndex = num(e.portIndex);
     return {
       elementID: uuid(e.elementID) ?? null,
       port: port && ["top", "right", "bottom", "left"].includes(port) ? port : null,
+      portIndex: portIndex !== void 0 && Number.isInteger(portIndex) && portIndex >= 0 ? portIndex : null,
       x: num(e.x) ?? 0,
       y: num(e.y) ?? 0
     };
@@ -198,6 +210,7 @@ var Reader = class {
       evenOdd: bool(v.evenOdd) ?? null,
       rotation: num(v.rotation) ?? null,
       link: uuid(v.link) ?? null,
+      url: str(v.url) ?? null,
       anchor: str(v.anchor) ?? null,
       click: this.click(v.click),
       hover: this.hover(v.hover),
@@ -206,9 +219,36 @@ var Reader = class {
       offset: num(v.offset) ?? null,
       args: strings(v.args),
       image: this.image(v.image, images),
-      reveal: num(v.reveal) ?? null
+      reveal: num(v.reveal) ?? null,
+      ports: Array.isArray(v.ports) ? v.ports.map((p) => {
+        const o = isObj(p) ? p : {};
+        return { x: num(o.x) ?? 0, y: num(o.y) ?? 0 };
+      }) : null,
+      labelRect: this.labelRect(v.labelRect),
+      extension: this.extension(v.extension)
     };
   }
+  labelRect(v) {
+    if (!isObj(v)) return null;
+    this.fields(v, "normalizedRect");
+    return { x: num(v.x) ?? 0, y: num(v.y) ?? 0, width: num(v.width) ?? 0, height: num(v.height) ?? 0 };
+  }
+  extension(v) {
+    if (!isObj(v)) return null;
+    this.fields(v, "extensionRef");
+    const id = str(v.id), shape = str(v.shape), version = str(v.version);
+    if (id === void 0 || shape === void 0 || version === void 0) {
+      this.warn("Skipped an extension without an id, shape or version");
+      return null;
+    }
+    const params = {};
+    if (isObj(v.params)) {
+      for (const [k, p] of Object.entries(v.params)) {
+        if (typeof p === "number" || typeof p === "boolean" || typeof p === "string") params[k] = p;
+      }
+    }
+    return { id, shape, version, params };
+  }
   click(v) {
     if (!isObj(v)) return null;
     this.fields(v, "click");
@@ -714,12 +754,45 @@ function portPoint(shape, port) {
   const p = port === "top" ? { x: midX(r), y: r.y } : port === "right" ? { x: maxX(r), y: midY(r) } : port === "bottom" ? { x: midX(r), y: maxY(r) } : { x: r.x, y: midY(r) };
   return rotated(shape, p);
 }
+function flattenContour(cp) {
+  const out = [];
+  for (let s = 0; s + 3 < cp.length; s += 3) {
+    const seg = cp.slice(s, s + 4);
+    for (let k = 0; k < 16; k++) out.push(bezierPoint(seg, k / 16));
+  }
+  out.push(cp[cp.length - 1]);
+  return out;
+}
+function outlineCrossing(shape, c, d) {
+  let nearest2 = null, farthest = null;
+  for (const contour of shapeContours(shape)) {
+    const pts = flattenContour(contour.points);
+    const n = pts.length;
+    const edges = contour.closed ? n : n - 1;
+    for (let i = 0; i < edges; i++) {
+      const a = pts[i], b = pts[(i + 1) % n];
+      const e = { x: b.x - a.x, y: b.y - a.y }, w = { x: a.x - c.x, y: a.y - c.y };
+      const det = e.x * d.y - d.x * e.y;
+      if (det === 0) continue;
+      const t = (e.x * w.y - e.y * w.x) / det, s = (d.x * w.y - d.y * w.x) / det;
+      if (!(t > 0 && s >= 0 && s <= 1)) continue;
+      if (nearest2 === null || t < nearest2) nearest2 = t;
+      if (t <= 1 && (farthest === null || t > farthest)) farthest = t;
+    }
+  }
+  const best = farthest ?? nearest2;
+  return best === null ? null : { x: c.x + d.x * best, y: c.y + d.y * best };
+}
 function edgePoint(shape, toward) {
   const r = frame(shape);
   const c = center(shape);
   const target = unrotated(shape, toward);
   const dx = target.x - c.x, dy = target.y - c.y;
   if (!((dx !== 0 || dy !== 0) && r.width > 0 && r.height > 0)) return c;
+  if (shape.kind === "path") {
+    const hit = outlineCrossing(shape, c, { x: dx, y: dy });
+    if (hit) return rotated(shape, hit);
+  }
   const hw = r.width / 2, hh = r.height / 2;
   let t;
   if (shape.kind === "ellipse") t = 1 / Math.sqrt(dx * dx / (hw * hw) + dy * dy / (hh * hh));
@@ -731,9 +804,15 @@ function reference(ep, index) {
   const s = ep.elementID ? index.get(ep.elementID) : void 0;
   return s ? center(s) : { x: ep.x, y: ep.y };
 }
+function normalizedPoint(shape, p) {
+  const r = frame(shape);
+  return rotated(shape, { x: r.x + p.x * r.width, y: r.y + p.y * r.height });
+}
 function resolve(ep, other, index) {
   const s = ep.elementID ? index.get(ep.elementID) : void 0;
   if (!s) return { x: ep.x, y: ep.y };
+  const i = ep.portIndex, ports = s.ports ?? [];
+  if (typeof i === "number" && Number.isInteger(i) && i >= 0 && i < ports.length) return normalizedPoint(s, ports[i]);
   return ep.port ? portPoint(s, ep.port) : edgePoint(s, other);
 }
 function endpoints(e, index) {
@@ -1917,7 +1996,7 @@ function clickTargets(page, file) {
         continue;
       }
     }
-    const url = c?.url ? allowedURL(c.url) : null;
+    const url = (c?.url ? allowedURL(c.url) : null) ?? webLink(e.url);
     if (url) {
       out.set(e.id, { url });
       continue;
@@ -2717,8 +2796,8 @@ function svgOpen(b, background, paint) {
   }
   return out;
 }
-function svgParts(page, background, fixed) {
-  if (hasInstances(page)) return svgParts(expandingSymbols(page, 0), background, fixed);
+function svgParts(page, background, fixed, links = false) {
+  if (hasInstances(page)) return svgParts(expandingSymbols(page, 0), background, fixed, links);
   const theme = themeNamed(page.theme);
   const bg = background ? theme?.background ?? background : null;
   const ink = theme?.ink ?? black;
@@ -2742,14 +2821,19 @@ function svgParts(page, background, fixed) {
 ${body}</g>
 `;
     }
-    parts.push({ key: e.id, markup: alpha < 1 ? `<g opacity="${fmt(alpha)}">
+    if (alpha < 1) body = `<g opacity="${fmt(alpha)}">
 ${body}</g>
-` : body });
+`;
+    const href = links ? (e.click?.url ? allowedURL(e.click.url) : null) ?? webLink(e.url) : null;
+    if (href) body = `<a href="${escapeXML(href).replace(/"/g, "&quot;")}" target="_blank">
+${body}</a>
+`;
+    parts.push({ key: e.id, markup: body });
   }
   return { bounds: b, parts };
 }
 function svg(page, background = { r: 1, g: 1, b: 1, a: 1 }, fixed) {
-  const { bounds: b, parts } = svgParts(page, background, fixed);
+  const { bounds: b, parts } = svgParts(page, background, fixed, true);
   return svgOpen(b, themeNamed(page.theme)?.background ?? background, background !== null) + parts.map((p) => p.markup).join("") + "</svg>\n";
 }
 function labelRect(e, index) {
@@ -2844,7 +2928,7 @@ function svgElement(e, index, labelBackground) {
       }
       s += `<path d="${outline(e).data()}" fill="none" ${strokeAttrs}/>
 `;
-      if (text) s += e.kind === "note" ? noteMarkup(text, e) : textElement(text, frame(e), e, true);
+      if (text) s += e.kind === "note" ? noteMarkup(text, e) : textElement(text, e.kind === "path" ? pathLabelBox(e) : frame(e), e, true);
       return s;
     }
     default:
@@ -2857,6 +2941,11 @@ function placeholder(e, strokeAttrs) {
   return `<path d="${p.data()}" fill="none" ${strokeAttrs} stroke-opacity="0.5" stroke-dasharray="6 4"/>
 ` + textElement(`${e.kind}${e.text ? `: ${e.text}` : ""}`, f, { ...e, style: { ...e.style, fontSize: Math.min(e.style.fontSize, 12) } }, true);
 }
+function pathLabelBox(e) {
+  const f = frame(e), r = e.labelRect;
+  if (!r) return f;
+  return { x: f.x + r.x * f.width, y: f.y + r.y * f.height, width: r.width * f.width, height: r.height * f.height };
+}
 function textElement(text, f, e, centered) {
   const size = e.style.fontSize;
   const lines = text.split("\n");
@@ -3555,7 +3644,7 @@ function render(source, options = {}) {
 function isFile(v) {
   return typeof v === "object" && v !== null && Array.isArray(v.pages) && Array.isArray(v.warnings);
 }
-var VERSION = "0.5.4";
+var VERSION = "0.6.1";
 export {
   BOIL_DRAWINGS,
   DottieFormatError,
@@ -3603,5 +3692,6 @@ export {
   themeNamed,
   themes,
   transientElements,
+  webLink,
   withRoughness
 };

package/dist/types/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/clicks.d.ts

@@ -11,7 +11,7 @@ export type Click = {
 /** The marker called `name`: an exact match, else one that differs only in case. */
 export declare function sceneNamed(name: string, markers: Marker[]): number;
 /** The page's clickable elements and what each click does, by element id. A scene named by no marker, or a link
- * that isn't allowed, makes nothing clickable. Given the whole file, an element whose `link` points at an element on
+ * that isn't allowed, makes nothing clickable; an element with no `click` opens its `url` when that is a web link. Given the whole file, an element whose `link` points at an element on
  * another page shows that page (the HTML export holds one page, so it can't). */
 export declare function clickTargets(page: Page, file?: DottieFile): Map<string, Click>;
 /** `e` as it looks hovered (HoverLook.apply). */

package/dist/types/index.d.ts

@@ -18,4 +18,4 @@ export interface RenderOptions {
 /** One page of a drawing as an SVG document, as Dottie's own SVG export draws it. */
 export declare function render(source: string | DottieFile | unknown, options?: RenderOptions): string;
 /** The library's version. */
-export declare const VERSION = "0.5.4";
+export declare const VERSION = "0.6.1";

package/dist/types/model.d.ts

@@ -26,12 +26,21 @@ export interface Style {
     /** How far into its dash pattern a dashed or dotted line starts; marching ants set it on every frame. */
     dashOffset: number | null;
 }
+/** `portIndex` pins the end to one of the bound element's `ports`, and wins over `port`. */
 export interface Endpoint {
     elementID: string | null;
     port: Port | null;
+    portIndex?: number | null;
     x: number;
     y: number;
 }
+/** The shape an extension generated a path with. Read-only here: nothing runs in dottie.js. */
+export interface ExtensionRef {
+    id: string;
+    shape: string;
+    version: string;
+    params: Record<string, number | boolean | string>;
+}
 export interface ConnectorData {
     start: Endpoint;
     end: Endpoint;
@@ -82,6 +91,9 @@ export interface Element {
     evenOdd: boolean | null;
     rotation: number | null;
     link: string | null;
+    /** Where the element links outside the drawing (Element.url): a web address, or another drawing. Only web
+     * addresses are followed here (`webLink`). */
+    url: string | null;
     anchor: string | null;
     click: ClickAction | null;
     hover: HoverLook | null;
@@ -94,6 +106,18 @@ export interface Element {
     /** Base64 bytes; an empty `data` is a picture that couldn't be found (drawn crossed out). */
     image: EmbeddedImage | null;
     reveal: number | null;
+    /** For an extension shape: connection points and label box, normalized to the frame. */
+    ports?: {
+        x: number;
+        y: number;
+    }[] | null;
+    labelRect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    extension?: ExtensionRef | null;
 }
 export interface Layer {
     id: string;
@@ -211,6 +235,8 @@ export declare function clampFPS(f: number): number;
 /** `url` trimmed, if it is a link a page may open: http, https or mailto, as ClickAction.allowed. A drawing can
  * play on someone else's site, so nothing else (javascript:, data:) is ever followed. */
 export declare function allowedURL(url: string): string | null;
+/** An element's `url`, if it is a web address (OutsideLink.webAddress); a link to another drawing gives null. */
+export declare function webLink(url: string | null | undefined): string | null;
 export declare function repeatIsValid(r: Repeat): boolean;
 /** Sorts in place by `key`, keeping equal keys in their original order (as Swift's sort happens to for these). */
 export declare function stableSortBy<T>(a: T[], key: (v: T) => number): void;

package/dist/types/svg.d.ts

@@ -23,8 +23,10 @@ export interface Part {
     key: string;
     markup: string;
 }
-/** The SVG for each thing drawn, back to front, keyed by element id (rock hatching as "rock"). */
-export declare function svgParts(page: Page, background: RGBA | null, fixed?: Rect): {
+/** The SVG for each thing drawn, back to front, keyed by element id (rock hatching as "rock"). With `links`, an
+ * element whose click or `url` is a web address is wrapped in an `<a>` that opens it, the click's first (the players
+ * make their own clickable groups). */
+export declare function svgParts(page: Page, background: RGBA | null, fixed?: Rect, links?: boolean): {
     bounds: Rect;
     parts: Part[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phin-tech/dottie",
-  "version": "0.5.4",
+  "version": "0.6.1",
   "description": "Render, play and compile Dottie (.dottie) drawings and animations in the browser",
   "type": "module",
   "license": "Apache-2.0",