@sarmal/core 0.18.0 → 0.19.0

package/dist/index.d.cts

@@ -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;

package/dist/index.d.ts

@@ -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;

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) {