@zenithbuild/runtime 0.7.4 → 0.7.7

package/dist/presence.js

@@ -0,0 +1,297 @@
+// @ts-nocheck
+import { zenOn } from './platform.js';
+/**
+ * @typedef {'hidden' | 'entering' | 'present' | 'exiting'} ZenPresencePhase
+ */
+function isRefLike(value) {
+    return !!value && typeof value === 'object' && 'current' in value;
+}
+function normalizeOptions(options) {
+    if (options === undefined || options === null) {
+        return {
+            timeoutMs: undefined,
+            onPhaseChange: null
+        };
+    }
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new Error('[Zenith Runtime] zenPresence(ref, options) requires an options object when provided');
+    }
+    if (options.timeoutMs !== undefined) {
+        if (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0) {
+            throw new Error('[Zenith Runtime] zenPresence options.timeoutMs must be a non-negative number');
+        }
+    }
+    if (options.onPhaseChange !== undefined && typeof options.onPhaseChange !== 'function') {
+        throw new Error('[Zenith Runtime] zenPresence options.onPhaseChange must be a function when provided');
+    }
+    return {
+        timeoutMs: options.timeoutMs === undefined ? undefined : Math.floor(options.timeoutMs),
+        onPhaseChange: typeof options.onPhaseChange === 'function' ? options.onPhaseChange : null
+    };
+}
+function parseCssTimeToken(token) {
+    const value = String(token || '').trim();
+    if (value.length === 0) {
+        return 0;
+    }
+    if (value.endsWith('ms')) {
+        const ms = Number.parseFloat(value.slice(0, -2));
+        return Number.isFinite(ms) ? Math.max(0, ms) : 0;
+    }
+    if (value.endsWith('s')) {
+        const seconds = Number.parseFloat(value.slice(0, -1));
+        return Number.isFinite(seconds) ? Math.max(0, seconds * 1000) : 0;
+    }
+    const numeric = Number.parseFloat(value);
+    return Number.isFinite(numeric) ? Math.max(0, numeric) : 0;
+}
+function parseCssTimeList(value) {
+    return String(value || '')
+        .split(',')
+        .map((token) => parseCssTimeToken(token))
+        .filter((candidate) => Number.isFinite(candidate));
+}
+function computeMaxCssTotal(durations, delays) {
+    if (!Array.isArray(durations) || durations.length === 0) {
+        return 0;
+    }
+    let maxTotal = 0;
+    for (let index = 0; index < durations.length; index += 1) {
+        const duration = durations[index] || 0;
+        const delay = Array.isArray(delays) && delays.length > 0
+            ? delays[index % delays.length] || 0
+            : 0;
+        const total = duration + delay;
+        if (total > maxTotal) {
+            maxTotal = total;
+        }
+    }
+    return maxTotal;
+}
+function resolveFallbackTimeoutMs(node, explicitTimeoutMs) {
+    if (Number.isFinite(explicitTimeoutMs)) {
+        return explicitTimeoutMs;
+    }
+    const activeWindow = node?.ownerDocument?.defaultView;
+    if (!activeWindow || typeof activeWindow.getComputedStyle !== 'function') {
+        return 34;
+    }
+    const styles = activeWindow.getComputedStyle(node);
+    const transitionTotal = computeMaxCssTotal(parseCssTimeList(styles.transitionDuration), parseCssTimeList(styles.transitionDelay));
+    const animationTotal = computeMaxCssTotal(parseCssTimeList(styles.animationDuration), parseCssTimeList(styles.animationDelay));
+    const total = Math.max(transitionTotal, animationTotal);
+    return total > 0 ? Math.ceil(total + 34) : 34;
+}
+function getTimerApi(node) {
+    const activeWindow = node?.ownerDocument?.defaultView;
+    if (activeWindow && typeof activeWindow.setTimeout === 'function' && typeof activeWindow.clearTimeout === 'function') {
+        return {
+            setTimeout: activeWindow.setTimeout.bind(activeWindow),
+            clearTimeout: activeWindow.clearTimeout.bind(activeWindow)
+        };
+    }
+    return {
+        setTimeout: globalThis.setTimeout.bind(globalThis),
+        clearTimeout: globalThis.clearTimeout.bind(globalThis)
+    };
+}
+function isOwnedEvent(event, node) {
+    return !!event && event.target === node;
+}
+/**
+ * Ref-owned presence controller for always-mounted nodes.
+ *
+ * Canonical pattern:
+ * - create once per ref
+ * - call `presence.mount()` inside `zenMount`
+ * - drive `presence.setPresent(next)` from reactive state
+ *
+ * @template {Element} T
+ * @param {{ current?: T | null }} ref
+ * @param {{ timeoutMs?: number, onPhaseChange?: ((phase: ZenPresencePhase, context: { node: T | null, previousPhase: ZenPresencePhase | null, present: boolean }) => void) } | null | undefined} [options]
+ * @returns {{
+ *   mount: () => () => void,
+ *   destroy: () => void,
+ *   getPhase: () => ZenPresencePhase,
+ *   setPresent: (nextPresent: boolean) => void
+ * }}
+ */
+export function zenPresence(ref, options = null) {
+    if (!isRefLike(ref)) {
+        throw new Error('[Zenith Runtime] zenPresence(ref, options) requires a ref-like object with current');
+    }
+    const normalizedOptions = normalizeOptions(options);
+    let desiredPresent = false;
+    /** @type {ZenPresencePhase} */
+    let currentPhase = 'hidden';
+    let mounted = false;
+    let mountEpoch = 0;
+    let pendingCompletion = null;
+    function getNode() {
+        const candidate = ref.current;
+        if (!candidate || typeof candidate !== 'object' || typeof candidate.nodeType !== 'number') {
+            return null;
+        }
+        return candidate;
+    }
+    function notifyPhaseChange(previousPhase) {
+        if (typeof normalizedOptions.onPhaseChange !== 'function') {
+            return;
+        }
+        normalizedOptions.onPhaseChange(currentPhase, {
+            node: getNode(),
+            previousPhase,
+            present: desiredPresent
+        });
+    }
+    function applyPhaseToNode() {
+        const node = getNode();
+        if (!node) {
+            return;
+        }
+        node.setAttribute('data-zen-presence', currentPhase);
+    }
+    function setPhase(nextPhase, forceApply = false) {
+        const previousPhase = currentPhase;
+        const changed = previousPhase !== nextPhase;
+        if (!changed && !forceApply) {
+            return;
+        }
+        currentPhase = nextPhase;
+        applyPhaseToNode();
+        if (changed) {
+            notifyPhaseChange(previousPhase);
+        }
+    }
+    function cancelPendingCompletion() {
+        if (!pendingCompletion) {
+            return;
+        }
+        pendingCompletion.cancel();
+        pendingCompletion = null;
+    }
+    function scheduleCompletion(targetPhase, node) {
+        cancelPendingCompletion();
+        if (!mounted || !node) {
+            setPhase(targetPhase);
+            return;
+        }
+        const timerApi = getTimerApi(node);
+        const timeoutMs = resolveFallbackTimeoutMs(node, normalizedOptions.timeoutMs);
+        const disposers = [];
+        let settled = false;
+        let timeoutId = null;
+        const settle = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            while (disposers.length > 0) {
+                const dispose = disposers.pop();
+                try {
+                    dispose();
+                }
+                catch {
+                }
+            }
+            if (timeoutId !== null) {
+                timerApi.clearTimeout(timeoutId);
+                timeoutId = null;
+            }
+            pendingCompletion = null;
+            setPhase(targetPhase);
+        };
+        const handleEnd = (event) => {
+            if (!isOwnedEvent(event, node)) {
+                return;
+            }
+            settle();
+        };
+        disposers.push(zenOn(node, 'transitionend', handleEnd));
+        disposers.push(zenOn(node, 'animationend', handleEnd));
+        timeoutId = timerApi.setTimeout(settle, timeoutMs);
+        pendingCompletion = {
+            cancel() {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                while (disposers.length > 0) {
+                    const dispose = disposers.pop();
+                    try {
+                        dispose();
+                    }
+                    catch {
+                    }
+                }
+                if (timeoutId !== null) {
+                    timerApi.clearTimeout(timeoutId);
+                    timeoutId = null;
+                }
+            }
+        };
+    }
+    function reconcile() {
+        if (!mounted) {
+            return;
+        }
+        const node = getNode();
+        if (!node) {
+            cancelPendingCompletion();
+            return;
+        }
+        if (desiredPresent) {
+            if (currentPhase === 'entering' || currentPhase === 'present') {
+                return;
+            }
+            setPhase('entering');
+            scheduleCompletion('present', node);
+            return;
+        }
+        if (currentPhase === 'hidden' || currentPhase === 'exiting') {
+            return;
+        }
+        setPhase('exiting');
+        scheduleCompletion('hidden', node);
+    }
+    function destroyCurrentMount() {
+        mounted = false;
+        cancelPendingCompletion();
+        currentPhase = 'hidden';
+        const node = getNode();
+        if (node) {
+            node.removeAttribute('data-zen-presence');
+        }
+    }
+    return {
+        mount() {
+            mountEpoch += 1;
+            const activeMount = mountEpoch;
+            mounted = true;
+            setPhase(currentPhase, true);
+            reconcile();
+            return () => {
+                if (activeMount !== mountEpoch) {
+                    return;
+                }
+                destroyCurrentMount();
+            };
+        },
+        destroy() {
+            mountEpoch += 1;
+            destroyCurrentMount();
+        },
+        getPhase() {
+            return currentPhase;
+        },
+        setPresent(nextPresent) {
+            desiredPresent = nextPresent === true;
+            reconcile();
+        }
+    };
+}
+/**
+ * @alias zenPresence
+ * @description Optional secondary alias for the canonical zenPresence helper.
+ */
+export const presence = zenPresence;

