@supermousejs/states 2.3.0 → 2.4.0

package/README.md

@@ -1,7 +1,6 @@
 # @supermousejs/states
 
-A **Logic Controller** that enables/disables other plugins based on hover attributes.
-Useful for creating complex interaction modes (e.g. "View" mode vs "Edit" mode).
+Logic controller that enables/disables other plugins based on hover attributes
 
 ## Installation
 
@@ -9,38 +8,36 @@ Useful for creating complex interaction modes (e.g. "View" mode vs "Edit" mode).
 pnpm add @supermousejs/states
 ```
 
-## Usage
+## States
+
+Logic controller that enables/disables other plugins based on hover attributes. The plugin names listed in `default` and `states` must match the registered `plugin.name` values you use in your app.
+
+### Usage
 
 ```ts
 import { Supermouse } from "@supermousejs/core";
 import { States } from "@supermousejs/states";
-
 const app = new Supermouse();
-
-// Define your plugins normally (names are required)
-app.use(Dot({ name: "dot" }));
-app.use(Ring({ name: "ring" }));
-app.use(Text({ name: "text" }));
-
-// Configure states
-app.use(
-  States({
-    default: ["dot"], // Plugins active by default
-    states: {
-      hover: ["dot", "ring"],
-      info: ["text"]
-    }
-  })
-);
+app.use(States({ default: ['dot'], states: { 'hover': ['ring'] } }));
 ```
 
-**HTML:**
+### HTML Example
 
 ```html
-<div data-supermouse-state="hover">Hover me</div>
-<div data-supermouse-state="info" data-supermouse-text="Hello">Info</div>
+<div data-supermouse-state="hover">
+  <span class="dot"></span>
+  <span class="ring"></span>
+</div>
 ```
 
+### Options
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| default | string[] | [] | List of plugin names active by default. |
+| states | Record<string, string[]> | {} | Map of state names to lists of active plugins. |
+| attribute | string | 'data-supermouse-state' | DOM attribute to trigger state changes. |
+
 ## Documentation
 
 Full documentation and interactive playground available at [supermouse](https://supermouse.js.org) or [check out the repo](https://github.com/Whitestar14/supermouse-js).

package/dist/index.d.ts

@@ -1,15 +1,24 @@
 import { SupermousePlugin } from '../packages/core/src';
 
+/**
+ * State machine plugin.
+ *
+ * Hovers over `[data-supermouse-state="foo"]` enable the plugin list
+ * registered for `"foo"`. Everything else falls back to `default`.
+ *
+ * Install this **after** all plugins it manages, or initialization will
+ * miss plugins that haven't been registered yet.
+ */
 export declare const States: (options: StatesOptions) => SupermousePlugin;
 
 export declare interface StatesOptions {
     name?: string;
     isEnabled?: boolean;
-    /** The default state (active when nothing else is hovered). */
+    /** Plugins active when no state attribute is hovered. */
     default: string[];
-    /** Map of state names to lists of plugin names to enable. */
+    /** Map of state names to plugin names to enable. */
     states: Record<string, string[]>;
-    /** CSS selector attribute to trigger state change. Default 'data-supermouse-state'. */
+    /** Attribute that triggers a state change. */
     attribute?: string;
 }
 

package/dist/index.mjs

@@ -1,41 +1,45 @@
-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(
+import { definePlugin as g } from "@supermousejs/utils";
+const E = (e) => {
+  const u = e.attribute ?? "data-supermouse-state", d = new Set(e.default), r = /* @__PURE__ */ new Set();
+  Object.values(e.states).forEach((t) => t.forEach((a) => r.add(a))), e.default.forEach((t) => r.add(t));
+  let f = "__UNINITIALIZED__";
+  return g(
     {
       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}]`);
+      install(t) {
+        t.registerHoverTarget(`[${u}]`);
       },
