@phin-tech/dottie 0.1.0 → 0.3.0

package/PARITY.md

@@ -24,11 +24,12 @@ fixture, so the gap is visible rather than silent.
 | Ports and edge-following, rotated shapes, free ends | Supported | [edge/connectors](../fixtures/edge/connectors.dottie) | |
 | Arrowheads: arrow, triangle, dot, bar | Supported | [edge/connectors](../fixtures/edge/connectors.dottie) | |
 | Connector labels | Supported | [edge/connectors](../fixtures/edge/connectors.dottie) | Label boxes sized with CoreText's measurements. The player paints them on the page color, like the app; Dottie's flipbook export leaves them unpainted |
-| Keys and eases (linear, in, out, in-out, hold) | Supported | [edge/timeline](../fixtures/edge/timeline.dottie) | |
+| Keys and eases (linear, in, out, in-out, hold, spring, bounce, elastic) | Supported | [edge/timeline](../fixtures/edge/timeline.dottie), [edge/eases](../fixtures/edge/eases.dottie) | Unknown ease names play linear, with a warning |
 | Visibility, reveal (draw-on, typing), opacity | Supported | [edge/timeline](../fixtures/edge/timeline.dottie) | |
 | Transitions | Supported | [edge/transitions](../fixtures/edge/transitions.dottie) | They are ordinary keys in the file |
 | Follow paths (connectors, outlines, orient, reverse, laps) | Supported | [edge/follow](../fixtures/edge/follow.dottie) | |
 | Packets, labelled packets | Supported | [design/labels](../fixtures/design/labels.dottie) | |
+| Marching ants (dashes travelling along a line) | Supported | [edge/march](../fixtures/edge/march.dottie) | `stroke-dashoffset` per frame, evened out to loop |
 | Repeats (counted and forever) | Supported | [edge/timeline](../fixtures/edge/timeline.dottie) | |
 | Boil (three drawings) and settle | Supported | [edge/timeline](../fixtures/edge/timeline.dottie) | Boiled seeds match bit for bit |
 | Camera views | Supported | [edge/camera](../fixtures/edge/camera.dottie), [design/zoom](../fixtures/design/zoom.dottie) | |

package/README.md

@@ -36,6 +36,25 @@ The element has `play()`, `pause()`, `nextScene()`, `prevScene()`, `currentTime`
 Without modules, `dist/dottie-player.min.js` is a classic script that registers the element and sets
 `window.Dottie`.
 
