@ailuracode/alpine-toggle 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) ailuracode
+
+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/README.md

@@ -0,0 +1,108 @@
+# @ailuracode/alpine-toggle
+
+Alpine.js magic for **binary** and **ternary** toggles with full TypeScript inference.
+
+## Install
+
+```bash
+npm install @ailuracode/alpine-toggle alpinejs
+```
+
+## Setup
+
+```js
+import Alpine from "alpinejs";
+import toggle from "@ailuracode/alpine-toggle";
+
+Alpine.plugin(toggle);
+Alpine.start();
+```
+
+## Usage
+
+Each call to `$toggle()` returns an independent reactive instance.
+
+### Binary (two opposite states)
+
+```html
+<div x-data="{ power: $toggle({ states: { truly: 'on', falsely: 'off' }, initial: 'off' }) }">
+  <p x-text="power.value"></p>
+  <button type="button" @click="power.toggle()">Toggle</button>
+</div>
+```
+
+```ts
+const power = createToggle({ states: { truly: "on", falsely: "off" } });
+power.ternary; // undefined
+```
+
+### Ternary (two opposites + one independent state)
+
+The third state is **independent** — `toggle()` only flips between `truly` and `falsely`. Use `cycle()` to visit all three.
+
+```html
+<div x-data="{ answer: $toggle({
+  states: { truly: 'yes', falsely: 'no', ternary: 'unknown' },
+  initial: 'unknown',
+}) }">
+  <p>
+    Value: <strong x-text="answer.value"></strong>
+    <span x-show="answer.is(answer.ternary)" class="badge">neutral</span>
+  </p>
+  <button type="button" @click="answer.toggle()">Yes / No</button>
+  <button type="button" @click="answer.cycle()">Cycle all</button>
+  <button type="button" @click="answer.set(answer.ternary)">Reset to unknown</button>
+</div>
+```
+
+```ts
+const answer = createToggle({
+  states: { truly: "yes", falsely: "no", ternary: "unknown" },
+});
+```
+
+Without `states.ternary`, the property defaults to `undefined`:
+
+```ts
+const power = createToggle({ states: { truly: "on", falsely: "off" } });
+power.ternary; // undefined
+```
+
+## API
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `states.truly` | `TA` | First opposite state |
+| `states.falsely` | `TB` | Second opposite state |
+| `states.ternary` | `TN` | Optional independent state (`undefined` by default) |
+| `initial` | value | Starting value (default: `truly`, or `ternary` when configured) |
+
+### Instance
+
+| Member | Description |
+|--------|-------------|
+| `value` | Current state |
+| `states` | Readonly object `{ truly, falsely, ternary }` |
+| `truly` / `falsely` / `ternary` | Shorthand for `states.*` |
+| `is(value)` | Whether `value` is active |
+| `set(value)` | Set state; returns `false` if unchanged or invalid |
+| `toggle()` | Flip between opposites (from ternary → `truly`) |
+| `cycle()` | Advance to the next state in order |
+| `reset()` | Restore `initial` |
+
+## Types
+
+```ts
+import { createToggle, type ToggleValue } from "@ailuracode/alpine-toggle";
+
+type OnOff = ToggleValue<"on", "off">;
+type Answer = ToggleValue<"yes", "no", "unknown">;
+```
+
+Add `/// <reference path="node_modules/@ailuracode/alpine-toggle/dist/global.d.ts" />` for `$toggle` in templates.
+
+## License
+
+MIT

package/dist/global.d.ts