-      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);
+      update(t) {
+        const a = t.state.hoverTarget;
+        let n = "default";
+        if (a) {
+          const s = a.closest(`[${u}]`);
+          if (s) {
+            const l = s.getAttribute(u);
+            l && e.states[l] && (n = l);
+          }
         }
-        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;
+        if (n === f) return;
+        const o = n === "default" ? e.default : e.states[n];
+        for (const s of r) {
+          const l = t.getPlugin(s);
+          if (!l) continue;
+          const i = o.includes(s), c = l.isEnabled !== !1;
+          i && !c && t.enablePlugin(s), !i && c && t.disablePlugin(s);
+        }
+        f = n;
+      },
+      destroy(t) {
+        for (const a of r) {
+          const n = t.getPlugin(a);
+          n && d.has(a) && n.isEnabled === !1 && t.enablePlugin(a);
         }
       }
     },
-    a
+    e
   );
 };
 export {
-  v as States
+  E as States
 };

package/dist/index.umd.js

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

package/package.json

@@ -1,20 +1,25 @@
 {
   "name": "@supermousejs/states",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "main": "dist/index.umd.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
+  "description": "Logic controller that enables/disables other plugins based on hover attributes",
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "author": "O.S David",
   "url": "https://github.com/Whitestar14/supermouse-js",
   "license": "MIT",
   "dependencies": {
-    "@supermousejs/utils": "2.3.0"
+    "@supermousejs/utils": "2.4.0"
   },
   "devDependencies": {
-    "@supermousejs/core": "2.2.0"
+    "@supermousejs/core": "2.4.0"
   },
   "peerDependencies": {
-    "@supermousejs/core": "2.2.0"
+    "@supermousejs/core": "2.4.0"
   },
   "repository": {
     "type": "git",

package/CHANGELOG.md

@@ -1,90 +0,0 @@
-# @supermousejs/states
-
-## 2.3.0
-
-### Patch Changes
-
-- Updated dependencies [f6f44b2]
-  - @supermousejs/core@2.2.0
-  - @supermousejs/utils@2.3.0
-
-## 2.2.0
-
-### Patch Changes
-
-- 6d70c18: remove legacy package and update supermouse domain in readme
-- 14fb5b6: Updated tsconfig to be reference-compliant with core, utils and zoetrope when required
-- Updated dependencies [6d70c18]
-- Updated dependencies [2590af3]
-- Updated dependencies [14fb5b6]
-- Updated dependencies [9fe1a7b]
-- Updated dependencies [9fa6ece]
-  - @supermousejs/core@2.1.0
-  - @supermousejs/utils@2.2.0
-
-## 2.1.1
-
-### Patch Changes
-
-- 67f771b: Add relevant npm metadata to package.json file
-- Updated dependencies [67f771b]
-  - @supermousejs/utils@2.1.1
-  - @supermousejs/core@2.0.5
-
-## 2.1.0
-
-### Minor Changes
-
-- 0a1652d: fixed build architecture and updated plugin metadata
-
-### Patch Changes
-
-- Updated dependencies [0a1652d]
-  - @supermousejs/utils@2.1.0
-
-## 2.0.4
-
-### Patch Changes
-
-- 993dc67: Updated supemousejs packages with proper author, license and url descriptors to repo
-- Updated dependencies [993dc67]
-  - @supermousejs/utils@2.0.4
-  - @supermousejs/core@2.0.4
-
-## 2.0.3
-
-### Patch Changes
-
-- Updated dependencies
-  - @supermousejs/core@2.0.3
-  - @supermousejs/utils@2.0.3
-
-## 2.0.2
-
-### Patch Changes
-
-- ae219a0: Update READMEs with correct link to documentation
-- Updated dependencies [ae219a0]
-  - @supermousejs/utils@2.0.2
-  - @supermousejs/core@2.0.2
-
-## 2.0.1
-
-### Patch Changes
-
-- Add minimal README.md files to packages
-- Updated dependencies
-  - @supermousejs/utils@2.0.1
-  - @supermousejs/core@2.0.1
-
-## 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/meta.json

@@ -1,31 +0,0 @@
-{
-  "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/src/index.ts

@@ -1,99 +0,0 @@
-import type { Supermouse } from "@supermousejs/core";
-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: Supermouse) {
-        // Register the trigger attribute
-        app.registerHoverTarget(`[${attr}]`);
-      },
-
-      update(app: Supermouse) {
-        // --- 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

@@ -1,4 +0,0 @@
-{
-  "extends": "../../tsconfig.plugin.json",
-  "include": ["src"]
-}

package/vite.config.ts

@@ -1,23 +0,0 @@
-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 })]
-});