@mintjamsinc/ichigojs 0.1.59 → 0.1.60

package/dist/ichigo.cjs

@@ -177,6 +177,8 @@
         StandardDirectiveName["V_HTML"] = "v-html";
         /** Text content directive. */
         StandardDirectiveName["V_TEXT"] = "v-text";
+        /** Focus management directive. */
+        StandardDirectiveName["V_FOCUS"] = "v-focus";
     })(StandardDirectiveName || (StandardDirectiveName = {}));
 
     // This file was generated. Do not modify manually!
@@ -12385,6 +12387,235 @@
         }
     }
 
+    // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
+    /**
+     * Directive for managing focus on form elements.
+     *
+     * Usage:
+     *     <input v-focus>                           Focus once on mount.
+     *     <input v-focus.select>                    Focus + select all on mount.
+     *     <input v-focus="isOpen">                  Focus when expression transitions from falsy to truthy.
+     *     <input v-focus.select="isOpen">           Conditional focus + select all.
+     *     <input v-focus.cursor-end="isOpen">       Conditional focus + place caret at end.
+     *
+     * Behavior notes:
+     * - 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.
+     * - Focus is deferred via requestAnimationFrame so that elements which
+     *   become visible just before this directive runs (e.g. inside v-if /
+     *   display:none containers) can still receive focus reliably.
+     */
+    class VFocusDirective {
+        /**
+         * The virtual node to which this directive is applied.
+         */
+        #vNode;
+        /**
+         * Optional expression evaluator. When absent, the directive focuses once on mount.
+         */
+        #evaluator;
+        /**
+         * Modifiers extracted from the directive name (e.g. "select", "cursor-end").
+         */
+        #modifiers = new Set();
+        /**
+         * Last evaluated boolean value, used for falsy -> truthy edge detection.
+         */
+        #previousValue = false;
+        /**
+         * @param context The context for parsing the directive.
+         */
+        constructor(context) {
+            this.#vNode = context.vNode;
+            // Extract modifiers from the directive name
+            // e.g., "v-focus.select" -> modifiers = {"select"}
+            const attrName = context.attribute.name;
+            if (attrName.startsWith(StandardDirectiveName.V_FOCUS + '.')) {
+                const parts = attrName.split('.');
+                parts.slice(1).forEach(mod => this.#modifiers.add(mod));
+            }
+            // Parse the expression and create the evaluator (optional)
+            const expression = context.attribute.value;
+            if (expression) {
+                if (!context.vNode.bindings) {
+                    throw new Error('VFocusDirective requires bindings when an expression is provided');
+                }
+                this.#evaluator = ExpressionEvaluator.create(expression, context.vNode.bindings, context.vNode.vApplication.functionDependencies);
+            }
+            // Remove the directive attribute from the element
+            this.#vNode.node.removeAttribute(context.attribute.name);
+        }
+        /**
+         * @inheritdoc
+         */
+        get name() {
+            return StandardDirectiveName.V_FOCUS;
+        }
+        /**
+         * @inheritdoc
+         */
+        get vNode() {
+            return this.#vNode;
+        }
+        /**
+         * @inheritdoc
+         */
+        get needsAnchor() {
+            return false;
+        }
+        /**
+         * @inheritdoc
+         */
+        get bindingsPreparer() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get domUpdater() {
+            // Without an expression, there is nothing reactive to track.
+            if (!this.#evaluator) {
+                return undefined;
+            }
+            const identifiers = this.#evaluator.dependentIdentifiers;
+            const evaluator = this.#evaluator;
+            const focusElement = () => this.#focus();
+            const updater = {
+                get dependentIdentifiers() {
+                    return identifiers;
+                },
+                applyToDOM: () => {
+                    const value = evaluator.evaluateAsBoolean();
+                    const previous = this.#previousValue;
+                    this.#previousValue = value;
+                    // Edge: falsy -> truthy
+                    if (!previous && value) {
+                        focusElement();
+                    }
+                }
+            };
+            return updater;
+        }
+        /**
+         * @inheritdoc
+         */
+        get templatize() {
+            return false;
+        }
+        /**
+         * @inheritdoc
+         */
+        get dependentIdentifiers() {
+            return this.#evaluator?.dependentIdentifiers ?? [];
+        }
+        /**
+         * @inheritdoc
+         */
+        get onMount() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onMounted() {
+            return () => {
+                if (!this.#evaluator) {
+                    // Unconditional: focus once on mount.
+                    this.#focus();
+                    return;
+                }
+                // Conditional: seed previous value and focus if already truthy on mount.
+                const value = this.#evaluator.evaluateAsBoolean();
+                this.#previousValue = value;
+                if (value) {
+                    this.#focus();
+                }
+            };
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdate() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUpdated() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmount() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        get onUnmounted() {
+            return undefined;
+        }
+        /**
+         * @inheritdoc
+         */
+        destroy() {
+            // No specific cleanup needed for this directive.
+        }
+        /**
+         * Focuses the element, applying any modifier-driven post-focus behavior.
+         * Deferred via requestAnimationFrame so that elements transitioning out
+         * of display:none (e.g. inside v-if) can receive focus reliably.
+         */
+        #focus() {
+            const element = this.#vNode.node;
+            if (!element || typeof element.focus !== 'function') {
+                return;
+            }
+            const applyModifiers = () => this.#applyModifiers();
+            requestAnimationFrame(() => {
+                // The element may have been unmounted between scheduling and execution.
+                if (!element.isConnected) {
+                    return;
+                }
+                element.focus();
+                applyModifiers();
+            });
+        }
+        /**
+         * Applies modifier-driven behavior after focus.
+         */
+        #applyModifiers() {
+            const element = this.#vNode.node;
+            if (this.#modifiers.has('select')) {
+                const inputEl = element;
+                if (typeof inputEl.select === 'function') {
+                    try {
+                        inputEl.select();
+                    }
+                    catch {
+                        // Some input types (e.g. number) reject select(); ignore.
+                    }
+                }
+                return;
+            }
+            if (this.#modifiers.has('cursor-end')) {
+                const inputEl = element;
+                if (typeof inputEl.setSelectionRange === 'function') {
+                    const len = (inputEl.value ?? '').length;
+                    try {
+                        inputEl.setSelectionRange(len, len);
+                    }
+                    catch {
+                        // Some input types (e.g. number) do not support selection ranges; ignore.
+                    }
+                }
+            }
+        }
+    }
+
     // Copyright (c) 2025 MintJams Inc. Licensed under MIT License.
     /**
      * The directive parser for standard directives.
@@ -12426,7 +12657,10 @@
                 // v-html
                 context.attribute.name === StandardDirectiveName.V_HTML ||
                 // v-text
-                context.attribute.name === StandardDirectiveName.V_TEXT) {
+                context.attribute.name === StandardDirectiveName.V_TEXT ||
+                // v-focus, v-focus.<modifier>
+                context.attribute.name === StandardDirectiveName.V_FOCUS ||
+                context.attribute.name.startsWith(StandardDirectiveName.V_FOCUS + ".")) {
                 return true;
             }
             return false;
@@ -12490,6 +12724,11 @@
             if (context.attribute.name === StandardDirectiveName.V_TEXT) {
                 return new VTextDirective(context);
             }
+            // v-focus, v-focus.<modifier>
+            if (context.attribute.name === StandardDirectiveName.V_FOCUS ||
+                context.attribute.name.startsWith(StandardDirectiveName.V_FOCUS + ".")) {
+                return new VFocusDirective(context);
+            }
             throw new Error(`The attribute "${context.attribute.name}" cannot be parsed by ${this.name}.`);
         }
     }