npm - @ape-egg/vibe - Versions diffs - 1.0.0 - Mend

@ape-egg/vibe 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/CHANGELOG.md +42 -0
package/README.md +108 -0
package/_vibe-compiled-iteration-batch.js +161 -0
package/affected.js +149 -0
package/conditionals.js +182 -0
package/constants.js +76 -0
package/hydrate.js +100 -0
package/index.js +250 -0
package/iterate.js +451 -0
package/iteration-utils.js +261 -0
package/link.js +13 -0
package/llms.txt +279 -0
package/package.json +26 -0
package/parse.js +225 -0
package/state.js +26 -0
package/utils.js +45 -0
package/vibe.css +11 -0

package/link.js ADDED Viewed

@@ -0,0 +1,13 @@
+const recursive = (tree, results, tagChain) => {
+  results[tagChain.join(".")] = tree.element;
+  if (tree.children && Object.keys(tree.children).length > 0) {
+    Object.keys(tree.children).forEach((tag) => {
+      results = recursive(tree.children[tag], results, [...tagChain, tag]);
+    });
+  }
+  return results;
+};
+export default (tree) => recursive(tree, {}, []);

package/llms.txt ADDED Viewed

@@ -0,0 +1,279 @@
+# Vibe - Complete Documentation
+> Runtime-first reactivity. No virtual DOM. No build step.
+## Overview
+Vibe is a lightweight reactive library that uses Proxy-based state and MutationObserver for fine-grained DOM updates. It works directly in the browser with zero compilation required.
+**Key characteristics:**
+- Proxy-based reactive state (`window.$`)
+- Surgical DOM updates (only affected elements re-render)
+- MutationObserver for dynamic element tracking
+- Works with vanilla HTML - no special file format
+## Installation
+```bash
+npm install @ape-egg/vibe
+```
+## Quick Start
+```html
+<script type="module">
+  import state from "@ape-egg/vibe";
+  window.$ = state({ name: "World", count: 0 });
+</script>
+<h1>Hello, @[name]!</h1>
+<button onclick="$.count++">Clicked @[count] times</button>
+```
+## Core Syntax
+### Reactive Bindings
+Use `@[property]` syntax anywhere in HTML or CSS:
+```html
+<!-- Text content -->
+<div>@[firstName]</div>
+<!-- Expressions -->
+<div>@[firstName + ' ' + lastName]</div>
+<div>@[count * 2]</div>
+<!-- Attributes -->
+<input value="@[inputValue]">
+<button disabled="@[isLoading]">Submit</button>
+<!-- CSS -->
+<style>
+  .box { background: @[themeColor]; }
+</style>
+```
+⚠️ **Important**: Bindings are evaluated using `new Function()`. Do not bind untrusted user input.
+### State Access
+State is accessed globally via `window.$`:
+```javascript
+// Read
+console.log($.firstName);
+// Write (triggers re-render)
+$.firstName = "John";
+// Increment
+$.count++;
+```
+## Control Flow
+### Iteration
+```html
+<!-- each items as item -->
+  <li>@[item]</li>
+<!-- /each -->
+```
+With index:
+```html
+<!-- each items as item, index -->
+  <li>@[index]: @[item]</li>
+<!-- /each -->
+```
+### Nested Iteration
+Use dot paths for nested arrays:
+```html
+<!-- each categories as category -->
+  <h2>@[category.name]</h2>
+  <!-- each category.items as item -->
+    <span>@[item.name]</span>
+  <!-- /each -->
+<!-- /each -->
+```
+### Conditionals
+```html
+<!-- if isLoggedIn -->
+  <span>Welcome, @[username]!</span>
+<!-- else -->
+  <span>Please log in</span>
+<!-- /if -->
+```
+Conditionals can be nested inside iterations and vice versa.
+## Special Attributes
+### Dehydrate
+Skip reactive processing for an element and its children:
+```html
+<code dehydrate>@[this] displays literally, not parsed</code>
+```
+Use cases:
+- Displaying `@[...]` syntax in documentation
+- Static content that shouldn't be reactive
+- Performance optimization for large static sections
+### Boolean Attributes
+Attributes not in the value whitelist are removed when falsy:
+```html
+<button disabled="@[isLoading]">Submit</button>
+<!-- When isLoading is false, disabled attribute is removed entirely -->
+```
+## Events
+Use standard inline event handlers:
+```html
+<button onclick="$.count++">Increment</button>
+<input oninput="$.text = this.value">
+<form onsubmit="event.preventDefault(); handleSubmit()">
+```
+## Styling
+### CSS Bindings
+Reactive values work inside `<style>` tags:
+```html
+<style>
+  .box {
+    background: @[backgroundColor];
+    color: @[textColor];
+    width: @[width]px;
+  }
+</style>
+```
+### Preventing FOUC
+Hide content until hydration completes:
+```html
+<body style="visibility: hidden;">
+```
+Or use the included CSS:
+```html
+<link rel="stylesheet" href="@ape-egg/vibe/vibe.css">
+<body vibe>
+```
+## Dynamic Elements
+Elements added via JavaScript are automatically hydrated through MutationObserver:
+```javascript
+const div = document.createElement('div');
+div.innerHTML = '<span>Hello, @[name]!</span>';
+document.body.appendChild(div);
+// Automatically becomes reactive
+```
+## API Reference
+### `state(initialState, afterUpdate?)`
+Creates reactive state and initializes the framework.
+```javascript
+import state from "@ape-egg/vibe";
+window.$ = state(
+  { count: 0, user: { name: "Alice" } },
+  (newState, oldState) => {
+    console.log("State updated:", newState);
+  }
+);
+```
+**Parameters:**
+- `initialState` - Object containing initial state values
+- `afterUpdate` - Optional callback after each state change (receives read-only snapshots)
+**Returns:** Proxy object for reactive state access
+## Scoped Variables
+Inside `<!-- each -->` blocks, these variables are available:
+- `item` (or custom name) - current array element
+- `index` (or custom name) - current index
+- Parent state remains accessible via `$`
+```html
+<!-- each users as user, i -->
+  <div>@[i]: @[user.name] (total: @[users.length])</div>
+<!-- /each -->
+```
+## Architecture
+Vibe consists of these core modules:
+- **state.js** - Proxy-based reactive state container
+- **parse.js** - DOM parser that finds `@[...]` bindings
+- **link.js** - Maps elements to parsed tree nodes
+- **hydrate.js** - Updates DOM with current state values
+- **affected.js** - Determines which elements need updating
+- **iterate.js** - Array rendering with efficient diffing
+- **conditionals.js** - Conditional block rendering
+## How It Works
+```
+1. state() initializes the Proxy and framework
+2. parse.js scans DOM for @[...], <!-- each -->, <!-- if -->
+3. link.js maps elements to the parsed tree
+4. hydrate.js replaces bindings with values
+5. iterate.js renders <!-- each --> loops
+6. conditionals.js renders <!-- if --> blocks
+7. MutationObserver watches for new elements
+8. On state change: affected.js finds changed elements → hydrate.js updates them
+```
+## Current Limitations
+- **Top-level reactivity only**: `$.nested.prop = value` doesn't trigger updates (must replace parent object)
+- **No computed values**: Derived state must be calculated manually
+- **No two-way binding sugar**: Must wire input events manually
+- **Expression security**: `new Function()` evaluation - don't bind untrusted input
+## Best Practices
+1. **Initialize state before DOM**: Place `<script>` in `<head>` or before reactive elements
+2. **Use dehydrate for docs**: When showing `@[...]` syntax examples
+3. **Prevent FOUC**: Use `visibility: hidden` on body until hydration
+4. **Keep expressions simple**: Complex logic belongs in JavaScript, not templates
+5. **Replace objects for deep updates**: `$.user = { ...$.user, name: "New" }`
+## Browser Support
+Modern browsers with:
+- Proxy (ES6)
+- MutationObserver
+- ES Modules
+## Resources
+- **Homepage**: https://vibe.korte.kim
+- **npm**: https://www.npmjs.com/package/@ape-egg/vibe

