@cfdez11/vex 0.8.2 → 0.9.0

package/client/services/html.js

@@ -1,377 +0,0 @@
-/**
- * Tagged template literal to create HTML elements with Vue-like directives.
- *
- * Supported syntax:
- * 
- * 1. Text interpolation:
- *    html`<span>${value}</span>`
- * 
- * 2. Attribute interpolation:
- *    html`<div class="${className}" id="${id}"></div>`
- * 
- * 3. Event bindings (@event):
- *    html`<button @click="${handler}">Click</button>`
- * 
- * 4. Property/Boolean bindings (:prop):
- *    html`<button :disabled="${isDisabled}">Send</button>`
- * 
- * 5. Conditional rendering (x-if, x-else-if, x-else):
- *    html`<div x-if="${condition}">Show if true</div>`
- *    html`<div x-else>Show if false</div>`
- *
- * 6. Loop rendering (x-for):
- *    html`<li x-for="${item => items}">Item: ${item}</li>`
- * 
- * 7. Nested templates and arrays:
- *    html`<div>${items.map(item => html`<li>${item}</li>`)}</div>`
- */
-
-/**
- * Main template literal function for creating DOM elements.
- * Processes directives, text interpolation, attributes, and events.
- *
- * @param {TemplateStringsArray} strings - The literal strings from the template.
- * @param  {...any} values - Interpolated values, can be primitives, arrays, or nodes.
- * @returns {HTMLElement | DocumentFragment} - The rendered DOM node(s).
- */
-export function html(strings, ...values) {
-  // Generate unique markers for interpolation positions
-  const markers = values.map((_, i) => `__HTML_MARKER_${i}__`);
-
-  // Combine template strings and markers to form HTML string
-  let htmlString = strings[0];
-  for (let i = 0; i < values.length; i++) {
-    htmlString += markers[i] + strings[i + 1];
-  }
-
-  // Create a template element to parse HTML
-  const template = document.createElement("template");
-  template.innerHTML = htmlString.trim();
-
-  // Clone content to avoid mutating the template
-  const fragment = template.content.cloneNode(true);
-
-  // Process VexJS directives (x-if, x-else-if, x-else, x-for)
-  processDirectives(fragment, markers, values);
-
-  // Determine single root element or return a fragment
-  const node =
-    fragment.childElementCount === 1
-      ? fragment.firstElementChild
-      : fragment;
-
-  // Process text interpolations, attributes, and event bindings
-  processNode(node, markers, values);
-
-  return node;
-}
-
-/**
- * Recursively processes directives on a node and its children.
- * Supports x-if, x-else-if, x-else, and x-for.
- *
- * @param {Node} node - The DOM node or fragment to process.
- * @param {string[]} markers - Unique markers for interpolated values.
- * @param {any[]} values - Interpolated values.
- */
-function processDirectives(node, markers, values) {
-  if (node.nodeType !== Node.ELEMENT_NODE && node.nodeType !== Node.DOCUMENT_FRAGMENT_NODE) return;
-
-  const children = Array.from(node.childNodes);
-
-  for (let i = 0; i < children.length; i++) {
-    const child = children[i];
-
-    if (child.nodeType === Node.ELEMENT_NODE) {
-      if (child.hasAttribute('x-if')) {
-        // skip all processed nodes in the conditional chain
-        i = handleConditionalChain(node, children, i, markers, values);
-        continue;
-      }
-
-      if (child.hasAttribute('x-for')) {
-        handleVFor(child, markers, values);
-        continue;
-      }
-
-      processDirectives(child, markers, values);
-    }
-  }
-}
-
-/**
- * Processes x-if, x-else-if, and x-else chains.
- * Keeps the first element whose condition is truthy.
- *
- * @param {Node} parent - Parent node of the conditional chain.
- * @param {Node[]} children - List of child nodes.
- * @param {number} startIndex - Index where v-if chain starts.
- * @param {string[]} markers - Unique markers for interpolation.
- * @param {any[]} values - Interpolated values.
- * @returns {number} - Updated index after processing chain.
- */
-function handleConditionalChain(parent, children, startIndex, markers, values) {
-  const chain = [];
-  let currentIndex = startIndex;
-
-  // Collect all conditional elements in the chain
-  while (currentIndex < children.length) {
-    const element = children[currentIndex];
-    if (element.nodeType !== Node.ELEMENT_NODE) {
-      currentIndex++;
-      continue;
-    }
-
-    if (element.hasAttribute('x-if')) {
-      chain.push({
-        element,
-        type: 'if',
-        condition: element.getAttribute('x-if'),
-      });
-      currentIndex++;
-    } else if (element.hasAttribute('x-else-if')) {
-      if (!chain.length) break;
-      chain.push({
-        element,
-        type: 'else-if',
-        condition: element.getAttribute('x-else-if'),
-      });
-      currentIndex++;
-    } else if (element.hasAttribute('x-else')) {
-      if (!chain.length) break;
-      chain.push({ 
-        element, 
-        type: 'else', 
-        condition: null,
-      });
-      currentIndex++;
-      break; // v-else must be last
-    } else break;
-  }
-
-  // Evaluate chain and keep only the first truthy element
-  let kept = null;
-  for (const item of chain) {
-    if (kept) {
-      item.element.remove();
-      continue;
-    }
-
-    if (item.type === 'else') {
-      kept = item.element;
-      item.element.removeAttribute('x-else');
-    } else {
-      const markerIndex = markers.findIndex(m => item.condition.includes(m));
-      const condition = markerIndex !== -1 ? values[markerIndex] : false;
-      if (condition) {
-        kept = item.element;
-        item.element.removeAttribute(item.type === 'if' ? 'x-if' : 'x-else-if');
-      } else {
-        item.element.remove();
-      }
-    }
-  }
-
-  return currentIndex - 1;
-}
-
-/**
- * Handles x-for directives to render lists.
- * Clones the template element for each item in the array.
- *
- * @param {HTMLElement} element - Template element with x-for attribute.
- * @param {string[]} markers - Unique markers for interpolation.
- * @param {any[]} values - Interpolated values (must include array for v-for).
- */
-function handleVFor(element, markers, values) {
-  const vForValue = element.getAttribute('x-for');
-  const markerIndex = markers.findIndex(m => vForValue.includes(m));
-  if (markerIndex === -1 || !Array.isArray(values[markerIndex])) {
-    element.removeAttribute('x-for');
-    return;
-  }
-
-  const items = values[markerIndex];
-  const parent = element.parentNode;
-  const template = element.cloneNode(true);
-  template.removeAttribute('x-for');
-
-  const fragment = document.createDocumentFragment();
-  for (const item of items) {
-    const clone = template.cloneNode(true);
-    replaceItemReferences(clone, item);
-    fragment.appendChild(clone);
-  }
-
-  parent.replaceChild(fragment, element);
-}
-
-/**
- * Replaces item references in cloned v-for elements.
- *
- * @param {Node} node - Node to replace references in.
- * @param {Object} item - Current item from the array.
- */
-function replaceItemReferences(node, item) {
-  if (node.nodeType === Node.ELEMENT_NODE) {
-    for (const attr of Array.from(node.attributes)) {
-      if (attr.value.includes('item.')) {
-        const prop = attr.value.replace('item.', '');
-        node.setAttribute(attr.name, item[prop] ?? '');
-      }
-    }
-  }
-  
-  for (const child of Array.from(node.childNodes)) {
-    replaceItemReferences(child, item)
-  };
-}
-
-/**
- * Recursively processes nodes, replacing markers with actual values.
- * Also handles attributes and event listeners.
- *
- * @param {Node} node - Node to process.
- * @param {string[]} markers - Unique markers for interpolation.
- * @param {any[]} values - Interpolated values.
- */
-function processNode(node, markers, values) {
-  if (node.nodeType === Node.TEXT_NODE) {
-    return processTextNode(node, markers, values)
-  };
-  if (node.nodeType === Node.ELEMENT_NODE) {
-    processAttributes(node, markers, values);
-  }
-  for (const child of Array.from(node.childNodes)) {
-    processNode(child, markers, values);
-  }
-}
-
-/**
- * Processes text nodes by replacing markers with values.
- * Supports primitives, nodes, and arrays of nodes.
- *
- * @param {Text} node - Text node to process.
- * @param {string[]} markers - Unique markers for interpolation.
- * @param {any[]} values - Interpolated values.
- */
-function processTextNode(node, markers, values) {
-  let text = node.textContent;
-
-  for (let i = 0; i < markers.length; i++) {
-    if (!text.includes(markers[i])) {
-      continue;
-    }
-    const value = values[i];
-    const parent = node.parentNode;
-    const parts = text.split(markers[i]);
-
-    if (parts[0]) {
-      parent.insertBefore(document.createTextNode(parts[0]), node);
-    }
-
-    if (Array.isArray(value)) {
-      // Insert arrays of nodes or primitives
-      for (const item of value) {
-        if (item instanceof Node) {
-          processNode(item, markers, values);
-          parent.insertBefore(item, node);
-        } else {
-          parent.insertBefore(document.createTextNode(String(item ?? "")), node);
-        }
-      }
-    } else if (value instanceof Node) {
-      processNode(value, markers, values);
-      parent.insertBefore(value, node);
-    } else {
-      parent.insertBefore(document.createTextNode(String(value ?? "")), node);
-    }
-
-    text = parts.slice(1).join(markers[i]);
-  }
-
-  node.textContent = text;
-}
-
-/**
- * Maps special HTML attributes to DOM properties.
- *
- * @param {string} attrName - Attribute name from template.
- * @returns {object|string} - Property name and joinability or original string.
- */
-function getNodePropertyInfo(attrName) {
-  const nodeProperties = { 
-    class: { property: "className", canBeJoined: true } 
-  };
-  return nodeProperties[attrName] || { property: attrName, canBeJoined: false };
-}
-
-/**
- * Processes element attributes.
- * Supports:
- * - @event bindings: adds native DOM event listeners.
- * - :prop bindings: sets DOM properties and boolean attributes.
- *
- * @param {HTMLElement} element - Element to process.
- * @param {string[]} markers - Interpolation markers.
- * @param {any[]} values - Interpolated values.
- */
-function processAttributes(element, markers, values) {
-  for (const attr of Array.from(element.attributes)) {
-    // Event binding: @event
-    if (attr.name.startsWith("@")) {
-      const event = attr.name.slice(1);
-      const idx = markers.findIndex(m => attr.value.includes(m));
-      const handler = values[idx];
-
-      if (typeof handler === "function") {
-        element.addEventListener(event, handler);
-      }
-
-      element.removeAttribute(attr.name);
-      continue;
-    }
-
-    // Property/boolean binding: :prop
-    if (attr.name.startsWith(":")) {
-      const { property, canBeJoined } = getNodePropertyInfo(attr.name.slice(1));
-      const idx = markers.findIndex((m) => attr.value.includes(m));
-
-      if (idx !== -1) {
-        const value = values[idx];
-        if (typeof value === "boolean") {
-          element.toggleAttribute(property, value);
-        }
-        else {
-          element[property] = canBeJoined && element[property] 
-            ? `${element[property]} ${value}` 
-            : value;
-        }
-      }
-
-      element.removeAttribute(attr.name);
-    }
-
-    // x-show directive
-    if (attr.name === "x-show") {
-      const idx = markers.findIndex((m) => attr.value.includes(m));
-      const value = idx !== -1 ? values[idx] : false;
-      element.style.display = value ? "" : "none";
-      element.removeAttribute("x-show");
-      continue;
-    }
-
-    // data set attributes
-    if(attr.name.startsWith("data-")) {
-      const dataAttr = attr.name.slice(5);
-      const idx = markers.findIndex((m) => attr.value.includes(m));
-
-      if (idx !== -1) {
-        const value = values[idx];
-        element.dataset[dataAttr] = typeof value === "object" && value !== null
-          ? JSON.stringify(value)
-          : String(value ?? "");
-      }
-    }
-  }
-}

