@vmz/core 0.3.13 → 0.3.15

package/dist/browser/client-nav.types.d.ts

@@ -5,20 +5,17 @@ import type { ComponentCtorLike, DirectInstance } from './direct-api.types.js';
 export type HydrateFn = (Ctor: ComponentCtorLike, root: Element, props: object) => Promise<unknown>;
 export type HydrateRouteFn = (Page: ComponentCtorLike, root: Element, props: object, layouts?: ComponentCtorLike[]) => Promise<unknown>;
 export type HydrateRoutePageFn = (Page: ComponentCtorLike, root: Element, props: object) => Promise<unknown>;
-export type DomFallbackModule = {
-    hydrate?: HydrateFn;
-    hydrateRoute?: HydrateRouteFn;
-    hydrateRoutePage?: HydrateRoutePageFn;
-};
 export type ClientNavOpts = {
     fetchImpl?: typeof fetch;
     document?: Document;
     history?: History;
     location?: Location;
+    /** Packed face 的 hydrate，由生成入口静态引入；页面导航缺失时显式报错，不回落到未打包路径。 */
     hydrate?: HydrateFn;
     hydrateRoute?: HydrateRouteFn;
     hydrateRoutePage?: HydrateRoutePageFn;
     destroy?: (inst: DirectInstance | object) => void;
+    /** Pack manifest 的 chunk 查表（生成入口的 import 表）；缺失时页面导航显式报错。 */
     importPage?: (chunkId: string) => Promise<unknown>;
 };
 export type TransitionToOpts = {

package/dist/browser/direct-api.types.d.ts

@@ -127,6 +127,10 @@ export type DirectApi = {
     el: (tag: string) => Element;
     text: (value?: unknown) => Text;
     frag: () => DocumentFragment;
+    /** Multi-root `<template v-for>` row fragment (scoped on resume by key). */
+    fragRow: (key?: unknown) => DocumentFragment;
+    /** Closes the row scope opened by `fragRow`. */
+    rowEnd: () => void;
     comment: (value?: string) => Comment;
     attr: (el: Element, name: string, value: unknown) => void;
     mergeClass: (...parts: unknown[]) => string;
@@ -140,12 +144,19 @@ export type DirectApi = {
     onMethod: (el: Element, type: string, method: string) => void;
     onComponentEvent: (el: Element, type: string, method: string) => void;
     adoptEnter: (node: Element) => boolean;
+    adoptEnterSlot: (hostEl: Element, name: string) => boolean;
     adoptLeave: () => void;
     projectDefaultSlot: (hostEl: HTMLElement, node: Node) => void;
     projectNamedSlot: (hostEl: HTMLElement, name: string, node: Node) => void;
     setHtml: (el: Element, value: unknown) => void;
+    /** `v-html` write that keeps the SSR subtree when its payload digest matches. */
+    html: (el: Element, value: unknown) => void;
     setShow: (el: HTMLElement, condition: unknown) => void;
     bindHtml: (inst: DirectInstance, bindingId: BindingId, deps: string[], get: PatchFn, el: Element) => void;
     bindComponentProp: (inst: DirectInstance, bindingId: BindingId, deps: string[], get: PatchFn, hostInst: DirectInstance, propName: string) => void;
+    bindComponentProps: (inst: DirectInstance, hostEl: HTMLElement, slot: string, deps: string[], get: PatchFn) => void;
+    bindComponentEvents: (inst: DirectInstance, hostEl: HTMLElement, slot: string, deps: string[], get: PatchFn) => void;
+    bindObjectListeners: (el: Element, slot: string, source: unknown, inst: DirectInstance | null, mode: 'bind' | 'on') => void;
+    spreadProps: (source: unknown) => Record<string, unknown>;
     component: (Ctor: ComponentCtorLike | string, props?: object) => HTMLElement;
 };

package/dist/browser/direct-host-box.d.ts

@@ -9,3 +9,14 @@ export declare function resolveDirectHostBox(name: string, Ctor: ComponentCtor |
 export declare function applyDirectHostBox(host: HTMLElement, name: string, Ctor: ComponentCtor | null | undefined): void;
 /** SSR attrs fragment for host box (only when contents). */
 export declare function directHostBoxStyleAttr(name: string, Ctor: ComponentCtor | null | undefined): string | null;
+/**
+ * Host element tag (`div` vs `span`).
+ *
+ * `display: contents` chips are phrasing content, so a `<div>` host is invalid
+ * HTML inside `<p>`. The browser parser then closes the `<p>` early and moves
+ * the host (and its trailing text) out of it, which desynchronizes the SSR tree
+ * from the client tree and makes resume rebuild those nodes. Emitting a `<span>`
+ * host keeps the SSR markup parse-stable: the parsed tree matches the tree the
+ * client `__vmzCreate` builds.
+ */
+export declare function resolveDirectHostTag(name: string, Ctor: ComponentCtor | null | undefined): 'div' | 'span';

package/dist/browser/direct-host-box.js

@@ -23,3 +23,16 @@ export function applyDirectHostBox(host, name, Ctor) {
 export function directHostBoxStyleAttr(name, Ctor) {
     return resolveDirectHostBox(name, Ctor) === 'contents' ? 'display:contents' : null;
 }
+/**
+ * Host element tag (`div` vs `span`).
+ *
+ * `display: contents` chips are phrasing content, so a `<div>` host is invalid
+ * HTML inside `<p>`. The browser parser then closes the `<p>` early and moves
+ * the host (and its trailing text) out of it, which desynchronizes the SSR tree
+ * from the client tree and makes resume rebuild those nodes. Emitting a `<span>`
+ * host keeps the SSR markup parse-stable: the parsed tree matches the tree the
+ * client `__vmzCreate` builds.
+ */
+export function resolveDirectHostTag(name, Ctor) {
+    return resolveDirectHostBox(name, Ctor) === 'contents' ? 'span' : 'div';
+}

package/dist/browser/dom/attributes.js

@@ -1,4 +1,10 @@
 import { mergeClassParts, mergeStyleParts } from '../../shared/dom-attr-normalize.js';
+/**
+ * `xlink:href` parsed from SSR HTML lives in the XLink namespace. A plain
+ * `setAttribute` writes a non-namespaced attribute instead, so the SVG host
+ * (`<use>`) no longer resolves the reference after hydration or client create.
+ */
+const XLINK_NS = 'http://www.w3.org/1999/xlink';
 export const BOOLEAN_HTML_ATTRS = new Set([
     'disabled',
     'checked',
@@ -21,6 +27,49 @@ export const BOOLEAN_HTML_ATTRS = new Set([
     'default',
     'inert',
 ]);
+/**
+ * A `<select>` is patched before its `<option>` children are appended: emit
+ * writes the model attr while the select is still empty, so the first write
+ * selects nothing and the model never changes again. Remember the pending
+ * value and replay it once the synchronous create pass has finished.
+ */
+const pendingSelectValues = new WeakMap();
+/** First `value` write seeds a textarea's default value once. */
+const seededTextareaDefaults = new WeakSet();
+/**
+ * `form.reset()` restores the *default* state, which browsers derive from the
+ * `selected`, `value` and `checked` attributes. The first write therefore
+ * records the initial model there, and later model updates move only the IDL
+ * state (or `selected` on the options) instead of rewriting the defaults.
+ */
+const seededSelectDefaults = new WeakSet();
+const seededInputValueDefaults = new WeakSet();
+const seededCheckedDefaults = new WeakSet();
+const pendingSelectReplays = new WeakSet();
+/** Checkbox and radio `value` attributes are submitted values, not defaults. */
+function isCheckableInput(el) {
+    const type = String(el.type || (el.getAttribute && el.getAttribute('type')) || 'text').toLowerCase();
+    return type === 'checkbox' || type === 'radio';
+}
+function replaySelectValue(el) {
+    if (!pendingSelectValues.has(el))
+        return;
+    const value = pendingSelectValues.get(el);
+    const opts = el.options || el.querySelectorAll?.('option') || [];
+    if (!opts.length)
+        return;
+    pendingSelectValues.delete(el);
+    applyDomAttr(el, 'value', value);
+}
+function deferSelectValue(el) {
+    if (pendingSelectReplays.has(el))
+        return;
+    pendingSelectReplays.add(el);
+    queueMicrotask(() => {
+        pendingSelectReplays.delete(el);
+        replaySelectValue(el);
+    });
+}
 export function applyDomAttr(el, name, value) {
     const key = name === 'className' ? 'class' : name;
     if (key === 'class') {
@@ -39,11 +88,36 @@ export function applyDomAttr(el, name, value) {
             el.removeAttribute('style');
         return;
     }
+    if (String(key).startsWith('xlink:') && el && typeof el.setAttributeNS === 'function') {
+        const local = String(key).slice('xlink:'.length);
+        if (value == null || value === false) {
+            if (typeof el.removeAttributeNS === 'function')
+                el.removeAttributeNS(XLINK_NS, local);
+            else
+                el.removeAttribute(key);
+        }
+        else {
+            el.setAttributeNS(XLINK_NS, `xlink:${local}`, value === true ? '' : String(value));
+        }
+        return;
+    }
     if (BOOLEAN_HTML_ATTRS.has(String(key).toLowerCase())) {
         const on = value === true || value === '';
-        if (key === 'checked' && el && el.tagName === 'INPUT' && String(el.type || '').toLowerCase() === 'checkbox') {
+        // Reflect `checked` through its IDL property. Once the user has interacted
+        // with a radio, attribute writes only reach its default state, so a later
+        // model update would otherwise leave the visible control stale. Only the
+        // first write records the default; later ones stay on the IDL.
+        if (key === 'checked' && el && el.tagName === 'INPUT') {
+            if (!seededCheckedDefaults.has(el)) {
+                seededCheckedDefaults.add(el);
+                if (on)
+                    el.setAttribute('checked', '');
+                else
+                    el.removeAttribute('checked');
+            }
             if (el.checked !== on)
                 el.checked = on;
+            return;
         }
         if (value === false || value == null || value === '') {
             el.removeAttribute(key);
@@ -57,16 +131,82 @@ export function applyDomAttr(el, name, value) {
     // also need the IDL `.value` property so controlled updates stay in sync after switches.
     // linkedom `<select>.value` is getter-only ??sync via `option.selected` instead of throwing.
     if (key === 'value' && el && (el.tagName === 'TEXTAREA' || el.tagName === 'INPUT' || el.tagName === 'SELECT')) {
+        // A `multiple` select model is a list: every option in the model is
+        // selected and there is no single `value` attribute to reflect.
+        const listed = Array.isArray(value) ? value.map((v) => String(v)) : null;
         const next = value == null || value === false ? '' : String(value);
         if (el.tagName === 'SELECT') {
             const opts = el.options || el.querySelectorAll?.('option') || [];
+            if (!opts.length) {
+                pendingSelectValues.set(el, value);
+                deferSelectValue(el);
+                return;
+            }
+            pendingSelectValues.delete(el);
+            // The `selected` attribute is the option's default state, the value
+            // `form.reset()` restores. Seed it with the initial model once and
+            // move only `option.selected` afterwards. Attribute writes run after
+            // the IDL pass: setting selectedness marks the option dirty, so the
+            // later attribute write records the default without moving the
+            // visible selection.
+            const seed = !seededSelectDefaults.has(el);
+            if (seed)
+                seededSelectDefaults.add(el);
+            const selections = [];
             for (const opt of opts) {
-                opt.selected = String(opt.value ?? '') === next;
+                // Match SSR `markSelectSelection`: an option without a `value`
+                // attribute contributes its trimmed text. Reading IDL `.value`
+                // here keeps the template's indentation and loses the selection
+                // right after hydration.
+                const optionValue = typeof opt.hasAttribute === 'function' && opt.hasAttribute('value')
+                    ? String(opt.getAttribute('value') ?? '')
+                    : String(opt.textContent ?? opt.value ?? '').trim();
+                selections.push([opt, listed ? listed.includes(optionValue) : optionValue === next]);
+            }
+            for (const [opt, on] of selections)
+                opt.selected = on;
+            if (seed) {
+                for (const [opt, on] of selections) {
+                    if (on)
+                        opt.setAttribute('selected', '');
+                    else if (typeof opt.removeAttribute === 'function')
+                        opt.removeAttribute('selected');
+                }
             }
         }
         else if (el.value !== next) {
             el.value = next;
         }
+        if (el.tagName === 'TEXTAREA' && !seededTextareaDefaults.has(el)) {
+            // SSR ships a textarea's initial value as its text child. Resume parks
+            // that child in the adopt pool, so `defaultValue` (the form-reset target)
+            // stayed empty. Seed it on the first write; later model updates leave it.
+            seededTextareaDefaults.add(el);
+            el.defaultValue = next;
+        }
+        if (el.tagName === 'INPUT') {
+            // For text-like inputs the `value` attribute *is* the default value:
+            // seed it once, then let the IDL follow the model alone. Checkbox and
+            // radio `value` attributes are submitted values, not defaults.
+            if (isCheckableInput(el)) {
+                if (value == null || value === false)
+                    el.removeAttribute('value');
+                else
+                    el.setAttribute('value', next);
+            }
+            else if (!seededInputValueDefaults.has(el)) {
+                seededInputValueDefaults.add(el);
+                if (value == null || value === false)
+                    el.removeAttribute('value');
+                else
+                    el.setAttribute('value', next);
+            }
+            return;
+        }
+        // A select carries its value as option selectedness: a `value` attribute
+        // on the select itself has no meaning and SSR never emits one.
+        if (listed || el.tagName === 'SELECT')
+            return;
         if (value == null || value === false)
             el.removeAttribute('value');
         else

package/dist/browser/dom/direct-api.d.ts

@@ -1,5 +1,5 @@
 import type { BindingId, DirectInstance, PatchFn } from '../direct-api.types.js';
-import type { EachCtx, ResumeAdoptCtx } from '../dom-core.types.js';
+import type { EachCtx, ResumeAdoptCtx, VmzDomNode } from '../dom-core.types.js';
 export declare const directApi: {
     _inst: DirectInstance | null;
     _branchBinds: Array<{
@@ -10,14 +10,31 @@ export declare const directApi: {
     _itemPatches: PatchFn[] | null;
     _eachCtx: EachCtx | null;
     _resumeAdopt: ResumeAdoptCtx | null;
-    el(tag: any): any;
+    el(tag: any, key?: any): any;
     elNS(ns: any, tag: any): Element;
     text(value: any): Text;
+    /**
+     * Emitted `v-html` write. Resume parks the SSR children of a reclaimed host,
+     * so the live `innerHTML` is still empty when the first patch runs. SSR stamps
+     * `HTML_HASH_ATTR` with the digest of the exact payload string it wrote: a
+     * matching digest proves the parked subtree is the same payload, so adopt
+     * moves it back and no text is ever re-parsed. A different digest writes the
+     * new payload and refreshes the marker for later identical runs.
+     */
+    html(el: any, value: any): void;
     nsScopeDepth(): number;
     rewindNsScope(depth: any): void;
     adoptEnter(node: any): boolean;
+    adoptEnterSlot(hostEl: any, name: any): boolean;
     adoptLeave(): void;
     frag(): DocumentFragment;
+    /**
+     * Multi-root `<template v-for>` row. Resume narrows adoption to the SSR
+     * marker pair for this key; a key with no pair gets an empty scope so a new
+     * row can never steal nodes that belong to another key.
+     */
+    fragRow(key?: any): DocumentFragment;
+    rowEnd(): void;
     comment(value: any): Comment;
     insertBefore(parent: any, node: any, ref: any): void;
     removeNode(node: any): void;
@@ -68,7 +85,14 @@ export declare const directApi: {
     /**
      * Nested component (sync Direct child or island schedule).
      */
-    component(hostInst: any, nameOrCtor: any, props: any, client: any): any;
+    component(hostInst: any, nameOrCtor: any, props: any, client: any, key?: any): VmzDomNode;
+    /**
+     * `<component :is>` boundary. The host element is stable, the child instance
+     * is torn down and rebuilt whenever the evaluated `is` value changes. Props
+     * are re-evaluated per mount so the new type starts from current values, and
+     * the child listener bag is carried over so `@event` handlers keep working.
+     */
+    dynamicComponent(hostInst: any, bindingId: any, deps: any, getCtor: any, getProps: any, key?: any): any;
     /**
      * Subscribe to a child component event (`@submit` ??event name `submit`).
      * Orthogonal to function props (`:on-submit` ??prop `onSubmit`).
@@ -78,6 +102,30 @@ export declare const directApi: {
      * Keep nested Direct child props live with parent field writes.
      */
     bindComponentProp(hostInst: any, hostEl: any, propName: any, deps: any, get: any): void;
+    /**
+     * Object form of `bindComponentProp`: spread every key of the patch-time object
+     * across the child props and clear props whose keys disappear from the object.
+     */
+    bindComponentProps(hostInst: any, hostEl: any, slot: any, deps: any, get: any): void;
+    /**
+     * Object form of `onComponentEvent`: diff event names per call site and detach
+     * listeners whose keys disappear. No global `off` semantics — the bag entry
+     * belongs to this call site only.
+     */
+    bindComponentEvents(hostInst: any, hostEl: any, slot: any, deps: any, get: any): void;
+    /**
+     * `v-bind="obj"` / `v-on="obj"` listeners scoped to one call site.
+     *
+     * `mode: 'bind'` reads `onXxx` keys out of a bind object, `mode: 'on'` reads
+     * event names directly. Vue lowercases element listener names, so both modes
+     * normalize before touching `addEventListener`.
+     */
+    bindObjectListeners(el: any, slot: any, source: any, inst: any, mode: any): void;
+    /**
+     * Filter a `v-bind="obj"` source down to bindable keys before it reaches
+     * component props (`#slot` markers belong to the compiler, not the child).
+     */
+    spreadProps(source: any): Record<string, unknown>;
     /**
      * Project parent children into nested Direct component default `<slot>`.
      * Uses {@link findOwnedDefaultSlot} so nested Button/Link slots are not stolen.