@@ -0,0 +1,49 @@
+/// <reference types="@types/alpinejs" />
+
+export interface ToggleBinaryStates<TA, TB> {
+  truly: TA;
+  falsely: TB;
+}
+
+export interface ToggleTernaryStates<TA, TB, TN> extends ToggleBinaryStates<TA, TB> {
+  ternary: TN;
+}
+
+export type ToggleValue<TA, TB, TN = undefined> = TN extends undefined ? TA | TB : TA | TB | TN;
+
+export interface ToggleOptions<TA, TB, TN = undefined> {
+  states: ToggleBinaryStates<TA, TB> & { ternary?: TN };
+  initial?: TA | TB | TN;
+}
+
+export interface ToggleInstance<TA, TB, TN, V> {
+  value: V;
+  readonly states: ToggleBinaryStates<TA, TB> & { ternary: TN };
+  readonly truly: TA;
+  readonly falsely: TB;
+  readonly ternary: TN;
+  is(value: V): boolean;
+  set(value: V): boolean;
+  toggle(): V;
+  cycle(): V;
+  reset(): V;
+}
+
+export type ToggleMagic = {
+  <const TA, const TB>(options: {
+    states: ToggleBinaryStates<TA, TB>;
+    initial?: TA | TB;
+  }): ToggleInstance<TA, TB, undefined, TA | TB>;
+  <const TA, const TB, const TN>(options: {
+    states: ToggleTernaryStates<TA, TB, TN>;
+    initial?: TA | TB | TN;
+  }): ToggleInstance<TA, TB, TN, TA | TB | TN>;
+};
+
+declare global {
+  namespace Alpine {
+    interface Magics<T> {
+      $toggle: ToggleMagic;
+    }
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import AlpineType from 'alpinejs';
+
+interface ToggleBinaryStates<TA, TB> {
+    truly: TA;
+    falsely: TB;
+}
+interface ToggleTernaryStates<TA, TB, TN> extends ToggleBinaryStates<TA, TB> {
+    ternary: TN;
+}
+type ToggleValue<TA, TB, TN = undefined> = TN extends undefined ? TA | TB : TA | TB | TN;
+interface ToggleOptions<TA, TB, TN = undefined> {
+    states: ToggleBinaryStates<TA, TB> & {
+        ternary?: TN;
+    };
+    initial?: TA | TB | TN;
+}
+interface ToggleInstance<TA, TB, TN, V> {
+    value: V;
+    readonly states: ToggleBinaryStates<TA, TB> & {
+        ternary: TN;
+    };
+    readonly truly: TA;
+    readonly falsely: TB;
+    readonly ternary: TN;
+    is(value: V): boolean;
+    set(value: V): boolean;
+    toggle(): V;
+    cycle(): V;
+    reset(): V;
+}
+type ToggleMagic = {
+    <const TA, const TB>(options: {
+        states: ToggleBinaryStates<TA, TB>;
+        initial?: TA | TB;
+    }): ToggleInstance<TA, TB, undefined, TA | TB>;
+    <const TA, const TB, const TN>(options: {
+        states: ToggleTernaryStates<TA, TB, TN>;
+        initial?: TA | TB | TN;
+    }): ToggleInstance<TA, TB, TN, TA | TB | TN>;
+};
+/** Creates an independent toggle instance with optional ternary state. */
+declare function createToggle<const TA, const TB>(options: {
+    states: ToggleBinaryStates<TA, TB>;
+    initial?: TA | TB;
+}): ToggleInstance<TA, TB, undefined, TA | TB>;
+declare function createToggle<const TA, const TB, const TN>(options: {
+    states: ToggleTernaryStates<TA, TB, TN>;
+    initial?: TA | TB | TN;
+}): ToggleInstance<TA, TB, TN, TA | TB | TN>;
+/** Builds callable `$toggle` magic that returns independent toggle instances. */
+declare function createToggleMagic(Alpine?: Pick<AlpineType.Alpine, "reactive">): ToggleMagic;
+/** Alpine.js toggle plugin. Registers callable magic `$toggle`. */
+declare function togglePlugin(Alpine: AlpineType.Alpine): void;
+
+export { type ToggleBinaryStates, type ToggleInstance, type ToggleMagic, type ToggleOptions, type ToggleTernaryStates, type ToggleValue, createToggle, createToggleMagic, togglePlugin as default };

package/dist/index.js

@@ -0,0 +1,78 @@
+// src/index.ts
+function isToggleState(states, value) {
+  return states.includes(value);
+}
+function indexOfState(states, value) {
+  return states.indexOf(value);
+}
+function buildToggle(options) {
+  const truly = options.states.truly;
+  const falsely = options.states.falsely;
+  const hasTernaryState = "ternary" in options.states;
+  const ternary = hasTernaryState ? options.states.ternary : void 0;
+  const stateValues = { truly, falsely, ternary };
+  const allStates = hasTernaryState ? [truly, falsely, ternary] : [truly, falsely];
+  const initial = "initial" in options ? options.initial : hasTernaryState ? ternary : truly;
+  const toggle = {
+    value: initial,
+    states: stateValues,
+    truly,
+    falsely,
+    ternary,
+    is(value) {
+      return this.value === value;
+    },
+    set(value) {
+      if (!isToggleState(allStates, value) || this.value === value) {
+        return false;
+      }
+      this.value = value;
+      return true;
+    },
+    toggle() {
+      if (hasTernaryState) {
+        if (this.value === ternary) {
+          this.value = truly;
+        } else if (this.value === truly) {
+          this.value = falsely;
+        } else {
+          this.value = truly;
+        }
+      } else {
+        this.value = this.value === truly ? falsely : truly;
+      }
+      return this.value;
+    },
+    cycle() {
+      const currentIndex = indexOfState(allStates, this.value);
+      const nextIndex = (currentIndex + 1) % allStates.length;
+      this.value = allStates[nextIndex];
+      return this.value;
+    },
+    reset() {
+      this.value = initial;
+      return this.value;
+    }
+  };
+  return toggle;
+}
+function createToggle(options) {
+  return buildToggle(options);
+}
+function createToggleMagic(Alpine) {
+  return ((options) => {
+    const instance = createToggle(
+      options
+    );
+    return Alpine ? Alpine.reactive(instance) : instance;
+  });
+}
+function togglePlugin(Alpine) {
+  Alpine.magic("toggle", () => createToggleMagic(Alpine));
+}
+export {
+  createToggle,
+  createToggleMagic,
+  togglePlugin as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type AlpineType from \"alpinejs\";\n\nexport interface ToggleBinaryStates<TA, TB> {\n  truly: TA;\n  falsely: TB;\n}\n\nexport interface ToggleTernaryStates<TA, TB, TN> extends ToggleBinaryStates<TA, TB> {\n  ternary: TN;\n}\n\nexport type ToggleValue<TA, TB, TN = undefined> = TN extends undefined ? TA | TB : TA | TB | TN;\n\nexport interface ToggleOptions<TA, TB, TN = undefined> {\n  states: ToggleBinaryStates<TA, TB> & { ternary?: TN };\n  initial?: TA | TB | TN;\n}\n\nexport interface ToggleInstance<TA, TB, TN, V> {\n  value: V;\n  readonly states: ToggleBinaryStates<TA, TB> & { ternary: TN };\n  readonly truly: TA;\n  readonly falsely: TB;\n  readonly ternary: TN;\n  is(value: V): boolean;\n  set(value: V): boolean;\n  toggle(): V;\n  cycle(): V;\n  reset(): V;\n}\n\nexport type ToggleMagic = {\n  <const TA, const TB>(options: {\n    states: ToggleBinaryStates<TA, TB>;\n    initial?: TA | TB;\n  }): ToggleInstance<TA, TB, undefined, TA | TB>;\n  <const TA, const TB, const TN>(options: {\n    states: ToggleTernaryStates<TA, TB, TN>;\n    initial?: TA | TB | TN;\n  }): ToggleInstance<TA, TB, TN, TA | TB | TN>;\n};\n\nfunction isToggleState(states: readonly unknown[], value: unknown): boolean {\n  return states.includes(value);\n}\n\nfunction indexOfState(states: readonly unknown[], value: unknown): number {\n  return states.indexOf(value);\n}\n\nfunction buildToggle<TA, TB, TN>(options: ToggleOptions<TA, TB, TN> & { initial?: unknown }) {\n  const truly = options.states.truly;\n  const falsely = options.states.falsely;\n  const hasTernaryState = \"ternary\" in options.states;\n  const ternary = (hasTernaryState ? options.states.ternary : undefined) as TN;\n  const stateValues = { truly, falsely, ternary };\n  const allStates = hasTernaryState ? [truly, falsely, ternary] : [truly, falsely];\n  const initial = (\n    \"initial\" in options ? options.initial : hasTernaryState ? ternary : truly\n  ) as unknown;\n\n  const toggle = {\n    value: initial,\n    states: stateValues,\n    truly,\n    falsely,\n    ternary,\n\n    is(value: unknown) {\n      return this.value === value;\n    },\n\n    set(value: unknown) {\n      if (!isToggleState(allStates, value) || this.value === value) {\n        return false;\n      }\n\n      this.value = value;\n      return true;\n    },\n\n    toggle() {\n      if (hasTernaryState) {\n        if (this.value === ternary) {\n          this.value = truly;\n        } else if (this.value === truly) {\n          this.value = falsely;\n        } else {\n          this.value = truly;\n        }\n      } else {\n        this.value = this.value === truly ? falsely : truly;\n      }\n\n      return this.value;\n    },\n\n    cycle() {\n      const currentIndex = indexOfState(allStates, this.value);\n      const nextIndex = (currentIndex + 1) % allStates.length;\n      this.value = allStates[nextIndex];\n      return this.value;\n    },\n\n    reset() {\n      this.value = initial;\n      return this.value;\n    },\n  };\n\n  return toggle;\n}\n\n/** Creates an independent toggle instance with optional ternary state. */\nexport function createToggle<const TA, const TB>(options: {\n  states: ToggleBinaryStates<TA, TB>;\n  initial?: TA | TB;\n}): ToggleInstance<TA, TB, undefined, TA | TB>;\nexport function createToggle<const TA, const TB, const TN>(options: {\n  states: ToggleTernaryStates<TA, TB, TN>;\n  initial?: TA | TB | TN;\n}): ToggleInstance<TA, TB, TN, TA | TB | TN>;\nexport function createToggle<const TA, const TB, const TN = undefined, const V = TA | TB>(\n  options: ToggleOptions<TA, TB, TN> & { initial?: V }\n): ToggleInstance<TA, TB, TN, V> {\n  return buildToggle(options) as unknown as ToggleInstance<TA, TB, TN, V>;\n}\n\n/** Builds callable `$toggle` magic that returns independent toggle instances. */\nexport function createToggleMagic(Alpine?: Pick<AlpineType.Alpine, \"reactive\">): ToggleMagic {\n  return ((options: Parameters<ToggleMagic>[0]) => {\n    const instance = createToggle(\n      options as ToggleOptions<unknown, unknown, unknown> & { initial?: unknown }\n    );\n    return Alpine ? Alpine.reactive(instance) : instance;\n  }) as ToggleMagic;\n}\n\n/** Alpine.js toggle plugin. Registers callable magic `$toggle`. */\nexport default function togglePlugin(Alpine: AlpineType.Alpine): void {\n  Alpine.magic(\"toggle\", () => createToggleMagic(Alpine));\n}\n"],"mappings":";AA0CA,SAAS,cAAc,QAA4B,OAAyB;AAC1E,SAAO,OAAO,SAAS,KAAK;AAC9B;AAEA,SAAS,aAAa,QAA4B,OAAwB;AACxE,SAAO,OAAO,QAAQ,KAAK;AAC7B;AAEA,SAAS,YAAwB,SAA4D;AAC3F,QAAM,QAAQ,QAAQ,OAAO;AAC7B,QAAM,UAAU,QAAQ,OAAO;AAC/B,QAAM,kBAAkB,aAAa,QAAQ;AAC7C,QAAM,UAAW,kBAAkB,QAAQ,OAAO,UAAU;AAC5D,QAAM,cAAc,EAAE,OAAO,SAAS,QAAQ;AAC9C,QAAM,YAAY,kBAAkB,CAAC,OAAO,SAAS,OAAO,IAAI,CAAC,OAAO,OAAO;AAC/E,QAAM,UACJ,aAAa,UAAU,QAAQ,UAAU,kBAAkB,UAAU;AAGvE,QAAM,SAAS;AAAA,IACb,OAAO;AAAA,IACP,QAAQ;AAAA,IACR;AAAA,IACA;AAAA,IACA;AAAA,IAEA,GAAG,OAAgB;AACjB,aAAO,KAAK,UAAU;AAAA,IACxB;AAAA,IAEA,IAAI,OAAgB;AAClB,UAAI,CAAC,cAAc,WAAW,KAAK,KAAK,KAAK,UAAU,OAAO;AAC5D,eAAO;AAAA,MACT;AAEA,WAAK,QAAQ;AACb,aAAO;AAAA,IACT;AAAA,IAEA,SAAS;AACP,UAAI,iBAAiB;AACnB,YAAI,KAAK,UAAU,SAAS;AAC1B,eAAK,QAAQ;AAAA,QACf,WAAW,KAAK,UAAU,OAAO;AAC/B,eAAK,QAAQ;AAAA,QACf,OAAO;AACL,eAAK,QAAQ;AAAA,QACf;AAAA,MACF,OAAO;AACL,aAAK,QAAQ,KAAK,UAAU,QAAQ,UAAU;AAAA,MAChD;AAEA,aAAO,KAAK;AAAA,IACd;AAAA,IAEA,QAAQ;AACN,YAAM,eAAe,aAAa,WAAW,KAAK,KAAK;AACvD,YAAM,aAAa,eAAe,KAAK,UAAU;AACjD,WAAK,QAAQ,UAAU,SAAS;AAChC,aAAO,KAAK;AAAA,IACd;AAAA,IAEA,QAAQ;AACN,WAAK,QAAQ;AACb,aAAO,KAAK;AAAA,IACd;AAAA,EACF;AAEA,SAAO;AACT;AAWO,SAAS,aACd,SAC+B;AAC/B,SAAO,YAAY,OAAO;AAC5B;AAGO,SAAS,kBAAkB,QAA2D;AAC3F,UAAQ,CAAC,YAAwC;AAC/C,UAAM,WAAW;AAAA,MACf;AAAA,IACF;AACA,WAAO,SAAS,OAAO,SAAS,QAAQ,IAAI;AAAA,EAC9C;AACF;AAGe,SAAR,aAA8B,QAAiC;AACpE,SAAO,MAAM,UAAU,MAAM,kBAAkB,MAAM,CAAC;AACxD;","names":[]}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ailuracode/alpine-toggle",
+  "version": "0.1.0",
+  "description": "Alpine.js toggle magic with binary and ternary state inference",
+  "type": "module",
+  "license": "MIT",
+  "author": "ailuracode",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ailuracode/alpine.git",
+    "directory": "packages/toggle"
+  },
+  "bugs": {
+    "url": "https://github.com/ailuracode/alpine/issues"
+  },
+  "homepage": "https://github.com/ailuracode/alpine/tree/master/packages/toggle#readme",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./global": {
+      "types": "./dist/global.d.ts"
+    }
+  },
+  "types": "./dist/global.d.ts",
+  "peerDependencies": {
+    "alpinejs": "^3.0.0",
+    "@types/alpinejs": "^3.13.11"
+  },
+  "peerDependenciesMeta": {
+    "@types/alpinejs": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "alpinejs",
+    "alpine",
+    "plugin",
+    "toggle",
+    "state"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --sourcemap --out-dir dist && cp src/global.d.ts dist/global.d.ts",
+    "test": "vitest run --config ../../vitest.config.ts test"
+  }
+}