package/client/services/hydrate-client-components.js

@@ -1,97 +0,0 @@
-/**
- * Client-side component hydration script.
- *
- * This script automatically hydrates all components marked with
- * `data-client:component` in the DOM. It supports:
- *   - Initial hydration on page load
- *   - Progressive hydration for streaming SSR content
- *   - SPA updates by exposing a global `window.hydrateComponents` function
- *
- * Each component module is dynamically imported, and its exported
- * `hydrateClientComponent` function is called with the component marker.
- */
-(function () {
-
-  /**
-   * Hydrates a single component marker.
-   *
-   * This function checks if the marker is already hydrated via the
-   * `data-hydrated` attribute to avoid rehydration. It dynamically imports
-   * the component module and calls its `hydrateClientComponent` function.
-   *
-   * @param {HTMLElement} marker - The <template> or marker element representing a client component.
-   * @param {Object} [props={}] - Optional props to pass to the client component.
-   */
-  async function hydrateMarker(marker, props = {}) {
-    if (marker.dataset.hydrated === "true") return;
-    marker.dataset.hydrated = "true";
-
-    const componentName = marker.getAttribute("data-client:component");
-    const componentProps = marker.getAttribute("data-client:props");
-
-    let parsedProps = {};
-    try {
-      parsedProps = JSON.parse(componentProps || "{}");
-    } catch (e) {
-      console.warn(`Failed to parse props for component ${componentName}`, e);
-    }
-    const finalProps = { ...parsedProps, ...props };
-
-    try {
-      const module = await import(`/_vexjs/_components/${componentName}.js`);
-      await module.hydrateClientComponent(marker, finalProps);
-    } catch (error) {
-      console.error(`Failed to load component: ${componentName}`, error);
-    }
-  }
-
-  /**
-   * Hydrates all unhydrated component markers inside a container.
-   *
-   * @param {HTMLElement|Document} [container=document] - The root container to scan for components.
-   */
-  async function hydrateComponents(container = document, props = {}) {
-    const markers = container.querySelectorAll(
-      "[data-client\\:component]:not([data-hydrated='true'])"
-    );
-
-    for (const marker of markers) {
-      await hydrateMarker(marker, props);
-    }
-  }
-
-  /**
-   * MutationObserver callback for progressive hydration.
-   *
-   * Observes DOM mutations and hydrates newly added components dynamically.
-   */
-  const observer = new MutationObserver((mutations) => {
-    for (const mutation of mutations) {
-      for (const node of mutation.addedNodes) {
-        if (node.nodeType !== 1) continue; // Only element nodes
-        if (node.matches?.("[data-client\\:component]")) hydrateMarker(node);
-        hydrateComponents(node);
-      }
-    }
-  });
-
-  // Start observing the document for new nodes
-  observer.observe(document, { childList: true, subtree: true });
-
-  // Hydrate existing components on DOMContentLoaded or immediately if already interactive.
-  // The observer is intentionally NOT disconnected here — it must stay active to catch
-  // components inserted after DOMContentLoaded (nested CSR components, Suspense streaming,
-  // SPA navigations). The `data-hydrated` guard in hydrateMarker prevents double-hydration.
-  if (document.readyState === "loading") {
-    document.addEventListener("DOMContentLoaded", () => hydrateComponents());
-  } else {
-    hydrateComponents();
-  }
-
-  /**
-   * Expose `hydrateComponents` globally so it can be called manually
-   * for SPA navigations or dynamically rendered content.
-   * @type {function(HTMLElement|Document): Promise<void>}
-   */
-  window.hydrateComponents = hydrateComponents;
-})();

