@kyralabs/m3e-shapes 1.2.0 → 1.4.0

package/dist/index.d.ts

@@ -291,7 +291,7 @@ declare function pillStar(options?: {
     centerY?: number;
 }): RoundedPolygon;
 
-type PathCommand = readonly ['M', number, number] | readonly ['L', number, number] | readonly ['C', number, number, number, number, number, number] | readonly ['Z'];
+type PathCommand = readonly ['M', number, number] | readonly ['L', number, number] | readonly ['Q', number, number, number, number] | readonly ['C', number, number, number, number, number, number] | readonly ['Z'];
 /** Compose `Path.translate(offset)`. */
 declare const translatePath: (path: readonly PathCommand[], dx: number, dy: number) => PathCommand[];
 /**
@@ -414,6 +414,99 @@ declare const materialShapeNames: MaterialShapeName[];
  */
 declare function materialShape(name: MaterialShapeName): RoundedPolygon;
 
+declare class PathMeasure {
+    #private;
+    /** Length of the first contour. */
+    readonly length: number;
+    /**
+     * Measures the first contour of `path`. With `forceClosed` (or a `Z`), a closing line back to
+     * the contour's start is part of it.
+     */
+    constructor(path: readonly PathCommand[], forceClosed?: boolean);
+    /** Compose `PathMeasure.getSegment(startD, stopD, destination)` (moveTo first). */
+    getSegment(startD: number, stopD: number): PathCommand[];
+}
+
+/** Stroke widths (px) and whether the caps are round (StrokeCap.Round, the default). */
+interface ProgressStrokes {
+    stroke: number;
+    trackStroke: number;
+    round?: boolean;
+}
+interface LinearWavyInput extends ProgressStrokes {
+    width: number;
+    height: number;
+    /** Wavelength in px (applies when amplitude > 0). */
+    wavelength: number;
+    /** Pairs of [start, end] fractions (0–1): one pair (determinate) or two (indeterminate). */
+    fractions: readonly number[];
+    /** 0–1 of the room the height leaves the stroke. */
+    amplitude: number;
+    /** 0–1: how far along a wavelength the wave has travelled. */
+    waveOffset: number;
+    /** Gap between the progress and the track (px). */
+    gap: number;
+}
+interface LinearWavyPaths {
+    track: PathCommand[];
+    /** One path per fraction pair (empty when the pair has no length). */
+    progress: PathCommand[][];
+    /** `currentStrokeCapWidth`. */
+    capWidth: number;
+}
+/**
+ * Linear wavy paths, LTR (Compose rotates the drawing 180° for RTL). Reuse one instance per
+ * indicator: like LinearProgressDrawingCache it caches the measured full path.
+ */
+declare class LinearWavyPathCache {
+    #private;
+    /** `updateDrawPaths`: the progress parts and the track for these fractions. */
+    paths(input: LinearWavyInput): LinearWavyPaths;
+}
+/**
+ * The wavy linear stop indicator (`drawStopIndicator`): a dot of min(track stroke, `maxSize`) at the
+ * end of the track that shrinks away as the progress reaches it. Returns its left edge and
+ * diameter (LTR), or null when it has shrunk to nothing.
+ */
+declare function linearWavyStopIndicator(progressEnd: number, width: number, maxSize: number, insets: number, trackStroke: number): {
+    x: number;
+    size: number;
+} | null;
+/**
+ * The wave count of a circular wavy indicator: as many wavelengths as fit around the circle (its
+ * radius inset by half the stroke), at least 5 (`MinCircularVertexCount`).
+ */
+declare const circularWavyVertexCount: (size: number, wavelength: number, stroke: number) => number;
+interface CircularWavyInput extends ProgressStrokes {
+    /** Square drawing size (px). */
+    size: number;
+    /** Preferred wavelength (px); the actual one fits a whole number of waves. */
+    wavelength: number;
+    start: number;
+    end: number;
+    amplitude: number;
+    waveOffset: number;
+    /** The wave offset applies (waveSpeed > 0 and a wave is drawn). */
+    motion: boolean;
+    gap: number;
+}
+interface CircularWavyPaths {
+    track: PathCommand[];
+    progress: PathCommand[];
+    /** Wave count, which scales the circular wave travel duration. */
+    vertexCount: number;
+}
+/**
+ * Circular wavy paths (CircularShapes + CircularProgressDrawingCache). Reuse one instance per
+ * indicator: it caches the polygons, the morph (created the first time the amplitude is between 0
+ * and 1, `requiresMorph`) and the measured full paths.
+ */
+declare class CircularWavyPathCache {
+    #private;
+    /** The paths for `input`; `requiresMorph` as the Compose node passes it. */
+    paths(input: CircularWavyInput, requiresMorph: boolean): CircularWavyPaths;
+}
+
 interface PathOptions {
     /**
      * Angle in degrees the path starts drawing from. Note that, as in Compose, the path is rotated
@@ -434,4 +527,4 @@ interface MorphPathOptions extends PathOptions {
 /** Path for a [Morph] at [progress]; the start angle is measured around the rotation pivot. */
 declare function morphToPath(morph: Morph, progress: number, options?: MorphPathOptions): PathCommand[];
 
-export { Corner, CornerRounding, Cubic, Edge, Feature, type LoadingIndicatorFrame, LoadingIndicatorShapes, type MaterialShapeName, Morph, type MorphPathOptions, MutableCubic, type PathCommand, type PathOptions, type Point, type PointTransformer, RoundedPolygon, calculateScaleFactor, circle, determinateFrame, determinateIndicatorPolygons, indeterminateIndicatorPolygons, loadingIndicatorShapes, materialShape, materialShapeNames, morphSequence, morphToPath, pathBounds, pill, pillStar, polygonToPath, processPath, rectangle, star, toShapeOutline, toSvgPathData, translatePath };
+export { type CircularWavyInput, CircularWavyPathCache, type CircularWavyPaths, Corner, CornerRounding, Cubic, Edge, Feature, type LinearWavyInput, LinearWavyPathCache, type LinearWavyPaths, type LoadingIndicatorFrame, LoadingIndicatorShapes, type MaterialShapeName, Morph, type MorphPathOptions, MutableCubic, type PathCommand, PathMeasure, type PathOptions, type Point, type PointTransformer, type ProgressStrokes, RoundedPolygon, calculateScaleFactor, circle, circularWavyVertexCount, determinateFrame, determinateIndicatorPolygons, indeterminateIndicatorPolygons, linearWavyStopIndicator, loadingIndicatorShapes, materialShape, materialShapeNames, morphSequence, morphToPath, pathBounds, pill, pillStar, polygonToPath, processPath, rectangle, star, toShapeOutline, toSvgPathData, translatePath };

package/dist/index.js

@@ -1529,33 +1529,35 @@ var Matrix = class {
 };
 
 // src/path.ts
-var mapPoints = (command, f4) => {
-  switch (command[0]) {
+var mapPoints = (command2, f4) => {
+  switch (command2[0]) {
     case "M":
     case "L":
-      return [command[0], ...f4(command[1], command[2])];
+      return [command2[0], ...f4(command2[1], command2[2])];
+    case "Q":
+      return ["Q", ...f4(command2[1], command2[2]), ...f4(command2[3], command2[4])];
     case "C":
       return [
         "C",
-        ...f4(command[1], command[2]),
-        ...f4(command[3], command[4]),
-        ...f4(command[5], command[6])
+        ...f4(command2[1], command2[2]),
+        ...f4(command2[3], command2[4]),
+        ...f4(command2[5], command2[6])
       ];
     case "Z":
-      return command;
+      return command2;
   }
 };
-var transformPath = (path, matrix) => path.map((command) => mapPoints(command, (x, y) => matrix.map(x, y)));
-var translatePath = (path, dx, dy) => path.map((command) => mapPoints(command, (x, y) => [x + dx, y + dy]));
+var transformPath = (path, matrix) => path.map((command2) => mapPoints(command2, (x, y) => matrix.map(x, y)));
+var translatePath = (path, dx, dy) => path.map((command2) => mapPoints(command2, (x, y) => [x + dx, y + dy]));
 function pathBounds(path) {
   let left = Infinity;
   let top = Infinity;
   let right = -Infinity;
   let bottom = -Infinity;
-  for (const command of path) {
-    for (let i = 1; i + 1 < command.length; i += 2) {
-      const x = command[i];
-      const y = command[i + 1];
+  for (const command2 of path) {
+    for (let i = 1; i + 1 < command2.length; i += 2) {
+      const x = command2[i];
+      const y = command2[i + 1];
       left = Math.min(left, x);
       top = Math.min(top, y);
       right = Math.max(right, x);
@@ -1957,23 +1959,31 @@ function processPath(path, width, height, scaleFactor) {
   const [left, top, right, bottom] = pathBounds(scaled);
   const dx = f2(f2(width / 2) - f2(left + f2(f2(right - left) / 2)));
   const dy = f2(f2(height / 2) - f2(top + f2(f2(bottom - top) / 2)));
-  return scaled.map((command) => {
-    switch (command[0]) {
+  return scaled.map((command2) => {
+    switch (command2[0]) {
       case "M":
       case "L":
-        return [command[0], f2(command[1] + dx), f2(command[2] + dy)];
+        return [command2[0], f2(command2[1] + dx), f2(command2[2] + dy)];
+      case "Q":
+        return [
+          "Q",
+          f2(command2[1] + dx),
+          f2(command2[2] + dy),
+          f2(command2[3] + dx),
+          f2(command2[4] + dy)
+        ];
       case "C":
         return [
           "C",
-          f2(command[1] + dx),
-          f2(command[2] + dy),
-          f2(command[3] + dx),
-          f2(command[4] + dy),
-          f2(command[5] + dx),
-          f2(command[6] + dy)
+          f2(command2[1] + dx),
+          f2(command2[2] + dy),
+          f2(command2[3] + dx),
+          f2(command2[4] + dy),
+          f2(command2[5] + dx),
+          f2(command2[6] + dy)
         ];
       case "Z":
-        return command;
+        return command2;
     }
   });
 }
@@ -2027,6 +2037,319 @@ function loadingIndicatorShapes(polygons, indeterminate, activeIndicatorScale) {
   return shapes;
 }
 
-export { Corner, CornerRounding, Cubic, Edge, Feature, LoadingIndicatorShapes, Morph, MutableCubic, RoundedPolygon, calculateScaleFactor, circle, determinateFrame, determinateIndicatorPolygons, indeterminateIndicatorPolygons, loadingIndicatorShapes, materialShape, materialShapeNames, morphSequence, morphToPath, pathBounds, pill, pillStar, polygonToPath, processPath, rectangle, star, toShapeOutline, toSvgPathData, translatePath };
+// src/path-measure.ts
+var SAMPLES = 32;
+function at(p, t) {
+  let q = [...p];
+  while (q.length > 2) {
+    const next = [];
+    for (let i = 0; i + 3 < q.length; i += 2) {
+      next.push(q[i] + (q[i + 2] - q[i]) * t, q[i + 1] + (q[i + 3] - q[i + 1]) * t);
+    }
+    q = next;
+  }
+  return [q[0], q[1]];
+}
+function sub(p, t0, t1) {
+  const left = (q, t) => {
+    const out = [q[0], q[1]];
+    let r = [...q];
+    while (r.length > 2) {
+      const next = [];
+      for (let i = 0; i + 3 < r.length; i += 2) {
+        next.push(r[i] + (r[i + 2] - r[i]) * t, r[i + 1] + (r[i + 3] - r[i + 1]) * t);
+      }
+      out.push(next[0], next[1]);
+      r = next;
+    }
+    return out;
+  };
+  const reverse = (q) => {
+    const out = [];
+    for (let i = q.length - 2; i >= 0; i -= 2) out.push(q[i], q[i + 1]);
+    return out;
+  };
+  const head = t1 < 1 ? left(p, t1) : [...p];
+  const s = t1 > 0 ? t0 / t1 : 0;
+  return s > 0 ? reverse(left(reverse(head), 1 - s)) : head;
+}
+var command = (p) => p.length === 4 ? ["L", p[2], p[3]] : p.length === 6 ? ["Q", p[2], p[3], p[4], p[5]] : ["C", p[2], p[3], p[4], p[5], p[6], p[7]];
+var PathMeasure = class {
+  #segs = [];
+  /** Length of the first contour. */
+  length = 0;
+  /**
+   * Measures the first contour of `path`. With `forceClosed` (or a `Z`), a closing line back to
+   * the contour's start is part of it.
+   */
+  constructor(path, forceClosed = false) {
+    let x = 0;
+    let y = 0;
+    let startX = 0;
+    let startY = 0;
+    let total = 0;
+    let started = false;
+    let closed = forceClosed;
+    const add = (p) => {
+      const d = [total];
+      let [px, py] = [p[0], p[1]];
+      for (let i = 1; i <= SAMPLES; i++) {
+        const [qx, qy] = at(p, i / SAMPLES);
+        total += Math.hypot(qx - px, qy - py);
+        d.push(total);
+        px = qx;
+        py = qy;
+      }
+      if (total > d[0]) this.#segs.push({ p, d });
+    };
+    for (const c of path) {
+      if (c[0] === "M") {
+        if (started) break;
+        started = true;
+        [x, y, startX, startY] = [c[1], c[2], c[1], c[2]];
+        continue;
+      }
+      if (c[0] === "Z") {
+        closed = true;
+        break;
+      }
+      const p = [x, y, ...c.slice(1)];
+      add(p);
+      x = p[p.length - 2];
+      y = p[p.length - 1];
+    }
+    if (closed && (x !== startX || y !== startY)) add([x, y, startX, startY]);
+    this.length = total;
+  }
+  /** The segment and its parameter at distance `d` (0 ≤ d ≤ length). */
+  #find(d) {
+    const segs = this.#segs;
+    let i = 0;
+    while (i < segs.length - 1 && segs[i].d[SAMPLES] < d) i++;
+    const seg = segs[i];
+    let k = 1;
+    while (k < SAMPLES && seg.d[k] < d) k++;
+    const d0 = seg.d[k - 1];
+    const d1 = seg.d[k];
+    const t = (k - 1 + (d1 > d0 ? (d - d0) / (d1 - d0) : 0)) / SAMPLES;
+    return [seg, Math.min(1, Math.max(0, t))];
+  }
+  /** Compose `PathMeasure.getSegment(startD, stopD, destination)` (moveTo first). */
+  getSegment(startD, stopD) {
+    const start = Math.max(0, startD);
+    const stop = Math.min(this.length, stopD);
+    if (!(start <= stop) || this.#segs.length === 0) return [];
+    const [seg0, t0] = this.#find(start);
+    const [seg1, t1] = this.#find(stop);
+    const [mx, my] = at(seg0.p, t0);
+    const out = [["M", mx, my]];
+    if (seg0 === seg1) {
+      out.push(t0 === t1 ? ["L", mx, my] : command(sub(seg0.p, t0, t1)));
+      return out;
+    }
+    const segs = this.#segs;
+    out.push(command(sub(seg0.p, t0, 1)));
+    for (let i = segs.indexOf(seg0) + 1; segs[i] !== seg1; i++) out.push(command(segs[i].p));
+    out.push(command(sub(seg1.p, 0, t1)));
+    return out;
+  }
+};
+
+// src/progress-indicator.ts
+var capWidth = (s, width, height) => s.round === false || height > width ? 0 : Math.max(s.stroke / 2, s.trackStroke / 2);
+var LinearWavyPathCache = class {
+  #full = null;
+  /** `updateFullPaths`: the full wave (or line, at amplitude 0), measured. */
+  #fullPath(input) {
+    const { width, height, wavelength, stroke } = input;
+    const wavy = input.amplitude !== 0;
+    const key = [width, height, wavy ? wavelength : 0, stroke].join();
+    if (this.#full?.key === key) return this.#full;
+    const path = [["M", 0, height / 2]];
+    if (!wavy) {
+      path.push(["L", width, height / 2]);
+    } else {
+      const half = wavelength / 2;
+      let anchorX = half;
+      let controlX = half / 2;
+      let controlY = height - stroke;
+      const end = width + wavelength * 2;
+      while (anchorX <= end) {
+        path.push(["Q", controlX, controlY + height / 2, anchorX, height / 2]);
+        anchorX += half;
+        controlX += half;
+        controlY *= -1;
+      }
+    }
+    const measure = new PathMeasure(path, false);
+    const [left, , right] = pathBounds(path);
+    this.#full = { key, measure, scale: measure.length / (right - left + 1e-8) };
+    return this.#full;
+  }
+  /** `updateDrawPaths`: the progress parts and the track for these fractions. */
+  paths(input) {
+    const { width, height, fractions, amplitude, waveOffset, gap } = input;
+    const { measure, scale } = this.#fullPath(input);
+    const cap = capWidth(input, width, height);
+    const halfHeight = height / 2;
+    const wavelength = input.wavelength;
+    const progress = [];
+    const track = [];
+    let adjustedGap = gap;
+    let activeVisible = false;
+    let nextEnd = width - cap;
+    track.push(["M", nextEnd, halfHeight]);
+    for (let i = 0; i + 1 < fractions.length; i += 2) {
+      const start = fractions[i];
+      const end = fractions[i + 1];
+      const barTail = start * width;
+      const barHead = end * width;
+      if (i === 0) {
+        adjustedGap = barHead < cap ? 0 : Math.min(barHead - cap, gap);
+        activeVisible = barHead >= cap;
+      }
+      const head = Math.min(Math.max(barHead, cap), width - cap);
+      const tail = Math.min(Math.max(barTail, cap), width - cap);
+      let part = [];
+      if (Math.abs(end - start) > 0) {
+        const shift = amplitude !== 0 ? waveOffset * wavelength : 0;
+        part = measure.getSegment((tail + shift) * scale, (head + shift) * scale);
+        part = part.map((c) => mapY(c, -Math.max(0, shift), amplitude, halfHeight));
+      }
+      progress.push(part);
+      const spacing = activeVisible ? adjustedGap + cap * 2 : adjustedGap;
+      if (nextEnd > head + spacing) track.push(["L", Math.max(cap, head + spacing), halfHeight]);
+      if (barHead > barTail) {
+        nextEnd = Math.max(cap, tail - spacing);
+        track.push(["M", nextEnd, halfHeight]);
+      }
+    }
+    if (nextEnd > cap) track.push(["L", cap, halfHeight]);
+    return { track, progress, capWidth: cap };
+  }
+};
+function mapY(c, dx, amplitude, halfHeight) {
+  const y = (v) => amplitude * v + (1 - amplitude) * halfHeight;
+  switch (c[0]) {
+    case "M":
+    case "L":
+      return [c[0], c[1] + dx, y(c[2])];
+    case "Q":
+      return ["Q", c[1] + dx, y(c[2]), c[3] + dx, y(c[4])];
+    case "C":
+      return ["C", c[1] + dx, y(c[2]), c[3] + dx, y(c[4]), c[5] + dx, y(c[6])];
+    case "Z":
+      return c;
+  }
+}
+function linearWavyStopIndicator(progressEnd, width, maxSize, insets, trackStroke) {
+  let size = Math.min(trackStroke, maxSize);
+  const offset = size === trackStroke ? 0 : trackStroke / 4;
+  let x = width - size - offset;
+  const progressX = width * progressEnd + insets;
+  if (x <= progressX) {
+    size = Math.max(0, size - (progressX - x));
+    x = progressX;
+  }
+  return size > 0 ? { x, size } : null;
+}
+var MIN_VERTICES = 5;
+var circularWavyVertexCount = (size, wavelength, stroke) => Math.max(MIN_VERTICES, Math.round(2 * Math.PI * (size / 2 - stroke / 2) / wavelength));
+var CircularWavyPathCache = class {
+  #shapesKey = "";
+  #vertices = -1;
+  #trackPolygon = null;
+  #activePolygon = null;
+  #morph = null;
+  #full = null;
+  /** `CircularShapes.update`. */
+  #update(size, wavelength, stroke, requiresMorph) {
+    const key = [size, wavelength].join();
+    if (key === this.#shapesKey) {
+      if (requiresMorph && this.#morph === null)
+        this.#morph = new Morph(this.#trackPolygon, this.#activePolygon);
+      return;
+    }
+    const n = circularWavyVertexCount(size, wavelength, stroke);
+    if (n !== this.#vertices) {
+      this.#trackPolygon = circle({ numVertices: n }).normalized();
+      this.#activePolygon = star(n, {
+        innerRadius: 0.75,
+        rounding: new CornerRounding(0.35, 0.4),
+        innerRounding: new CornerRounding(0.5)
+      }).normalized();
+      this.#morph = requiresMorph ? new Morph(this.#trackPolygon, this.#activePolygon) : null;
+      this.#full = null;
+    }
+    this.#shapesKey = key;
+    this.#vertices = n;
+  }
+  /** The paths for `input`; `requiresMorph` as the Compose node passes it. */
+  paths(input, requiresMorph) {
+    const { size, wavelength, stroke, motion, start, end, gap } = input;
+    this.#update(size, wavelength, stroke, requiresMorph);
+    const full = this.#fullPaths(input);
+    const cap = capWidth(input, size, size);
+    const pStart = start * full.length;
+    const pStop = end * full.length;
+    const trackGap = Math.min(pStop, gap);
+    const insets = Math.min(pStop, cap);
+    const spacing = insets * 2 + trackGap;
+    let progress;
+    if (motion) {
+      const offset = Math.min(Math.max(input.waveOffset, 0), 1);
+      const shift = offset * full.length;
+      progress = full.measure.getSegment(pStart + shift, pStop + shift);
+      const angle2 = offset * 360 % 360;
+      if (angle2 !== 0) {
+        const [cx, cy] = full.center;
+        progress = translatePath(
+          transformPath(translatePath(progress, -cx, -cy), new Matrix().rotateZ(-angle2)),
+          cx,
+          cy
+        );
+      }
+    } else {
+      progress = full.measure.getSegment(pStart, pStop);
+    }
+    const trackLength = full.track.length;
+    const track = trackLength > 0 ? full.track.getSegment(end * trackLength + spacing, trackLength - spacing) : [];
+    return { track, progress, vertexCount: this.#vertices };
+  }
+  /** `updateFullPaths` + `getProgressPath` / `getTrackPath` + `processPath`. */
+  #fullPaths(input) {
+    const { size, stroke, amplitude, motion } = input;
+    const key = [size, stroke, amplitude, motion, this.#vertices, this.#morph !== null].join();
+    if (this.#full?.key === key) return this.#full;
+    const pivot = { rotationPivotX: 0.5, rotationPivotY: 0.5 };
+    const raw = this.#morph !== null ? morphToPath(this.#morph, amplitude, { startAngle: 270, repeatPath: motion, ...pivot }) : polygonToPath(amplitude === 1 ? this.#activePolygon : this.#trackPolygon, {
+      startAngle: 270,
+      repeatPath: motion
+    });
+    const progress = processPath2(raw, size, stroke);
+    const measure = new PathMeasure(progress, true);
+    const track = new PathMeasure(
+      processPath2(polygonToPath(this.#trackPolygon, { startAngle: 270 }), size, stroke),
+      true
+    );
+    const [left, top, right, bottom] = pathBounds(progress);
+    this.#full = {
+      key,
+      progress,
+      measure,
+      length: motion ? measure.length / 2 : measure.length,
+      center: [(left + right) / 2, (top + bottom) / 2],
+      track
+    };
+    return this.#full;
+  }
+};
+function processPath2(path, size, stroke) {
+  const scaled = transformPath(path, new Matrix().scale(size - stroke, size - stroke));
+  const [left, top, right, bottom] = pathBounds(scaled);
+  return translatePath(scaled, size / 2 - (left + right) / 2, size / 2 - (top + bottom) / 2);
+}
+
+export { CircularWavyPathCache, Corner, CornerRounding, Cubic, Edge, Feature, LinearWavyPathCache, LoadingIndicatorShapes, Morph, MutableCubic, PathMeasure, RoundedPolygon, calculateScaleFactor, circle, circularWavyVertexCount, determinateFrame, determinateIndicatorPolygons, indeterminateIndicatorPolygons, linearWavyStopIndicator, loadingIndicatorShapes, materialShape, materialShapeNames, morphSequence, morphToPath, pathBounds, pill, pillStar, polygonToPath, processPath, rectangle, star, toShapeOutline, toSvgPathData, translatePath };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map