@bedlamhotel/attrmanager 0.2.0

package/dist/js/bh-attrmanager.js

@@ -0,0 +1,143 @@
+(function (global, factory) {
+    typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
+    typeof define === 'function' && define.amd ? define(factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, global.BhAttrManager = factory());
+})(this, (function () { 'use strict';
+
+    /**
+     * A class used to create and/or enforce HTMLElement attribute values.
+     */
+    class BhAttrManager {
+        el;
+        /** Unique ID for self-removal from `restorers` array. */
+        id;
+        /** An array of the attributes under management in BhNormalizedAttr form. */
+        items = [];
+        /** An array of the attribute values (used to restore initial DOM state). */
+        original = [];
+        /** A var used to track the state of the attributes under management. */
+        currentState = false;
+        /** Optional reference to the restorer array for self-removal. */
+        restorers;
+        /**
+         * Generates a unique ID for this instance.
+         */
+        static createId() {
+            return Math.random().toString(36).slice(2, 7);
+        }
+        /**
+         * Constructs a new BhAttrManager instance.
+         *
+         * @param el
+         *   The HTMLElement to manage.
+         * @param config
+         *   The attribute configuration.
+         * @param restorers
+         *   Optional restorer array for lifecycle management.
+         */
+        constructor(el, config, restorers) {
+            this.el = el;
+            let hasExplicitInitial = false;
+            // Generate unique ID for self-removal from restorers
+            this.id = BhAttrManager.createId();
+            for (const [name, { whenTrue: trueValue, whenFalse, initial, fixed },] of Object.entries(config)) {
+                if (trueValue === undefined) {
+                    throw new Error("BhAttrManager: each attribute must supply a `whenTrue` value.");
+                }
+                if (initial !== undefined &&
+                    !["whenTrue", "whenFalse", null].includes(initial)) {
+                    throw new Error("BhAttrManager: if attributes supply an `initial` value, it must be one of `whenTrue`, `whenFalse`, or `null`.");
+                }
+                const originalVal = el.getAttribute(name);
+                this.original.push([name, originalVal]);
+                const falseValue = whenFalse !== undefined ? whenFalse : originalVal;
+                this.items.push({ name, trueValue, falseValue, fixed: !!fixed });
+                if (initial !== undefined) {
+                    this.applyValue(name, initial === "whenTrue" ? trueValue : falseValue);
+                    if (!hasExplicitInitial) {
+                        this.currentState = initial === "whenTrue";
+                        hasExplicitInitial = true;
+                    }
+                }
+            }
+            // Register restorer with ID for self-removal
+            if (restorers) {
+                this.restorers = restorers;
+                restorers.push({
+                    id: this.id,
+                    restore: () => this.restore(),
+                });
+            }
+        }
+        /**
+         * Toggles state of attributes managed by this instance.
+         *
+         * @param condition
+         *   The condition to set. If omitted, toggles the current state.
+         */
+        toggle(condition) {
+            this.currentState = condition ?? !this.currentState;
+            for (const { name, trueValue, falseValue, fixed } of this.items) {
+                if (fixed) {
+                    continue;
+                }
+                this.applyValue(name, this.currentState ? trueValue : falseValue);
+            }
+        }
+        /**
+         * Restores original state of attributes.
+         *
+         * @param teardown
+         *   If `true` (default), also clears internal state and self-removes from
+         *   `restorers`.
+         */
+        restore(teardown = false) {
+            for (const [name, value] of this.original) {
+                this.applyValue(name, value);
+            }
+            if (teardown) {
+                this.destroy();
+            }
+        }
+        /**
+         * Clears internal state and self-removes from `restorers`.
+         *
+         * Use this to clean up state without affecting the DOM.
+         */
+        destroy() {
+            // Remove self from restorers if registered
+            if (this.restorers) {
+                const index = this.restorers.findIndex((r) => r.id === this.id);
+                if (index > -1) {
+                    this.restorers.splice(index, 1);
+                }
+            }
+            // Clear all state
+            this.items = [];
+            this.original = [];
+            this.currentState = false;
+        }
+        /**
+         * Handles actual DOM attribute manipulation for toggle(), restore().
+         *
+         * @param name
+         *   The attribute name.
+         * @param value
+         *   The value to set. Pass `null` to remove the attribute.
+         */
+        applyValue(name, value) {
+            if (this.el.getAttribute(name) === value) {
+                return;
+            }
+            if (value === null) {
+                this.el.removeAttribute(name);
+            }
+            else {
+                this.el.setAttribute(name, value);
+            }
+        }
+    }
+
+    return BhAttrManager;
+
+}));

package/dist/js/bh-attrmanager.min.js

