@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/keep-alive.js

@@ -0,0 +1,421 @@
+let keepAliveIdCounter = 0;
+function generateKeepAliveId() {
+  return `keep-alive-${++keepAliveIdCounter}-${Date.now().toString(36)}`;
+}
+export function processKeepAliveDirectives(template, _context = {}, _filePath) {
+  const keepAliveRegex = /@keepAlive(?:\s*\(([^)]*)\))?\s*([\s\S]*?)@endkeepAlive/gi;
+  return template.replace(keepAliveRegex, (_match, optionsStr, content) => {
+    const keepAliveId = generateKeepAliveId(), options = parseKeepAliveOptions(optionsStr || "");
+    return generateKeepAliveHtml(keepAliveId, content.trim(), options);
+  });
+}
+function parseKeepAliveOptions(optionsStr) {
+  const options = {
+    max: 10
+  }, keyValueRegex = /(\w+)\s*:\s*(?:'([^']*)'|"([^"]*)"|(\d+)|(\w+))/g;
+  let match;
+  while ((match = keyValueRegex.exec(optionsStr)) !== null) {
+    const key = match[1], strValue = match[2] || match[3], numValue = match[4];
+    switch (key) {
+      case "max":
+        options.max = numValue ? parseInt(numValue, 10) : 10;
+        break;
+      case "include":
+        options.include = strValue;
+        break;
+      case "exclude":
+        options.exclude = strValue;
+        break;
+      case "id":
+        options.id = strValue;
+        break;
+    }
+  }
+  return options;
+}
+function generateKeepAliveHtml(keepAliveId, content, options) {
+  const { max, include, exclude } = options, customId = options.id || keepAliveId;
+  return `
+<div class="stx-keep-alive" data-keep-alive-id="${keepAliveId}" data-custom-id="${customId}">
+  <div class="stx-keep-alive-content" data-keep-alive-content="${keepAliveId}">
+    ${content}
+  </div>
+  <div class="stx-keep-alive-cache" data-keep-alive-cache="${keepAliveId}" style="display: none;">
+  </div>
+</div>
+<script>
+(function() {
+  const keepAliveId = '${keepAliveId}';
+  const customId = '${customId}';
+  const maxCache = ${max || 10};
+  const includeFilter = ${include ? JSON.stringify(include.split(",").map((s) => s.trim())) : "null"};
+  const excludeFilter = ${exclude ? JSON.stringify(exclude.split(",").map((s) => s.trim())) : "null"};
+
+  const container = document.querySelector('[data-keep-alive-id="' + keepAliveId + '"]');
+  const contentEl = document.querySelector('[data-keep-alive-content="' + keepAliveId + '"]');
+  const cacheEl = document.querySelector('[data-keep-alive-cache="' + keepAliveId + '"]');
+
+  if (!container || !contentEl || !cacheEl) return;
+
+  // LRU Cache
+  const cache = new Map();
+  const cacheOrder = [];
+
+  // Check if component should be cached
+  function shouldCache(componentName) {
+    if (excludeFilter && excludeFilter.includes(componentName)) {
+      return false;
+    }
+    if (includeFilter && !includeFilter.includes(componentName)) {
+      return false;
+    }
+    return true;
+  }
+
+  // Get component key from element
+  function getComponentKey(element) {
+    // Try various ways to identify the component
+    return element.getAttribute('data-component') ||
+           element.getAttribute('data-key') ||
+           element.id ||
+           element.className.split(' ')[0] ||
+           element.tagName.toLowerCase();
+  }
+
+  // Save scroll positions
+  function saveScrollPositions(element) {
+    const positions = new Map();
+    // eslint-disable-next-line pickier/no-unused-vars
+    element.querySelectorAll('[data-keep-scroll]').forEach(function(el) {
+      const key = el.getAttribute('data-keep-scroll') || el.id || 'default';
+      positions.set(key, { top: el.scrollTop, left: el.scrollLeft });
+    });
+    // Also save the element's own scroll if scrollable
+    if (element.scrollHeight > element.clientHeight || element.scrollWidth > element.clientWidth) {
+      positions.set('__self__', { top: element.scrollTop, left: element.scrollLeft });
+    }
+    return positions;
+  }
+
+  // Restore scroll positions
+  function restoreScrollPositions(element, positions) {
+    if (!positions) return;
+
+    positions.forEach(function(pos, key) {
+      if (key === '__self__') {
+        element.scrollTop = pos.top;
+        element.scrollLeft = pos.left;
+      }
+else {
+        const el = element.querySelector('[data-keep-scroll="' + key + '"]') ||
+                   document.getElementById(key);
+        if (el) {
+          el.scrollTop = pos.top;
+          el.scrollLeft = pos.left;
+        }
+      }
+    });
+  }
+
+  // Save component state (form values, etc.)
+  function saveComponentState(element) {
+    const state = {};
+
+    // Save form inputs
+    // eslint-disable-next-line pickier/no-unused-vars
+    element.querySelectorAll('input, textarea, select').forEach(function(input, index) {
+      const key = input.name || input.id || 'input_' + index;
+      if (input.type === 'checkbox' || input.type === 'radio') {
+        state[key] = input.checked;
+      }
+else {
+        state[key] = input.value;
+      }
+    });
+
+    // Save data attributes marked for keeping
+    // eslint-disable-next-line pickier/no-unused-vars
+    element.querySelectorAll('[data-keep-state]').forEach(function(el) {
+      const key = el.getAttribute('data-keep-state');
+      const value = el.getAttribute('data-state-value') || el.textContent;
+      state['__data__' + key] = value;
+    });
+
+    return state;
+  }
+
+  // Restore component state
+  function restoreComponentState(element, state) {
+    if (!state) return;
+
+    // Restore form inputs
+    // eslint-disable-next-line pickier/no-unused-vars
+    element.querySelectorAll('input, textarea, select').forEach(function(input, index) {
+      const key = input.name || input.id || 'input_' + index;
+      if (state[key] !== undefined) {
+        if (input.type === 'checkbox' || input.type === 'radio') {
+          input.checked = state[key];
+        }
+else {
+          input.value = state[key];
+        }
+      }
+    });
+  }
+
+  // Cache a component
+  function cacheComponent(key, element) {
+    if (!shouldCache(key)) return;
+
+    // Remove from cache order if exists (for LRU)
+    const existingIndex = cacheOrder.indexOf(key);
+    if (existingIndex > -1) {
+      cacheOrder.splice(existingIndex, 1);
+    }
+
+    // Evict oldest if at max capacity
+    while (cacheOrder.length >= maxCache) {
+      const oldestKey = cacheOrder.shift();
+      const oldCached = cache.get(oldestKey);
+      if (oldCached && oldCached.element) {
+        oldCached.element.remove();
+      }
+      cache.delete(oldestKey);
+    }
+
+    // Clone and cache
+    const clone = element.cloneNode(true);
+    clone.style.display = 'none';
+    clone.setAttribute('data-cached-key', key);
+
+    const cached = {
+      key: key,
+      element: clone,
+      state: saveComponentState(element),
+      scrollPositions: saveScrollPositions(element),
+      cachedAt: Date.now()
+    };
+
+    cache.set(key, cached);
+    cacheOrder.push(key);
+    cacheEl.appendChild(clone);
+
+    // Dispatch deactivated event
+    element.dispatchEvent(new CustomEvent('stx:deactivated', {
+      detail: { key: key, keepAliveId: keepAliveId },
+      bubbles: true
+    }));
+  }
+
+  // Restore a component from cache
+  function restoreComponent(key) {
+    const cached = cache.get(key);
+    if (!cached) return null;
+
+    // Move to end of cache order (most recently used)
+    const index = cacheOrder.indexOf(key);
+    if (index > -1) {
+      cacheOrder.splice(index, 1);
+      cacheOrder.push(key);
+    }
+
+    // Clone the cached element
+    const restored = cached.element.cloneNode(true);
+    restored.style.display = '';
+    restored.removeAttribute('data-cached-key');
+
+    // Restore state after a tick (to let DOM settle)
+    setTimeout(function() {
+      restoreComponentState(restored, cached.state);
+      restoreScrollPositions(restored, cached.scrollPositions);
+
+      // Dispatch activated event
+      restored.dispatchEvent(new CustomEvent('stx:activated', {
+        detail: { key: key, keepAliveId: keepAliveId, cachedAt: cached.cachedAt },
+        bubbles: true
+      }));
+    }, 0);
+
+    return restored;
+  }
+
+  // Check if component is cached
+  function isCached(key) {
+    return cache.has(key);
+  }
+
+  // Clear cache
+  function clearCache(key) {
+    if (key) {
+      const cached = cache.get(key);
+      if (cached && cached.element) {
+        cached.element.remove();
+      }
+      cache.delete(key);
+      const index = cacheOrder.indexOf(key);
+      if (index > -1) {
+        cacheOrder.splice(index, 1);
+      }
+    }
+else {
+      cache.forEach(function(cached) {
+        if (cached.element) {
+          cached.element.remove();
+        }
+      });
+      cache.clear();
+      cacheOrder.length = 0;
+    }
+  }
+
+  // Expose API
+  window.STX = window.STX || {};
+  window.STX.keepAlive = window.STX.keepAlive || { instances: {} };
+  window.STX.keepAlive.instances[keepAliveId] = {
+    id: keepAliveId,
+    customId: customId,
+    cache: cacheComponent,
+    restore: restoreComponent,
+    isCached: isCached,
+    clear: clearCache,
+    getCacheKeys: function() { return Array.from(cache.keys()); },
+    getCacheSize: function() { return cache.size; }
+  };
+
+  // Observe for component changes
+  const observer = new MutationObserver(function(mutations) {
+    mutations.forEach(function(mutation) {
+      // Handle removed nodes (cache them)
+      mutation.removedNodes.forEach(function(node) {
+        if (node.nodeType === Node.ELEMENT_NODE && node.hasAttribute && !node.hasAttribute('data-cached-key')) {
+          const key = getComponentKey(node);
+          if (key && shouldCache(key)) {
+            // Check if this removal is intentional (not just DOM restructuring)
+            if (!contentEl.contains(node)) {
+              cacheComponent(key, node);
+            }
+          }
+        }
+      });
+
+      // Handle added nodes (check if we should restore from cache)
+      mutation.addedNodes.forEach(function(node) {
+        if (node.nodeType === Node.ELEMENT_NODE && node.hasAttribute) {
+          const key = getComponentKey(node);
+          if (key && isCached(key)) {
+            const restored = restoreComponent(key);
+            if (restored) {
+              node.replaceWith(restored);
+            }
+          }
+        }
+      });
+    });
+  });
+
+  observer.observe(contentEl, { childList: true, subtree: true });
+
+  // Cleanup on removal
+  container.addEventListener('stx:destroy', function() {
+    observer.disconnect();
+    clearCache();
+  });
+})();
+</script>
+`;
+}
+export function createKeepAliveCache(options = {}) {
+  return {
+    id: options.id || generateKeepAliveId(),
+    cache: new Map,
+    max: options.max || 10,
+    include: options.include ? options.include.split(",").map((s) => s.trim()) : null,
+    exclude: options.exclude ? options.exclude.split(",").map((s) => s.trim()) : null
+  };
+}
+export function shouldCacheComponent(componentName, cache) {
+  if (cache.exclude && cache.exclude.includes(componentName))
+    return !1;
+  if (cache.include && !cache.include.includes(componentName))
+    return !1;
+  return !0;
+}
+export function generateKeepAliveCSS() {
+  return `
+/* STX Keep-Alive Styles */
+.stx-keep-alive {
+  position: relative;
+}
+
+.stx-keep-alive-cache {
+  display: none !important;
+  visibility: hidden;
+  position: absolute;
+  pointer-events: none;
+}
+
+/* Activation transition */
+.stx-keep-alive-content > * {
+  transition: opacity 0.15s ease;
+}
+
+.stx-keep-alive-content > [data-activating] {
+  opacity: 0;
+}
+
+.stx-keep-alive-content > [data-activated] {
+  opacity: 1;
+}
+`;
+}
+export function generateKeepAliveRuntime() {
+  return `
+// STX Keep-Alive Runtime
+(function() {
+  if (typeof window === 'undefined') return;
+
+  window.STX = window.STX || {};
+  window.STX.keepAlive = window.STX.keepAlive || { instances: {} };
+
+  // Global keep-alive utilities
+  window.STX.keepAlive.clearAll = function() {
+    Object.values(window.STX.keepAlive.instances).forEach(function(instance) {
+      instance.clear();
+    });
+  };
+
+  window.STX.keepAlive.getTotalCached = function() {
+    return Object.values(window.STX.keepAlive.instances).reduce(function(total, instance) {
+      return total + instance.getCacheSize();
+    }, 0);
+  };
+
+  // Lifecycle hooks for keep-alive
+  window.STX.onActivated = function(callback) {
+    document.addEventListener('stx:activated', function(e) {
+      callback(e.detail);
+    });
+  };
+
+  window.STX.onDeactivated = function(callback) {
+    document.addEventListener('stx:deactivated', function(e) {
+      callback(e.detail);
+    });
+  };
+
+  console.log('[stx] Keep-alive runtime initialized');
+})();
+`;
+}
+export function onActivated(callback) {
+  if (typeof document < "u")
+    document.addEventListener("stx:activated", (e) => {
+      callback(e.detail);
+    });
+}
+export function onDeactivated(callback) {
+  if (typeof document < "u")
+    document.addEventListener("stx:deactivated", (e) => {
+      callback(e.detail);
+    });
+}