package/package.json ADDED Viewed

@@ -0,0 +1,26 @@
+{
+  "name": "@ape-egg/vibe",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Runtime-first reactivity",
+  "main": "index.js",
+  "homepage": "https://vibe.korte.kim",
+  "keywords": [
+    "reactive",
+    "framework",
+    "frontend",
+    "ui",
+    "mutation-observer",
+    "proxy",
+    "minimalistic"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Kim Korte",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {}
+}

package/parse.js ADDED Viewed

@@ -0,0 +1,225 @@
+import { hash } from './utils.js'
+import { findEndComment, findConditionalEnd } from './iteration-utils.js'
+import { NON_REACTIVE_ELEMENTS, BINDING_REGEX, ITERATION_REGEX, CONDITIONAL_REGEX } from './constants.js'
+const parseHTML = (children, rootKey = undefined) =>
+  children.reduce((s, element, i) => {
+    const { nodeName, textContent } = element
+    if (['#comment'].includes(nodeName)) {
+      return `${s}${nodeName === '#comment' ? `asd` : textContent}`
+    }
+    const name = nodeName.startsWith('#') ? nodeName.slice(1) : nodeName
+    const innerNodeIdentifier = `${name}_${i}`.toLowerCase()
+    return rootKey || `${s}${`\$[${innerNodeIdentifier}]`}`
+  }, '')
+const recursive = (children, rootKey = undefined, skipIndices = new Set()) => {
+  let result = {};
+  for (let i = 0; i < children.length; i++) {
+    // Skip if this index was part of an iteration template
+    if (skipIndices.has(i)) continue;
+    const element = children[i];
+    const { nodeName, childNodes, outerHTML, innerHTML, textContent } = element;
+    // Skip non-reactive elements and dehydrated elements
+    if (NON_REACTIVE_ELEMENTS.includes(nodeName)) continue;
+    if (element.hasAttribute?.('dehydrate')) continue;
+    // Handle iteration comments
+    if (nodeName === '#comment') {
+      const iterationMatch = textContent.trim().match(ITERATION_REGEX);
+      if (iterationMatch) {
+        const [_, arrayPath, itemAlias, indexAlias] = iterationMatch;
+        try {
+          // Find matching end comment
+          const endIndex = findEndComment(children, i + 1);
+          // Extract template nodes (between start and end comments)
+          const templateNodes = Array.from(children).slice(i + 1, endIndex);
+          // Create a temporary container for the template
+          const templateContainer = document.createElement('div');
+          templateNodes.forEach(node => {
+            templateContainer.appendChild(node.cloneNode(true));
+          });
+          // Parse the template recursively
+          const templateParsed = recursive([...templateContainer.childNodes]);
+          // Store iteration metadata
+          const iterationKey = `iteration_${hash()}`;
+          result[iterationKey] = {
+            type: 'iteration',
+            meta: {
+              arrayPath,
+              itemAlias,
+              indexAlias: indexAlias || 'index',
+              startComment: element,
+              endComment: children[endIndex],
+              template: {
+                parsed: parseHTML([...templateContainer.childNodes]),
+                element: templateContainer,
+                children: templateParsed
+              }
+            },
+            runtime: {
+              instances: [],
+              templateRemoved: false
+            },
+            children: {}
+          };
+          // Mark template indices as processed
+          for (let j = i + 1; j < endIndex; j++) {
+            skipIndices.add(j);
+          }
+          skipIndices.add(endIndex); // Also skip the end comment
+          // Skip past this iteration block
+          i = endIndex;
+          continue;
+        } catch (e) {
+          console.error('Error parsing iteration block:', e);
+          continue;
+        }
+      }
+      // Handle conditional comments
+      const conditionalMatch = textContent.trim().match(CONDITIONAL_REGEX);
+      if (conditionalMatch) {
+        const [_, expression] = conditionalMatch;
+        try {
+          // Find matching end comment and optional else
+          const { elseIndex, endIndex } = findConditionalEnd(children, i + 1);
+          // Extract true branch nodes (between if and else/endif)
+          const trueBranchEnd = elseIndex !== null ? elseIndex : endIndex;
+          const trueBranchNodes = Array.from(children).slice(i + 1, trueBranchEnd);
+          // Create temporary container for true branch
+          const trueBranchContainer = document.createElement('div');
+          trueBranchNodes.forEach(node => {
+            trueBranchContainer.appendChild(node.cloneNode(true));
+          });
+          // Parse the true branch recursively
+          const trueBranchParsed = recursive([...trueBranchContainer.childNodes]);
+          // Extract false branch nodes if else exists
+          let falseBranchParsed = null;
+          let falseBranchContainer = null;
+          if (elseIndex !== null) {
+            const falseBranchNodes = Array.from(children).slice(elseIndex + 1, endIndex);
+            falseBranchContainer = document.createElement('div');
+            falseBranchNodes.forEach(node => {
+              falseBranchContainer.appendChild(node.cloneNode(true));
+            });
+            falseBranchParsed = recursive([...falseBranchContainer.childNodes]);
+          }
+          // Store conditional metadata
+          const conditionalKey = `conditional_${hash()}`;
+          result[conditionalKey] = {
+            type: 'conditional',
+            meta: {
+              expression,
+              startComment: element,
+              elseComment: elseIndex !== null ? children[elseIndex] : null,
+              endComment: children[endIndex],
+              branches: {
+                if: {
+                  parsed: parseHTML([...trueBranchContainer.childNodes]),
+                  element: trueBranchContainer,
+                  children: trueBranchParsed
+                },
+                else: falseBranchContainer ? {
+                  parsed: parseHTML([...falseBranchContainer.childNodes]),
+                  element: falseBranchContainer,
+                  children: falseBranchParsed
+                } : null
+              }
+            },
+            runtime: {
+              activeBranch: undefined,
+              activeInstance: null,
+              templateRemoved: false
+            },
+            children: {}
+          };
+          // Mark template indices as processed
+          for (let j = i + 1; j <= endIndex; j++) {
+            skipIndices.add(j);
+          }
+          // Skip past this conditional block
+          i = endIndex;
+          continue;
+        } catch (e) {
+          console.error('Error parsing conditional block:', e);
+          continue;
+        }
+      }
+      // Skip other comments
+      continue;
+    }
+    const name = nodeName.startsWith('#') ? nodeName.slice(1) : nodeName;
+    const nodeIdentifier = `${name}_${i}`.toLowerCase();
+    // Check for attribute bindings
+    const attributes = {};
+    if (element.attributes) {
+      for (let j = 0; j < element.attributes.length; j++) {
+        const attr = element.attributes[j];
+        // Reset lastIndex before test - BINDING_REGEX has 'g' flag which persists state
+        BINDING_REGEX.lastIndex = 0;
+        if (BINDING_REGEX.test(attr.value)) {
+          attributes[attr.name] = attr.value;
+        }
+      }
+    }
+    const hasAttributeBindings = Object.keys(attributes).length > 0;
+    const hasChildren = childNodes.length;
+    if (hasChildren) {
+      const iteratableChildren = [...childNodes];
+      const parsed = parseHTML(iteratableChildren);
+      result[rootKey || nodeIdentifier] = {
+        parsed,
+        element,
+        children: recursive(iteratableChildren),
+        ...(hasAttributeBindings && { attributes })
+      };
+    } else {
+      result[nodeIdentifier] = {
+        parsed: innerHTML || textContent,
+        element,
+        children: {},
+        ...(hasAttributeBindings && { attributes })
+      };
+    }
+  }
+  return result;
+}
+export default (root, rootKey = undefined) => {
+  const { childNodes } = root
+  return {
+    // html: root.outerHTML,
+    parsed: parseHTML([...childNodes], rootKey),
+    element: root,
+    children: recursive(Array.from(childNodes), rootKey)
+  }
+}

package/state.js ADDED Viewed

@@ -0,0 +1,26 @@
+export default (state, rerender) =>
+  new Proxy(state, {
+    set(obj, prop, value) {
+      const ref = Reflect.set(...arguments)
+      rerender({
+        [prop]: value,
+      })
+      // console.info("state change", { obj, prop, value });
+      return ref
+    },
+    get(target, prop) {
+      // if (typeof target[prop] === 'function') {
+      //   const inputString = target[prop].toString();
+      //   const regex = /\$\.\w+/g;
+      //   let match;
+      //   while ((match = regex.exec(inputString))) {
+      //     const varName = match[0].split('.')[1];
+      //     console.log(varName, state[varName]);
+      //   }
+      //   console.log(arguments)
+      // }
+      return Reflect.get(...arguments)
+    },
+  })

package/utils.js ADDED Viewed

@@ -0,0 +1,45 @@
+// Fast incrementing counter instead of expensive random hash
+let hashCounter = 0;
+export const hash = () => `_${hashCounter++}`;
+// Instead of using lodash-es as a dependency, we run our own deepMerge (mergeWith in lodash)
+export const deepMerge = (target, source) => {
+  // Handle null/undefined
+  if (source == null) return target;
+  if (target == null) return source;
+  // If source is not an object, return it
+  if (typeof source !== "object") return source;
+  // If source is an array, replace target array (don't merge arrays)
+  if (Array.isArray(source)) return source;
+  // Clone target to avoid mutation
+  const result = { ...target };
+  // Merge each property from source
+  for (const key in source) {
+    if (source.hasOwnProperty(key)) {
+      const targetValue = result[key];
+      const sourceValue = source[key];
+      // If both are objects (but not arrays), merge recursively
+      if (
+        targetValue != null &&
+        sourceValue != null &&
+        typeof targetValue === "object" &&
+        typeof sourceValue === "object" &&
+        !Array.isArray(targetValue) &&
+        !Array.isArray(sourceValue)
+      ) {
+        result[key] = deepMerge(targetValue, sourceValue);
+      } else {
+        // Otherwise, replace with source value (handles arrays and primitives)
+        result[key] = sourceValue;
+      }
+    }
+  }
+  return result;
+};

package/vibe.css ADDED Viewed

@@ -0,0 +1,11 @@
+/* Vibe Framework - Hydration Styles
+ * Elements with [vibe] attribute are hidden until framework removes it after hydration.
+ * This prevents flash of unprocessed content and disables transitions during init.
+ */
+[vibe] {
+  visibility: hidden;
+}
+[vibe] * {
+  transition: none !important;
+}