package/client/services/hydrate.js

@@ -1,25 +0,0 @@
-/**
- * Client-side hydration helper for streaming Suspense boundaries.
- *
- * Previously this script was injected as a separate <script src="hydrate.js">
- * tag for every Suspense boundary on the page. The browser cached the file after
- * the first load, but still had to parse and initialise a new script execution
- * context for each tag — O(N) work per page with N Suspense boundaries.
- *
- * Now the script is loaded exactly once from root.html and exposes
- * `window.hydrateTarget(targetId, sourceId)`. Each Suspense replacement payload
- * calls that global function via a tiny inline script instead of loading this
- * file again.
- *
- * @param {string} targetId  - ID of the fallback <div> to replace.
- * @param {string} sourceId  - ID of the <template> containing the real content.
- */
-window.hydrateTarget = function (targetId, sourceId) {
-  const target = document.getElementById(targetId);
-  const template = document.getElementById(sourceId);
-
-  if (target && template) {
-    target.replaceWith(template.content.cloneNode(true));
-    template.remove();
-  }
-};

package/client/services/index.js

@@ -1,9 +0,0 @@
-import { initializeRouter, navigate } from "./navigation/index.js";
-
-window.app = {
-  navigate,
-};
-
-document.addEventListener("DOMContentLoaded", () => {
-  initializeRouter();
-});

