@mintjamsinc/ichigojs 0.1.76 → 0.1.78

package/dist/types/ichigo/VApplication.d.ts

@@ -2,6 +2,7 @@ import { VLogManager } from "./util/VLogManager";
 import { VApplicationOptions } from "./VApplicationOptions";
 import { VBindings } from "./VBindings";
 import { VNode } from "./VNode";
+import { VNodeInit } from "./VNodeInit";
 import { VDirectiveParserRegistry } from "./directives/VDirectiveParserRegistry";
 import { VComponentRegistry } from "./components/VComponentRegistry";
 import { VApplicationInit } from "./VApplicationInit";
@@ -52,11 +53,28 @@ export declare class VApplication {
      * object is exposed to data(), methods, and expressions as `$refs`. Non-reactive by design.
      */
     get refs(): Record<string, Element | Element[]>;
+    /**
+     * The custom element hosting this application when it powers a component
+     * (see the #hostElement field). Undefined for regular applications.
+     */
+    get hostElement(): HTMLElement | undefined;
+    set hostElement(element: HTMLElement | undefined);
+    /**
+     * Creates a VNode. Directives that need to build VNode trees at runtime
+     * (e.g. the scoped slot outlet) call this instead of constructing VNode
+     * directly, so they can keep their VNode import type-only and avoid a
+     * VNode -> VDirectiveManager -> directive -> VNode module cycle.
+     * @param init The initialization arguments for the virtual node.
+     * @returns The created VNode.
+     */
+    createVNode(init: VNodeInit): VNode;
     /**
      * Mounts the application.
      * @param target The CSS selector string or HTMLElement to mount the application to.
+     * @returns This application instance, so `VDOM.createApp(...).mount('#app')`
+     * can be assigned for later access (e.g. `app.bindings`, `app.unmount()`).
      */
-    mount(target: string | HTMLElement): void;
+    mount(target: string | HTMLElement): this;
     /**
      * Unmounts the application and cleans up resources.
      */

package/dist/types/ichigo/VApplicationOptions.d.ts

@@ -11,9 +11,12 @@ export type VComputedDefinition = (() => unknown) | {
 export interface VApplicationOptions {
     /**
      * A function that returns the initial data for the application.
+     * Optional: an application (or component) whose state comes entirely from
+     * props, computed properties, or methods may omit it — the runtime already
+     * treats it as optional.
      * @returns The initial data for the application.
      */
-    data: () => unknown;
+    data?: () => unknown;
     /**
      * A dictionary of computed properties for the application.
      * Each key is the name of the computed property, and the value is either:

package/dist/types/ichigo/components/IchigoComponentOptions.d.ts

@@ -1,16 +1,60 @@
 import { VApplicationOptions } from '../VApplicationOptions';
+/**
+ * Per-prop declaration options.
+ *
+ * All checks (type, required, validator) report console warnings only; values
+ * are never rejected or coerced. This mirrors the philosophy of the `emits`
+ * declaration: the declaration documents the contract and helps development,
+ * without changing runtime behavior.
+ */
+export interface PropOptions {
+    /**
+     * Expected type(s), given as constructor functions
+     * (String, Number, Boolean, Array, Object, Function, Date, or any class).
+     * When omitted, any type is accepted. null/undefined values always pass
+     * the type check (undefined is subject to `default`/`required` instead,
+     * and null is treated as an explicit "no value").
+     */
+    type?: Function | Function[];
+    /**
+     * Default value applied when the prop is undefined at mount time, or when
+     * the parent later assigns undefined.
+     *
+     * Object/Array defaults must be declared as a factory function
+     * (e.g. `default: () => []`) so that instances are not shared across
+     * component instances. A function default is treated as the value itself
+     * only when `type` includes Function; otherwise it is called as a factory.
+     */
+    default?: any;
+    /**
+     * When true, a warning is logged if the prop is still undefined at mount
+     * time (after `default` resolution). The mount proceeds either way.
+     */
+    required?: boolean;
+    /**
+     * Custom validator. A falsy return value logs a warning.
+     * Called for every non-null/undefined value delivered to the component.
+     */
+    validator?: (value: any) => boolean;
+}
+/**
+ * Props declaration: either a simple list of prop names, or a record of
+ * per-prop options. Use `null` (or `{}`) as the value for a prop that needs
+ * no constraints, e.g. `props: { target: null, size: { default: 'md' } }`.
+ */
+export type PropsDeclaration = string[] | Record<string, PropOptions | null>;
 /**
  * Options for defining a Web Component backed by ichigo.js reactivity.
  * Extends VApplicationOptions with component-specific settings.
  */
 export interface IchigoComponentOptions extends VApplicationOptions {
     /**
-     * List of property names to receive from the parent via attribute/property binding.
-     * Each name in this list will be exposed as a property setter on the custom element.
-     * When the parent updates a bound value (e.g., :items="items"), the component's
-     * reactive bindings are updated automatically.
+     * Properties to receive from the parent via property binding.
+     * Each declared prop is exposed as a property accessor on the custom
+     * element. When the parent updates a bound value (e.g., :items="items"),
+     * the component's reactive bindings are updated automatically.
      */
-    props?: string[];
+    props?: PropsDeclaration;
     /**
      * CSS selector for the <template> element that defines this component's markup.
      * Example: '#my-card' targets <template id="my-card">.

package/dist/types/ichigo/components/IchigoElement.d.ts

@@ -1,26 +1,67 @@
 import { VApplicationOptions } from '../VApplicationOptions';
+import { PropOptions } from './IchigoComponentOptions';
+import type { VNode } from '../VNode';
+/**
+ * A scoped slot template captured from the host element's children:
+ * the `<template v-slot:name="scopeVar">` element and the scope variable name
+ * its content receives the slot props under (may be empty when no variable
+ * was declared).
+ */
+export interface ScopedSlotEntry {
+    template: HTMLTemplateElement;
+    scopeVar: string;
+}
 /**
  * Base class for ichigo.js-backed Web Components (Light DOM, no Shadow DOM).
  *
  * Mount timing:
  *  - If the component declares no props, the VApplication is mounted synchronously
  *    at the end of connectedCallback (the template is known, no props to wait for).
- *  - If the component declares props, the VApplication is mounted the first time
- *    _setProp() is called after connectedCallback has prepared the DOM. This
- *    guarantees that the parent framework (e.g. ichigo.js VBindDirective) has
- *    already delivered at least one prop value before data() is evaluated.
+ *  - If the component declares props, a mount microtask is scheduled at the end of
+ *    connectedCallback. Prop values delivered synchronously by the parent framework
+ *    (VBindDirective runs within the parent's mount task) are stored before the
+ *    microtask fires, so data() can read them. A component used without any prop
+ *    binding still mounts — with its declared defaults — instead of waiting forever.
  *
- * Subclasses must set the static fields _template, _props and _buildOptions before
- * calling customElements.define(). defineComponent() handles this automatically.
+ * Slot content is captured on the first connection and cached, so a component
+ * that is moved in the DOM (e.g. reordered by v-for) re-expands its template
+ * and redistributes the same slot nodes on reconnection.
+ *
+ * Subclasses must set the static fields _template, _props, _propOptions and
+ * _buildOptions before calling customElements.define(). defineComponent()
+ * handles this automatically.
  */
 export declare class IchigoElement extends HTMLElement {
     #private;
+    /**
+     * True once this element's children are the expanded component template.
+     * Read by VNode during compilation: a parent application must not compile
+     * an expanded component's internals as its own template (the internals
+     * belong to this component's VApplication and scope).
+     */
+    _ichigoExpanded: boolean;
+    /**
+     * Host context installed by the parent application's VNode when it
+     * compiles this element. Gives component-boundary features (e.g. scoped
+     * slot outlets) access to the parent scope. Undefined when the element is
+     * placed outside any ichigo application.
+     */
+    _ichigoHost?: {
+        vNode: VNode;
+    };
+    /**
+     * The scoped slot templates captured from this element's children, keyed
+     * by slot name ('default' for `v-slot` without a name). Read by
+     * VSlotOutletDirective when the component template renders a `<slot>`.
+     */
+    get _ichigoScopedSlots(): Map<string, ScopedSlotEntry> | undefined;
     connectedCallback(): void;
     disconnectedCallback(): void;
     /**
      * Called by the property setters generated by defineComponent().
      * Before mount: stores the value and schedules a mount microtask.
      * After mount: pushes the value directly into the reactive bindings.
+     * An undefined value is replaced by the prop's declared default, if any.
      */
     _setProp(name: string, value: any): void;
     /**
@@ -32,9 +73,16 @@ export declare class IchigoElement extends HTMLElement {
      */
     static _template: string;
     /**
-     * List of declared prop names. Used to decide whether to defer mounting.
+     * List of declared prop names. Used to decide whether to defer mounting,
+     * and by VBindDirective to resolve kebab-case attributes to prop names.
      */
     static _props: string[];
+    /**
+     * Per-prop declaration options (type / default / required / validator),
+     * keyed by prop name. Normalized by defineComponent(): a prop declared
+     * without options gets an empty object.
+     */
+    static _propOptions: Record<string, PropOptions>;
     /**
      * Factory that builds VApplicationOptions from the current prop values.
      * Implemented by defineComponent() as a closure that captures the user's options.

package/dist/types/ichigo/components/IchigoElementRegistry.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Registry of custom element tag names defined via defineComponent().
+ *
+ * VNode consults this registry during compilation to recognize component
+ * boundaries: the children of an already-expanded ichigo component belong to
+ * the component's own VApplication and must not be compiled by the parent
+ * application (doing so would strip the component's directives and evaluate
+ * its template expressions in the wrong scope).
+ */
+export declare class IchigoElementRegistry {
+    #private;
+    /**
+     * Registers a component tag name. Called by defineComponent().
+     * @param tagName The custom element tag name (case-insensitive).
+     */
+    static add(tagName: string): void;
+    /**
+     * Checks whether a tag name belongs to a component defined via defineComponent().
+     * @param tagName The tag name to check (case-insensitive; nodeName is accepted as-is).
+     */
+    static has(tagName: string): boolean;
+}

package/dist/types/ichigo/components/defineComponent.d.ts

@@ -16,9 +16,8 @@ import { IchigoComponentOptions } from './IchigoComponentOptions';
  * ```typescript
  * defineComponent('my-list', {
  *   template: '#my-list',
- *   props: ['items'],
- *   data() {
- *     return { items: this.items ?? [] };
+ *   props: {
+ *     items: { type: Array, default: () => [] },
  *   },
  * });
  * ```
@@ -28,6 +27,10 @@ import { IchigoComponentOptions } from './IchigoComponentOptions';
  * </my-list>
  * ```
  *
+ * Props may be declared as a simple name list (`props: ['items']`) or as a
+ * record with per-prop options (type / default / required / validator).
+ * See {@link PropOptions} for the declaration semantics.
+ *
  * @param tagName  Custom element tag name (must contain a hyphen, e.g. 'my-card').
  * @param options  Component options including template selector and optional props.
  */

package/dist/types/ichigo/directives/VSlotOutletDirective.d.ts

@@ -0,0 +1,114 @@
+import type { VNode } from "../VNode";
+import { VBindingsPreparer } from "../VBindingsPreparer";
+import { VDirective } from "./VDirective";
+import { VDOMUpdater } from "../VDOMUpdater";
+/**
+ * Renders a scoped slot outlet: a `<slot>` element inside a component template
+ * whose host element received a matching `<template v-slot:name="scope">` from
+ * the parent.
+ *
+ * The slot content is compiled in the PARENT application's scope (the scope in
+ * which the template was authored), extended with the slot props — the values
+ * bound on the `<slot>` outlet with `v-bind` / `:` — exposed under the single
+ * scope variable declared in `v-slot` (e.g. `v-slot:item="row"` makes
+ * `row.node`, `row.index`, ... available):
+ *
+ * ```html
+ * <!-- component template -->
+ * <li v-for="(node, i) of items">
+ *   <slot name="item" :node="node" :index="i">fallback</slot>
+ * </li>
+ *
+ * <!-- usage -->
+ * <my-tree :items="nodes">
+ *   <template v-slot:item="row">{{ row.node.label }} ({{ appTitle }})</template>
+ * </my-tree>
+ * ```
+ *
+ * This directive is created only when a scoped template for the slot's name
+ * exists (see {@link VSlotOutletDirective.tryCreate}); otherwise `<slot>`
+ * elements keep their existing behavior (static distribution at expansion,
+ * or fallback content compiled in the component scope).
+ *
+ * Rendering happens synchronously in onMount — before the component
+ * application would compile the slot's fallback children — by replacing the
+ * `<slot>` element with a clone of the scoped template's content. The content
+ * VNode is attached under the host element's VNode in the parent application,
+ * so parent-side data changes flow through the normal update cycle; slot-prop
+ * changes on the component side are pushed by this directive's domUpdater.
+ */
+export declare class VSlotOutletDirective implements VDirective {
+    #private;
+    /**
+     * Creates a slot outlet directive for the given `<slot>` VNode when a
+     * scoped template for its slot name was captured on the host element.
+     * Returns undefined when there is nothing to do (no component host, no
+     * scoped template for this name) so the `<slot>` element keeps its
+     * existing behavior.
+     */
+    static tryCreate(vNode: VNode): VSlotOutletDirective | undefined;
+    private constructor();
+    /**
+     * @inheritdoc
+     */
+    get name(): string;
+    /**
+     * @inheritdoc
+     */
+    get vNode(): VNode;
+    /**
+     * @inheritdoc
+     */
+    get needsAnchor(): boolean;
+    /**
+     * @inheritdoc
+     */
+    get bindingsPreparer(): VBindingsPreparer | undefined;
+    /**
+     * @inheritdoc
+     */
+    get domUpdater(): VDOMUpdater | undefined;
+    /**
+     * @inheritdoc
+     */
+    get templatize(): boolean;
+    /**
+     * @inheritdoc
+     */
+    get dependentIdentifiers(): string[];
+    /**
+     * @inheritdoc
+     *
+     * The initial render happens here — synchronously during VNode
+     * construction, after the directives are created and BEFORE the component
+     * application compiles the slot element's children. This guarantees the
+     * outlet renders exactly once regardless of whether its slot props have
+     * reactive identifiers, and removes the fallback children before they
+     * could be compiled in the component scope.
+     */
+    get onMount(): (() => void) | undefined;
+    /**
+     * @inheritdoc
+     */
+    get onMounted(): (() => void) | undefined;
+    /**
+     * @inheritdoc
+     */
+    get onUpdate(): (() => void) | undefined;
+    /**
+     * @inheritdoc
+     */
+    get onUpdated(): (() => void) | undefined;
+    /**
+     * @inheritdoc
+     */
+    get onUnmount(): (() => void) | undefined;
+    /**
+     * @inheritdoc
+     */
+    get onUnmounted(): (() => void) | undefined;
+    /**
+     * @inheritdoc
+     */
+    destroy(): void;
+}

package/dist/types/index.d.ts

@@ -5,6 +5,6 @@ export { ReactiveProxy } from './ichigo/util/ReactiveProxy';
 export { ExpressionUtils } from './ichigo/util/ExpressionUtils';
 export { toDisplayString } from './ichigo/util/DisplayString';
 export { defineComponent } from './ichigo/components/defineComponent';
-export type { IchigoComponentOptions } from './ichigo/components/IchigoComponentOptions';
+export type { IchigoComponentOptions, PropOptions, PropsDeclaration } from './ichigo/components/IchigoComponentOptions';
 export { IchigoElement } from './ichigo/components/IchigoElement';
 export type { VEmitOptions } from './ichigo/VEmitOptions';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintjamsinc/ichigojs",
-  "version": "0.1.76",
+  "version": "0.1.78",
   "description": "ichigo.js - Simple and intuitive reactive framework. Lightweight, fast, and user-friendly virtual DOM library",
   "main": "./dist/ichigo.cjs",
   "module": "./dist/ichigo.esm.js",