@supermousejs/core 2.4.2 → 2.5.0-beta.0

package/dist/index.d.ts

@@ -1,7 +1,42 @@
-/** Default selectors that trigger `state.isHover`. Override with `hoverSelectors`. */
-export declare const DEFAULT_HOVER_SELECTORS: string[];
+/** Overall cursor mode. */
+export declare type CursorMode = "auto" | "custom" | "native" | "both";
+
+export declare interface CursorPolicy {
+    rules: CursorTargetRule[];
+}
+
+/** Shorthand form accepted at the public API boundary. */
+export declare type CursorPolicyInput = CursorPolicy | {
+    native?: string[];
+    hide?: string[];
+};
+
+/**
+ * A single rule that ties a CSS selector to native-cursor behaviour
+ * and/or native-cursor CSS suppression.
+ */
+export declare interface CursorTargetRule {
+    /** CSS selector to match. */
+    selector: string;
+    /**
+     * In `"auto"` cursor mode, an element matching this selector yields to the
+     * OS cursor.
+     * @default true
+     */
+    native?: boolean;
+    /**
+     * Generate a `cursor: none !important` rule for this selector when the
+     * custom cursor is active. Needed for elements whose UA stylesheet sets a
+     * cursor value (e.g. `a { cursor: pointer }`) that would otherwise override
+     * the container's inherited `cursor: none`.
+     * @default true
+     */
+    hide?: boolean;
+}
+
+export declare const DEFAULT_CURSOR_POLICY: CursorPolicy;
 
-/* Excluded from this release type: Input */
+export declare const DEFAULT_HOVER_SELECTORS: string[];
 
 /**
  * Interaction state consumed by plugins.
@@ -45,7 +80,7 @@ export declare interface MouseState {
     /** Native cursor temporarily restored due to native-input heuristics. */
     isNative: boolean;
     /** Current cursor mode: auto, custom, native, or both. */
-    cursorMode: "auto" | "custom" | "native" | "both";
+    cursorMode: CursorMode;
     /** Currently hovered DOM element, if any. */
     hoverTarget: HTMLElement | null;
     /** User has `prefers-reduced-motion` enabled. */
@@ -58,11 +93,7 @@ export declare interface MouseState {
     interaction: InteractionState;
 }
 
-/**
- * The subset of `SupermouseOptions` guaranteed to have a concrete value once
- * the constructor has merged user input over the defaults.
- */
-declare type ResolvedOptions = SupermouseOptions & Required<Pick<SupermouseOptions, "smoothness" | "enableTouch" | "autoDisableOnMobile" | "cursor" | "hideOnLeave" | "autoStart" | "container" | "dataPrefix" | "zIndex">>;
+declare type ResolvedOptions = SupermouseOptions & Required<Pick<SupermouseOptions, "smoothness" | "enableTouch" | "autoDisableOnMobile" | "cursor" | "hideOnLeave" | "autoStart" | "container" | "dataPrefix" | "zIndex" | "inheritDataAttributes">>;
 
 export declare type RuleDefinition = RuleSet | ((el: HTMLElement) => RuleSet);
 
