@supermousejs/states 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @supermousejs/states
+
+## 2.0.0
+
+### Major Changes
+
+- Initial v2.0.0 release
+
+### Patch Changes
+
+- Updated dependencies
+  - @supermousejs/utils@2.0.0
+  - @supermousejs/core@2.0.0

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,16 @@
+import { SupermousePlugin } from '../../core/src/index.ts';
+
+export declare const States: (options: StatesOptions) => SupermousePlugin;
+
+export declare interface StatesOptions {
+    name?: string;
+    isEnabled?: boolean;
+    /** The default state (active when nothing else is hovered). */
+    default: string[];
+    /** Map of state names to lists of plugin names to enable. */
+    states: Record<string, string[]>;
+    /** CSS selector attribute to trigger state change. Default 'data-supermouse-state'. */
+    attribute?: string;
+}
+
+export { }

package/dist/index.mjs

@@ -0,0 +1,38 @@
+import { definePlugin as f } from "@supermousejs/utils";
+const v = (a) => {
+  const r = a.attribute || "data-supermouse-state", i = /* @__PURE__ */ new Set(), u = new Set(a.default);
+  Object.values(a.states).forEach((e) => {
+    e.forEach((l) => i.add(l));
+  });
+  let c = "default", d = !1;
+  return f({
+    name: "states",
+    // High priority: Run BEFORE visual plugins so they know if they are enabled/disabled this frame
+    priority: -999,
+    install(e) {
+      e.registerHoverTarget(`[${r}]`);
+    },
+    update(e) {
+      d || (i.forEach((t) => {
+        u.has(t) || e.disablePlugin(t);
+      }), u.forEach((t) => {
+        e.enablePlugin(t);
+      }), d = !0);
+      const l = e.state.hoverTarget;
+      let s = "default";
+      if (l && l.hasAttribute(r)) {
+        const t = l.getAttribute(r);
+        t && a.states[t] && (s = t);
+      }
+      if (s !== c) {
+        const t = s === "default" ? a.default : a.states[s];
+        (/* @__PURE__ */ new Set([...u, ...i])).forEach((n) => {
+          t.includes(n) ? e.enablePlugin(n) : e.disablePlugin(n);
+        }), c = s;
+      }
+    }
+  }, a);
+};
+export {
+  v as States
+};

package/dist/index.umd.js

@@ -0,0 +1 @@
+(function(s,i){typeof exports=="object"&&typeof module<"u"?i(exports,require("@supermousejs/utils")):typeof define=="function"&&define.amd?define(["exports","@supermousejs/utils"],i):(s=typeof globalThis<"u"?globalThis:s||self,i(s.SupermouseStates={},s.SupermouseUtils))})(this,(function(s,i){"use strict";const h=u=>{const n=u.attribute||"data-supermouse-state",r=new Set,d=new Set(u.default);Object.values(u.states).forEach(t=>{t.forEach(a=>r.add(a))});let o="default",c=!1;return i.definePlugin({name:"states",priority:-999,install(t){t.registerHoverTarget(`[${n}]`)},update(t){c||(r.forEach(e=>{d.has(e)||t.disablePlugin(e)}),d.forEach(e=>{t.enablePlugin(e)}),c=!0);const a=t.state.hoverTarget;let l="default";if(a&&a.hasAttribute(n)){const e=a.getAttribute(n);e&&u.states[e]&&(l=e)}if(l!==o){const e=l==="default"?u.default:u.states[l];new Set([...d,...r]).forEach(f=>{e.includes(f)?t.enablePlugin(f):t.disablePlugin(f)}),o=l}}},u)};s.States=h,Object.defineProperty(s,Symbol.toStringTag,{value:"Module"})}));

package/meta.json

@@ -0,0 +1,14 @@
+
+{
+  "id": "states",
+  "name": "States",
+  "package": "@supermousejs/states",
+  "description": "Logic controller that enables/disables other plugins based on hover attributes.",
+  "code": "app.use(States({ default: ['dot'], states: { 'hover': ['ring'] } }));",
+  "icon": "context",
+  "options": [
+    { "name": "default", "type": "string[]", "default": "[]", "description": "List of plugin names active by default.", "reactive": false },
+    { "name": "states", "type": "Record<string, string[]>", "default": "{}", "description": "Map of state names to lists of active plugins.", "reactive": false },
+    { "name": "attribute", "type": "string", "default": "'data-supermouse-state'", "description": "DOM attribute to trigger state changes.", "reactive": false }
+  ]
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@supermousejs/states",
+  "version": "2.0.0",
+  "main": "dist/index.umd.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@supermousejs/core": "2.0.0",
+    "@supermousejs/utils": "2.0.0"
+  },
+  "devDependencies": {},
+  "peerDependencies": {},
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.umd.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build"
+  }
+}