@@ -0,0 +1,2 @@
+/*! bh-attrmanager 0.0.0 — © Christopher Torgalson */
+var global,factory;global=this,factory=function(){class BhAttrManager{el;id;items=[];original=[];currentState=!1;restorers;static createId(){return Math.random().toString(36).slice(2,7)}constructor(t,e,r){this.el=t;let i=!1;this.id=BhAttrManager.createId();for(const[r,{whenTrue:s,whenFalse:a,initial:o,fixed:n}]of Object.entries(e)){if(void 0===s)throw new Error("BhAttrManager: each attribute must supply a `whenTrue` value.");if(void 0!==o&&!["whenTrue","whenFalse",null].includes(o))throw new Error("BhAttrManager: if attributes supply an `initial` value, it must be one of `whenTrue`, `whenFalse`, or `null`.");const e=t.getAttribute(r);this.original.push([r,e]);const l=void 0!==a?a:e;this.items.push({name:r,trueValue:s,falseValue:l,fixed:!!n}),void 0!==o&&(this.applyValue(r,"whenTrue"===o?s:l),i||(this.currentState="whenTrue"===o,i=!0))}r&&(this.restorers=r,r.push({id:this.id,restore:()=>this.restore()}))}toggle(t){this.currentState=t??!this.currentState;for(const{name:t,trueValue:e,falseValue:r,fixed:i}of this.items)i||this.applyValue(t,this.currentState?e:r)}restore(t=!1){for(const[t,e]of this.original)this.applyValue(t,e);t&&this.destroy()}destroy(){if(this.restorers){const t=this.restorers.findIndex(t=>t.id===this.id);t>-1&&this.restorers.splice(t,1)}this.items=[],this.original=[],this.currentState=!1}applyValue(t,e){this.el.getAttribute(t)!==e&&(null===e?this.el.removeAttribute(t):this.el.setAttribute(t,e))}}return BhAttrManager},"object"==typeof exports&&"undefined"!=typeof module?module.exports=factory():"function"==typeof define&&define.amd?define(factory):(global="undefined"!=typeof globalThis?globalThis:global||self).BhAttrManager=factory();

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@bedlamhotel/attrmanager",
+  "type": "module",
+  "version": "0.2.0",
+  "description": "Utility library for toggling HTML attributes and optionally restoring them to their original values.",
+  "homepage": "https://github.com/ctorgalson/bh-attrmanager",
+  "license": "GPL-2.0-or-later",
+  "main": "dist/js/attr-manager.js",
+  "module": "dist/js/attr-manager.esm.js",
+  "types": "dist/js/attr-manager.d.ts",
+  "exports": {
+    ".": {
+      "import": "dist/js/attr-manager.esm.js",
+      "browser": "dist/js/attr-manager.js",
+      "require": "dist/js/attr-manager.cjs",
+      "types": "dist/js/attr-manager.d.ts"
+    },
+    "./*": "./*"
+  },
+  "keywords": [
+    "html",
+    "DOM"
+  ],
+  "author": "Christopher Torgalson",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ctorgalson/bh-attrmanager.git"
+  },
+  "files": [
+    "dist/*"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "preview": "vite preview",
+    "build": "concurrently --raw npm:build:*",
+    "build:docs": "typedoc --logLevel Verbose --coverageLabel 'Docs' --coverageOutputType json && node scripts/typedoc-coverage.cjs",
+    "build:ts": "rollup --config",
+    "start": "npm run build ; npm run watch",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage && node scripts/vitest-coverage.cjs",
+    "test:watch": "vitest",
+    "coverage:badges": "node scripts/typedoc-coverage.cjs && node scripts/vitest-coverage.cjs",
+    "watch": "concurrently --kill-others --raw npm:watch:*",
+    "watch:md": "onchange 'README.md' -- npm run build:docs",
+    "watch:ts": "onchange 'src/**/*.ts' -- concurrently --raw npm:build:ts npm:build:docs"
+  },
+  "devDependencies": {
+    "@rollup/plugin-terser": "^1.0.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "badge-maker": "^6.0.0",
+    "concurrently": "^10.0.5",
+    "jsdom": "^30.0.1",
+    "onchange": "^7.1.0",
+    "prettier": "^3.9.6",
+    "rollup": "^4.63.0",
+    "typedoc-plugin-coverage": "^4.0.3",
+    "typedoc-plugin-markdown": "^4.13.0",
+    "typedoc-plugin-mdn-links": "^5.1.1",
+    "typedoc-plugin-rename-defaults": "^0.7.3",
+    "typescript": "~6.0.2",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11",
+    "@rollup/plugin-node-resolve": "^16.0.3"
+  }
+}