@mintjamsinc/ichigojs 0.1.68 → 0.1.69

package/README.md

@@ -9,14 +9,17 @@ A simple and intuitive reactive framework. Lightweight, fast, and user-friendly
 
 - ✨ **Vue-like API** - Familiar syntax for Vue developers
 - ⚡ **Reactive Proxy System** - Automatic change detection without manual triggers
-- 🎯 **Computed Properties** - Automatic dependency tracking and re-evaluation
+- 🎯 **Computed Properties** - Automatic dependency tracking and re-evaluation, including writable computed (`{ get, set }`)
+- 👀 **Watchers** - React to data changes with the `watch` option (`deep`, `immediate`)
 - 🔄 **Two-way Binding** - `v-model` with modifiers (`.lazy`, `.number`, `.trim`)
 - 🔌 **Lifecycle Hooks** - `@mount`, `@mounted`, `@update`, `@updated`, `@unmount`, `@unmounted` with context (`$ctx`)
 - 💾 **userData Storage** - Proxy-free storage for third-party library instances with auto-cleanup
+- 🧩 **Components** - Reusable Web Components via `defineComponent` with `props`, `slot`, and `$emit`
 - 📦 **Lightweight** - Minimal bundle size
 - 🚀 **High Performance** - Efficient batched updates via microtask queue
 - 💪 **TypeScript** - Written in TypeScript with full type support
-- 🎨 **Directives** - `v-if`, `v-for`, `v-show`, `v-bind`, `v-on`, `v-model`, `v-resize`, `v-intersection`, `v-performance`
+- 🎨 **Directives** - `v-if`, `v-else-if`, `v-else`, `v-for`, `v-show`, `v-bind`, `v-on`, `v-model`, `v-text`, `v-html`, `v-focus`, `v-resize`, `v-intersection`, `v-performance`
+- 🎯 **Focus Management** - Declarative focus control with the `v-focus` directive (`.select`, `.cursor-end`)
 - 📐 **Resize Observer** - Monitor element size changes with `v-resize` directive
 - 👁️ **Intersection Observer** - Detect element visibility with `v-intersection` directive
 - ⚡ **Performance Observer** - Monitor performance metrics with `v-performance` directive
@@ -195,6 +198,84 @@ VDOM.createApp({
 }).mount('#app');
 ```
 
+**Writable Computed Properties:**
+
+A computed property can also be defined as an object with both a `get` and a
+`set` function. This makes it writable, so it can be used as a `v-model` target
+or assigned to directly. Reads go through `get`, while assignments are routed
+through `set`.
+
+```javascript
+VDOM.createApp({
+  data() {
+    return {
+      firstName: 'John',
+      lastName: 'Doe'
+    };
+  },
+  computed: {
+    fullName: {
+      get() {
+        return `${this.firstName} ${this.lastName}`;
+      },
+      set(value) {
+        const [first, last] = value.split(' ');
+        this.firstName = first;
+        this.lastName = last;
+      }
+    }
+  }
+}).mount('#app');
+```
+
+```html
+<!-- Assigning through v-model invokes the computed setter -->
+<input v-model="fullName">
+```
+
+### Watchers
+
+Use the `watch` option to run a callback whenever a watched property changes.
+Keys are property paths (e.g. `"count"`, `"user.name"`), and the callback
+receives the new and previous values.
+
+```javascript
+VDOM.createApp({
+  data() {
+    return {
+      count: 0,
+      user: { name: 'Alice' }
+    };
+  },
+  watch: {
+    // Shorthand: a callback function
+    count(newValue, oldValue) {
+      console.log(`count changed from ${oldValue} to ${newValue}`);
+    },
+
+    // Watch a nested property by path
+    'user.name'(newValue, oldValue) {
+      console.log(`name changed from ${oldValue} to ${newValue}`);
+    },
+
+    // Full form: an options object with deep / immediate
+    user: {
+      handler(newValue, oldValue) {
+        console.log('user object changed', newValue);
+      },
+      deep: true,      // Observe nested changes inside the object
+      immediate: true  // Invoke once immediately with the current value
+    }
+  }
+}).mount('#app');
+```
+
+**Watcher options:**
+
+- `handler` - The callback invoked when the watched value changes
+- `deep` - When `true`, deeply observes nested object/array changes (default: `false`)
+- `immediate` - When `true`, invokes the handler once immediately on registration with the current value (default: `false`)
+
 ### Directives
 
 #### v-if / v-else-if / v-else
@@ -314,6 +395,73 @@ methods: {
 }
 ```
 