package/dist/layout-types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Generate a union of the layouts that exist on disk, so naming one wrong is a
+ * type error rather than an unlayouted page (stacksjs/stx#1879 ask 3).
+ *
+ * `definePageMeta({ layout: 'app' })` now selects a layout, which makes the
+ * name a load-bearing string — and a typo produces exactly the same render as a
+ * correct name pointing at a missing file. Nuxt types `layout` as a union of
+ * the files on disk for this reason; the failure is caught before the build,
+ * not by reading the console afterwards.
+ *
+ * ## Why this augments the real package, not a synthetic specifier
+ *
+ * The augmentation targets `@stacksjs/stx`, where `KnownLayouts` is really
+ * declared and really referenced by `PageMeta['layout']`.
+ *
+ * That mattered because the route-type generator used to emit
+ * `declare module "stx/routes"` — a specifier nothing in the source tree
+ * declares or imports, which TypeScript reads as an ambient module declaration
+ * rather than an augmentation. It parsed, shipped, and constrained nothing: the
+ * same "typed and never read" shape #1879 is about, one level up. Routes now
+ * use this same target (#1887); the reasoning below is what kept this file from
+ * repeating it.
+ *
+ * @module layout-types
+ */
+/** The name of the generated declaration file, inside the state directory. */
+export declare const LAYOUT_TYPES_FILE = "layout-types.d.ts";
+/**
+ * Layout names in `layoutsDir`, without the `.stx` extension.
+ *
+ * Nested layouts keep their path (`admin/settings`), matching what the layout
+ * resolver accepts. `_layout.stx` files are excluded: they are applied by
+ * directory position, never named.
+ */
+export declare function discoverLayoutNames(layoutsDir: string): string[];
+/** The declaration text for a set of layout names. */
+export declare function renderLayoutTypes(names: readonly string[]): string;
+/**
+ * Write the declaration for `layoutsDir` into `outputDir`.
+ *
+ * Best-effort and idempotent: an unwritable state directory is not a build
+ * failure, and an unchanged file is left alone so watchers do not see a write
+ * on every render.
+ */
+export declare function generateLayoutTypes(layoutsDir: string | undefined, outputDir: string): string[];

package/dist/layout-types.js

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import path from "node:path";
+export const LAYOUT_TYPES_FILE = "layout-types.d.ts";
+export function discoverLayoutNames(layoutsDir) {
+  const names = [], walk = (dir, prefix) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: !0 });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith("."))
+        continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory())
+        walk(full, prefix ? `${prefix}/${entry.name}` : entry.name);
+      else if (entry.isFile() && entry.name.endsWith(".stx") && entry.name !== "_layout.stx") {
+        const base = entry.name.slice(0, -4);
+        names.push(prefix ? `${prefix}/${base}` : base);
+      }
+    }
+  };
+  walk(layoutsDir, "");
+  return names.sort();
+}
+export function renderLayoutTypes(names) {
+  const lines = [
+    "// Auto-generated by stx \u2014 do not edit.",
+    "//",
+    "// Makes `definePageMeta({ layout })` reject a name with no layout behind it.",
+    "// Include this file in your tsconfig (it lives in the stx state directory,",
+    "// `.stx/` by default) for the check to apply.",
+    ""
+  ];
+  if (names.length === 0) {
+    lines.push("// No layouts found \u2014 `layout` stays typed as `string`.", "export {}", "");
+    return lines.join(`
+`);
+  }
+  lines.push("declare module '@stacksjs/stx' {", "  interface KnownLayouts {", ...names.map((name) => `    '${name}': true`), "  }", "}", "", "export {}", "");
+  return lines.join(`
+`);
+}
+export function generateLayoutTypes(layoutsDir, outputDir) {
+  if (!layoutsDir)
+    return [];
+  const abs = path.isAbsolute(layoutsDir) ? layoutsDir : path.resolve(process.cwd(), layoutsDir), names = discoverLayoutNames(abs), contents = renderLayoutTypes(names), target = path.join(outputDir, LAYOUT_TYPES_FILE);
+  try {
+    if (fs.existsSync(target) && fs.readFileSync(target, "utf8") === contents)
+      return names;
+    fs.mkdirSync(outputDir, { recursive: !0 });
+    fs.writeFileSync(target, contents);
+  } catch {}
+  return names;
+}