@@ -70,71 +101,91 @@ export declare type RuleSet = Record<string, RuleValue | ((el: HTMLElement) => R
 
 export declare type RuleValue = string | boolean | number;
 
+/**
+ * Configuration for a single scope. A scope owns a container, its cursor
+ * mode, its hover selectors, and its plugin set. Scopes stack: the innermost
+ * scope whose container contains the pointer is the active one.
+ */
+export declare interface ScopeConfig {
+    /** Optional identifier for `getScope(name)` lookups. */
+    name?: string;
+    /** The element this scope is bound to. */
+    container: HTMLElement;
+    /** Cursor mode for this scope. Inherits from top-level if omitted. */
+    cursor?: CursorMode;
+    /** Hover selectors for this scope. Inherits from top-level if omitted. */
+    hoverSelectors?: string[];
+    /** Custom cursor policy for this scope. Inherits from top-level if omitted. */
+    cursorPolicy?: CursorPolicyInput;
+    /** Plugins installed when this scope activates. */
+    plugins?: SupermousePlugin[];
+    /**
+     * Whether data attributes and rules on ancestors cascade to the hovered
+     * element. Inherits from top-level if omitted.
+     * @default true
+     */
+    inheritDataAttributes?: boolean;
+    /** Stage z-index for this scope. Inherits from top-level if omitted. */
+    zIndex?: number;
+}
+
+export declare interface ScopeHandle {
+    readonly name: string | undefined;
+    readonly container: HTMLElement;
+    remove(): void;
+    setCursor(mode: CursorMode): void;
+}
+
 export declare interface ShapeState {
     width: number;
     height: number;
     borderRadius: number;
 }
 
-/* Excluded from this release type: Stage */
-
-/**
- * Orchestrates state, animation loop, and plugin lifecycle.
- */
 export declare class Supermouse {
     static readonly version: string;
     readonly version: string;
     state: MouseState;
-    /** Configuration options, fully resolved with defaults applied. */
     options: ResolvedOptions;
-    private plugins;
-    private _stage;
+    private _scopes;
+    private _activeScope;
+    private _installingScope;
+    private scopeByContainer;
     private input;
     private rafId;
     private lastTime;
-    private isRunning;
-    private isSuspended;
     private visibilityAbortController;
-    private hoverSelectors;
-    private hoverSelectorString;
     private crashedPlugins;
     constructor(options?: SupermouseOptions);
-    /** Look up a registered plugin by name. */
-    getPlugin(name: string): SupermousePlugin | undefined;
-    /** Whether the instance is not disabled/suspended and is processing input. */
+    get container(): HTMLElement;
+    get stage(): HTMLDivElement;
     get isEnabled(): boolean;
-    /** Enable a plugin by name. */
+    get isRunning(): boolean;
+    use(plugin: SupermousePlugin): this;
+    getPlugin(name: string): SupermousePlugin | undefined;
     enablePlugin(name: string): void;
-    /** Disable a plugin by name and hide its element. */
     disablePlugin(name: string): void;
-    /** Toggle a plugin's enabled state by name. */
     togglePlugin(name: string): void;
-    /** Add a selector to hover detection and cursor suppression. */
-    registerHoverTarget(selector: string): void;
-    /** The DOM element the instance is scoped to. */
-    get container(): HTMLElement;
-    /** The stage element that plugins append their visuals into. */
-    get stage(): HTMLDivElement;
-    /** Set the current cursor mode. */
-    setCursor(mode: "auto" | "custom" | "native" | "both"): void;
-    private init;
-    /** Re‑enable input processing and re‑apply cursor state. */
+    setCursor(mode: CursorMode): void;
+    addScope(config: ScopeConfig): ScopeHandle;
     enable(): void;
-    /** Disable input processing and restore native cursor. */
-    disable(): void;
-    /** Temporarily yield to a scoped instance. */
-    suspend(): void;
-    /** Resume from `suspend()`. */
-    resume(): void;
-    /** Register a new plugin. */
-    use(plugin: SupermousePlugin): this;
-    /** Reset physics; optionally clear all input state. */
-    private reset;
-    private startLoop;
-    /** Start the animation loop. */
+    disable(opts?: {
+        reset?: boolean;
+    }): void;
+    reset(): void;
     start(): void;
-    /** Manually step the animation loop. */
     step(time: number): void;
+    destroy(): void;
+    private _running;
+    private createScope;
+    private removeScope;
+    private setScopeCursor;
+    private installPlugins;
+    private installPlugin;
+    private handleActiveScopeChange;
+    private activatePlugin;
+    private deactivatePlugin;
+    private rebuildStylesheet;
     private runPluginSafe;
     private cleanupCrashedPlugins;
     private resolveStageVisibility;
@@ -142,10 +193,24 @@ export declare class Supermouse {
     private resetMotion;
     private update;
     private tick;
-    /** Pause rAF loop when tab hidden; resume on visible. */
     private bindVisibilityHandling;
-    /** Destroy the instance, freeing all resources. */
-    destroy(): void;
+    private startLoop;
+    /**
+     * @deprecated Prefer setting `hoverSelectors` at scope creation, or use
+     * `definePlugin`'s `selector` option. This method is kept for raw-object
+     * plugins and runtime extension; it mutates the active scope's selector set.
+     */
+    registerHoverTarget(selector: string): void;
+    /**
+     * @deprecated Read from the active scope instead. Exposed for tests and
+     * debugging only.
+     */
+    get hoverSelectors(): Set<string>;
+    /**
+     * @deprecated Read from the active scope instead. Exposed for tests and
+     * debugging only.
+     */
+    get plugins(): SupermousePlugin[];
 }
 
 export declare type SupermouseInstance = Supermouse;
@@ -180,7 +245,23 @@ export declare interface SupermouseOptions {
      * - `"both"`: always show custom cursor **and** native cursor together (no suppression).
      * @default "auto"
      */
-    cursor?: "auto" | "custom" | "native" | "both";
+    cursor?: CursorMode;
+    /**
+     * Custom cursor policy. Defaults to `DEFAULT_CURSOR_POLICY` from `./policy`.
+     */
+    cursorPolicy?: CursorPolicyInput;
+    /**
+     * Additional scopes registered at construction. The primary scope is
+     * created from the top-level `container` / `hoverSelectors` / `plugins`
+     * options; these are appended after it.
+     */
+    scopes?: ScopeConfig[];
+    /**
+     * Whether data attributes and rules on ancestors cascade to the hovered
+     * element. Applies to the primary scope; individual scopes can override.
+     * @default true
+     */
+    inheritDataAttributes?: boolean;
     /**
      * Whether to hide the custom cursor when the pointer leaves the browser viewport.
      * @default true
@@ -239,7 +320,8 @@ export declare interface SupermousePlugin {
     /** Called when plugin disabled via `.disablePlugin()`. */
     onDisable?: (instance: SupermouseInstance) => void;
     /**
-     * Called before the plugin is disabled.
+     * Called before the plugin is disabled. Return a Promise to delay hiding
+     * until an exit animation completes.
      */
     onBeforeDisable?(instance: SupermouseInstance): void | Promise<void>;
 }