+#### v-text
+
+Set the text content of an element. The expression result replaces the
+element's `textContent`. Unlike `v-html`, the content is rendered as plain
+text, so HTML is escaped and XSS is not a concern.
+
+```html
+<span v-text="message"></span>
+
+<!-- Equivalent to -->
+<span>{{ message }}</span>
+```
+
+Use `v-text` when you want to set the entire text content of an element from a
+single expression (it overwrites any existing content), rather than
+interpolating with `{{ }}`.
+
+#### v-html
+
+Set the raw HTML content of an element. The expression result is assigned to
+the element's `innerHTML`.
+
+```html
+<div v-html="htmlContent"></div>
+```
+
+> ⚠️ **Security warning:** Dynamically rendering arbitrary HTML can easily lead
+> to XSS attacks. Only use `v-html` on **trusted** content, and **never** on
+> user-provided content. For plain text, use `v-text` or `{{ }}` interpolation
+> instead.
+
+#### v-focus
+
+Declaratively manage focus on an element. Focus is deferred via
+`requestAnimationFrame`, so elements that become visible just before the
+directive runs (for example inside a `v-if` or a `display: none` container)
+still receive focus reliably.
+
+```html
+<!-- Focus once after mount -->
+<input v-focus>
+
+<!-- Focus + select all text after mount -->
+<input v-focus.select>
+
+<!-- Focus + place the caret at the end of the value -->
+<input v-focus.cursor-end value="prefilled">
+
+<!-- Conditional focus: fires when the expression goes from falsy to truthy -->
+<input v-focus="isEditing">
+
+<!-- Conditional focus + select all -->
+<input v-focus.select="isEditing">
+```
+
+**Behavior:**
+
+- **Without an expression**, the element is focused exactly once after mount.
+- **With an expression**, focus fires only on the falsy → truthy edge, so the
+  user is not repeatedly re-focused on every reactive update. If the value is
+  already truthy on mount, the element is focused immediately.
+
+**Modifiers:**
+
+- `.select` - After focusing, selects all text in the input/textarea
+- `.cursor-end` - After focusing, places the caret at the end of the value
+
 #### v-resize
 
 Monitor element size changes using ResizeObserver:
@@ -591,9 +739,20 @@ Two-way data binding:
 <input v-model.number="age">          <!-- Convert to number -->
 <input v-model.trim="username">       <!-- Trim whitespace -->
 
-<!-- Checkbox -->
+<!-- Checkbox (boolean) -->
 <input type="checkbox" v-model="isChecked">
 
+<!-- Checkbox with custom true/false values -->
+<input type="checkbox" v-model="status" :true-value="'yes'" :false-value="'no'">
+
+<!-- Checkbox group bound to an array -->
+<input type="checkbox" value="a" v-model="selectedItems">
+<input type="checkbox" value="b" v-model="selectedItems">
+
+<!-- Radio -->
+<input type="radio" value="a" v-model="picked">
+<input type="radio" value="b" v-model="picked">
+
 <!-- Select -->
 <select v-model="selected">
   <option value="a">Option A</option>
@@ -601,6 +760,13 @@ Two-way data binding:
 </select>
 ```
 
+**Supported elements:**
+
+- **Text inputs / `<textarea>`** - Binds to the element's value
+- **Checkbox** - Binds to a boolean, to a custom value pair via `:true-value` / `:false-value`, or to an array (when the bound value is an array, the checkbox's `value` is added/removed)
+- **Radio** - Binds to the `value` (or `:value`) of the selected radio button
+- **Select** - Binds to the selected option's value (re-applied automatically when options are generated dynamically via `v-for`)
+
 ### Methods
 
 Methods have access to data and computed properties via `this`:
@@ -639,6 +805,108 @@ methods: {
 }
 ```
 