package/dist/lazy-loader.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Default lazy-loaded directive registry
+ */
+export declare function createDirectiveRegistry(): DirectiveLoaderRegistry;
+/**
+ * Create a lazy module that loads on first access
+ */
+export declare function createLazyModule<T>(loader: ModuleLoader<T>): {
+  get: () => Promise<T>
+  isLoaded: () => boolean
+  preload: () => Promise<void>
+};
+/**
+ * Batch load multiple modules with progress callback
+ */
+export declare function batchLoad<T>(loader: LazyLoader<T>, names: string[], onProgress?: (loaded: number, total: number, name: string) => void): Promise<Map<string, T>>;
+/**
+ * Global lazy loader instance
+ */
+export declare const globalLoader: LazyLoader<unknown>;
+/**
+ * Global directive registry
+ */
+export declare const directiveRegistry: DirectiveLoaderRegistry;
+/**
+ * Lazy loader options
+ */
+export declare interface LazyLoaderOptions {
+  preload?: string[]
+  timeout?: number
+  debug?: boolean
+  onError?: (name: string, error: Error) => void
+}
+/**
+ * Directive processor interface
+ */
+export declare interface DirectiveProcessor {
+  process: (content: string, params?: string, context?: Record<string, unknown>) => string | Promise<string>
+  name?: string
+  hasEndTag?: boolean
+}
+/**
+ * Module loader function
+ */
+export type ModuleLoader<T = unknown> = () => Promise<T> | T;
+/**
+ * Module status
+ */
+export type ModuleStatus = 'pending' | 'loading' | 'loaded' | 'error';
+/**
+ * Lazy loader for directive processors
+ */
+export declare class LazyLoader<T = unknown> {
+  constructor(options?: LazyLoaderOptions);
+  register(name: string, loader: ModuleLoader<T>, dependencies?: string[]): void;
+  registerAll(modules: Record<string, ModuleLoader<T>>): void;
+  has(name: string): boolean;
+  getStatus(name: string): ModuleStatus | null;
+  isLoaded(name: string): boolean;
+  load(name: string): Promise<T>;
+  loadAll(names: string[]): Promise<T[]>;
+  loadSync(name: string): T;
+  preload(names: string[]): Promise<void>;
+  unload(name: string): boolean;
+  unloadAll(): void;
+  getStats(): {
+    registered: number
+    loaded: number
+    pending: number
+    errors: number
+    totalLoadTime: number
+    modules: Array<{
+      name: string
+      status: ModuleStatus
+      loadCount: number
+      loadTime?: number
+    }>
+  };
+}
+/**
+ * Lazy loader specifically for directive processors
+ */
+export declare class DirectiveLoaderRegistry {
+  constructor(options?: LazyLoaderOptions);
+  registerDirective(directiveName: string, moduleName: string, loader: ModuleLoader<DirectiveProcessor | { default: DirectiveProcessor }>): void;
+  getProcessor(directiveName: string): Promise<DirectiveProcessor | null>;
+  hasDirective(directiveName: string): boolean;
+  getDirectiveNames(): string[];
+  preloadDirectives(directiveNames: string[]): Promise<void>;
+}