lume-js 0.4.1 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lume-js",
-  "version": "0.4.1",
+  "version": "1.0.0",
   "description": "Minimal reactive state management using only standard JavaScript and HTML - no custom syntax, no build step required",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -18,6 +18,7 @@
   },
   "scripts": {
     "dev": "vite",
+    "dev:site": "node scripts/build-site-assets.js && vite -c vite.site.config.js",
     "build": "echo 'No build step needed - zero-runtime library!'",
     "size": "node scripts/check-size.js",
     "test": "vitest run",
@@ -57,12 +58,19 @@
   "bugs": {
     "url": "https://github.com/sathvikc/lume-js/issues"
   },
-  "homepage": "https://github.com/sathvikc/lume-js#readme",
+  "homepage": "https://sathvikc.github.io/lume-js/",
   "devDependencies": {
-    "vite": "^7.1.9",
-    "vitest": "^2.1.4",
+    "@tailwindcss/postcss": "^4.1.17",
+    "@tailwindcss/typography": "^0.5.19",
     "@vitest/coverage-v8": "^2.1.4",
-    "jsdom": "^25.0.1"
+    "autoprefixer": "^10.4.22",
+    "highlight.js": "^11.11.1",
+    "jsdom": "^25.0.1",
+    "marked": "^17.0.1",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^4.1.17",
+    "vite": "^7.1.9",
+    "vitest": "^2.1.4"
   },
   "engines": {
     "node": ">=20.19.0"

package/src/addons/index.d.ts

@@ -83,3 +83,176 @@ export function watch<T extends object, K extends keyof T>(
   key: K,
   callback: Subscriber<T[K]>
 ): Unsubscribe;
+
+/**
+ * Context passed to preservation functions
+ */
+export interface PreservationContext {
+  /** Whether this update is a reorder (vs add/remove) */
+  isReorder?: boolean;
+}
+
+/**
+ * Focus preservation function signature
+ * 
+ * @param container - The list container element
+ * @returns Restore function to call after DOM updates, or null if nothing to restore
+ */
+export type FocusPreservation = (container: HTMLElement) => (() => void) | null;
+
+/**
+ * Scroll preservation function signature
+ * 
+ * @param container - The list container element
+ * @param context - Additional context about the update
+ * @returns Restore function to call after DOM updates
+ */
+export type ScrollPreservation = (container: HTMLElement, context?: PreservationContext) => () => void;
+
+/**
+ * Options for the repeat() function
+ */
+export interface RepeatOptions<T> {
+  /** Function to extract unique key from item */
+  key: (item: T) => string | number;
+  
+  /** Function to render/update an item's element */
+  render: (item: T, element: HTMLElement, index: number) => void;
+  
+  /** Element tag name or factory function (default: 'div') */
+  element?: string | (() => HTMLElement);
+  
+  /** 
+   * Focus preservation strategy (default: defaultFocusPreservation)
+   * Set to null to disable focus preservation
+   */
+  preserveFocus?: FocusPreservation | null;
+  
+  /** 
+   * Scroll preservation strategy (default: defaultScrollPreservation)
+   * Set to null to disable scroll preservation
+   */
+  preserveScroll?: ScrollPreservation | null;
+}
+
+/**
+ * Default focus preservation strategy
+ * Saves activeElement and selection state before DOM updates
+ * 
+ * @param container - The list container element
+ * @returns Restore function or null
+ * 
+ * @example
+ * ```typescript
+ * import { defaultFocusPreservation } from 'lume-js/addons';
+ * 
+ * // Use in custom preservation wrapper
+ * const myPreservation = (container) => {
+ *   console.log('Saving focus...');
+ *   const restore = defaultFocusPreservation(container);
+ *   return restore ? () => {
+ *     restore();
+ *     console.log('Focus restored!');
+ *   } : null;
+ * };
+ * ```
+ */
+export function defaultFocusPreservation(container: HTMLElement): (() => void) | null;
+
+/**
+ * Default scroll preservation strategy
+ * Uses anchor-based preservation for add/remove, pixel position for reorder
+ * 
+ * @param container - The list container element
+ * @param context - Additional context about the update
+ * @returns Restore function
+ * 
+ * @example
+ * ```typescript
+ * import { defaultScrollPreservation } from 'lume-js/addons';
+ * 
+ * // Wrap default behavior
+ * const myScrollPreservation = (container, context) => {
+ *   const restore = defaultScrollPreservation(container, context);
+ *   return () => {
+ *     restore();
+ *     console.log('Scroll position restored');
+ *   };
+ * };
+ * ```
+ */
+export function defaultScrollPreservation(container: HTMLElement, context?: PreservationContext): () => void;
+
+/**
+ * Efficiently render a list with element reuse by key.
+ * 
+ * Features:
+ * - Element reuse (same DOM nodes, not recreated)
+ * - Minimal DOM operations (only updates what changed)
+ * - Optional focus preservation (maintains activeElement and selection)
+ * - Optional scroll preservation (intelligent positioning)
+ * - Fully customizable preservation strategies
+ * 
+ * @param container - Container element or CSS selector
+ * @param store - Reactive state object
+ * @param arrayKey - Key in store containing the array
+ * @param options - Configuration options
+ * @returns Cleanup function
+ * 
+ * @example
+ * ```typescript
+ * import { state } from 'lume-js';
+ * import { repeat } from 'lume-js/addons';
+ * 
+ * const store = state({
+ *   todos: [
+ *     { id: 1, text: 'Learn Lume.js' },
+ *     { id: 2, text: 'Build an app' }
+ *   ]
+ * });
+ * 
+ * // Basic usage (preservation enabled by default)
+ * const cleanup = repeat('#todo-list', store, 'todos', {
+ *   key: todo => todo.id,
+ *   render: (todo, el) => {
+ *     if (!el.dataset.init) {
+ *       el.innerHTML = `<input value="${todo.text}">`;
+ *       el.dataset.init = 'true';
+ *     }
+ *   }
+ * });
+ * 
+ * // Disable preservation (bare-bones)
+ * repeat('#list', store, 'todos', {
+ *   key: todo => todo.id,
+ *   render: (todo, el) => { el.textContent = todo.text; },
+ *   preserveFocus: null,
+ *   preserveScroll: null
+ * });
+ * 
+ * // Custom preservation
+ * import { defaultFocusPreservation } from 'lume-js/addons';
+ * 
+ * repeat('#list', store, 'todos', {
+ *   key: todo => todo.id,
+ *   render: (todo, el) => { ... },
+ *   preserveFocus: (container) => {
+ *     // Custom logic
+ *     const restore = defaultFocusPreservation(container);
+ *     return () => {
+ *       restore?.();
+ *       console.log('Focus restored');
+ *     };
+ *   }
+ * });
+ * 
+ * // Cleanup
+ * cleanup();
+ * ```
+ */
+export function repeat<T>(
+  container: string | HTMLElement,
+  store: ReactiveState<any>,
+  arrayKey: string,
+  options: RepeatOptions<T>
+): Unsubscribe;

package/src/addons/index.js

@@ -1,2 +1,3 @@
 export { computed } from "./computed.js";
-export { watch } from "./watch.js";
+export { watch } from "./watch.js";
+export { repeat } from "./repeat.js";

package/src/addons/repeat.js

@@ -0,0 +1,342 @@
+/**
+ * Lume-JS List Rendering (Addon)
+ * @experimental
+ *
+ * Renders lists with automatic subscription and element reuse by key.
+ * 
+ * Core guarantees:
+ * ✅ Element reuse by key (same DOM nodes, not recreated)
+ * ✅ Minimal DOM operations (only updates what changed)
+ * ✅ Memory efficiency (cleanup on remove)
+ * 
+ * Default behavior (can be disabled/customized):
+ * ✅ Focus preservation (maintains activeElement and selection)
+ * ✅ Scroll preservation (intelligent positioning for add/remove/reorder)
+ * 
+ * Philosophy: No artificial limitations
+ * - All preservation logic is overridable via options
+ * - Set to null/false to disable, or provide custom functions
+ * - Export utilities so you can wrap/extend them
+ *
+ * Usage:
+ *   import { repeat } from "lume-js/addons/repeat.js";
+ *   
+ *   // ⚠️ IMPORTANT: Arrays must be updated immutably!
+ *   // store.items.push(x)      // ❌ Won't trigger update
+ *   // store.items = [...items] // ✅ Triggers update
+ *   
+ *   // Basic usage (focus & scroll preservation enabled by default)
+ *   repeat('#list', store, 'todos', {
+ *     key: todo => todo.id,
+ *     render: (todo, el) => {
+ *       if (!el.dataset.init) {
+ *         el.innerHTML = `<input value="${todo.text}">`;
+ *         el.dataset.init = 'true';
+ *       }
+ *     }
+ *   });
+ *   
+ *   // Disable all preservation (bare-bones repeat)
+ *   repeat('#list', store, 'items', {
+ *     key: item => item.id,
+ *     render: (item, el) => { el.textContent = item.name; },
+ *     preserveFocus: null,
+ *     preserveScroll: null
+ *   });
+ *   
+ *   // Custom focus preservation
+ *   repeat('#list', store, 'items', {
+ *     key: item => item.id,
+ *     render: (item, el) => { ... },
+ *     preserveFocus: (container) => {
+ *       // Your custom logic
+ *       const state = { focused: document.activeElement };
+ *       return () => state.focused?.focus();
+ *     }
+ *   });
+ *   
+ *   // Mix built-in and custom
+ *   import { defaultFocusPreservation, defaultScrollPreservation } from "lume-js/addons/repeat.js";
+ *   
+ *   repeat('#list', store, 'items', {
+ *     key: item => item.id,
+ *     render: (item, el) => { ... },
+ *     preserveFocus: defaultFocusPreservation, // use built-in
+ *     preserveScroll: (container, context) => {
+ *       // wrap/extend built-in
+ *       const restore = defaultScrollPreservation(container, context);
+ *       return () => {
+ *         restore();
+ *         console.log('Scroll restored!');
+ *       };
+ *     }
+ *   });
+ */
+
+// ============================================================================
+// PRESERVATION UTILITIES (Exported for customization)
+// ============================================================================
+
+/**
+ * Default focus preservation strategy
+ * Saves activeElement and selection state before DOM updates
+ * 
+ * @param {HTMLElement} container - The list container
+ * @returns {Function|null} Restore function, or null if nothing to restore
+ */
+export function defaultFocusPreservation(container) {
+  const activeEl = document.activeElement;
+  const shouldRestore = container.contains(activeEl);
+
+  if (!shouldRestore) return null;
+
+  let selectionStart = null;
+  let selectionEnd = null;
+
+  if (activeEl.tagName === 'INPUT' || activeEl.tagName === 'TEXTAREA') {
+    selectionStart = activeEl.selectionStart;
+    selectionEnd = activeEl.selectionEnd;
+  }
+
+  return () => {
+    if (document.body.contains(activeEl)) {
+      activeEl.focus();
+      if (selectionStart !== null && selectionEnd !== null) {
+        activeEl.setSelectionRange(selectionStart, selectionEnd);
+      }
+    }
+  };
+}
+
+/**
+ * Default scroll preservation strategy
+ * Uses anchor-based preservation for add/remove, pixel position for reorder
+ * 
+ * @param {HTMLElement} container - The list container
+ * @param {Object} context - Additional context
+ * @param {boolean} context.isReorder - Whether this is a reorder operation
+ * @returns {Function} Restore function
+ */
+export function defaultScrollPreservation(container, context = {}) {
+  const { isReorder = false } = context;
+  const scrollTop = container.scrollTop;
+
+  // Early return if no scroll
+  if (scrollTop === 0) {
+    return () => { container.scrollTop = 0; };
+  }
+
+  let anchorElement = null;
+  let anchorOffset = 0;
+
+  // Only use anchor-based preservation for add/remove, not reorder
+  if (!isReorder) {
+    const containerRect = container.getBoundingClientRect();
+    // Avoid Array.from - iterate children directly
+    for (let child = container.firstElementChild; child; child = child.nextElementSibling) {
+      const rect = child.getBoundingClientRect();
+
+      if (rect.bottom > containerRect.top) {
+        anchorElement = child;
+        anchorOffset = rect.top - containerRect.top;
+        break;
+      }
+    }
+  }
+
+  return () => {
+    if (anchorElement && document.body.contains(anchorElement)) {
+      const newRect = anchorElement.getBoundingClientRect();
+      const containerRect = container.getBoundingClientRect();
+      const currentOffset = newRect.top - containerRect.top;
+      const scrollAdjustment = currentOffset - anchorOffset;
+
+      container.scrollTop = container.scrollTop + scrollAdjustment;
+    } else {
+      container.scrollTop = scrollTop;
+    }
+  };
+}
+
+// ============================================================================
+// MAIN REPEAT FUNCTION
+// ============================================================================
+
+/**
+ * Efficiently render a list with element reuse
+ * 
+ * @param {string|HTMLElement} container - Container element or selector
+ * @param {Object} store - Reactive state object
+ * @param {string} arrayKey - Key in store containing the array
+ * @param {Object} options - Configuration
+ * @param {Function} options.key - Function to extract unique key: (item) => key
+ * @param {Function} options.render - Function to render item: (item, element, index) => void
+ * @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)
+ * @returns {Function} Cleanup function
+ */
+export function repeat(container, store, arrayKey, options) {
+  const {
+    key,
+    render,
+    element = 'div',
+    preserveFocus = defaultFocusPreservation,
+    preserveScroll = defaultScrollPreservation
+  } = options;
+
+  // Resolve container
+  const containerEl =
+    typeof container === 'string'
+      ? document.querySelector(container)
+      : container;
+
+  if (!containerEl) {
+    console.warn(`[Lume.js] repeat(): container "${container}" not found`);
+    return () => { };
+  }
+
+  if (typeof key !== 'function') {
+    throw new Error('[Lume.js] repeat(): options.key must be a function');
+  }
+
+  if (typeof render !== 'function') {
+    throw new Error('[Lume.js] repeat(): options.render must be a function');
+  }
+
+  // key -> HTMLElement
+  const elementsByKey = new Map();
+  const seenKeys = new Set();
+
+  function createElement() {
+    return typeof element === 'function'
+      ? element()
+      : document.createElement(element);
+  }
+
+  function updateList() {
+    const items = store[arrayKey];
+
+    if (!Array.isArray(items)) {
+      console.warn(`[Lume.js] repeat(): store.${arrayKey} is not an array`);
+      return;
+    }
+
+    // Skip preservation if container is not in document (performance optimization)
+    const shouldPreserve = document.body.contains(containerEl);
+
+    // Only compute isReorder if scroll preservation needs it
+    let isReorder = false;
+    if (shouldPreserve && preserveScroll) {
+      const previousKeys = new Set(elementsByKey.keys());
+      const currentKeys = new Set(items.map(item => key(item)));
+      isReorder = previousKeys.size === currentKeys.size &&
+        [...previousKeys].every(k => currentKeys.has(k));
+    }
+
+    // Save state before DOM manipulation
+    const restoreFocus = shouldPreserve && preserveFocus ? preserveFocus(containerEl) : null;
+    const restoreScroll = shouldPreserve && preserveScroll ? preserveScroll(containerEl, { isReorder }) : null;
+
+    seenKeys.clear();
+    const nextKeys = new Set();
+    const nextEls = [];
+
+    // Build ordered list of DOM nodes (created or reused)
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i];
+      const k = key(item);
+
+      if (seenKeys.has(k)) {
+        console.warn(`[Lume.js] repeat(): duplicate key "${k}"`);
+      }
+      seenKeys.add(k);
+      nextKeys.add(k);
+
+      let el = elementsByKey.get(k);
+      const isNew = !el;
+
+      if (isNew) {
+        el = createElement();
+        elementsByKey.set(k, el);
+      }
+
+      try {
+        if (isNew) {
+          el.__lume_new = true;
+        }
+
+        render(item, el, i);
+
+      } catch (err) {
+        console.error(`[Lume.js] repeat(): error rendering key "${k}"`, err);
+      } finally {
+        delete el.__lume_new;
+      }
+
+      nextEls.push(el);
+    }
+
+    // Reconcile actual DOM ordering
+    let ptr = containerEl.firstChild;
+
+    for (let i = 0; i < nextEls.length; i++) {
+      const desired = nextEls[i];
+
+      if (ptr === desired) {
+        ptr = ptr.nextSibling;
+        continue;
+      }
+
+      containerEl.insertBefore(desired, ptr);
+    }
+
+    // Remove leftover children not in nextEls
+    while (ptr) {
+      const next = ptr.nextSibling;
+      containerEl.removeChild(ptr);
+      ptr = next;
+    }
+
+    // Clean map: remove keys not in nextKeys
+    // Iterate over elementsByKey entries and delete if not in nextKeys
+    if (elementsByKey.size !== nextKeys.size) {
+      for (const k of elementsByKey.keys()) {
+        if (!nextKeys.has(k)) {
+          elementsByKey.delete(k);
+        }
+      }
+    }
+
+    // Restore state after DOM manipulation
+    if (restoreFocus) restoreFocus();
+    if (restoreScroll) restoreScroll();
+  }
+
+  // Initial render
+  updateList();
+
+  // Subscription
+  let unsubscribe;
+  if (typeof store.$subscribe === 'function') {
+    unsubscribe = store.$subscribe(arrayKey, updateList);
+  } else if (typeof store.subscribe === 'function') {
+    // Generic subscribe (e.g. computed)
+    unsubscribe = store.subscribe(() => updateList());
+  } else {
+    console.warn('[Lume.js] repeat(): store is not reactive (no $subscribe or subscribe method)');
+    return () => {
+      containerEl.replaceChildren();
+      elementsByKey.clear();
+      seenKeys.clear();
+    };
+  }
+
+  return () => {
+    unsubscribe();
+    // Clear DOM elements (replaceChildren is faster than loop)
+    containerEl.replaceChildren();
+    elementsByKey.clear();
+    seenKeys.clear();
+  };
+}