@supermousejs/core 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @supermousejs/core
+
+## 2.0.0
+
+### Major Changes
+
+- Initial v2.0.0 release

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sijibomi Olusunmbola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,304 @@
+export declare const DEFAULT_HOVER_SELECTORS: string[];
+
+/**
+ * The Interface for interaction state.
+ * Plugins should use Module Augmentation to add their specific properties to this interface.
+ *
+ * @example
+ * declare module '@supermousejs/core' {
+ *   interface InteractionState {
+ *     magnetic: boolean | number;
+ *     text: string;
+ *   }
+ * }
+ */
+export declare interface InteractionState {
+    /**
+     * Allow arbitrary keys for rapid prototyping.
+     * For type safety, use module augmentation to define expected keys.
+     */
+    [key: string]: any;
+}
+
+export declare interface MousePosition {
+    x: number;
+    y: number;
+}
+
+export declare interface MouseState {
+    /** The raw position of the input pointer (mouse/touch). */
+    pointer: MousePosition;
+    /** The target position the cursor logic wants to reach. */
+    target: MousePosition;
+    /** The smoothed/interpolated position used for rendering. */
+    smooth: MousePosition;
+    /** The current velocity vector of the smooth position. */
+    velocity: MousePosition;
+    /** The angle of movement in degrees. Calculated from velocity. */
+    angle: number;
+    /** Whether the pointer is currently pressed down. */
+    isDown: boolean;
+    /** Whether the pointer is currently hovering over a registered interactive element. */
+    isHover: boolean;
+    /** Whether the native cursor is currently forced visible by internal logic (e.g. input elements). */
+    isNative: boolean;
+    /**
+     * If set, this overrides all auto-detection logic.
+     * 'auto' = Force Native Cursor (Show)
+     * 'none' = Force Custom Cursor (Hide Native)
+     * null = Let the Core decide based on isNative/isHover
+     */
+    forcedCursor: 'auto' | 'none' | null;
+    /** The DOM element currently being hovered, if any. */
+    hoverTarget: HTMLElement | null;
+    /** Whether the user has `prefers-reduced-motion` enabled. */
+    reducedMotion: boolean;
+    /** Whether the system has received valid input coordinates at least once. */
+    hasReceivedInput: boolean;
+    /** Defines a specific geometric shape the cursor should conform to. */
+    shape: ShapeState | null;
+    /** Centralized store for hover metadata from data attributes. */
+    interaction: InteractionState;
+}
+
+export declare type NativeIgnoreStrategy = 'auto' | 'tag' | 'css';
+
+export declare interface ShapeState {
+    width: number;
+    height: number;
+    borderRadius: number;
+}
+
+/**
+ * The Central Conductor & Runtime Loop of Supermouse.
+ *
+ * This class orchestrates the application state, manages the animation loop (`requestAnimationFrame`),
+ * and coordinates data flow between the Input system, the Stage system, and the Plugins.
+ *
+ * ## Architecture
+ * 1. **Input System**: Captures raw events and writes to `state.pointer`.
+ * 2. **Logic Plugins**: (Priority < 0) Read `pointer`, modify `state.target` (e.g. Magnetic, Stick).
+ * 3. **Physics**: Core interpolates `state.smooth` towards `state.target`.
+ * 4. **Visual Plugins**: (Priority >= 0) Read `state.smooth`, update DOM transforms.
+ *
+ * @example
+ * ```ts
+ * const app = new Supermouse({ smoothness: 0.15 });
+ * app.use(Dot({ color: 'red' }));
+ * ```
+ */
+export declare class Supermouse {
+    /** The current version of Supermouse.js */
+    static readonly version: string;
+    readonly version: string;
+    /**
+     * The Single Source of Truth.
+     *
+     * This object is shared by reference. `Input` writes to it; `Supermouse` physics reads/writes to it;
+     * Plugins read/write to it.
+     */
+    state: MouseState;
+    /**
+     * Configuration options.
+     */
+    options: SupermouseOptions;
+    /* Excluded from this release type: plugins */
+    /* Excluded from this release type: stage */
+    /* Excluded from this release type: input */
+    private rafId;
+    private lastTime;
+    private isRunning;
+    private hoverSelectors;
+    /**
+     * Creates a new Supermouse instance.
+     *
+     * @param options - Global configuration options.
+     * @throws Will throw if running in a non-browser environment (window/document undefined).
+     */
+    constructor(options?: SupermouseOptions);
+    /**
+     * Retrieves a registered plugin instance by its unique name.
+     */
+    getPlugin(name: string): SupermousePlugin | undefined;
+    /**
+     * Returns whether the cursor system is currently enabled (processing input).
+     */
+    get isEnabled(): boolean;
+    /**
+     * Enables a specific plugin by name.
+     * Triggers the `onEnable` lifecycle hook of the plugin.
+     */
+    enablePlugin(name: string): void;
+    /**
+     * Disables a specific plugin by name.
+     * Triggers the `onDisable` lifecycle hook.
+     */
+    disablePlugin(name: string): void;
+    /**
+     * Toggles the enabled state of a plugin.
+     */
+    togglePlugin(name: string): void;
+    /**
+     * Registers a CSS selector as an "Interactive Target".
+     *
+     * When the mouse hovers over an element matching this selector:
+     * 1. `state.isHover` becomes `true`.
+     * 2. `state.hoverTarget` is set to the element.
+     * 3. The `Stage` system injects CSS to hide the native cursor for this element (if `hideCursor: true`).
+     *
+     * @param selector - A valid CSS selector string (e.g., `.my-button`, `[data-trigger]`).
+     */
+    registerHoverTarget(selector: string): void;
+    /**
+     * The fixed container element where plugins should append their DOM nodes.
+     */
+    get container(): HTMLDivElement;
+    /**
+     * Manually override the native cursor visibility.
+     * Useful for drag-and-drop operations, modals, or special UI states.
+     *
+     * @param type 'auto' (Show Native), 'none' (Hide Native), or null (Resume Auto-detection)
+     */
+    setCursor(type: 'auto' | 'none' | null): void;
+    private init;
+    /**
+     * Starts the update loop and enables input listeners.
+     * Hides the native cursor if configured.
+     */
+    enable(): void;
+    /**
+     * Stops the update loop, disables listeners, and restores the native cursor.
+     * Resets internal state positions to off-screen.
+     */
+    disable(): void;
+    /**
+     * Registers a new plugin.
+     *
+     * @remarks
+     * Plugins are sorted by `priority` immediately after registration.
+     * - **Negative Priority (< 0)**: Logic plugins (run before physics).
+     * - **Positive Priority (>= 0)**: Visual plugins (run after physics).
+     *
+     * @param plugin - The plugin object to install.
+     */
+    use(plugin: SupermousePlugin): this;
+    private resetPosition;
+    private startLoop;
+    /**
+     * Manually steps the animation loop.
+     * Useful when integrating with external game loops (e.g., Three.js, PixiJS) where
+     * you want to disable the internal RAF and drive `Supermouse` from your own ticker.
+     *
+     * @param time Current timestamp in milliseconds.
+     */
+    step(time: number): void;
+    private runPluginSafe;
+    /**
+     * The Heartbeat.
+     * Runs on every animation frame.
+     */
+    private tick;
+    /**
+     * Destroys the instance.
+     * Stops the loop, removes all DOM elements, removes all event listeners, and calls destroy on all plugins.
+     */
+    destroy(): void;
+}
+
+/**
+ * Configuration options passed to the Supermouse constructor.
+ */
+export declare interface SupermouseOptions {
+    /**
+     * The interpolation factor (0 to 1). Lower is smoother/slower.
+     * @default 0.15
+     */
+    smoothness?: number;
+    /**
+     * List of CSS selectors that trigger the "Hover" state.
+     * Overrides the default set if provided.
+     */
+    hoverSelectors?: string[];
+    /**
+     * Whether to enable custom cursor effects on touch devices.
+     * @default false
+     */
+    enableTouch?: boolean;
+    /**
+     * Whether to automatically disable the custom cursor on devices with coarse pointers.
+     * @default true
+     */
+    autoDisableOnMobile?: boolean;
+    /**
+     * Strategy for detecting when to fallback to the native cursor.
+     * - `true` / `'auto'`: Checks both HTML tags and CSS cursor styles (Accurate but slower).
+     * - `'tag'`: Checks only semantic tags like <input>, <textarea> (Fastest, prevents layout thrashing).
+     * - `'css'`: Checks only computed CSS cursor styles (Slow, triggers reflow).
+     * - `false`: Never fallback to native cursor.
+     * @default 'auto'
+     */
+    ignoreOnNative?: boolean | NativeIgnoreStrategy;
+    /**
+     * Whether to hide the native cursor via global CSS injection.
+     * @default true
+     */
+    hideCursor?: boolean;
+    /**
+     * Whether to hide the custom cursor when the mouse leaves the browser window.
+     * @default true
+     */
+    hideOnLeave?: boolean;
+    /**
+     * List of plugins to initialize with the instance.
+     */
+    plugins?: SupermousePlugin[];
+    /**
+     * The DOM element to append the cursor stage to.
+     * @default document.body
+     */
+    container?: HTMLElement;
+    /**
+     * Whether to start the internal animation loop automatically.
+     * @default true
+     */
+    autoStart?: boolean;
+    /**
+     * Semantic rules mapping CSS selectors to interaction state.
+     * @example { 'button': { icon: 'pointer' } }
+     */
+    rules?: Record<string, InteractionState>;
+    /**
+     * Custom strategy to resolve interaction state from a hovered element.
+     * Overrides the default data-attribute scraping.
+     */
+    resolveInteraction?: (target: HTMLElement) => InteractionState;
+}
+
+/**
+ * Interface for defining a Supermouse Plugin.
+ */
+export declare interface SupermousePlugin {
+    /** Unique name for the plugin. Used for toggling/retrieval. */
+    name: string;
+    /** Execution priority. Lower numbers run first. */
+    priority?: number;
+    /** If false, update() will not be called. */
+    isEnabled?: boolean;
+    /** Called when `app.use()` is executed. */
+    install?: (instance: Supermouse) => void;
+    /** Called on every animation frame. */
+    update?: (instance: Supermouse, deltaTime: number) => void;
+    /** Called when the plugin is removed or the app is destroyed. */
+    destroy?: (instance: Supermouse) => void;
+    /** Called when the plugin is enabled via .enablePlugin() */
+    onEnable?: (instance: Supermouse) => void;
+    /** Called when the plugin is disabled via .disablePlugin() */
+    onDisable?: (instance: Supermouse) => void;
+}
+
+/**
+ * Helper type: Allows a property to be a static value OR a function that returns the value based on state.
+ */
+export declare type ValueOrGetter<T> = T | ((state: MouseState) => T);
+
+export { }