@johnhenry/cyclable 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Henry
+
+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,173 @@
+# cyclable
+
+[![npm version](https://img.shields.io/npm/v/%40johnhenry%2Fcyclable.svg)](https://www.npmjs.com/package/@johnhenry/cyclable)
+[![CI](https://github.com/johnhenry/cyclable/actions/workflows/ci.yml/badge.svg)](https://github.com/johnhenry/cyclable/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/%40johnhenry%2Fcyclable.svg)](LICENSE)
+
+Full documentation: [opensource.johnhenry.me/cyclable](https://opensource.johnhenry.me/cyclable/)
+
+> **Provenance:** originally four individually-versioned modules under
+> [`johnhenry/lib`](https://github.com/johnhenry/lib)'s `js/` directory
+> (`js/localstorage-cycler/0.0.0/`, `js/localstorage-class-cycler/0.0.0/`,
+> `js/class-cycler.component/0.0.0/`, `js/class-cycler.button.component/0.0.0/`),
+> then briefly part of [`@johnhenry/domkit`](https://github.com/johnhenry/domkit)'s
+> ~33-module toolkit, now extracted into this standalone package because
+> the four form a real, coherent family — one engine plus wrapper variants
+> — rather than an unrelated grab-bag of widgets. `domkit` no longer
+> carries this functionality. See `## Family` below and `CHANGELOG.md` for
+> the full history.
+
+A localStorage-backed value cycler: **one engine, three consumption
+shapes.** `localStorageCycler` cycles a `localStorage`-backed value
+through a fixed list of strings and calls an optional change handler.
+`classStorageCycler` wraps it to apply the cycled value as a CSS class on
+a DOM element. `<class-cycler>` and
+`<button is="class-cycler-button">` are two ready-made custom elements
+built on that wrapper — a global-function variant and a self-contained
+button variant, respectively. All four modules are independent files
+under `src/`, importable individually with no shared barrel and no build
+step.
+
+## Install
+
+```bash
+npm install @johnhenry/cyclable
+```
+
+## `localstorage-cycler` — the engine
+
+Cycle a `localStorage` value through a given list of strings.
+
+```javascript
+import localStorageCycler from "@johnhenry/cyclable/localstorage-cycler/index.mjs";
+const updateLocalStorage = localStorageCycler("my-key", "a", "b", "c");
+```
+
+The call to `localStorageCycler` checks for the existence of the key
+(`"my-key"`) in `localStorage`, and sets it to the first value (`"a"`) if
+not already set.
+
+When called, the returned `updateLocalStorage` function cycles the value
+associated with the key in `localStorage` through the given values (`"a"`,
+`"b"`, and `"c"`).
+
+`updateLocalStorage` returns an object with the following keys:
+
+- `key` — the associated local storage key
+- `value` — the current value of the local storage item
+- `index` — the current index of the local storage item
+- `result` — the result of a handler, if passed (see below)
+
+### Change handler
+
+To react to the change, pass an optional change handler as the second
+parameter to `localStorageCycler`.
+
+```javascript
+const onChange = ({ value, key, index, events }) =>
+  console.log({ value, key, index, events });
+const updateLocalStorage = localStorageCycler(
+  "my-key",
+  onChange,
+  "a",
+  "b",
+  "c"
+);
+```
+
+The handler takes four parameters:
+
+- the same `key`, `value`, and `index` parameters returned from calling
+  `updateLocalStorage`
+- an `events` parameter — an array of everything passed into the
+  `updateLocalStorage` function, or an `init` `CustomEvent` if fired from
+  the initial call to `localStorageCycler`
+
+## `localstorage-class-cycler` — apply the cycled value as a class
+
+Cycle a `localStorage` value through a given list of strings, and render
+the cycled value as a class on a given element.
+
+```javascript
+import classStorageCycler from "@johnhenry/cyclable/localstorage-class-cycler/index.mjs";
+const updateBodyClass = classStorageCycler(
+  document.body,
+  "my-key",
+  "a",
+  "b",
+  "c"
+);
+updateBodyClass();
+```
+
+## `class-cycler.component` — global-function custom element
+
+Exposes a `localstorage-class-cycler` instance as a named global
+function, so it can be called from anywhere (e.g. a plain `<button
+onclick="...">`).
+
+| Attribute | Description |
+|---|---|
+| `global` | Name to assign the cycler function to on `globalThis` (required — removing this attribute, or disconnecting the element, unassigns it) |
+| `selector` | Selector for the element whose classes get cycled. Defaults to `body` |
+| `storage-key` | localStorage key the current class value persists under |
+| `classes` | Comma-delimited list of classes to cycle through |
+
+```html
+<script
+  type="module"
+  src="https://esm.sh/@johnhenry/cyclable/class-cycler.component/global.mjs"
+></script>
+<class-cycler
+  global="cycleTheme"
+  selector="body"
+  storage-key="theme"
+  classes="light,dark,system"
+></class-cycler>
+<button onclick="cycleTheme()">Toggle theme</button>
+```
+
+## `class-cycler.button.component` — self-contained button custom element
+
+A `<button is="class-cycler-button">` that cycles the classes of one or
+more target elements every time it's clicked.
+
+| Attribute | Description |
+|---|---|
+| `select` | Selector for a single target element. Defaults to `html` if neither `select` nor `select-all` is set |
+| `select-all` | Selector for multiple target elements (all matches get cycled together) |
+| `storage-key` | localStorage key the current class value persists under |
+| `classes` | Comma-delimited list of classes to cycle through |
+
+```html
+<script
+  type="module"
+  src="https://esm.sh/@johnhenry/cyclable/class-cycler.button.component/global.mjs"
+></script>
+<button
+  is="class-cycler-button"
+  select="body"
+  storage-key="theme"
+  classes="light,dark,system"
+>
+  Toggle theme
+</button>
+```
+
+## Family
+
+- [`@johnhenry/domkit`](https://github.com/johnhenry/domkit) — the
+  ~33-module DOM/HTML-component toolkit this package was extracted from.
+  domkit is a real npm dependency of neither direction of this
+  relationship — it does not depend on cyclable, and cyclable does not
+  depend on domkit; the four modules here simply no longer live in
+  domkit's `src/`.
+- [`@johnhenry/domable`](https://github.com/johnhenry/domable) — the DOM
+  ⇄ text ⇄ React conversion primitives domkit itself builds on. Unrelated
+  to this package's functionality; listed here only because it's the
+  other sibling extraction in this same lineage
+  (`johnhenry/lib` → `johnhenry/domkit` → standalone package).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@johnhenry/cyclable",
+  "version": "0.0.0",
+  "description": "A localStorage-backed value cycler: one engine, a class-cycler wrapper, and two ready-made custom elements for cycling CSS classes on click.",
+  "type": "module",
+  "exports": {
+    "./*": "./src/*"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "test": "node scripts/check-syntax.mjs"
+  },
+  "keywords": [
+    "html",
+    "dom",
+    "web-components",
+    "custom-elements",
+    "localstorage",
+    "cycler",
+    "theme-toggle"
+  ],
+  "author": "John Henry",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnhenry/cyclable.git"
+  },
+  "homepage": "https://opensource.johnhenry.me/cyclable/",
+  "engines": {
+    "node": ">=26.0.0"
+  }
+}

package/src/class-cycler.button.component/global.mjs

@@ -0,0 +1,4 @@
+import DefineComponent from "./index.mjs";
+globalThis.customElements.define("class-cycler-button", DefineComponent, {
+  extends: "button",
+});

package/src/class-cycler.button.component/index.mjs

@@ -0,0 +1,46 @@
+import classCycler from "../localstorage-class-cycler/index.mjs";
+
+const DEFAULT_SELECTOR = "html";
+export default class extends globalThis.HTMLButtonElement {
+  updateBound = null;
+  constructor() {
+    super();
+  }
+  connectedCallback() {
+    this.init();
+    this.updateBound = this.update.bind(this);
+    this.addEventListener("click", this.updateBound);
+  }
+  disconnectedCallback() {
+    this.removeEventListener("click", this.updateBound);
+  }
+  update() {
+    this.classCycler?.();
+  }
+  init() {
+    const selectors = [];
+    if (this.getAttribute("select")) {
+      selectors.push(document.querySelector(this.getAttribute("select")));
+    } else if (this.getAttribute("select-all")) {
+      selectors.push(
+        ...document.querySelectorAll(this.getAttribute("select-all"))
+      );
+    }
+    if (
+      !selectors.length &&
+      this.getAttribute("select") !== "" &&
+      this.getAttribute("select-all") !== ""
+    ) {
+      selectors.push(document.querySelector(DEFAULT_SELECTOR));
+    }
+    const storageKey = this.getAttribute("storage-key");
+    const classes = (this.getAttribute("classes") || "").split(",");
+    this.classCycler = classCycler(selectors, storageKey, ...classes);
+  }
+  static get observedAttributes() {
+    return ["select", "storage-key", "select-all", "classes"];
+  }
+  attributeChangedCallback() {
+    this.init();
+  }
+}

package/src/class-cycler.button.component/readme.md

@@ -0,0 +1,34 @@
+# Class Cycler Button
+
+A `<button is="class-cycler-button">` that cycles the classes of one or
+more target elements every time it's clicked, via
+[localstorage-class-cycler](../localstorage-class-cycler/readme.md).
+Self-contained button variant — see
+[class-cycler.component](../class-cycler.component/readme.md)
+for a global-function variant callable from anywhere.
+
+## Attributes
+
+| Attribute | Description |
+|---|---|
+| `select` | Selector for a single target element. Defaults to `html` if neither `select` nor `select-all` is set |
+| `select-all` | Selector for multiple target elements (all matches get cycled together) |
+| `storage-key` | localStorage key the current class value persists under |
+| `classes` | Comma-delimited list of classes to cycle through |
+
+## Usage
+
+```html
+<script
+  type="module"
+  src="https://esm.sh/@johnhenry/domkit/class-cycler.button.component/global.mjs"
+></script>
+<button
+  is="class-cycler-button"
+  select="body"
+  storage-key="theme"
+  classes="light,dark,system"
+>
+  Toggle theme
+</button>
+```

package/src/class-cycler.component/global.mjs

@@ -0,0 +1,2 @@
+import DefineComponent from "./index.mjs";
+globalThis.customElements.define("class-cycler", DefineComponent);

package/src/class-cycler.component/index.mjs

@@ -0,0 +1,40 @@
+import classCycler from "../localstorage-class-cycler/index.mjs";
+const DEFAULT_SELECTOR = "body";
+export default class extends globalThis.HTMLElement {
+  constructor() {
+    super();
+  }
+  connectedCallback() {
+    this.reset();
+  }
+  reset() {
+    const global = this.getAttribute("global");
+    if (global) {
+      const selector = this.getAttribute("selector") || DEFAULT_SELECTOR;
+      const storageKey = this.getAttribute("storage-key");
+      const classes = (this.getAttribute("classes") || "").split(",");
+      globalThis[global] = classCycler(
+        document.querySelector(selector),
+        storageKey,
+        ...classes
+      );
+    }
+  }
+  disconnectedCallback() {
+    delete globalThis[this.getAttribute("global")];
+  }
+  static get observedAttributes() {
+    return ["global", "selector", "storage-key", "classes"];
+  }
+  attributeChangedCallback(name, old, current) {
+    switch (name) {
+      case "global":
+        if (old && !current) {
+          delete globalThis[old];
+          return;
+        }
+        break;
+    }
+    this.reset();
+  }
+}

package/src/class-cycler.component/readme.md

@@ -0,0 +1,32 @@
+# Class Cycler
+
+Exposes a [localstorage-class-cycler](../localstorage-class-cycler/readme.md)
+instance as a named global function, so it can be called from anywhere
+(e.g. a plain `<button onclick="...">`). Container/global variant — see
+[class-cycler.button.component](../class-cycler.button.component/readme.md)
+for a self-contained `<button>` element that cycles its own classes.
+
+## Attributes
+
+| Attribute | Description |
+|---|---|
+| `global` | Name to assign the cycler function to on `globalThis` (required — removing this attribute, or disconnecting the element, unassigns it) |
+| `selector` | Selector for the element whose classes get cycled. Defaults to `body` |
+| `storage-key` | localStorage key the current class value persists under |
+| `classes` | Comma-delimited list of classes to cycle through |
+
+## Usage
+
+```html
+<script
+  type="module"
+  src="https://esm.sh/@johnhenry/domkit/class-cycler.component/global.mjs"
+></script>
+<class-cycler
+  global="cycleTheme"
+  selector="body"
+  storage-key="theme"
+  classes="light,dark,system"
+></class-cycler>
+<button onclick="cycleTheme()">Toggle theme</button>
+```

package/src/localstorage-class-cycler/index.mjs

@@ -0,0 +1,14 @@
+import localStorageCycler from "../localstorage-cycler/index.mjs";
+export default (targets, key, ...classes) => {
+  const values = classes;
+  const emit = ({ value }) => {
+    const target_list = Array.isArray(targets) ? targets : [targets];
+    for (const target of target_list) {
+      target.classList.remove(...values.filter((s) => s));
+      if (value) {
+        target.classList.add(value);
+      }
+    }
+  };
+  return localStorageCycler(key, emit, ...values);
+};

package/src/localstorage-class-cycler/readme.md

@@ -0,0 +1,18 @@
+# LocalStorage Cycler
+
+Cycle local storage values through a given list of strings.
+Renders cycled value as class on given element.
+
+## Usage
+
+```javascript
+import classStorageCycler from "..";
+const updateBodyClass = classStorageCycler(
+  document.body,
+  "my-key",
+  "a",
+  "b",
+  "c"
+);
+updateBodyClass();
+```

package/src/localstorage-cycler/class.mjs

@@ -0,0 +1,11 @@
+import localStorageCycler from "./index.mjs";
+export default (target, key, ...classes) => {
+  const values = classes;
+  const emit = ({ value }) => {
+    target.classList.remove(...values.filter((s) => s));
+    if (value) {
+      target.classList.add(value);
+    }
+  };
+  return localStorageCycler(key, emit, ...values);
+};

package/src/localstorage-cycler/index.mjs

@@ -0,0 +1,31 @@
+const createNext =
+  (key, handler, ...values) =>
+  (...events) => {
+    const stored = globalThis.localStorage.getItem(key);
+    const index = values.indexOf(stored) + 1;
+    const value = values[index] ?? values[0];
+    globalThis.localStorage.setItem(key, value);
+    return {
+      value,
+      key,
+      index,
+      result: handler({ value, key, index, events }),
+    };
+  };
+export default (key, ...values) => {
+  if (!key) {
+    throw new Error("key is required");
+  }
+  const handler = typeof values[0] === "function" ? values.shift() : () => {};
+  const stored = globalThis.localStorage.getItem(key) ?? values[0];
+  const index = values.indexOf(stored);
+  const value = values[index] ?? values[0];
+  globalThis.localStorage.setItem(key, value);
+  handler({
+    value,
+    key,
+    index,
+    events: [new CustomEvent("init", { detail: { value, key, index } })],
+  });
+  return createNext(key, handler, ...values);
+};

package/src/localstorage-cycler/readme.md

@@ -0,0 +1,54 @@
+# LocalStorage Cycler
+
+Cycle local storage values through a given list of strings
+
+## Usage
+
+```javascript
+import localStorageCycler from "?";
+const updateLocalStorage = localStorageCycler("my-key", "a", "b", "c");
+```
+
+The call to "localStorageCycler"
+checks for the existence
+of the key ("my-key") in localStorage.
+and sets it to the first key ("a") if not already set.
+
+When called, the "updateLocalStorage" function
+cycles the value associated with the key
+in localStorage through the given values ("a", "b", and "c").
+
+The "updateLocalStorage" returns an object with the following keys:
+
+- key - the associated local storage key
+- value - the current value of the local storage item
+- index - the current index of the local storage item
+- result - the reuslt of an handler, if passed (see below)
+
+## Change Handler
+
+To react to the change,
+pass a optional change handler
+as the second parameter to "localStorageCycler".
+
+```javascript
+const onChange = ({ value, key, index, events }) =>
+  console.log({ value, key, index, events });
+const updateLocalStorage = localStorageCycler(
+  "my-key",
+  onChange,
+  "a",
+  "b",
+  "c"
+);
+```
+
+The handler takes four parametes:
+
+- the same, "key", "value", and "index" parameters
+  returned from calling "updateLocalStorage"
+
+- an "events" parameter -- an array of everything
+  passed into the "updateLocalStorage" function OR
+  an "init" CustomEvent if fired from the initial
+  call to localStorageCycler.