@supermousejs/utils 2.3.0 → 2.4.0

package/src/plugin.ts

@@ -1,147 +1,211 @@
-import type { Supermouse, SupermousePlugin } from "@supermousejs/core";
-import { normalize } from "./options";
-import { setStyle } from "./dom";
+import type { SupermouseInstance, SupermousePlugin } from "@supermousejs/core";
 
+/** Options that can be passed to any plugin factory. */
 export interface BasePluginOptions {
+  /** Overrides the plugin's internal name. */
   name?: string;
+  /** Whether the plugin starts enabled. Defaults to `true`. */
   isEnabled?: boolean;
 }
 
-interface LogicConfig {
+interface CoreConfig {
+  /** Unique identifier. Used by `getPlugin()`, `enablePlugin()`, etc. */
   name: string;
+  /** Execution order in the frame loop. Lower values are executed earlier */
   priority?: number;
-  install?: (app: Supermouse) => void;
-  update?: (app: Supermouse, deltaTime: number) => void;
-  destroy?: (app: Supermouse) => void;
-  onEnable?: (app: Supermouse) => void;
-  onDisable?: (app: Supermouse) => void;
-  // Explicitly disallow 'create' here to ensure type separation
-  create?: never;
+  /** Whether the plugin starts enabled. Defaults to `true`. */
+  isEnabled?: boolean;
+  /** Called once when the plugin is registered via `app.use()`. */
+  install?(app: SupermouseInstance): void;
 }
 
-// --- MODE B: VISUAL PLUGIN CONFIG ---
-interface VisualConfig<E extends HTMLElement, O extends object> {
-  name: string;
-  /** Automatically register this attribute selector */
-  selector?: string;
-  /** Create and return the DOM Element */
-  create: (app: Supermouse) => E;
-  /** Map option keys to CSS properties */
-  styles?: Partial<Record<keyof O, keyof CSSStyleDeclaration>>;
-  /** Update loop with access to the element */
-  update?: (app: Supermouse, element: E, deltaTime: number) => void;
-  onEnable?: (app: Supermouse, element: E) => void;
-  onDisable?: (app: Supermouse, element: E) => void;
-  cleanup?: (element: E) => void;
-  destroy?: never; // Visual plugins use cleanup(), not destroy()
+/**
+ * Declarative config for a logic plugin.
+ *
+ * Logic plugins modify cursor intent (e.g. magnetism, snapping, gravity).
+ */
+export interface LogicConfig extends CoreConfig {
+  /**
+   * Called every frame while the plugin is enabled.
+   * @param app       The Supermouse instance.
+   * @param deltaTime Elapsed time since last frame, in milliseconds.
+   */
+  update?(app: SupermouseInstance, deltaTime: number): void;
+  /** Called when the plugin is removed or the app is destroyed. */
+  destroy?(app: SupermouseInstance): void;
+  /** Called when `app.enablePlugin(name)` is invoked. */
+  onEnable?(app: SupermouseInstance): void;
+  /** Called when `app.disablePlugin(name)` is invoked. */
+  onDisable?(app: SupermouseInstance): void;
+  /**
+   * Called before the plugin is disabled. Can return a Promise to delay
+   * hiding until an exit animation finishes. This is the declarative
+   * equivalent of `SupermousePlugin.onBeforeDisable`.
+   */
+  beforeDisable?(app: SupermouseInstance): void | Promise<void>;
 }
 
-// Helper Type Guard to safely distinguish VisualConfig at runtime
-function isVisualConfig<E extends HTMLElement, O extends object>(
-  config: LogicConfig | VisualConfig<E, O>
-): config is VisualConfig<E, O> {
-  return "create" in config && typeof (config as any).create === "function";
-}
+/**
+ * Declarative config for a visual plugin.
+ *
+ * @typeParam E - The specific element subtype returned by `create`.
+ *   Can be an `HTMLElement` (e.g. `HTMLDivElement`) or an `SVGElement`
+ *   (e.g. `SVGSVGElement`).
+ */
+export interface VisualConfig<
+  E extends HTMLElement | SVGElement = HTMLElement | SVGElement
+> extends CoreConfig {
+  /**
+   * Factory that creates the plugin's root DOM element.
+   * Called once during `install()`. The returned element is automatically
+   * appended to the **stage** (not `app.container`).
+   */
+  create: (app: SupermouseInstance) => E;
+
+  /**
+   * Called every frame while the plugin is enabled.
+   * Use `css()` from `@supermousejs/utils` for style writes,
+   * and `setTransform()` for positioning.
+   */
+  update?(app: SupermouseInstance, element: E, deltaTime: number): void;
+
+  /** Called when the plugin is enabled. The element is already visible. */
+  onEnable?(app: SupermouseInstance, element: E): void;
+  /**
+   * Called when the plugin is disabled.
+   * The element is still in the DOM when this runs, so you can start
+   * CSS transitions. If `beforeDisable` is defined and returns a Promise,
+   * the core will wait for it to resolve before hiding the element.
+   */
+  onDisable?(app: SupermouseInstance, element: E): void;
+
+  /**
+   * Called during `destroy()`, before the element is removed from the DOM.
+   * Use this to tear down external listeners or GSAP timelines.
+   */
+  cleanup?(app: SupermouseInstance, element: E): void;
+  /** General teardown hook, called after cleanup and element removal. */
+  destroy?(app: SupermouseInstance): void;
+
+  /**
+   * Auto-registers this selector as a hover target on install.
+   * Equivalent to `app.registerHoverTarget(selector)` inside `install()`.
+   */
+  selector?: string;
 
-// --- THE OVERLOADS ---
+  /**
+   * Called before the plugin is disabled. Can return a Promise to delay
+   * hiding until an exit animation finishes.
+   * Receives the element as the second argument.
+   */
+  beforeDisable?(app: SupermouseInstance, element: E): void | Promise<void>;
+}
 
-// Overload 1: Visual Plugin (Infer Element E and Options O)
-export function definePlugin<E extends HTMLElement, O extends BasePluginOptions>(
-  config: VisualConfig<E, O>,
-  userOptions?: O
-): SupermousePlugin;
+function isVisual<E extends HTMLElement | SVGElement>(
+  config: LogicConfig | VisualConfig<E>
+): config is VisualConfig<E> {
+  return typeof (config as VisualConfig).create === "function";
+}
 
-// Overload 2: Logic Plugin
+/**
+ * Creates a visual plugin with automatic DOM mounting and lifecycle management.
+ *
+ * @param config        Visual plugin definition.
+ * @param userOptions   Optional overrides for `name` and `isEnabled`.
+ * @returns A `SupermousePlugin` whose `element` property is typed as `E`.
+ */
+export function definePlugin<E extends HTMLElement | SVGElement>(
+  config: VisualConfig<E>,
+  userOptions?: BasePluginOptions
+): SupermousePlugin & { element?: E };
+
+/**
+ * Creates a logic plugin that is passed through directly.
+ *
+ * @param config        Logic plugin definition.
+ * @param userOptions   Optional overrides for `name` and `isEnabled`.
+ * @returns A `SupermousePlugin`.
+ */
 export function definePlugin(
   config: LogicConfig,
   userOptions?: BasePluginOptions
 ): SupermousePlugin;
 
-// --- THE IMPLEMENTATION ---
-
 export function definePlugin(
-  config: LogicConfig | VisualConfig<HTMLElement, any>,
-  userOptions: any = {}
+  config: LogicConfig | VisualConfig,
+  userOptions: BasePluginOptions = {}
 ): SupermousePlugin {
-  const name = userOptions.name || config.name;
-  const initialEnabled = userOptions.isEnabled ?? true;
-
-  // MODE A: VISUAL
-  if (isVisualConfig(config)) {
-    let element: HTMLElement;
-
-    // PRE-COMPILE STYLE SETTERS
-    const styleSetters: ((app: Supermouse, el: HTMLElement) => void)[] = [];
-
-    if (config.styles) {
-      for (const [optKey, cssProp] of Object.entries(config.styles)) {
-        const getter = normalize(userOptions[optKey], undefined);
-        const prop = cssProp as any;
-
-        styleSetters.push((app, el) => {
-          const val = getter(app.state);
-          if (val !== undefined) {
-            setStyle(el, prop, val);
-          }
-        });
-      }
-    }
+  const resolvedName = userOptions.name ?? config.name;
+  const resolvedEnabled = userOptions.isEnabled ?? true;
 
-    return {
-      name,
-      isEnabled: initialEnabled,
-
-      install(app) {
-        // 1. Create & Append
-        element = config.create(app);
-        if (config.selector) app.registerHoverTarget(config.selector);
-
-        // 2. Handle Initial State
-        if (this.isEnabled === false) {
-          element.style.opacity = "0";
-        }
-        app.container.appendChild(element);
-      },
-
-      update(app, dt) {
-        if (!element) return;
-
-        // 3. Run Pre-compiled Style Setters
-        for (let i = 0; i < styleSetters.length; i++) {
-          styleSetters[i](app, element);
-        }
-
-        // 4. Run Custom Update
-        config.update?.(app, element, dt);
-      },
-
-      onDisable(app) {
-        if (!element) return;
-        // Use setStyle to ensure cache remains in sync (0)
-        setStyle(element, "opacity", 0);
-        config.onDisable?.(app, element);
-      },
-
-      onEnable(app) {
-        if (!element) return;
-        setStyle(element, "opacity", 1);
-        config.onEnable?.(app, element);
-      },
-
-      destroy() {
-        if (!element) return;
-        config.cleanup?.(element);
-        element.remove();
-      }
-    };
-  }
-
-  // MODE B: LOGIC (Standard Pass-through)
-  else {
+  if (!isVisual(config)) {
     return {
       ...config,
-      name,
-      isEnabled: initialEnabled
+      name: resolvedName,
+      isEnabled: resolvedEnabled
     };
   }
+
+  let root: HTMLElement | SVGElement | null = null;
+  let isMounted = false;
+
+  const beforeDisable = (app: SupermouseInstance): void | Promise<void> => {
+    if (!root) return;
+    return config.beforeDisable?.(app, root);
+  };
+
+  return {
+    name: resolvedName,
+    isEnabled: resolvedEnabled,
+    priority: config.priority,
+
+    install(app) {
+      root = config.create(app);
+      if (!(root instanceof HTMLElement) && !(root instanceof SVGElement)) {
+        console.warn(
+          `[supermouse] Plugin "${resolvedName}" create() did not return an HTMLElement or SVGElement.`
+        );
+        return;
+      }
+      this.element = app.stage.appendChild(root);
+      isMounted = true;
+      if (config.selector) {
+        app.registerHoverTarget(config.selector);
+      }
+      if (!resolvedEnabled) {
+        root.style.display = "none";
+      }
+      config.install?.(app);
+    },
+
+    update(app, dt) {
+      if (!root || !isMounted) return;
+      config.update?.(app, root, dt);
+    },
+
+    onEnable(app) {
+      if (!root) return;
+      root.style.display = "";
+      config.onEnable?.(app, root);
+    },
+
+    async onBeforeDisable(app) {
+      await beforeDisable(app);
+    },
+
+    onDisable(app) {
+      if (!root) return;
+      config.onDisable?.(app, root);
+    },
+
+    destroy(app) {
+      if (root) {
+        config.cleanup?.(app, root);
+        root.remove();
+        root = null;
+        isMounted = false;
+      }
+      config.destroy?.(app);
+    }
+  };
 }

package/src/svg.ts

@@ -0,0 +1,119 @@
+type SVGAttrs = Record<string, string | number | boolean>;
+
+/** Create any SVG element by tag name with attributes. */
+export function createSVGElement<K extends keyof SVGElementTagNameMap>(
+  tag: K,
+  attrs: SVGAttrs = {}
+): SVGElementTagNameMap[K] {
+  const el = document.createElementNS("http://www.w3.org/2000/svg", tag);
+  for (const [key, value] of Object.entries(attrs)) {
+    el.setAttribute(key, String(value));
+  }
+  return el;
+}
+
+/** Set multiple attributes on an SVG element. */
+export function setSVGAttrs(el: SVGElement, attrs: SVGAttrs): void {
+  for (const [key, value] of Object.entries(attrs)) {
+    el.setAttribute(key, String(value));
+  }
+}
+
+/** Create a `<g>` group. */
+export function group(attrs: SVGAttrs = {}): SVGGElement {
+  return createSVGElement("g", attrs);
+}
+
+/** Create a `<circle>`. */
+export function circle(attrs: SVGAttrs = {}): SVGCircleElement {
+  return createSVGElement("circle", attrs);
+}
+
+/** Create a `<rect>`. */
+export function rect(attrs: SVGAttrs = {}): SVGRectElement {
+  return createSVGElement("rect", attrs);
+}
+
+/** Create a `<path>` with optional `d` attribute. */
+export function path(d?: string, attrs: SVGAttrs = {}): SVGPathElement {
+  const el = createSVGElement("path", attrs);
+  if (d !== undefined) el.setAttribute("d", d);
+  return el;
+}
+
+/** Create a `<text>` element. */
+export function text(attrs: SVGAttrs = {}, content?: string): SVGTextElement {
+  const el = createSVGElement("text", attrs);
+  if (content !== undefined) el.textContent = content;
+  return el;
+}
+
+/** Create a `<textPath>` with proper `href` and `xlink:href`. */
+export function textPath(href: string, attrs: SVGAttrs = {}): SVGTextPathElement {
+  const el = createSVGElement("textPath", { ...attrs, href });
+  el.setAttributeNS("http://www.w3.org/1999/xlink", "xlink:href", href);
+  return el;
+}
+
+/** Create a `<filter>` with region attributes and children. */
+export function filter(
+  id: string,
+  attrs: SVGAttrs = {},
+  children: SVGElement[] = []
+): SVGFilterElement {
+  const el = createSVGElement("filter", { id, ...attrs });
+  children.forEach((child) => el.appendChild(child));
+  return el;
+}
+
+/** Create a `<feGaussianBlur>` primitive. */
+export function gaussianBlur(
+  stdDeviation: string | number = 0,
+  attrs: SVGAttrs = {}
+): SVGFEGaussianBlurElement {
+  return createSVGElement("feGaussianBlur", {
+    stdDeviation: String(stdDeviation),
+    ...attrs
+  });
+}
+
+/** Create a `<feTurbulence>` primitive. */
+export function turbulence(
+  baseFrequency: string | number = 0.1,
+  attrs: SVGAttrs = {}
+): SVGFETurbulenceElement {
+  return createSVGElement("feTurbulence", {
+    baseFrequency: String(baseFrequency),
+    ...attrs
+  });
+}
+
+/** Create a `<feMergeNode>` primitive. */
+export function mergeNode(inAttr?: string): SVGFEMergeNodeElement {
+  return createSVGElement("feMergeNode", inAttr ? { in: inAttr } : {});
+}
+
+/** Create a `<feMerge>` container with merge node children. */
+export function merge(nodes: SVGFEMergeNodeElement[] = []): SVGFEMergeElement {
+  const el = createSVGElement("feMerge");
+  nodes.forEach((node) => el.appendChild(node));
+  return el;
+}
+
+/**
+ * Calculates the SVG Path data for a perfect circle starting at the top center (12 o'clock).
+ *
+ * Path moves to (0, -r), then draws two semi-circles.
+ * @param r Radius in pixels
+ */
+export function circlePath(r: number): string {
+  const rClean = Math.round(r * 100) / 100;
+
+  return `
+    M 0, -${rClean}
+    A ${rClean},${rClean} 0 1,1 0,${rClean}
+    A ${rClean},${rClean} 0 1,1 0,-${rClean}
+  `
+    .replace(/\s+/g, " ")
+    .trim();
+}

package/dist/layers.d.ts

@@ -1,15 +0,0 @@
-/**
- * Standard Z-Index layers for the Supermouse ecosystem.
- * Relative to the Supermouse Container.
- */
-export declare const Layers: {
-    /** The top-most layer. For text, tooltips, and crucial UI. */
-    readonly OVERLAY: "400";
-    /** The main cursor layer. For the primary Dot/Pointer. */
-    readonly CURSOR: "300";
-    /** The secondary layer. For Rings, brackets, or followers. */
-    readonly FOLLOWER: "200";
-    /** The background layer. For trails, sparkles, and particles. */
-    readonly TRACE: "100";
-};
-//# sourceMappingURL=layers.d.ts.map

package/dist/layers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"layers.d.ts","sourceRoot":"","sources":["../src/layers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,MAAM;IACjB,8DAA8D;;IAG9D,0DAA0D;;IAG1D,8DAA8D;;IAG9D,iEAAiE;;CAEzD,CAAC"}

package/src/layers.ts

@@ -1,17 +0,0 @@
-/**
- * Standard Z-Index layers for the Supermouse ecosystem.
- * Relative to the Supermouse Container.
- */
-export const Layers = {
-  /** The top-most layer. For text, tooltips, and crucial UI. */
-  OVERLAY: "400",
-
-  /** The main cursor layer. For the primary Dot/Pointer. */
-  CURSOR: "300",
-
-  /** The secondary layer. For Rings, brackets, or followers. */
-  FOLLOWER: "200",
-
-  /** The background layer. For trails, sparkles, and particles. */
-  TRACE: "100"
-} as const;