package/dist/render.js

@@ -12,20 +12,21 @@ export function _applyMarkerValue(nodes, marker, value) {
         try {
             const node = nodes[i];
             if (marker.kind === 'text') {
+                const textPath = `${markerPath}.text`;
                 if (node && node.nodeType === 8) {
-                    _applyCommentMarkerValue(node, value, `${markerPath}.text`);
+                    _applyCommentMarkerValue(node, value, textPath);
                     continue;
                 }
                 if (_isStructuralFragment(value)) {
-                    _mountStructuralFragment(node, value, `${markerPath}.text`);
+                    _mountStructuralFragment(node, value, textPath);
                     continue;
                 }
-                const html = _renderFragmentValue(value, `${markerPath}.text`);
+                const html = _renderFragmentValue(value, textPath);
                 if (html !== null) {
                     node.innerHTML = html;
                 }
                 else {
-                    node.textContent = _coerceText(value, `${markerPath}.text`);
+                    node.textContent = _coerceText(value, textPath);
                 }
                 continue;
             }
@@ -45,7 +46,7 @@ export function _applyMarkerValue(nodes, marker, value) {
                 path: marker.kind === 'attr'
                     ? `${markerPath}.attr.${marker.attr}`
                     : `${markerPath}.${marker.kind}`,
-                hint: 'Check the binding value type and marker mapping.',
+                hint: 'Check binding value and marker mapping.',
                 docsLink: DOCS_LINKS.markerTable,
                 source: marker.source
             });
@@ -105,16 +106,7 @@ function _ensureCommentPlaceholderEnd(anchor) {
     return end;
 }
 function _clearCommentPlaceholderContent(anchor) {
-    if (anchor.__z_unmounts) {
-        for (let i = 0; i < anchor.__z_unmounts.length; i++) {
-            try {
-                anchor.__z_unmounts[i]();
-            }
-            catch {
-            }
-        }
-    }
-    anchor.__z_unmounts = [];
+    _runUnmounts(anchor);
     const end = _ensureCommentPlaceholderEnd(anchor);
     if (!end) {
         return anchor;
@@ -130,21 +122,7 @@ function _clearCommentPlaceholderContent(anchor) {
     return end;
 }
 function _mountStructuralFragmentIntoCommentRange(anchor, value, rootPath = 'renderable') {
-    let region = anchor.__z_fragment_region;
-    if (region && anchor.__z_fragment_region_active) {
-        try {
-            region.update(value, { parent: anchor.parentNode, insertBefore: anchor.__z_range_end, rootPath });
-        }
-        catch (error) {
-            rethrowZenithRuntimeError(error, {
-                phase: 'render',
-                code: 'FRAGMENT_MOUNT_FAILED',
-                message: 'Fragment update failed',
-                path: rootPath,
-                hint: 'Verify fragment values and nested renderable arrays.',
-                docsLink: DOCS_LINKS.markerTable
-            });
-        }
+    if (_tryUpdateFragmentTarget(anchor, value, anchor.parentNode, anchor.__z_range_end, rootPath)) {
         return;
     }
     const end = _clearCommentPlaceholderContent(anchor);
@@ -152,75 +130,15 @@ function _mountStructuralFragmentIntoCommentRange(anchor, value, rootPath = 'ren
     if (!parent) {
         return;
     }
-    region = createFragmentRegion();
-    anchor.__z_fragment_region = region;
-    anchor.__z_fragment_region_active = true;
-    try {
-        region.mount(value, { parent, insertBefore: end, rootPath });
-    }
-    catch (error) {
-        rethrowZenithRuntimeError(error, {
-            phase: 'render',
-            code: 'FRAGMENT_MOUNT_FAILED',
-            message: 'Fragment mount failed',
-            path: rootPath,
-            hint: 'Verify fragment values and nested renderable arrays.',
-            docsLink: DOCS_LINKS.markerTable
-        });
-    }
-    anchor.__z_unmounts = [() => {
-            anchor.__z_fragment_region_active = false;
-            region.destroy();
-        }];
+    _mountFragmentRegion(anchor, value, parent, end, rootPath);
 }
 function _mountStructuralFragment(container, value, rootPath = 'renderable') {
-    let region = container.__z_fragment_region;
-    if (region && container.__z_fragment_region_active) {
-        try {
-            region.update(value, { parent: container, insertBefore: null, rootPath });
-        }
-        catch (error) {
-            rethrowZenithRuntimeError(error, {
-                phase: 'render',
-                code: 'FRAGMENT_MOUNT_FAILED',
-                message: 'Fragment update failed',
-                path: rootPath,
-                hint: 'Verify fragment values and nested renderable arrays.',
-                docsLink: DOCS_LINKS.markerTable
-            });
-        }
+    if (_tryUpdateFragmentTarget(container, value, container, null, rootPath)) {
         return;
     }
-    if (container.__z_unmounts) {
-        for (let i = 0; i < container.__z_unmounts.length; i++) {
-            try {
-                container.__z_unmounts[i]();
-            }
-            catch {
-            }
-        }
-    }
+    _runUnmounts(container);
     container.innerHTML = '';
-    region = createFragmentRegion();
-    container.__z_fragment_region = region;
-    container.__z_fragment_region_active = true;
-    try {
-        region.mount(value, { parent: container, insertBefore: null, rootPath });
-    }
-    catch (error) {
-        rethrowZenithRuntimeError(error, {
-            phase: 'render',
-            code: 'FRAGMENT_MOUNT_FAILED',
-            message: 'Fragment mount failed',
-            path: rootPath,
-            hint: 'Verify fragment values and nested renderable arrays.',
-            docsLink: DOCS_LINKS.markerTable
-        });
-    }
-    container.__z_unmounts = [() => {
-            container.__z_fragment_region_active = false;
-            region.destroy();
-        }];
+    _mountFragmentRegion(container, value, container, null, rootPath);
 }
 export function _coerceText(value, path = 'renderable') {
     if (value === null || value === undefined || value === false || value === true) {
@@ -232,7 +150,7 @@ export function _coerceText(value, path = 'renderable') {
             code: 'NON_RENDERABLE_VALUE',
             message: `Zenith Render Error: non-renderable function at ${path}. Use map() to render fields.`,
             path,
-            hint: 'Convert functions into explicit event handlers or renderable text.',
+            hint: 'Convert functions to handlers or text.',
             docsLink: DOCS_LINKS.expressionScope
         });
     }
@@ -242,7 +160,7 @@ export function _coerceText(value, path = 'renderable') {
             code: 'NON_RENDERABLE_VALUE',
             message: `Zenith Render Error: non-renderable object at ${path}. Use map() to render fields.`,
             path,
-            hint: 'Use map() to render object fields into nodes.',
+            hint: 'Use map() to render object fields.',
             docsLink: DOCS_LINKS.expressionScope
         });
     }
@@ -279,21 +197,22 @@ function _escapeHtml(input) {
         .replace(/'/g, '&#39;');
 }
 function _applyAttribute(node, attrName, value) {
-    if (typeof attrName === 'string' && attrName.toLowerCase() === 'innerhtml') {
+    const normalizedAttrName = typeof attrName === 'string' ? attrName.toLowerCase() : '';
+    if (normalizedAttrName === 'innerhtml') {
         throwZenithRuntimeError({
             phase: 'bind',
             code: 'UNSAFE_HTML_REQUIRES_EXPLICIT_BOUNDARY',
             message: 'innerHTML bindings are forbidden in Zenith',
             path: `attr:${attrName}`,
-            hint: 'Use unsafeHTML={value} for explicit raw HTML insertion, or embedded markup expressions for compiler-owned fragments.'
+            hint: 'Use unsafeHTML={value} or compiler-owned markup fragments.'
         });
     }
-    if (typeof attrName === 'string' && attrName.toLowerCase() === 'unsafehtml') {
+    if (normalizedAttrName === 'unsafehtml') {
         node.innerHTML = value === null || value === undefined || value === false ? '' : String(value);
         return;
     }
     if (attrName === 'class' || attrName === 'className') {
-        const classValue = value === null || value === undefined || value === false ? '' : String(value);
+        const classValue = _isEmptyAttrValue(value) ? '' : String(value);
         if (node && node.namespaceURI === SVG_NAMESPACE && typeof node.setAttribute === 'function') {
             node.setAttribute('class', classValue);
             return;
@@ -302,25 +221,13 @@ function _applyAttribute(node, attrName, value) {
         return;
     }
     if (attrName === 'style') {
-        if (value === null || value === undefined || value === false) {
+        const styleValue = _resolveStyleAttributeValue(value);
+        if (styleValue === null) {
             node.removeAttribute('style');
-            return;
         }
-        if (typeof value === 'string') {
-            node.setAttribute('style', value);
-            return;
-        }
-        if (typeof value === 'object') {
-            const entries = Object.entries(value);
-            let styleText = '';
-            for (let i = 0; i < entries.length; i++) {
-                const [key, rawValue] = entries[i];
-                styleText += `${key}: ${rawValue};`;
-            }
-            node.setAttribute('style', styleText);
-            return;
+        else {
+            node.setAttribute('style', styleValue);
         }
-        node.setAttribute('style', String(value));
         return;
     }
     if (BOOLEAN_ATTRIBUTES.has(attrName)) {
@@ -332,9 +239,84 @@ function _applyAttribute(node, attrName, value) {
         }
         return;
     }
-    if (value === null || value === undefined || value === false) {
+    if (_isEmptyAttrValue(value)) {
         node.removeAttribute(attrName);
         return;
     }
     node.setAttribute(attrName, String(value));
 }
+function _runUnmounts(target) {
+    if (!target.__z_unmounts) {
+        return;
+    }
+    for (let i = 0; i < target.__z_unmounts.length; i++) {
+        try {
+            target.__z_unmounts[i]();
+        }
+        catch {
+        }
+    }
+    target.__z_unmounts = [];
+}
+function _updateFragmentRegion(region, value, parent, insertBefore, rootPath) {
+    try {
+        region.update(value, { parent, insertBefore, rootPath });
+    }
+    catch (error) {
+        _throwFragmentMountFailure(error, rootPath, 'Fragment update failed');
+    }
+}
+function _mountFragmentRegion(target, value, parent, insertBefore, rootPath) {
+    const region = createFragmentRegion();
+    target.__z_fragment_region = region;
+    target.__z_fragment_region_active = true;
+    try {
+        region.mount(value, { parent, insertBefore, rootPath });
+    }
+    catch (error) {
+        _throwFragmentMountFailure(error, rootPath, 'Fragment mount failed');
+    }
+    target.__z_unmounts = [() => {
+            target.__z_fragment_region_active = false;
+            region.destroy();
+        }];
+}
+function _tryUpdateFragmentTarget(target, value, parent, insertBefore, rootPath) {
+    const region = target.__z_fragment_region;
+    if (!region || !target.__z_fragment_region_active) {
+        return false;
+    }
+    _updateFragmentRegion(region, value, parent, insertBefore, rootPath);
+    return true;
+}
+function _throwFragmentMountFailure(error, path, message) {
+    rethrowZenithRuntimeError(error, {
+        phase: 'render',
+        code: 'FRAGMENT_MOUNT_FAILED',
+        message,
+        path,
+        hint: 'Verify fragment values and nested arrays.',
+        docsLink: DOCS_LINKS.markerTable
+    });
+}
+function _resolveStyleAttributeValue(value) {
+    if (_isEmptyAttrValue(value)) {
+        return null;
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value);
+        let styleText = '';
+        for (let i = 0; i < entries.length; i++) {
+            const [key, rawValue] = entries[i];
+            styleText += `${key}: ${rawValue};`;
+        }
+        return styleText;
+    }
+    return String(value);
+}
+function _isEmptyAttrValue(value) {
+    return value === null || value === undefined || value === false;
+}

package/dist/runtime-template-profile.d.ts

@@ -0,0 +1,20 @@
+export function normalizeRuntimeTemplateProfile(profile: any): "default" | "production-emitted" | "production-emitted-with-presence";
+export function buildRuntimeTemplateProfile({ profile, normalizeNewlines, readRuntimeSourceFile }: {
+    profile: any;
+    normalizeNewlines: any;
+    readRuntimeSourceFile: any;
+}): {
+    profile: "default" | "production-emitted" | "production-emitted-with-presence";
+    source: any;
+    contributors: {
+        id: string;
+        sourceFile: string;
+        bytes: number;
+    }[];
+    coverageBytes: number;
+};
+export const RUNTIME_TEMPLATE_PROFILES: Readonly<{
+    DEFAULT: "default";
+    PRODUCTION_EMITTED: "production-emitted";
+    PRODUCTION_EMITTED_WITH_PRESENCE: "production-emitted-with-presence";
+}>;