@sarmal/core 0.18.0 → 0.20.0

package/dist/index.d.cts

@@ -4,11 +4,11 @@ import {
   S as SarmalInstance,
   C as CurveDef,
   R as RendererOptions,
+  P as Point,
   a as SarmalOptions,
 } from "./types-frtEoAq6.cjs";
 export {
   J as JumpOptions,
-  P as Point,
   b as RuntimeRenderOptions,
   c as SeekOptions,
   T as TrailColor,
@@ -31,8 +31,8 @@ import "./curves/star4.cjs";
 import "./curves/star7.cjs";
 
 interface SVGRendererOptions extends BaseRendererOptions {
-  /** Container element that will contain the SVG */
-  container: Element;
+  /** SVG element the renderer draws into directly */
+  container: SVGSVGElement;
   engine: Engine;
   /** @default 'Loading' */
   ariaLabel?: string;
@@ -47,22 +47,25 @@ interface SVGSarmalOptions extends Omit<SVGRendererOptions, "container" | "engin
  */
 declare function createSVGRenderer(options: SVGRendererOptions): SarmalInstance;
 /**
- * Creates a sarmal animation inside a container element using an SVG renderer
- * The SVG is appended to the container and animated via requestAnimationFrame
+ * Creates a sarmal animation directly inside an `<svg>` element using an SVG renderer.
+ * The passed `<svg>` element is set to `viewBox="0 0 100 100"` and animated via requestAnimationFrame
  *
  * @example
  * ```ts
  * import { createSarmalSVG, epitrochoid7 } from '@sarmal/core'
- * const sarmal = createSarmalSVG(document.getElementById('spinner'), epitrochoid7)
+ *
+ * // <svg id="spinner"></svg> in your HTML
+ * const svg = document.getElementById('spinner')
+ * const sarmal = createSarmalSVG(svg, epitrochoid7)
  *
  * // To control manually, use autoStart: false
- * const controlled = createSarmalSVG(container, rose5, { autoStart: false })
+ * const controlled = createSarmalSVG(svg, rose5, { autoStart: false })
  * controlled.play()  // Start when ready
  * controlled.pause() // Pause later
  * ```
  */
 declare function createSarmalSVG(
-  container: Element,
+  container: SVGSVGElement,
   curveDef: CurveDef,
   options?: SVGSarmalOptions,
 ): SarmalInstance;
@@ -89,6 +92,45 @@ declare function createEngine(curveDef: CurveDef, trailLength?: number): Engine;
  */
 declare function createRenderer(options: RendererOptions): SarmalInstance;
 
+/**
+ * Evaluates a closed Catmull-Rom spline through every point in `points`
+ *
+ * The spline treats `points` as a **closed loop**
+ * The last point wraps back to the first,
+ *  and each segment uses a phantom predecessor / successor so the
+ *    curve passes exactly through every control point.
+ *
+ * @param points  At least 1 point.  An empty array yields `(0, 0)`.  A single point returns that point for every `t`
+ * @param t       Parametric position along the closed loop.  Wraps into `[0, 2π)` automatically, so values outside that range are remapped rather than rejected
+ * @returns       The `(x, y)` position on the spline at time `t`
+ */
+declare function evaluateCatmullRom(points: Array<[number, number]>, t: number): Point;
+/**
+ * The returned curve definition produces a closed Catmull-Rom spline that
+ *  passes through every point in order, looping back from the last point to the first.
+ *
+ * @param points  Array of control points in **normalized `[−1, 1]` space**,
+ *                  matching the playground's draw-mode coordinate system.
+ *                ! Must contain at least 3 points.
+ * @returns       A `CurveDef` with `period: 2π` and the spline evaluator as its `fn`.
+ *                `name` is set to `"custom"`.
+ * @throws        If `points` has fewer than 3 entries.
+ *
+ * @example
+ * ```ts
+ * import { createSarmal, drawCurve } from '@sarmal/core'
+ *
+ * const curve = drawCurve([
+ *   [-0.5,  0.3],
+ *   [ 0.2, -0.8],
+ *   [ 0.7,  0.4],
+ * ])
+ *
+ * createSarmal(canvas, curve)
+ * ```
+ */
+declare function drawCurve(points: Array<[number, number]>): CurveDef;
+
 /**
  * Creates a sarmal animation on a canvas element
  *
@@ -113,6 +155,7 @@ export {
   BaseRendererOptions,
   CurveDef,
   Engine,
+  Point,
   RendererOptions,
   type SVGRendererOptions,
   type SVGSarmalOptions,
@@ -124,5 +167,7 @@ export {
   createSVGRenderer,
   createSarmal,
   createSarmalSVG,
+  drawCurve,
+  evaluateCatmullRom,
   palettes,
 };

package/dist/index.d.ts

@@ -4,11 +4,11 @@ import {
   S as SarmalInstance,
   C as CurveDef,
   R as RendererOptions,
+  P as Point,
   a as SarmalOptions,
 } from "./types-frtEoAq6.js";
 export {
   J as JumpOptions,
-  P as Point,
   b as RuntimeRenderOptions,
   c as SeekOptions,
   T as TrailColor,
@@ -31,8 +31,8 @@ import "./curves/star4.js";
 import "./curves/star7.js";
 
 interface SVGRendererOptions extends BaseRendererOptions {
-  /** Container element that will contain the SVG */
-  container: Element;
+  /** SVG element the renderer draws into directly */
+  container: SVGSVGElement;
   engine: Engine;
   /** @default 'Loading' */
   ariaLabel?: string;
@@ -47,22 +47,25 @@ interface SVGSarmalOptions extends Omit<SVGRendererOptions, "container" | "engin
  */
 declare function createSVGRenderer(options: SVGRendererOptions): SarmalInstance;
 /**
- * Creates a sarmal animation inside a container element using an SVG renderer
- * The SVG is appended to the container and animated via requestAnimationFrame
+ * Creates a sarmal animation directly inside an `<svg>` element using an SVG renderer.
+ * The passed `<svg>` element is set to `viewBox="0 0 100 100"` and animated via requestAnimationFrame
  *
  * @example
  * ```ts
  * import { createSarmalSVG, epitrochoid7 } from '@sarmal/core'
- * const sarmal = createSarmalSVG(document.getElementById('spinner'), epitrochoid7)
+ *
+ * // <svg id="spinner"></svg> in your HTML
+ * const svg = document.getElementById('spinner')
+ * const sarmal = createSarmalSVG(svg, epitrochoid7)
  *
  * // To control manually, use autoStart: false
- * const controlled = createSarmalSVG(container, rose5, { autoStart: false })
+ * const controlled = createSarmalSVG(svg, rose5, { autoStart: false })
  * controlled.play()  // Start when ready
  * controlled.pause() // Pause later
  * ```
  */
 declare function createSarmalSVG(
-  container: Element,
+  container: SVGSVGElement,
   curveDef: CurveDef,
   options?: SVGSarmalOptions,
 ): SarmalInstance;
@@ -89,6 +92,45 @@ declare function createEngine(curveDef: CurveDef, trailLength?: number): Engine;
  */
 declare function createRenderer(options: RendererOptions): SarmalInstance;
 
+/**
+ * Evaluates a closed Catmull-Rom spline through every point in `points`
+ *
+ * The spline treats `points` as a **closed loop**
+ * The last point wraps back to the first,
+ *  and each segment uses a phantom predecessor / successor so the
+ *    curve passes exactly through every control point.
+ *
+ * @param points  At least 1 point.  An empty array yields `(0, 0)`.  A single point returns that point for every `t`
+ * @param t       Parametric position along the closed loop.  Wraps into `[0, 2π)` automatically, so values outside that range are remapped rather than rejected
+ * @returns       The `(x, y)` position on the spline at time `t`
+ */
+declare function evaluateCatmullRom(points: Array<[number, number]>, t: number): Point;
+/**
+ * The returned curve definition produces a closed Catmull-Rom spline that
+ *  passes through every point in order, looping back from the last point to the first.
+ *
+ * @param points  Array of control points in **normalized `[−1, 1]` space**,
+ *                  matching the playground's draw-mode coordinate system.
+ *                ! Must contain at least 3 points.
+ * @returns       A `CurveDef` with `period: 2π` and the spline evaluator as its `fn`.
+ *                `name` is set to `"custom"`.
+ * @throws        If `points` has fewer than 3 entries.
+ *
+ * @example
+ * ```ts
+ * import { createSarmal, drawCurve } from '@sarmal/core'
+ *
+ * const curve = drawCurve([
+ *   [-0.5,  0.3],
+ *   [ 0.2, -0.8],
+ *   [ 0.7,  0.4],
+ * ])
+ *
+ * createSarmal(canvas, curve)
+ * ```
+ */
+declare function drawCurve(points: Array<[number, number]>): CurveDef;
+
 /**
  * Creates a sarmal animation on a canvas element
  *
@@ -113,6 +155,7 @@ export {
   BaseRendererOptions,
   CurveDef,
   Engine,
+  Point,
   RendererOptions,
   type SVGRendererOptions,
   type SVGSarmalOptions,
@@ -124,5 +167,7 @@ export {
   createSVGRenderer,
   createSarmal,
   createSarmalSVG,
+  drawCurve,
+  evaluateCatmullRom,
   palettes,
 };

package/dist/index.js

@@ -298,12 +298,20 @@ function computeNormal(trail, i) {
   const tangent = computeTangent(trail, i);
   return { x: -tangent.y, y: tangent.x };
 }
-function computeTrailQuad(trail, i, trailCount, toX, toY) {
+function computeTrailQuad(
+  trail,
+  i,
+  trailCount,
+  toX,
+  toY,
+  minWidth = TRAIL_MIN_WIDTH,
+  maxWidth = TRAIL_MAX_WIDTH,
+) {
   const progress = i / (trailCount - 1);
   const nextProgress = (i + 1) / (trailCount - 1);
   const opacity = Math.pow(progress, TRAIL_FADE_CURVE) * TRAIL_MAX_OPACITY;
-  const w0 = (TRAIL_MIN_WIDTH + progress * (TRAIL_MAX_WIDTH - TRAIL_MIN_WIDTH)) / 2;
-  const w1 = (TRAIL_MIN_WIDTH + nextProgress * (TRAIL_MAX_WIDTH - TRAIL_MIN_WIDTH)) / 2;
+  const w0 = (minWidth + progress * (maxWidth - minWidth)) / 2;
+  const w1 = (minWidth + nextProgress * (maxWidth - minWidth)) / 2;
   const curr = trail[i];
   const next = trail[i + 1];
   const n0 = computeNormal(trail, i);
@@ -867,62 +875,61 @@ function createSVGRenderer(options) {
   let trailPalette = resolveTrailPalette(trailColor);
   const ariaLabel = options.ariaLabel ?? "Loading";
   warnIfTrailColorMismatch(trailColor, trailStyle);
-  const htmlContainer = container;
-  const width = htmlContainer.offsetWidth || 200;
-  const height = htmlContainer.offsetHeight || 200;
-  const headRadius = options.headRadius ?? getHeadDotRadius(width, height);
-  const svg = el("svg");
-  svg.setAttribute("width", String(width));
-  svg.setAttribute("height", String(height));
-  svg.setAttribute("viewBox", `0 0 ${width} ${height}`);
-  svg.setAttribute("role", "img");
-  svg.setAttribute("aria-label", ariaLabel);
+  const viewSize = 100;
+  const headRadius = options.headRadius ?? 1.5;
+  const svgTrailMinWidth = 0.25;
+  const svgTrailMaxWidth = 1.25;
+  const svgSkeletonStrokeWidth = "0.75";
+  container.setAttribute("viewBox", `0 0 ${viewSize} ${viewSize}`);
+  container.setAttribute("role", "img");
+  container.setAttribute("aria-label", ariaLabel);
+  const group = el("g");
   const titleEl = el("title");
   titleEl.textContent = ariaLabel;
-  svg.appendChild(titleEl);
+  group.appendChild(titleEl);
   const skeletonPath = el("path");
   skeletonPath.setAttribute("data-sarmal-role", "skeleton");
   skeletonPath.setAttribute("fill", "none");
   skeletonPath.setAttribute("stroke", skeletonColor);
   skeletonPath.setAttribute("stroke-opacity", String(DEFAULT_SKELETON_OPACITY));
-  skeletonPath.setAttribute("stroke-width", "1.5");
+  skeletonPath.setAttribute("stroke-width", svgSkeletonStrokeWidth);
   if (skeletonColor === "transparent") {
     skeletonPath.setAttribute("visibility", "hidden");
   }
-  svg.appendChild(skeletonPath);
+  group.appendChild(skeletonPath);
   const skeletonPathA = el("path");
   skeletonPathA.setAttribute("fill", "none");
   skeletonPathA.setAttribute("stroke", skeletonColor);
-  skeletonPathA.setAttribute("stroke-width", "1.5");
+  skeletonPathA.setAttribute("stroke-width", svgSkeletonStrokeWidth);
   skeletonPathA.setAttribute("visibility", "hidden");
-  svg.appendChild(skeletonPathA);
+  group.appendChild(skeletonPathA);
   const skeletonPathB = el("path");
   skeletonPathB.setAttribute("fill", "none");
   skeletonPathB.setAttribute("stroke", skeletonColor);
-  skeletonPathB.setAttribute("stroke-width", "1.5");
+  skeletonPathB.setAttribute("stroke-width", svgSkeletonStrokeWidth);
   skeletonPathB.setAttribute("visibility", "hidden");
-  svg.appendChild(skeletonPathB);
+  group.appendChild(skeletonPathB);
   let morphPathABuilt = "";
   let morphPathBBuilt = "";
   const trailPaths = [];
   for (let i = 0; i < poolSize; i++) {
     const path = el("path");
     path.setAttribute("fill", trailSolid);
-    svg.appendChild(path);
+    group.appendChild(path);
     trailPaths.push(path);
   }
   const headCircle = el("circle");
   headCircle.setAttribute("data-sarmal-role", "head");
   headCircle.setAttribute("fill", headColor);
   headCircle.setAttribute("r", String(headRadius));
-  svg.appendChild(headCircle);
-  container.appendChild(svg);
+  group.appendChild(headCircle);
+  container.appendChild(group);
   let gradientAnimTime = 0;
   let scale = 1;
   let offsetX = 0;
   let offsetY = 0;
   function applyBoundaries(skeleton2) {
-    const b = computeBoundaries(skeleton2, width, height);
+    const b = computeBoundaries(skeleton2, viewSize, viewSize);
     if (b) {
       scale = b.scale;
       offsetX = b.offsetX;
@@ -958,6 +965,8 @@ function createSVGRenderer(options) {
         trailCount,
         px,
         py,
+        svgTrailMinWidth,
+        svgTrailMaxWidth,
       );
       const d = `M${l0x.toFixed(2)} ${l0y.toFixed(2)} L${l1x.toFixed(2)} ${l1y.toFixed(2)} L${r1x.toFixed(2)} ${r1y.toFixed(2)} L${r0x.toFixed(2)} ${r0y.toFixed(2)} Z`;
       trailPaths[i].setAttribute("d", d);
@@ -1080,7 +1089,7 @@ function createSVGRenderer(options) {
         morphResolve = null;
         morphReject = null;
       }
-      svg.remove();
+      group.remove();
     },
     ...enginePassthroughs(engine),
     morphTo(target, options2) {
@@ -1433,6 +1442,55 @@ var curves = {
   lame,
 };
 
+// src/catmull-rom.ts
+var PERIOD = 2 * Math.PI;
+function catmullRom1D(p0, p1, p2, p3, u) {
+  const u2 = u * u;
+  const u3 = u2 * u;
+  return (
+    0.5 *
+    (2 * p1 +
+      (-p0 + p2) * u +
+      (2 * p0 - 5 * p1 + 4 * p2 - p3) * u2 +
+      (-p0 + 3 * p1 - 3 * p2 + p3) * u3)
+  );
+}
+function evaluateCatmullRom(points, t) {
+  const N = points.length;
+  if (N === 0) {
+    return { x: 0, y: 0 };
+  }
+  if (N === 1) {
+    return { x: points[0][0], y: points[0][1] };
+  }
+  t = ((t % PERIOD) + PERIOD) % PERIOD;
+  const segmentSize = PERIOD / N;
+  let i = Math.floor(t / segmentSize);
+  if (i >= N) {
+    i = N - 1;
+  }
+  let u = (t - i * segmentSize) / segmentSize;
+  u = Math.max(0, Math.min(1, u));
+  const p0 = points[(i - 1 + N) % N];
+  const p1 = points[i];
+  const p2 = points[(i + 1) % N];
+  const p3 = points[(i + 2) % N];
+  return {
+    x: catmullRom1D(p0[0], p1[0], p2[0], p3[0], u),
+    y: catmullRom1D(p0[1], p1[1], p2[1], p3[1], u),
+  };
+}
+function drawCurve(points) {
+  if (points.length < 3) {
+    throw new Error(`drawCurve requires at least 3 points, received ${points.length}.`);
+  }
+  return {
+    name: "custom",
+    fn: (t) => evaluateCatmullRom(points, t),
+    period: PERIOD,
+  };
+}
+
 // src/index.ts
 function createSarmal(canvas, curveDef, options) {
   const { trailLength, ...rendererOpts } = options ?? {};
@@ -1450,8 +1508,10 @@ export {
   createSarmalSVG,
   curves,
   deltoid,
+  drawCurve,
   epicycloid3,
   epitrochoid7,
+  evaluateCatmullRom,
   lame,
   lissajous32,
   lissajous43,