package/client/services/navigation/create-layouts.js

@@ -1,172 +0,0 @@
-/**
- * @typedef {Object} Layout
- * @property {string} name - Layout name.
- * @property {string} importPath - Path to the module.
- */
-
-/**
- * @typedef {Object} RenderedLayout
- * @property {string} name - Layout name.
- * @property {Node} children - Original children node.
- * @property {Node} node - Rendered layout node.
- */
-
-/**
- * @typedef {Object} GenerateParams
- * @property {Layout[]} [routeLayouts] - Layouts to render for this route.
- * @property {Node} pageNode - The page node to wrap.
- * @property {any} metadata - Metadata for the page/layout.
- */
-
-/**
- * @typedef {Object} GenerateResult
- * @property {string | null} layoutId - ID of the nearest rendered layout.
- * @property {Node} node - The root node after layout wrapping.
- * @property {any} metadata - Metadata after merging layouts.
- */
-
-/**
- * Creates a layout renderer responsible for dynamically loading,
- * rendering, caching, and patching route-based layouts.
- *
- * The renderer keeps track of already rendered layouts to avoid
- * unnecessary re-renders and supports incremental layout updates.
- *
- * @returns {{
- *   generate: (params: GenerateParams) => Promise<GenerateResult>,
- *   patch: (layoutId: string, node: Node) => void,
- *   reset: () => void
- * }}
- */
-export function createLayoutRenderer() {
-  /** @type {Map<string, RenderedLayout>} */
-  const renderedLayouts = new Map();
-
-  /**
-   * Removes cached layouts that are no longer part of the current route.
-   * @param {Layout[]} routeLayouts
-   */
-  function cleanNotNeeded(routeLayouts) {
-    for (const name of renderedLayouts.keys()) {
-      const exists = routeLayouts.some((l) => l.name === name);
-      if (!exists) {
-        renderedLayouts.delete(name);
-      }
-    }
-  }
-
-  /**
-   * Finds the nearest already-rendered layout in the route hierarchy.
-   * @param {Layout[]} routeLayouts
-   * @returns {RenderedLayout | null}
-   */
-  function getNearestRendered(routeLayouts) {
-    const reversed = routeLayouts.toReversed();
-
-    for (const layout of reversed) {
-      if (renderedLayouts.has(layout.name)) {
-        return renderedLayouts.get(layout.name);
-      }
-    }
-
-    return null;
-  }
-
-  /**
-   * Determines which layouts need to be rendered based on
-   * the nearest cached layout.
-   * @param {Layout[]} routeLayouts
-   * @param {RenderedLayout | null} nearestRendered
-   * @returns {Layout[]}
-   */
-  function getLayoutsToRender(routeLayouts, nearestRendered) {
-    if (!nearestRendered) return routeLayouts;
-
-    const reversed = routeLayouts.toReversed();
-    const idx = reversed.findIndex((l) => l.name === nearestRendered.name);
-
-    return idx === -1 ? routeLayouts : reversed.slice(0, idx);
-  }
-
-  /**
-   * Dynamically imports layout modules.
-   * @param {Layout[]} layouts
-   * @returns {Promise<any[]>}
-   */
-  async function loadLayoutModules(layouts) {
-    return Promise.all(layouts.map((layout) => import(layout.importPath)));
-  }
-
-  /**
-   * Generates the layout tree wrapping the provided page node.
-   * @param {GenerateParams} params
-   * @returns {Promise<GenerateResult>}
-   */
-  async function generate({ routeLayouts = [], pageNode, metadata }) {
-    if (!pageNode || routeLayouts.length === 0) {
-      return {
-        layoutId: null,
-        node: pageNode,
-        metadata,
-      };
-    }
-
-    cleanNotNeeded(routeLayouts);
-
-    const nearestRendered = getNearestRendered(routeLayouts);
-    const layoutsToRender = getLayoutsToRender(routeLayouts, nearestRendered);
-
-    const modules = await loadLayoutModules(layoutsToRender);
-
-    let htmlContainerNode = pageNode;
-    let deepestMetadata = metadata;
-
-    for (let i = modules.length - 1; i >= 0; i--) {
-      const layout = layoutsToRender[i];
-      const mod = modules[i];
-
-      const children = htmlContainerNode;
-      const marker = document.createElement("template");
-
-      htmlContainerNode = mod.hydrateClientComponent(marker, { children });
-
-      if (!deepestMetadata && mod.metadata) {
-        deepestMetadata = mod.metadata;
-      }
-
-      renderedLayouts.set(layout.name, {
-        name: layout.name,
-        children,
-        node: htmlContainerNode,
-      });
-    }
-
-    return {
-      layoutId: nearestRendered?.name ?? null,
-      node: htmlContainerNode,
-      metadata: deepestMetadata,
-    };
-  }
-
-  /**
-   * Patches an already-rendered layout by replacing its children node.
-   * @param {string} layoutId
-   * @param {Node} node
-   */
-  function patch(layoutId, node) {
-    const record = renderedLayouts.get(layoutId);
-    if (!record) return;
-
-    record.children.replaceWith(node);
-    record.children = node;
-  }
-
-  /**
-   * Clears all cached rendered layouts.
-   */
-  function reset() {
-    renderedLayouts.clear();
-  }
-
-  return { generate, patch, reset };
-}