lume-js 2.0.1 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lume-js",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "Minimal reactive state management using only standard JavaScript and HTML - no custom syntax, no build step required",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",
@@ -28,14 +28,19 @@
     "dev": "vite",
     "dev:site": "node scripts/build-site-assets.js && vite -c vite.site.config.js",
     "build:site": "node scripts/build-site-assets.js && vite build -c vite.site.config.js",
+    "preview:site": "node scripts/build-site-assets.js && vite build -c vite.site.config.js --base / && vite preview -c vite.site.config.js --base /",
     "build": "node scripts/build.js",
-    "size": "node scripts/check-size.js",
+    "size": "npm run build && node scripts/check-size.js",
+    "size:ci": "node scripts/check-size.js",
+    "bench": "npm run build && node scripts/bench-core.js",
+    "complexity": "node scripts/complexity.js",
+    "lint": "eslint src/",
     "test": "vitest run",
     "test:watch": "vitest",
     "coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
-    "validate": "npm run size && npm run typecheck && npm test",
-    "prepublishOnly": "npm run build && npm run validate"
+    "validate": "npm run build && node scripts/check-size.js && node scripts/complexity.js && npm run lint && npm run typecheck && npm run coverage",
+    "prepublishOnly": "npm run validate"
   },
   "files": [
     "dist",
@@ -77,6 +82,8 @@
     "@tailwindcss/typography": "^0.5.19",
     "@vitest/coverage-v8": "^2.1.4",
     "autoprefixer": "^10.4.22",
+    "eslint": "^10.3.0",
+    "eslint-plugin-sonarjs": "^4.0.3",
     "highlight.js": "^11.11.1",
     "jsdom": "^25.0.1",
     "marked": "^17.0.1",
@@ -90,4 +97,4 @@
   "engines": {
     "node": ">=20.19.0"
   }
-}
+}

package/src/addons/index.d.ts