+## Components
+
+ichigo.js components are real [Custom Elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)
+backed by the same reactivity system. Define a component with `defineComponent`,
+pointing it at a `<template>` for its markup.
+
+```html
+<!-- Component markup -->
+<template id="my-list">
+  <ul v-if="items.length > 0">
+    <li v-for="item of items" :key="item.id">{{ item.name }}</li>
+  </ul>
+  <!-- Fallback content projected from the parent -->
+  <slot></slot>
+</template>
+```
+
+```javascript
+import { defineComponent } from '@mintjamsinc/ichigojs';
+
+defineComponent('my-list', {
+  template: '#my-list',     // CSS selector for the <template>
+  props: ['items'],         // Props received from the parent
+  data() {
+    // Props are accessible via `this` and can be defaulted/transformed here
+    return { items: this.items ?? [] };
+  }
+});
+```
+
+```html
+<!-- Usage -->
+<my-list :items="searchResults">
+  <span slot="empty">No results.</span>
+</my-list>
+```
+
+**Props:**
+
+- Declared via the `props` array. Each declared prop becomes a property on the
+  custom element, so the parent can bind to it with `v-bind` / `:`
+  (e.g. `:items="searchResults"`).
+- Props are reactive from the start and are included in the component's data
+  automatically. Values returned from `data()` take precedence, allowing you to
+  default or transform a prop (e.g. `this.items ?? []`).
+
+**Slots:**
+
+Use the native `<slot>` element in the component template to project content
+from the parent. ichigo.js components use Light DOM.
+
+### Events (`$emit`)
+
+Components (and applications) can dispatch custom events with `$emit`, which is
+available in both templates and methods. By default the event bubbles from the
+component's root element, so a parent can listen for it with `v-on` / `@` on the
+component tag.
+
+```javascript
+defineComponent('my-button', {
+  template: '#my-button',
+  // Optional: declare the events this component emits.
+  // Emitting an undeclared event logs a development warning (validation only;
+  // it never blocks dispatch). Omit `emits` to allow any event name.
+  emits: ['selected'],
+  methods: {
+    onClick() {
+      // $emit(name, detail?, options?)
+      this.$emit('selected', { id: 42 });
+    }
+  }
+});
+```
+
+```html
+<!-- Parent listens for the custom event; payload is in event.detail -->
+<my-button @selected="onSelected"></my-button>
+```
+
+**`$emit(name, detail?, options?)`:**
+
+- `name` - The event name (listened to as `@name` on the parent)
+- `detail` - The payload exposed as `event.detail`
+- `options` - Dispatch options (`VEmitOptions`):
+  - `bubbles` - Whether the event bubbles (default: `true`)
+  - `cancelable` - Whether `preventDefault()` has an effect (default: `true`); `$emit` returns `false` when a listener calls `preventDefault()`
+  - `composed` - Whether the event crosses shadow DOM boundaries (default: `false`)
+  - `target` - The dispatch target (default: the application root element). Set to `document` / `window` for a global event bus.
+
+### Legacy component directive (`v-component`)
+
+> ⚠️ **Deprecated.** The `v-component` directive and the `VComponentRegistry`
+> are deprecated and will be removed in a future release. Use
+> [`defineComponent`](#components) (Custom Elements) for new code.
+
+For reference, the legacy mechanism renders a component registered in the
+application's `VComponentRegistry` by id, passing props through `:options`:
+
+```html
+<div v-component="my-component" :options="{ message: 'Hello' }"></div>
+```
+
 ## Performance
 
 ichigo.js uses several optimization techniques:
@@ -696,13 +964,33 @@ Creates a new application instance.
 
 **Options:**
 
-- `data()`: Function that returns the initial data object
-- `computed`: Object containing computed property definitions
+- `data()`: Function that returns the initial data object. Called with a `$ctx` (`{ $markRaw }`) as `this`.
+- `computed`: Object containing computed property definitions. Each value is either a getter function (read-only) or a `{ get, set }` object (writable).
 - `methods`: Object containing method definitions
+- `watch`: Object mapping property paths to watcher definitions (a callback, or `{ handler, deep, immediate }`)
+- `emits`: Optional array of event names the app/component is expected to emit via `$emit`. Emitting an undeclared event logs a development warning (validation only).
 - `logLevel`: Logging level (`'debug'` | `'info'` | `'warn'` | `'error'`)
 
 **Returns:** Application instance with `mount(selector)` method
 
+**Instance helpers** (available in `data()`, methods, expressions, and lifecycle hooks as appropriate):
+
+- `$markRaw(obj)`: Marks an object as non-reactive (see [Marking Objects as Non-Reactive](#marking-objects-as-non-reactive))
+- `$nextTick(callback)`: Runs a callback after the next DOM update
+- `$emit(name, detail?, options?)`: Dispatches a custom event (see [Events](#events-emit))
+- `$ctx`: Lifecycle/handler context with `element`, `vnode`, and `userData`
+
+### defineComponent(tagName, options)
+
+Defines and registers a custom element backed by ichigo.js reactivity. See [Components](#components).
+
+**Options** (extends the `createApp` options above):
+
+- `template`: CSS selector for the `<template>` element that defines the component's markup (required)
+- `props`: Array of property names received from the parent via attribute/property binding
+
+**Returns:** `void` (the custom element is registered via `customElements.define`)
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/ichigo.cjs

@@ -10270,9 +10270,18 @@
         #sourceName;
         #useOfSyntax = false; // Track if 'of' syntax was used
         /**
-         * Map to track rendered items by their keys
+         * Ordered list of currently rendered items.
+         *
+         * This is intentionally an ordered array of { key, vNode } entries rather
+         * than a Map<key, VNode>. The :key attribute is a *reconciliation hint*
+         * used to identify and reuse the same logical row across re-renders — it is
+         * not the identity of the rendered set. Keying the rendered set by a Map
+         * would make it structurally impossible to hold two rows that resolve to
+         * the same key, which would silently drop application data. The most
+         * fundamental invariant of a list directive is "N items in => N rows out",
+         * so the rendered set must be a positional list that can carry duplicates.
          */
-        #renderedItems = new Map();
+        #renderedItems = [];
         /**
          * Previous iterations to detect changes
          */
@@ -10395,11 +10404,11 @@
         destroy() {
             // Clean up all rendered items
             // First destroy all VNodes (calls @unmount hooks), then remove from DOM
-            for (const vNode of this.#renderedItems.values()) {
+            for (const { vNode } of this.#renderedItems) {
                 vNode.destroy();
             }
             // Then remove DOM nodes
-            for (const vNode of this.#renderedItems.values()) {
+            for (const { vNode } of this.#renderedItems) {
                 const range = vNode.fragmentRange;
                 if (range) {
                     range.remove();
@@ -10410,7 +10419,7 @@
                     vNode.node.parentNode.removeChild(vNode.node);
                 }
             }
-            this.#renderedItems.clear();
+            this.#renderedItems = [];
             this.#previousIterations = [];
         }
         /**
@@ -10451,7 +10460,24 @@
             this.#previousIterations = iterations;
         }
         /**
-         * Key-based diffing for efficient DOM updates
+         * Key-based diffing for efficient DOM updates.
+         *
+         * Reconciliation model
+         * --------------------
+         * The :key attribute is treated as a *hint* for reusing the same logical
+         * row across re-renders, not as the identity of the rendered set. The
+         * previously rendered rows are placed into a pool keyed by :key (a queue
+         * per key, so equal keys can hold more than one row). Each incoming
+         * iteration then claims a row from its key's queue when one is available,
+         * otherwise a fresh row is created. Whatever stays in the pool at the end
+         * is genuinely gone and is destroyed and removed.
+         *
+         * This guarantees the directive's most fundamental invariant — "N items in
+         * => N rows out" — even when the application supplies duplicate keys. We
+         * still warn on duplicates because they make reuse ambiguous (reordering
+         * becomes positional rather than identity-stable), but we never silently
+         * drop the application's data, and no row is ever orphaned: every old row
+         * is either reused or explicitly removed.
          */
         #updateList(newIterations) {
             const parent = this.#vNode.anchorNode?.parentNode;
@@ -10459,22 +10485,38 @@
             if (!parent || !anchor) {
                 throw new Error('v-for element must have a parent and anchor');
             }
-            const newRenderedItems = new Map();
-            // Track which keys are still needed and detect duplicates
-            const neededKeys = new Set();
+            // Build a reuse pool from the currently rendered rows. A queue per key
+            // (FIFO) lets duplicate keys reuse multiple rows: the first incoming
+            // occurrence claims the first existing row, the second claims the next,
+            // and so on.
+            const pool = new Map();
+            for (const { key, vNode } of this.#renderedItems) {
+                let queue = pool.get(key);
+                if (!queue) {
+                    queue = [];
+                    pool.set(key, queue);
+                }
+                queue.push(vNode);
+            }
+            // Decide, for each incoming iteration in order, whether it reuses an
+            // existing row or needs a new one. Reused rows are taken out of the
+            // pool so that what remains afterwards is exactly the set to remove.
             const seenKeys = new Set();
-            for (const ctx of newIterations) {
-                if (seenKeys.has(ctx.key)) {
-                    console.warn(`[ichigo.js] Duplicate key detected in v-for: "${ctx.key}". This may cause unexpected behavior. Keys should be unique.`);
+            const plan = [];
+            for (const context of newIterations) {
+                if (seenKeys.has(context.key)) {
+                    console.warn(`[ichigo.js] Duplicate key detected in v-for: "${context.key}". All entries are still rendered, but reordering may be unstable. Keys should be unique.`);
                 }
-                seenKeys.add(ctx.key);
-                neededKeys.add(ctx.key);
+                seenKeys.add(context.key);
+                const queue = pool.get(context.key);
+                const reused = queue && queue.length ? queue.shift() : undefined;
+                plan.push({ context, reused });
             }
-            // Remove items that are no longer needed
+            // Remove rows that were not reused.
             // First destroy VNodes (calls @unmount hooks while DOM is still accessible)
             const nodesToRemove = [];
-            for (const [key, vNode] of this.#renderedItems) {
-                if (!neededKeys.has(key)) {
+            for (const queue of pool.values()) {
+                for (const vNode of queue) {
                     nodesToRemove.push(vNode);
                     vNode.destroy();
                 }
@@ -10493,11 +10535,12 @@
                     parentOfNode.removeChild(vNode.node);
                 }
             }
-            // Add or reorder items
+            // Add or reorder rows, building the new ordered rendered set.
+            const newRenderedItems = [];
             let prevNode = anchor;
-            for (const context of newIterations) {
+            for (const { context, reused } of plan) {
                 const { key } = context;
-                let vNode = this.#renderedItems.get(key);
+                let vNode = reused;
                 if (!vNode) {
                     // Create new item
                     const clone = this.#cloneNode();
@@ -10529,7 +10572,7 @@
                     if (clone.nodeType === Node.DOCUMENT_FRAGMENT_NODE) {
                         const range = VFragmentRange.insert(parent, prevNode.nextSibling, 'vfor-fragment', clone);
                         vNode.fragmentRange = range;
-                        newRenderedItems.set(key, vNode);
+                        newRenderedItems.push({ key, vNode });
                         vNode.forceUpdate();
                         prevNode = range.lastNode;
                         continue;
@@ -10543,12 +10586,12 @@
                     else {
                         parent.appendChild(nodeToInsert);
                     }
-                    newRenderedItems.set(key, vNode);
+                    newRenderedItems.push({ key, vNode });
                     vNode.forceUpdate();
                 }
                 else {
                     // Reuse existing item
-                    newRenderedItems.set(key, vNode);
+                    newRenderedItems.push({ key, vNode });
                     // Update bindings
                     this.#updateItemBindings(vNode, context);
                     // For fragment-backed iterations, move the entire range atomically.
@@ -10574,7 +10617,7 @@
                 // Advance prevNode to this iteration's last DOM node
                 prevNode = vNode.fragmentRange?.lastNode ?? vNode.anchorNode ?? vNode.node;
             }
-            // Update rendered items map
+            // Update the ordered rendered set
             this.#renderedItems = newRenderedItems;
         }
         /**