+## Compile a drawing into one script
+
+```sh
+npx -p @phin-tech/dottie dottie-compile tour.dottie        # writes tour.js
+```
+
+`tour.js` holds the player and the drawing (about 75 KB plus the drawing; around 25 KB gzipped), so one file
+shows it anywhere you can put a script tag:
+
+```html
+<script src="tour.js"></script>                            <!-- a player right here -->
+<script src="tour.js" data-target="#demo"></script>        <!-- a player inside #demo -->
+<script src="tour.js" data-clean data-no-loop></script>    <!-- data-* set the player's attributes -->
+```
+
+`dottie-compile` takes `--page`, `--at`, `--clean`, `--no-controls`, `--no-autoplay`, `--no-loop` and `--label`;
+only the chosen page (and its pictures) goes in. The Dottie Mac app's command-line tool writes the same file:
+`dottie render tour.dottie -f js`. From code: `import { compile } from "@phin-tech/dottie/compile"`.
+
 ## Use the library
 
 ```js

package/dist/compile.js

@@ -0,0 +1,394 @@
+/*! dottie.js 0.3.0 | Apache-2.0 | https://github.com/phin-tech/dottie */
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/model.ts
+var SUPPORTED_VERSION = 2;
+var KINDS = ["rectangle", "ellipse", "diamond", "text", "connector", "freehand", "path", "note", "image"];
+var EASES = ["linear", "easeIn", "easeOut", "easeInOut", "hold", "spring", "bounce", "elastic"];
+var KNOWN_FIELDS = {
+  file: ["version", "pages", "images"],
+  page: ["id", "name", "layers", "elements", "theme", "guidesX", "guidesY", "guidesLocked", "timeline"],
+  layer: ["id", "name", "visible", "locked"],
+  rgba: ["r", "g", "b", "a"],
+  style: ["stroke", "fill", "fillStyle", "strokeWidth", "dash", "roughness", "bowing", "fontSize", "gridSize", "opacity", "dashOffset"],
+  element: [
+    "id",
+    "kind",
+    "x",
+    "y",
+    "width",
+    "height",
+    "style",
+    "seed",
+    "layerID",
+    "text",
+    "connector",
+    "groupID",
+    "points",
+    "path",
+    "subpaths",
+    "evenOdd",
+    "rotation",
+    "link",
+    "anchor",
+    "image",
+    "reveal"
+  ],
+  strokePoint: ["x", "y"],
+  subpath: ["closed", "coords"],
+  inlineImage: ["data", "format"],
+  endpoint: ["elementID", "port", "x", "y"],
+  connector: ["start", "end", "routing", "startHead", "endHead"],
+  timeline: ["fps", "duration", "boil", "settle", "poster", "tracks", "camera", "markers"],
+  track: ["element", "keys", "boil", "follow", "repeats", "march"],
+  keyframe: ["t", "x", "y", "width", "height", "rotation", "strokeWidth", "stroke", "fill", "visible", "reveal", "opacity", "ease"],
+  follow: ["path", "start", "end", "ease", "reverse", "orient", "laps"],
+  repeat: ["start", "end", "count"],
+  cameraKey: ["t", "x", "y", "width", "height", "ease"],
+  marker: ["t", "name"]
+};
+var MAX_DURATION = 3600;
+var MAX_MARCH = 1e4;
+var clampMarch = (v) => v === void 0 || !Number.isFinite(v) || v === 0 ? null : Math.min(Math.max(v, -MAX_MARCH), MAX_MARCH);
+var black = { r: 0.12, g: 0.12, b: 0.13, a: 1 };
+var clear = { r: 0, g: 0, b: 0, a: 0 };
+var DottieFormatError = class extends Error {
+};
+var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var num = (v) => typeof v === "number" && Number.isFinite(v) ? v : void 0;
+var str = (v) => typeof v === "string" ? v : void 0;
+var bool = (v) => typeof v === "boolean" ? v : void 0;
+var uuid = (v) => typeof v === "string" ? v.toUpperCase() : void 0;
+function clampTime(t) {
+  if (!Number.isFinite(t)) return t === Infinity ? MAX_DURATION : 0;
+  return Math.min(Math.max(t, 0), MAX_DURATION);
+}
+function clampFPS(f) {
+  return Number.isFinite(f) ? Math.min(Math.max(f, 1), 60) : 12;
+}
+function rgba(v) {
+  if (!isObj(v)) return void 0;
+  const r = num(v.r), g = num(v.g), b = num(v.b);
+  if (r === void 0 || g === void 0 || b === void 0) return void 0;
+  return { r, g, b, a: num(v.a) ?? 1 };
+}
+var Reader = class {
+  constructor() {
+    __publicField(this, "warnings", []);
+    __publicField(this, "seen", /* @__PURE__ */ new Set());
+  }
+  warn(message) {
+    if (!this.seen.has(message)) {
+      this.seen.add(message);
+      this.warnings.push(message);
+    }
+  }
+  /** Reports fields this version doesn't read (they're ignored, as Dottie ignores them). */
+  fields(v, kind) {
+    const known = KNOWN_FIELDS[kind];
+    for (const k of Object.keys(v)) if (!known.includes(k)) this.warn(`Unknown field "${k}" on ${kind}, ignored`);
+  }
+  style(v) {
+    const s = isObj(v) ? v : {};
+    this.fields(s, "style");
+    const fillStyle = str(s.fillStyle) ?? "solid";
+    const dash = str(s.dash) ?? "solid";
+    if (!["solid", "hachure", "crossHatch", "grid"].includes(fillStyle)) this.warn(`Unknown fill style "${fillStyle}", drawn solid`);
+    if (!["solid", "dashed", "dotted"].includes(dash)) this.warn(`Unknown dash "${dash}", drawn solid`);
+    return {
+      stroke: rgba(s.stroke) ?? { ...black },
+      fill: rgba(s.fill) ?? { ...clear },
+      fillStyle: ["solid", "hachure", "crossHatch", "grid"].includes(fillStyle) ? fillStyle : "solid",
+      strokeWidth: num(s.strokeWidth) ?? 2,
+      dash: ["solid", "dashed", "dotted"].includes(dash) ? dash : "solid",
+      roughness: num(s.roughness) ?? 1,
+      bowing: num(s.bowing) ?? 1,
+      fontSize: num(s.fontSize) ?? 18,
+      gridSize: num(s.gridSize) ?? null,
+      opacity: num(s.opacity) ?? null,
+      dashOffset: num(s.dashOffset) ?? null
+    };
+  }
+  endpoint(v) {
+    const e = isObj(v) ? v : {};
+    const port = str(e.port);
+    return {
+      elementID: uuid(e.elementID) ?? null,
+      port: port && ["top", "right", "bottom", "left"].includes(port) ? port : null,
+      x: num(e.x) ?? 0,
+      y: num(e.y) ?? 0
+    };
+  }
+  connector(v) {
+    if (!isObj(v)) return null;
+    this.fields(v, "connector");
+    const head = (h, d) => {
+      const s = str(h);
+      return s && ["none", "arrow", "triangle", "dot", "bar"].includes(s) ? s : d;
+    };
+    const routing = str(v.routing);
+    return {
+      start: this.endpoint(v.start),
+      end: this.endpoint(v.end),
+      routing: routing && ["straight", "curved", "elbow"].includes(routing) ? routing : "straight",
+      startHead: head(v.startHead, "none"),
+      endHead: head(v.endHead, "arrow")
+    };
+  }
+  image(v, table) {
+    if (!isObj(v)) return null;
+    const ref = str(v.ref);
+    if (ref !== void 0) return table[ref] ?? { data: "", format: "png" };
+    const data = str(v.data);
+    return data === void 0 ? null : this.picture(data, str(v.format));
+  }
+  /** A picture's bytes, only if they really are base64: they go into an attribute of the drawn SVG. */
+  picture(data, format) {
+    if (!BASE64.test(data)) {
+      this.warn("Skipped a picture whose data isn't base64");
+      return { data: "", format: "png" };
+    }
+    return { data: data.replace(/\s+/g, ""), format: format === "jpeg" ? "jpeg" : "png" };
+  }
+  element(v, images) {
+    if (!isObj(v)) return null;
+    this.fields(v, "element");
+    const id = uuid(v.id), kind = str(v.kind), layerID = uuid(v.layerID);
+    if (!id || !kind || !layerID) {
+      this.warn("Skipped an element without an id, kind or layer");
+      return null;
+    }
+    if (!KINDS.includes(kind)) this.warn(`Unknown element kind "${kind}", drawn as a placeholder`);
+    const subpaths = Array.isArray(v.subpaths) ? v.subpaths.filter(isObj).map((s) => ({ closed: bool(s.closed) ?? false, coords: Array.isArray(s.coords) ? s.coords.filter((c) => typeof c === "number") : [] })) : null;
+    return {
+      id,
+      kind,
+      layerID,
+      x: num(v.x) ?? 0,
+      y: num(v.y) ?? 0,
+      width: num(v.width) ?? 0,
+      height: num(v.height) ?? 0,
+      style: this.style(v.style),
+      seed: (num(v.seed) ?? 1) >>> 0,
+      text: str(v.text) ?? null,
+      connector: this.connector(v.connector),
+      groupID: uuid(v.groupID) ?? null,
+      points: Array.isArray(v.points) ? v.points.filter(isObj).map((p) => ({ x: num(p.x) ?? 0, y: num(p.y) ?? 0 })) : null,
+      path: Array.isArray(v.path) ? v.path.filter((c) => typeof c === "number") : null,
+      subpaths,
+      evenOdd: bool(v.evenOdd) ?? null,
+      rotation: num(v.rotation) ?? null,
+      link: uuid(v.link) ?? null,
+      anchor: str(v.anchor) ?? null,
+      image: this.image(v.image, images),
+      reveal: num(v.reveal) ?? null
+    };
+  }
+  ease(v) {
+    const s = str(v);
+    if (s === void 0) return null;
+    if (!EASES.includes(s)) {
+      this.warn(`Unknown ease "${s}", played linear`);
+      return null;
+    }
+    return s;
+  }
+  keyframe(v) {
+    if (!isObj(v)) return null;
+    this.fields(v, "keyframe");
+    const t = num(v.t);
+    if (t === void 0) return null;
+    const k = { t };
+    for (const p of ["x", "y", "width", "height", "rotation", "strokeWidth", "reveal", "opacity"]) {
+      const n = num(v[p]);
+      if (n !== void 0) k[p] = n;
+    }
+    const stroke = rgba(v.stroke), fill = rgba(v.fill), visible = bool(v.visible), ease = this.ease(v.ease);
+    if (stroke) k.stroke = stroke;
+    if (fill) k.fill = fill;
+    if (visible !== void 0) k.visible = visible;
+    if (ease) k.ease = ease;
+    return k;
+  }
+  track(v) {
+    if (!isObj(v)) return null;
+    this.fields(v, "track");
+    const element = uuid(v.element);
+    if (!element) return null;
+    const keys = (Array.isArray(v.keys) ? v.keys : []).map((k) => this.keyframe(k)).filter((k) => k !== null && k.t >= 0 && k.t <= MAX_DURATION);
+    stableSortBy(keys, (k) => k.t);
+    const follow = Array.isArray(v.follow) ? v.follow.filter(isObj).flatMap((f) => {
+      const path = uuid(f.path), start = num(f.start), end = num(f.end);
+      if (!path || start === void 0 || end === void 0 || start < 0 || end > MAX_DURATION) return [];
+      return [{ path, start, end, ease: this.ease(f.ease), reverse: bool(f.reverse) ?? null, orient: bool(f.orient) ?? null, laps: num(f.laps) ?? null }];
+    }) : null;
+    const repeats = Array.isArray(v.repeats) ? v.repeats.filter(isObj).flatMap((r) => {
+      const start = num(r.start), end = num(r.end);
+      if (start === void 0 || end === void 0) return [];
+      const count = num(r.count);
+      const rep = { start, end, count: count === void 0 ? null : Math.trunc(count) };
+      return repeatIsValid(rep) ? [rep] : [];
+    }) : null;
+    return { element, keys, boil: bool(v.boil) ?? null, follow, repeats, march: clampMarch(num(v.march)) };
+  }
+  timeline(v) {
+    if (!isObj(v)) return null;
+    this.fields(v, "timeline");
+    const boil = num(v.boil);
+    const camera = Array.isArray(v.camera) ? v.camera.filter(isObj).flatMap((c) => {
+      const t = num(c.t), x = num(c.x), y = num(c.y), width = num(c.width), height = num(c.height);
+      if (t === void 0 || x === void 0 || y === void 0 || width === void 0 || height === void 0) return [];
+      if (!(width > 1 && height > 1 && t >= 0)) return [];
+      return [{ t, x, y, width, height, ease: this.ease(c.ease) }];
+    }) : null;
+    if (camera) stableSortBy(camera, (c) => c.t);
+    const markers = Array.isArray(v.markers) ? v.markers.filter(isObj).flatMap((m) => {
+      const t = num(m.t);
+      return t !== void 0 && t >= 0 ? [{ t, name: str(m.name) ?? "" }] : [];
+    }) : null;
+    if (markers) stableSortBy(markers, (m) => m.t);
+    const poster = num(v.poster);
+    return {
+      fps: clampFPS(num(v.fps) ?? 12),
+      duration: clampTime(num(v.duration) ?? 0),
+      boil: boil !== void 0 && Number.isInteger(boil) && boil > 0 ? Math.min(boil, 1e4) : null,
+      settle: bool(v.settle) ?? null,
+      poster: poster === void 0 ? null : clampTime(poster),
+      tracks: (Array.isArray(v.tracks) ? v.tracks : []).map((t) => this.track(t)).filter((t) => t !== null),
+      camera,
+      markers
+    };
+  }
+  page(v, images, n) {
+    if (!isObj(v)) throw new DottieFormatError(`Page ${n} is not an object`);
+    this.fields(v, "page");
+    const layers = (Array.isArray(v.layers) ? v.layers : []).filter(isObj).flatMap((l) => {
+      const id = uuid(l.id);
+      return id ? [{ id, name: str(l.name) ?? "", visible: bool(l.visible) ?? true, locked: bool(l.locked) ?? false }] : [];
+    });
+    if (layers.length === 0) {
+      this.warn(`Page ${n} has no layers`);
+      layers.push({ id: "LAYER", name: "Layer 1", visible: true, locked: false });
+    }
+    return {
+      id: uuid(v.id) ?? `PAGE-${n}`,
+      name: str(v.name) ?? `Page ${n}`,
+      layers,
+      elements: (Array.isArray(v.elements) ? v.elements : []).map((e) => this.element(e, images)).filter((e) => e !== null),
+      theme: str(v.theme) ?? null,
+      timeline: this.timeline(v.timeline)
+    };
+  }
+};
+var BASE64 = /^[A-Za-z0-9+/=\s]*$/;
+function repeatIsValid(r) {
+  return Number.isFinite(r.start) && Number.isFinite(r.end) && r.start >= 0 && r.end - r.start > 1e-3 && r.end <= MAX_DURATION && (r.count === null || r.count >= 1 && r.count <= 1e4);
+}
+function stableSortBy(a, key) {
+  const indexed = a.map((v, i) => [v, i]);
+  indexed.sort((p, q) => key(p[0]) - key(q[0]) || p[1] - q[1]);
+  for (let i = 0; i < a.length; i++) a[i] = indexed[i][0];
+}
+function parseDottie(source) {
+  let json = source;
+  if (typeof source === "string") {
+    try {
+      json = JSON.parse(source);
+    } catch (e) {
+      throw new DottieFormatError(`Not JSON: ${e.message}`);
+    }
+  }
+  if (!isObj(json)) throw new DottieFormatError("Not a Dottie drawing");
+  const version = num(json.version);
+  if (version === void 0) throw new DottieFormatError("Not a Dottie drawing (no version)");
+  if (!Array.isArray(json.pages) || json.pages.length === 0) throw new DottieFormatError("A drawing needs at least one page");
+  const reader = new Reader();
+  reader.fields(json, "file");
+  if (version > SUPPORTED_VERSION) reader.warn(`File version ${version} is newer than this player knows (${SUPPORTED_VERSION}); some things may not show`);
+  const images = {};
+  if (isObj(json.images)) {
+    for (const [k, v] of Object.entries(json.images)) {
+      if (isObj(v) && typeof v.data === "string") images[k] = reader.picture(v.data, str(v.format));
+    }
+  }
+  const pages = json.pages.map((p, i) => reader.page(p, images, i + 1));
+  if (new Set(pages.map((p) => p.id)).size !== pages.length) throw new DottieFormatError("Two pages share an id");
+  return { version, pages, warnings: reader.warnings };
+}
+
+// src/player.ts
+function pageIndex(file, spec) {
+  const s = (spec ?? "").trim();
+  if (!s) return 0;
+  const byName = file.pages.findIndex((p) => p.name.toLowerCase() === s.toLowerCase());
+  if (byName >= 0) return byName;
+  const n = Number(s);
+  return Number.isInteger(n) && n >= 1 && n <= file.pages.length ? n - 1 : 0;
+}
+
+// src/compile.ts
+var LOADER = `;(function () {
+  var data = DOTTIE_DATA, options = DOTTIE_OPTIONS;
+  var script = document.currentScript;
+  function attr(el, name, value) { el.setAttribute(name.replace(/[A-Z]/g, function (c) { return "-" + c.toLowerCase(); }), value); }
+  function mount() {
+    var player = document.createElement("dottie-player"), k;
+    for (k in options) attr(player, k, options[k]);
+    if (script) for (k in script.dataset) if (k !== "target") attr(player, k, script.dataset[k]);
+    var target = script && script.dataset.target ? document.querySelector(script.dataset.target) : null;
+    if (target) target.appendChild(player);
+    else if (script && script.parentNode && script.parentNode !== document.head) script.parentNode.insertBefore(player, script);
+    else document.body.appendChild(player);
+    player.setFile(window.Dottie.parseDottie(data));
+  }
+  if (document.readyState === "loading" && (!script || script.parentNode === document.head || script.dataset.target)) {
+    document.addEventListener("DOMContentLoaded", mount);
+  } else {
+    mount();
+  }
+})();
+`;
+function scriptJSON(value) {
+  return JSON.stringify(value).replace(/<\//g, "<\\/").replace(/<!--/g, "<\\!--").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+function playerAttributes(options) {
+  const out = {};
+  if (options.at !== void 0) out.at = String(options.at);
+  if (options.clean) out.clean = "";
+  if (options.noControls) out["no-controls"] = "";
+  if (options.noAutoplay) out["no-autoplay"] = "";
+  if (options.noLoop) out["no-loop"] = "";
+  if (options.label !== void 0) out.label = options.label;
+  return out;
+}
+function compile(source, runtime, options = {}) {
+  let raw = source;
+  if (typeof source === "string") {
+    try {
+      raw = JSON.parse(source);
+    } catch (e) {
+      throw new DottieFormatError(`Not JSON: ${e.message}`);
+    }
+  }
+  const file = parseDottie(raw);
+  const json = raw;
+  const i = pageIndex(file, options.page === void 0 ? null : String(options.page));
+  const page = json.pages[i];
+  const refs = /* @__PURE__ */ new Set();
+  JSON.stringify(page, (k, v) => {
+    if (k === "ref" && typeof v === "string") refs.add(v);
+    return v;
+  });
+  const images = Object.fromEntries(Object.entries(json.images ?? {}).filter(([k]) => refs.has(k)));
+  const data = { version: json.version, pages: [page] };
+  if (Object.keys(images).length) data.images = images;
+  return runtime.trimEnd() + "\n" + LOADER.replace("DOTTIE_DATA", () => scriptJSON(data)).replace("DOTTIE_OPTIONS", () => scriptJSON(playerAttributes(options)));
+}
+export {
+  LOADER,
+  compile,
+  playerAttributes,
+  scriptJSON
+};