@@ -56,26 +56,44 @@ export interface Computed<T> {
  */
 export function computed<T>(fn: () => T): Computed<T>;
 
+export interface WatchOptions {
+  /**
+   * Whether to call the callback immediately with the current value (default: true).
+   * Set to false to skip the initial call and only react to future changes.
+   */
+  immediate?: boolean;
+}
+
 /**
  * Watch a single key on a reactive state object; convenience wrapper around $subscribe.
- * 
+ *
+ * By default the callback fires immediately with the current value, then on every change.
+ * Pass `{ immediate: false }` to skip the initial call and only react to future changes.
+ *
  * @param store - Reactive state object created with state().
  * @param key - Property key to observe.
- * @param callback - Invoked immediately and on subsequent changes.
+ * @param callback - Called with new value on change (and immediately unless immediate=false).
+ * @param options - Watch options
  * @returns Unsubscribe function for cleanup
  * @throws {Error} If store is not a reactive state object
- * 
+ *
  * @example
  * ```typescript
  * import { state } from 'lume-js';
  * import { watch } from 'lume-js/addons';
- * 
+ *
  * const store = state({ count: 0 });
- * 
+ *
+ * // Fires immediately with 0, then on every change
  * const unwatch = watch(store, 'count', (value) => {
  *   console.log('Count is now:', value);
  * });
- * 
+ *
+ * // Only fires on future changes (not the initial value)
+ * watch(store, 'count', (value) => {
+ *   console.log('Count changed to:', value);
+ * }, { immediate: false });
+ *
  * // Cleanup
  * unwatch();
  * ```
@@ -83,7 +101,8 @@ export function computed<T>(fn: () => T): Computed<T>;
 export function watch<T extends object, K extends keyof T>(
   store: ReactiveState<T>,
   key: K,
-  callback: Subscriber<T[K]>
+  callback: Subscriber<T[K]>,
+  options?: WatchOptions
 ): Unsubscribe;
 
 /**

package/src/addons/repeat.js

@@ -35,7 +35,7 @@
  * ═══════════════════════════════════════════════════════════════════════
  * PATTERN 2: Clean separation (create + update) - recommended
  * ═══════════════════════════════════════════════════════════════════════
- * 
+ *
  *   repeat('#list', store, 'todos', {
  *     key: todo => todo.id,
  *     create: (todo, el) => {
@@ -47,6 +47,11 @@
  *       btn.textContent = 'Delete';
  *       btn.onclick = () => deleteTodo(todo.id);
  *       el.appendChild(btn);
+ *
+ *       // Return a cleanup function — called automatically when element is removed
+ *       return () => {
+ *         // Unsubscribe from external listeners, remove timers, etc.
+ *       };
  *     },
  *     update: (todo, el, index, { isFirstRender }) => {
  *       // Called on every update - bind data
@@ -165,8 +170,9 @@ export function defaultScrollPreservation(container, context = {}) {
  * @param {Object} options - Configuration
  * @param {Function} options.key - Function to extract unique key: (item) => key
  * @param {Function} [options.render] - Function to render item (called for all items): (item, element, index) => void
- * @param {Function} [options.create] - Function for new elements only: (item, element, index) => void
+ * @param {Function} [options.create] - Function for new elements only: (item, element, index) => void | Function. If a function is returned, it is registered as the element's cleanup and called automatically when the element is removed (by list update or full cleanup).
  * @param {Function} [options.update] - Function for data binding: (item, element, index, { isFirstRender }) => void. Skipped if same item reference AND same index.
+ * @param {Function} [options.remove] - Additional cleanup when element is removed: (item, element) => void. Called after any cleanup function returned by create(). Optional — prefer returning a cleanup from create() for automatic lifecycle management.
  * @param {string|Function} [options.element='div'] - Element tag name or factory function
  * @param {Function|null} [options.preserveFocus=defaultFocusPreservation] - Focus preservation strategy (null to disable)
  * @param {Function|null} [options.preserveScroll=defaultScrollPreservation] - Scroll preservation strategy (null to disable)
@@ -179,6 +185,7 @@ export function repeat(container, store, arrayKey, options) {
     render,
     create,
     update,
+    remove,
     element = 'div',
     preserveFocus = defaultFocusPreservation,
     preserveScroll = defaultScrollPreservation
@@ -209,6 +216,8 @@ export function repeat(container, store, arrayKey, options) {
   const prevItemsByKey = new Map();
   // key -> previous index (for reorder detection)
   const prevIndexByKey = new Map();
+  // key -> cleanup function returned by create()
+  const cleanupByKey = new Map();
   const seenKeys = new Set();
 
   function createElement() {
@@ -250,6 +259,7 @@ export function repeat(container, store, arrayKey, options) {
     if (restoreScroll) restoreScroll();
   }
 
+  // eslint-disable-next-line sonarjs/cognitive-complexity -- keyed DOM reconciliation: create/reuse/remove nodes, key dedup, scroll/focus preservation
   function updateList() {
     const items = store[arrayKey];
 
@@ -293,7 +303,10 @@ export function repeat(container, store, arrayKey, options) {
       try {
         // Call create for new elements (DOM structure)
         if (isFirstRender && create) {
-          create(item, el, i);
+          const cleanup = create(item, el, i);
+          if (typeof cleanup === 'function') {
+            cleanupByKey.set(k, cleanup);
+          }
         }
 
         // Call update for data binding (new and existing elements)
@@ -320,6 +333,7 @@ export function repeat(container, store, arrayKey, options) {
       nextEls.push(el);
     }
 
+    // eslint-disable-next-line sonarjs/cognitive-complexity -- DOM cleanup pass: remove stale nodes, call per-item cleanup callbacks, update maps
     applyPreservation(containerEl, () => {
       reconcileDOM(containerEl, nextEls);
 
@@ -327,9 +341,24 @@ export function repeat(container, store, arrayKey, options) {
       if (elementsByKey.size !== seenKeys.size) {
         for (const k of elementsByKey.keys()) {
           if (!seenKeys.has(k)) {
+            const el = elementsByKey.get(k);
+            const prevItem = prevItemsByKey.get(k);
+            // Call create-returned cleanup first, then remove callback
+            const cleanup = cleanupByKey.get(k);
+            if (typeof cleanup === 'function') {
+              try {
+                cleanup();
+              } catch (err) {
+                logError(`[Lume.js] repeat(): cleanup error for key "${k}":`, err);
+              }
+            }
+            if (typeof remove === 'function' && el) {
+              remove(prevItem, el);
+            }
             elementsByKey.delete(k);
             prevItemsByKey.delete(k);
             prevIndexByKey.delete(k);
+            cleanupByKey.delete(k);
           }
         }
       }
@@ -354,10 +383,25 @@ export function repeat(container, store, arrayKey, options) {
     updateList();
     logWarn('[Lume.js] repeat(): store is not reactive (no $subscribe or subscribe method)');
     return () => {
+      for (const [k, el] of elementsByKey) {
+        const prevItem = prevItemsByKey.get(k);
+        const cleanup = cleanupByKey.get(k);
+        if (typeof cleanup === 'function') {
+          try {
+            cleanup();
+          } catch (err) {
+            logError(`[Lume.js] repeat(): cleanup error for key "${k}":`, err);
+          }
+        }
+        if (typeof remove === 'function') {
+          remove(prevItem, el);
+        }
+      }
       containerEl.replaceChildren();
       elementsByKey.clear();
       prevItemsByKey.clear();
       prevIndexByKey.clear();
+      cleanupByKey.clear();
       seenKeys.clear();
     };
   }
@@ -366,11 +410,27 @@ export function repeat(container, store, arrayKey, options) {
     if (typeof unsubscribe === 'function') {
       unsubscribe();
     }
+    // Invoke cleanup and remove callback for all remaining elements before clearing
+    for (const [k, el] of elementsByKey) {
+      const prevItem = prevItemsByKey.get(k);
+      const cleanup = cleanupByKey.get(k);
+      if (typeof cleanup === 'function') {
+        try {
+          cleanup();
+        } catch (err) {
+          logError(`[Lume.js] repeat(): cleanup error for key "${k}":`, err);
+        }
+      }
+      if (typeof remove === 'function') {
+        remove(prevItem, el);
+      }
+    }
     // Clear DOM elements (replaceChildren is faster than loop)
     containerEl.replaceChildren();
     elementsByKey.clear();
     prevItemsByKey.clear();
     prevIndexByKey.clear();
+    cleanupByKey.clear();
     seenKeys.clear();
   };
 }

package/src/addons/watch.js

@@ -3,11 +3,20 @@
  * @param {Object} store - reactive store created with state()
  * @param {string} key - key in store to watch
  * @param {Function} callback - called with new value
+ * @param {Object} [options]
+ * @param {boolean} [options.immediate=true] - call callback immediately with current value
  * @returns {Function} unsubscribe function
  */
-export function watch(store, key, callback) {
+export function watch(store, key, callback, { immediate = true } = {}) {
   if (!store.$subscribe) {
     throw new Error("store must be created with state()");
   }
+  if (!immediate) {
+    let skipped = false;
+    return store.$subscribe(key, (val) => {
+      if (!skipped) { skipped = true; return; }
+      callback(val);
+    });
+  }
   return store.$subscribe(key, callback);
 }

package/src/core/effect.js

@@ -58,6 +58,7 @@ let currentEffect = null;
  *   analytics.log(store.count);  // Won't track store.count automatically
  * }, [[store, 'count']]);        // Explicit: only re-run on store.count
  */