package/src/index.ts

@@ -0,0 +1,97 @@
+import { definePlugin } from '@supermousejs/utils';
+
+export interface StatesOptions {
+  name?: string;
+  isEnabled?: boolean;
+  /** The default state (active when nothing else is hovered). */
+  default: string[];
+  /** Map of state names to lists of plugin names to enable. */
+  states: Record<string, string[]>;
+  /** CSS selector attribute to trigger state change. Default 'data-supermouse-state'. */
+  attribute?: string;
+}
+
+export const States = (options: StatesOptions) => {
+  const attr = options.attribute || 'data-supermouse-state';
+  
+  // Cache the relationships for fast lookups
+  const allManagedPlugins = new Set<string>(); // All plugins mentioned in 'states'
+  const defaultPlugins = new Set(options.default);
+  
+  // Populate the set of managed plugins (excluding defaults for now)
+  Object.values(options.states).forEach(list => {
+    list.forEach(p => allManagedPlugins.add(p));
+  });
+
+  let currentState = 'default';
+  let hasInitialized = false;
+
+  return definePlugin({
+    name: 'states',
+    // High priority: Run BEFORE visual plugins so they know if they are enabled/disabled this frame
+    priority: -999, 
+    
+    install(app) {
+      // Register the trigger attribute
+      app.registerHoverTarget(`[${attr}]`);
+    },
+
+    update(app) {
+      // --- INITIALIZATION STEP ---
+      // We do this in the first update tick to ensure all other plugins 
+      // have been registered via .use(), regardless of order.
+      if (!hasInitialized) {
+        // 1. Disable all "Special State" plugins initially
+        allManagedPlugins.forEach(name => {
+          if (!defaultPlugins.has(name)) {
+            app.disablePlugin(name);
+          }
+        });
+
+        // 2. Ensure default plugins are enabled
+        defaultPlugins.forEach(name => {
+          app.enablePlugin(name);
+        });
+
+        hasInitialized = true;
+      }
+
+      // --- STANDARD LOGIC ---
+      const target = app.state.hoverTarget;
+      let nextState = 'default';
+
+      // 1. Determine Desired State
+      if (target && target.hasAttribute(attr)) {
+        const val = target.getAttribute(attr);
+        if (val && options.states[val]) {
+          nextState = val;
+        }
+      }
+
+      // 2. Switch State (Only if changed)
+      if (nextState !== currentState) {
+        
+        // A. Determine which plugins should be active
+        const activePlugins = nextState === 'default' 
+          ? options.default 
+          : options.states[nextState];
+
+        // B. Apply changes
+        // Note: We combine default + managed to ensure we cover everyone involved
+        const involved = new Set([...defaultPlugins, ...allManagedPlugins]);
+        
+        involved.forEach(pluginName => {
+          const shouldBeActive = activePlugins.includes(pluginName);
+          
+          if (shouldBeActive) {
+            app.enablePlugin(pluginName);
+          } else {
+            app.disablePlugin(pluginName);
+          }
+        });
+
+        currentState = nextState;
+      }
+    }
+  }, options);
+};

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "include": [
+    "src"
+  ],
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {
+      "@supermousejs/core": [
+        "../core/src/index.ts"
+      ],
+      "@supermousejs/utils": [
+        "../utils/src/index.ts"
+      ]
+    }
+  }
+}

package/vite.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+import path from 'path';
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: path.resolve(__dirname, 'src/index.ts'),
+      name: 'SupermouseStates',
+      fileName: (format) => format === 'es' ? 'index.mjs' : 'index.umd.js',
+    },
+    rollupOptions: {
+      external: ['@supermousejs/core', '@supermousejs/utils'],
+      output: {
+        globals: {
+          '@supermousejs/core': 'SupermouseCore'
+        , '@supermousejs/utils': 'SupermouseUtils'}
+      }
+    }
+  },
+  plugins: [dts({ rollupTypes: true })]
+});