+// eslint-disable-next-line sonarjs/cognitive-complexity -- handles both auto-tracking and explicit-deps modes with cleanup; splitting would require exporting internal state
 export function effect(fn, deps) {
   if (typeof fn !== 'function') {
     throw new Error('effect() requires a function');

package/src/core/state.js

@@ -100,6 +100,7 @@ export function state(obj) {
     if (flushScheduled) return;
 
     flushScheduled = true;
+    // eslint-disable-next-line sonarjs/cognitive-complexity -- single-pass flush loop: hooks → subscribers → effects → cycle detection; must stay atomic
     queueMicrotask(() => {
       let iterations = 0;
       const MAX_ITERATIONS = 100;

package/src/handlers/ariaAttr.js

@@ -0,0 +1,14 @@
+/**
+ * Create a handler for an ARIA attribute.
+ * Coerces value to "true"/"false" string — use stringAttr("aria-X") for token/string ARIA attrs.
+ *
+ * @param {string} name - ARIA name, with or without "aria-" prefix
+ * @returns {{ attr: string, apply: function }}
+ */
+export function ariaAttr(name) {
+  const fullName = name.startsWith('aria-') ? name : `aria-${name}`;
+  return {
+    attr: `data-${fullName}`,
+    apply(el, val) { el.setAttribute(fullName, val ? 'true' : 'false'); }
+  };
+}

package/src/handlers/boolAttr.js

@@ -0,0 +1,14 @@
+/**
+ * Create a handler for any HTML boolean attribute.
+ * Uses toggleAttribute() — works correctly with any attribute name
+ * (readonly, contenteditable, etc.) without worrying about camelCase property names.
+ *
+ * @param {string} name - Attribute name (e.g., 'readonly', 'open', 'contenteditable')
+ * @returns {{ attr: string, apply: function }}
+ */
+export function boolAttr(name) {
+  return {
+    attr: `data-${name}`,
+    apply(el, val) { el.toggleAttribute(name, Boolean(val)); }
+  };
+}

package/src/handlers/className.js

@@ -0,0 +1,5 @@
+/** data-classname="key" → el.className = val || '' */
+export const className = {
+  attr: 'data-classname',
+  apply(el, val) { el.className = val || ''; }
+};

package/src/handlers/classToggle.js

@@ -0,0 +1,14 @@
+/**
+ * Create handlers for CSS class toggling.
+ * Each name creates a handler: data-class-{name}="key" → el.classList.toggle(name, Boolean(val))
+ * Returns an array — pass directly to handlers (auto-flattened by bindDom).
+ *
+ * @param {...string} names - CSS class names to create handlers for
+ * @returns {Array<{ attr: string, apply: function }>}
+ */
+export function classToggle(...names) {
+  return names.map(name => ({
+    attr: `data-class-${name}`,
+    apply(el, val) { el.classList.toggle(name, Boolean(val)); }
+  }));
+}

package/src/handlers/htmlAttrs.js

@@ -0,0 +1,57 @@
+import { show }       from './show.js';
+import { boolAttr }   from './boolAttr.js';
+import { ariaAttr }   from './ariaAttr.js';
+import { stringAttr } from './stringAttr.js';
+
+/** @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#boolean_attributes */
+const BOOL_ATTRS = [
+  'readonly', 'open', 'novalidate', 'formnovalidate', 'multiple',
+  'autofocus', 'autoplay', 'controls', 'loop', 'muted', 'defer',
+  'async', 'reversed', 'selected', 'inert', 'allowfullscreen',
+];
+
+/** @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes */
+const STRING_ATTRS = [
+  'href', 'src', 'alt', 'title', 'placeholder', 'action', 'method',
+  'target', 'rel', 'type', 'name', 'role', 'lang', 'tabindex',
+  'pattern', 'min', 'max', 'step', 'minlength', 'maxlength',
+  'width', 'height', 'for', 'form', 'accept', 'autocomplete',
+  'loading', 'decoding', 'inputmode', 'enterkeyhint', 'draggable',
+  'contenteditable', 'spellcheck', 'translate', 'dir', 'id',
+  'poster', 'preload', 'download', 'media', 'sizes', 'srcset',
+  'colspan', 'rowspan', 'scope', 'headers', 'wrap', 'sandbox',
+];
+
+/** ARIA boolean state attributes — coerced to "true"/"false" string. */
+const ARIA_BOOL_ATTRS = [
+  'pressed', 'selected', 'disabled', 'checked', 'invalid', 'required',
+  'busy', 'modal', 'multiselectable', 'multiline', 'readonly', 'atomic',
+];
+
+/** ARIA string/token/numeric attributes — value passed through as-is. */
+const ARIA_STRING_ATTRS = [
+  'current', 'live', 'relevant', 'haspopup',
+  'sort', 'autocomplete', 'orientation',
+  'label', 'describedby', 'labelledby', 'controls', 'owns',
+  'activedescendant', 'errormessage', 'details', 'flowto',
+  'valuenow', 'valuemin', 'valuemax', 'valuetext',
+  'colcount', 'colindex', 'colspan', 'rowcount', 'rowindex', 'rowspan',
+  'level', 'setsize', 'posinset', 'placeholder', 'roledescription',
+  'keyshortcuts', 'braillelabel', 'brailleroledescription',
+];
+
+/**
+ * One-import preset that enables all standard HTML attributes as reactive handlers.
+ * Returns a flat array — pass directly to handlers option.
+ *
+ * @returns {Array<{ attr: string, apply: function }>}
+ */
+export function htmlAttrs() {
+  return [
+    show,
+    ...BOOL_ATTRS.map(name => boolAttr(name)),
+    ...STRING_ATTRS.map(name => stringAttr(name)),
+    ...ARIA_BOOL_ATTRS.map(name => ariaAttr(name)),
+    ...ARIA_STRING_ATTRS.map(name => stringAttr(`aria-${name}`)),
+  ];
+}

package/src/handlers/index.d.ts

@@ -14,6 +14,19 @@ import type { Handler } from '../index.js';
  */
 export const show: Handler;
 
+/**
+ * data-classname="key" → el.className = val (replaces full class string)
+ * Use classToggle() for toggling individual classes.
+ *
+ * @example
+ * ```typescript
+ * bindDom(root, store, { handlers: [className] });
+ * // <div data-classname="cardClass">...</div>
+ * // store.cardClass = 'card card--error card--large';
+ * ```
+ */
+export const className: Handler;
+
 /**
  * Create a handler for any HTML boolean property.
  * Use for properties beyond the built-in hidden/disabled/checked/required.

package/src/handlers/index.js

@@ -19,199 +19,11 @@
  *   { attr: string, apply(el: HTMLElement, val: any): void }
  */
 
-// --- Ready-to-use Handlers ---
-
-/**
- * data-show="key" → el.hidden = !Boolean(val)
- * Shows element when state value is truthy (inverse of built-in data-hidden).
- */
-export const show = {
-  attr: 'data-show',
-  apply(el, val) { el.hidden = !Boolean(val); }
-};
-
-// --- Factory Functions ---
-
-/**
- * Create a handler for any HTML boolean attribute.
- * Uses toggleAttribute() — works correctly with any attribute name
- * (readonly, contenteditable, etc.) without worrying about camelCase property names.
- *
- * Note: built-in boolean handlers (hidden, disabled, checked, required) use
- * property assignment directly. This factory uses toggleAttribute for broader
- * attribute name compatibility.
- *
- * @param {string} name - Attribute name (e.g., 'readonly', 'open', 'contenteditable')
- * @returns {{ attr: string, apply: function }}
- *
- * @example
- * bindDom(root, store, { handlers: [boolAttr('readonly')] });
- * // <input data-readonly="isReadonly" />
- */
-export function boolAttr(name) {
-  return {
-    attr: `data-${name}`,
-    apply(el, val) { el.toggleAttribute(name, Boolean(val)); }
-  };
-}
-
-/**
- * Create a handler for an ARIA attribute.
- * Use for ARIA attrs beyond the built-in aria-expanded/aria-hidden.
- *
- * @param {string} name - ARIA name, with or without "aria-" prefix
- * @returns {{ attr: string, apply: function }}
- *
- * @example
- * bindDom(root, store, { handlers: [ariaAttr('pressed'), ariaAttr('selected')] });
- * // <button data-aria-pressed="isPressed">Toggle</button>
- */
-export function ariaAttr(name) {
-  const fullName = name.startsWith('aria-') ? name : `aria-${name}`;
-  return {
-    attr: `data-${fullName}`,
-    apply(el, val) { el.setAttribute(fullName, val ? 'true' : 'false'); }
-  };
-}
-
-/**
- * Create handlers for CSS class toggling.
- * Each name creates a handler: data-class-{name}="key" → el.classList.toggle(name, Boolean(val))
- *
- * Returns an array — pass directly to handlers (auto-flattened by bindDom).
- *
- * @param {...string} names - CSS class names to create handlers for
- * @returns {Array<{ attr: string, apply: function }>}
- *
- * @example
- * bindDom(root, store, { handlers: [classToggle('active', 'loading', 'error')] });
- * // <div data-class-active="isActive" data-class-loading="isLoading">
- */
-export function classToggle(...names) {
-  return names.map(name => ({
-    attr: `data-class-${name}`,
-    apply(el, val) { el.classList.toggle(name, Boolean(val)); }
-  }));
-}
-
-/**
- * Create a handler for any string attribute (href, src, title, alt, action, etc.)
- * Sets the attribute value as a string. Removes attribute when value is null/undefined.
- *
- * @param {string} name - HTML attribute name (e.g., 'href', 'src', 'title')
- * @returns {{ attr: string, apply: function }}
- *
- * @example
- * bindDom(root, store, { handlers: [stringAttr('href'), stringAttr('src')] });
- * // <a data-href="profileUrl">Profile</a>
- * // <img data-src="imageUrl" />
- */
-export function stringAttr(name) {
-  return {
-    attr: `data-${name}`,
-    apply(el, val) {
-      if (val == null) el.removeAttribute(name);
-      else el.setAttribute(name, String(val));
-    }
-  };
-}
-
-// --- Presets ---
-
-/** Form-related handlers (beyond built-in disabled/checked/required) */
-export const formHandlers = [
-  boolAttr('readonly'),
-];
-
-/** Additional ARIA handlers (beyond built-in aria-expanded/aria-hidden) */
-export const a11yHandlers = [
-  ariaAttr('pressed'),
-  ariaAttr('selected'),
-  ariaAttr('disabled'),
-];
-
-// --- htmlAttrs() — All Standard HTML Attributes ---
-
-/**
- * Standard HTML boolean attributes (beyond built-in hidden/disabled/checked/required).
- * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#boolean_attributes
- */
-const BOOL_ATTRS = [
-  'readonly', 'open', 'novalidate', 'formnovalidate', 'multiple',
-  'autofocus', 'autoplay', 'controls', 'loop', 'muted', 'defer',
-  'async', 'reversed', 'selected', 'inert', 'allowfullscreen',
-];
-
-/**
- * Standard HTML string attributes.
- * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes
- */
-const STRING_ATTRS = [
-  'href', 'src', 'alt', 'title', 'placeholder', 'action', 'method',
-  'target', 'rel', 'type', 'name', 'role', 'lang', 'tabindex',
-  'pattern', 'min', 'max', 'step', 'minlength', 'maxlength',
-  'width', 'height', 'for', 'form', 'accept', 'autocomplete',
-  'loading', 'decoding', 'inputmode', 'enterkeyhint', 'draggable',
-  'contenteditable', 'spellcheck', 'translate', 'dir', 'id',
-  'poster', 'preload', 'download', 'media', 'sizes', 'srcset',
-  'colspan', 'rowspan', 'scope', 'headers', 'wrap', 'sandbox',
-];
-
-/**
- * ARIA boolean state attributes — toggled between "true" and "false".
- * Use ariaAttr() for these (coerces to "true"/"false" string).
- * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes
- */
-const ARIA_BOOL_ATTRS = [
-  'pressed', 'selected', 'disabled', 'checked', 'invalid', 'required',
-  'busy', 'modal', 'multiselectable', 'multiline', 'readonly', 'atomic',
-];
-
-/**
- * ARIA string/token/numeric attributes — value passed through as-is.
- * Use stringAttr() with "aria-" prefix for these.
- * @see https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes
- */
-const ARIA_STRING_ATTRS = [
-  'current', 'live', 'relevant', 'haspopup',
-  'sort', 'autocomplete', 'orientation',
-  'label', 'describedby', 'labelledby', 'controls', 'owns',
-  'activedescendant', 'errormessage', 'details', 'flowto',
-  'valuenow', 'valuemin', 'valuemax', 'valuetext',
-  'colcount', 'colindex', 'colspan', 'rowcount', 'rowindex', 'rowspan',
-  'level', 'setsize', 'posinset', 'placeholder', 'roledescription',
-  'keyshortcuts', 'braillelabel', 'brailleroledescription',
-];
-
-/**
- * One-import preset that enables all standard HTML attributes as reactive handlers.
- *
- * Includes:
- * - Boolean attributes: readonly, open, autofocus, controls, muted, inert, etc.
- * - String attributes: href, src, alt, title, placeholder, role, tabindex, etc.
- * - ARIA attributes: aria-pressed, aria-label, aria-describedby, aria-valuenow, etc.
- * - Show handler: data-show (inverse of data-hidden)
- *
- * Returns a flat array — pass directly to handlers option.
- *
- * @returns {Array<{ attr: string, apply: function }>}
- *
- * @example
- * import { htmlAttrs } from 'lume-js/handlers';
- *
- * bindDom(document.body, store, { handlers: [htmlAttrs()] });
- * // Now use any data-* attribute:
- * //   <a data-href="url">Link</a>
- * //   <input data-readonly="isLocked" />
- * //   <div data-aria-label="labelText">...</div>
- * //   <div data-show="isVisible">...</div>
- */
-export function htmlAttrs() {
-  return [
-    show,
-    ...BOOL_ATTRS.map(name => boolAttr(name)),
-    ...STRING_ATTRS.map(name => stringAttr(name)),
-    ...ARIA_BOOL_ATTRS.map(name => ariaAttr(name)),
-    ...ARIA_STRING_ATTRS.map(name => stringAttr(`aria-${name}`)),
-  ];
-}
+export { show }                    from './show.js';
+export { className }               from './className.js';
+export { boolAttr }                from './boolAttr.js';
+export { ariaAttr }                from './ariaAttr.js';
+export { classToggle }             from './classToggle.js';
+export { stringAttr }              from './stringAttr.js';
+export { htmlAttrs }               from './htmlAttrs.js';
+export { formHandlers, a11yHandlers } from './presets.js';

package/src/handlers/presets.js

@@ -0,0 +1,14 @@
+import { boolAttr } from './boolAttr.js';
+import { ariaAttr } from './ariaAttr.js';
+
+/** Form-related handlers (beyond built-in disabled/checked/required) */
+export const formHandlers = [
+  boolAttr('readonly'),
+];
+
+/** Additional ARIA handlers (beyond built-in aria-expanded/aria-hidden) */
+export const a11yHandlers = [
+  ariaAttr('pressed'),
+  ariaAttr('selected'),
+  ariaAttr('disabled'),
+];

package/src/handlers/show.js

@@ -0,0 +1,5 @@
+/** data-show="key" → el.hidden = !Boolean(val) */
+export const show = {
+  attr: 'data-show',
+  apply(el, val) { el.hidden = !Boolean(val); }
+};