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

package/dist/store-loader.js

@@ -0,0 +1,111 @@
+import path from "node:path";
+import { bundleClientScript, clientBundleDependencies, hasUserImports } from "./client-script-bundler.js";
+import { loadStxConfig } from "./config.js";
+import { getPublicEnvDefine } from "./public-env.js";
+import { STX_RUNTIME_GLOBALS } from "./runtime-globals.js";
+import { stripStxRuntimeImports } from "./signal-processing.js";
+import { readSigned, sourceSignature, writeSigned } from "./source-signature.js";
+import { stripModuleImports, transformStoreImports } from "./store-imports.js";
+import { getSharedTranspiler } from "./utils.js";
+const _cachedStoreScripts = new Map;
+function collectDeclaredNames(code, into) {
+  for (const match of code.matchAll(/\b(?:const|let|var|function|class)\s+([A-Z_a-z$][\w$]*)/g))
+    if (match[1])
+      into.add(match[1]);
+  for (const match of code.matchAll(/\b(?:const|let|var)\s*\{([^{}]*)\}\s*=/g))
+    for (const part of (match[1] ?? "").split(",")) {
+      const name = ((part.includes(":") ? part.split(":").pop() : part) ?? "").replace(/=.*$/s, "").replace(/^\s*\.\.\./, "").trim();
+      if (/^[A-Z_a-z$][\w$]*$/.test(name))
+        into.add(name);
+    }
+  for (const match of code.matchAll(/\b(?:const|let|var)\s*\[([^\]]*)\]\s*=/g))
+    for (const part of (match[1] ?? "").split(",")) {
+      const name = part.replace(/=.*$/s, "").replace(/^\s*\.\.\./, "").trim();
+      if (/^[A-Z_a-z$][\w$]*$/.test(name))
+        into.add(name);
+    }
+}
+export async function getStoreScript(storesDir) {
+  let resolvedDir;
+  if (storesDir)
+    resolvedDir = path.resolve(storesDir);
+  else {
+    const config = await loadStxConfig();
+    resolvedDir = path.resolve(config.root || process.cwd(), config.storesDir || "stores");
+  }
+  const glob = new Bun.Glob("*.ts"), storeFiles = [];
+  try {
+    for await (const file of glob.scan({ cwd: resolvedDir, absolute: !0 })) {
+      const name = path.basename(file, ".ts");
+      if (["index", "types"].includes(name))
+        continue;
+      if (file.includes(".d.ts"))
+        continue;
+      storeFiles.push(file);
+    }
+  } catch {
+    writeSigned(_cachedStoreScripts, resolvedDir, "", "");
+    return null;
+  }
+  const storeInputs = () => [...new Set([
+    ...storeFiles,
+    ...storeFiles.flatMap((file) => clientBundleDependencies(file))
+  ])];
+  let signature = sourceSignature(storeInputs());
+  const cached = readSigned(_cachedStoreScripts, resolvedDir, signature);
+  if (cached !== void 0)
+    return cached || null;
+  if (storeFiles.length === 0) {
+    writeSigned(_cachedStoreScripts, resolvedDir, signature, "");
+    return null;
+  }
+  const filesWithDeps = [];
+  for (const file of storeFiles) {
+    const content = await Bun.file(file).text();
+    filesWithDeps.push({
+      file,
+      hasUseStore: /useStore\s*\(/.test(content)
+    });
+  }
+  filesWithDeps.sort((a, b) => {
+    if (a.hasUseStore === b.hasUseStore)
+      return 0;
+    return a.hasUseStore ? 1 : -1;
+  });
+  const sortedFiles = filesWithDeps.map((f) => f.file), chunks = [], declaredNames = new Set, transpiler = getSharedTranspiler({ loader: "ts", target: "browser", define: getPublicEnvDefine() });
+  for (const file of sortedFiles)
+    try {
+      let code = await Bun.file(file).text();
+      const storeName = path.basename(file, ".ts");
+      collectDeclaredNames(code, declaredNames);
+      if (hasUserImports(code))
+        code = await bundleClientScript(code, file, { projectRoot: process.cwd() });
+      code = stripStxRuntimeImports(code);
+      code = transformStoreImports(code);
+      code = stripModuleImports(code);
+      code = code.replace(/^export\s+(default\s+)?/gm, "");
+      code = transpiler.transformSync(code);
+      chunks.push(`// Store: ${storeName}
+${code.trim()}`);
+    } catch (e) {
+      console.warn(`[stx] Failed to load store ${file}:`, e);
+    }
+  if (chunks.length === 0) {
+    writeSigned(_cachedStoreScripts, resolvedDir, signature, "");
+    return null;
+  }
+  const joinedChunks = chunks.join(`
+
+`), code = `;(function(){
+var __stx = window.stx || {};
+${STX_RUNTIME_GLOBALS.filter((name) => !declaredNames.has(name) && new RegExp(`\\b${name}\\b`).test(joinedChunks)).map((name) => `var ${name} = __stx[${JSON.stringify(name)}];`).join(`
+`)}
+${joinedChunks}
+})();`;
+  signature = sourceSignature(storeInputs());
+  writeSigned(_cachedStoreScripts, resolvedDir, signature, code);
+  return code;
+}
+export function clearStoreCache() {
+  _cachedStoreScripts.clear();
+}

package/dist/stores-client.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Define a reactive store with state, getters, and actions.
+ */
+export declare function defineStore<S extends object, G extends Record<string, (state: S) => any> = Record<string, never>, A extends Record<string, (...args: any[]) => any> = Record<string, never>,>(id: string, options: StoreOptions<S, G, A>): Store<S> & { [K in keyof G]: ReturnType<G[K]> } & { [K in keyof A]: A[K] };
+/**
+ * Register multiple stores at once.
+ */
+export declare function registerStores(stores: Record<string, any>): void;
+/**
+ * Get a store by name.
+ */
+export declare function getStore<T = any>(name: string): T | undefined;
+/**
+ * Wait for a store to be available.
+ */
+export declare function waitForStore<T = any>(name: string, timeout?: number): Promise<T>;
+/**
+ * STX Stores - Client Runtime
+ *
+ * This module provides the client-side store functionality for STX applications.
+ * It enables clean imports like: import { appStore } from '@stores'
+ *
+ * @example
+ * ```html
+ * <!-- In your layout or main template -->
+ * <script src="/js/stx-stores.js"></script>
+ *
+ * <!-- In your stores definition file -->
+ * <script>
+ * const { defineStore, registerStores } = window.STX;
+ *
+ * const appStore = defineStore('app', {
+ *   state: { count: 0 },
+ *   actions: {
+ *     increment() { this.count++ }
+ *   }
+ * });
+ *
+ * registerStores({ appStore });
+ * </script>
+ *
+ * <!-- In your components -->
+ * <script client>
+ * import { appStore } from '@stores'
+ * appStore.increment()
+ * </script>
+ * ```
+ */
+// Type definitions
+export declare interface Subscriber<T> {
+  (value: T, previousValue?: T): void
+}
+export declare interface PersistOptions {
+  storage?: 'local' | 'session' | 'memory'
+  key?: string
+}
+export declare interface StoreOptions<S, G, A> {
+  state: S | (() => S)
+  getters?: G
+  actions?: A
+  persist?: PersistOptions | boolean
+}
+export declare interface Store<S> {
+  $state: S
+  $subscribe: (callback: Subscriber<S>) => Unsubscribe
+  $reset: () => void
+  $patch: (partial: Partial<S> | ((state: S) => void)) => void
+  $id: string
+}
+export type Unsubscribe = () => void;

package/dist/stores-client.js

@@ -0,0 +1,132 @@
+const memoryStorage = new Map;
+function getStorage(type = "local") {
+  if (type === "memory" || typeof localStorage > "u")
+    return {
+      getItem: (key) => memoryStorage.get(key) ?? null,
+      setItem: (key, value) => memoryStorage.set(key, value),
+      removeItem: (key) => memoryStorage.delete(key)
+    };
+  return type === "local" ? localStorage : sessionStorage;
+}
+export function defineStore(id, options) {
+  const { state: initialState, getters = {}, actions = {}, persist } = options;
+  let currentState = typeof initialState === "function" ? initialState() : { ...initialState };
+  const subscribers = new Set;
+  if (persist) {
+    const opts = persist === !0 ? { storage: "local", key: `stx:${id}` } : persist, storage = getStorage(opts.storage), key = opts.key || `stx:${id}`;
+    try {
+      const stored = storage.getItem(key);
+      if (stored)
+        currentState = { ...currentState, ...JSON.parse(stored) };
+    } catch {}
+  }
+  const persistState = () => {
+    if (!persist)
+      return;
+    const opts = persist === !0 ? { storage: "local", key: `stx:${id}` } : persist, storage = getStorage(opts.storage), key = opts.key || `stx:${id}`;
+    storage.setItem(key, JSON.stringify(currentState));
+  }, notify = (prev) => {
+    for (const sub of subscribers)
+      try {
+        sub(currentState, prev);
+      } catch (e) {
+        console.error(`[stx:${id}] Subscriber error:`, e);
+      }
+  }, initialStateCopy = typeof initialState === "function" ? initialState() : { ...initialState }, store = new Proxy({}, {
+    get(_, prop) {
+      if (prop === "$state")
+        return { ...currentState };
+      if (prop === "$id")
+        return id;
+      if (prop === "$subscribe")
+        return (callback) => {
+          subscribers.add(callback);
+          return () => subscribers.delete(callback);
+        };
+      if (prop === "$reset")
+        return () => {
+          const prev = currentState;
+          currentState = { ...initialStateCopy };
+          persistState();
+          notify(prev);
+        };
+      if (prop === "$patch")
+        return (partial) => {
+          const prev = currentState;
+          if (typeof partial === "function") {
+            const draft = { ...currentState };
+            partial(draft);
+            currentState = draft;
+          } else
+            currentState = { ...currentState, ...partial };
+          persistState();
+          notify(prev);
+        };
+      if (prop in getters)
+        return getters[prop](currentState);
+      if (prop in actions)
+        return (...args) => actions[prop].apply(store, args);
+      if (prop in currentState)
+        return currentState[prop];
+      return;
+    },
+    set(_, prop, value) {
+      if (prop.startsWith("$"))
+        return !1;
+      const prev = currentState;
+      currentState = { ...currentState, [prop]: value };
+      persistState();
+      notify(prev);
+      return !0;
+    },
+    has(_, prop) {
+      return prop.startsWith("$") || prop in getters || prop in actions || prop in currentState;
+    }
+  });
+  if (typeof window < "u") {
+    window.__STX_STORES__ = window.__STX_STORES__ || {};
+    window.__STX_STORES__[id] = store;
+  }
+  return store;
+}
+export function registerStores(stores) {
+  if (typeof window > "u")
+    return;
+  const w = window;
+  w.__STX_STORES__ = w.__STX_STORES__ || {};
+  for (const [name, store] of Object.entries(stores))
+    w.__STX_STORES__[name] = store;
+  window.dispatchEvent(new CustomEvent("stx:stores-ready", { detail: Object.keys(stores) }));
+}
+export function getStore(name) {
+  if (typeof window > "u")
+    return;
+  return window.__STX_STORES__?.[name];
+}
+export function waitForStore(name, timeout = 5000) {
+  return new Promise((resolve, reject) => {
+    const store = getStore(name);
+    if (store) {
+      resolve(store);
+      return;
+    }
+    const start = Date.now(), check = () => {
+      const store = getStore(name);
+      if (store)
+        resolve(store);
+      else if (Date.now() - start > timeout)
+        reject(Error(`Store "${name}" not found after ${timeout}ms`));
+      else
+        requestAnimationFrame(check);
+    };
+    check();
+  });
+}
+if (typeof window < "u")
+  window.STX = {
+    ...window.STX,
+    defineStore,
+    registerStores,
+    getStore,
+    waitForStore
+  };

package/dist/story/addons.d.ts

@@ -0,0 +1,123 @@
+import type { ServerStoryFile, StoryContext } from './types';
+/**
+ * Register an addon
+ */
+export declare function registerAddon(addon: StoryAddon): void;
+/**
+ * Unregister an addon
+ */
+export declare function unregisterAddon(id: string): boolean;
+/**
+ * Get all registered addons
+ */
+export declare function getAddons(): StoryAddon[];
+/**
+ * Get an addon by ID
+ */
+export declare function getAddon(id: string): StoryAddon | undefined;
+/**
+ * Initialize all addons
+ */
+export declare function initializeAddons(ctx: StoryContext): Promise<void>;
+/**
+ * Apply all decorators to a story
+ */
+export declare function applyDecorators(story: ServerStoryFile, ctx: AddonContext): ServerStoryFile;
+/**
+ * Get all addon panels
+ */
+export declare function getAddonPanels(): AddonPanel[];
+/**
+ * Get all toolbar items
+ */
+export declare function getToolbarItems(): ToolbarItem[];
+/**
+ * Register all built-in addons
+ */
+export declare function registerBuiltinAddons(): void;
+/**
+ * Actions addon - logs component events
+ */
+export declare const actionsAddon: StoryAddon;
+/**
+ * Viewport addon - responsive preview sizes
+ */
+export declare const viewportAddon: StoryAddon;
+/**
+ * Backgrounds addon - change preview background
+ */
+export declare const backgroundsAddon: StoryAddon;
+/**
+ * Docs addon - auto-generated documentation
+ */
+export declare const docsAddon: StoryAddon;
+/**
+ * Measure addon - spacing/sizing overlay
+ */
+export declare const measureAddon: StoryAddon;
+/**
+ * Outline addon - component boundaries
+ */
+export declare const outlineAddon: StoryAddon;
+/**
+ * i18n addon - test with different locales
+ */
+export declare const i18nAddon: StoryAddon;
+/**
+ * Performance addon - render timing metrics
+ */
+export declare const performanceAddon: StoryAddon;
+/**
+ * State addon - component state inspector
+ */
+export declare const stateAddon: StoryAddon;
+/**
+ * A11y addon - accessibility audit panel
+ */
+export declare const a11yAddon: StoryAddon;
+/**
+ * Addon panel configuration
+ */
+export declare interface AddonPanel {
+  id: string
+  title: string
+  icon?: string
+  render: (ctx: AddonContext) => string
+}
+/**
+ * Toolbar item configuration
+ */
+export declare interface ToolbarItem {
+  id: string
+  title: string
+  icon?: string
+  render: (ctx: AddonContext) => string
+  onClick?: string
+}
+/**
+ * Addon context passed to render functions
+ */
+export declare interface AddonContext {
+  story?: ServerStoryFile
+  variantId?: string
+  storyContext: StoryContext
+  state: Record<string, any>
+}
+/**
+ * Addon definition
+ */
+export declare interface StoryAddon {
+  name: string
+  id: string
+  panel?: AddonPanel
+  decorator?: StoryDecorator
+  toolbar?: ToolbarItem[]
+  init?: (ctx: StoryContext) => void | Promise<void>
+}
+/**
+ * Story decorator function
+ */
+export type StoryDecorator = (
+  story: ServerStoryFile,
+  ctx: AddonContext,
+) => ServerStoryFile;

package/dist/story/addons.js

@@ -0,0 +1,261 @@
+const addons = new Map;
+export function registerAddon(addon) {
+  if (addons.has(addon.id))
+    console.warn(`Addon "${addon.id}" is already registered, overwriting...`);
+  addons.set(addon.id, addon);
+}
+export function unregisterAddon(id) {
+  return addons.delete(id);
+}
+export function getAddons() {
+  return Array.from(addons.values());
+}
+export function getAddon(id) {
+  return addons.get(id);
+}
+export async function initializeAddons(ctx) {
+  for (const addon of addons.values())
+    if (addon.init)
+      await addon.init(ctx);
+}
+export function applyDecorators(story, ctx) {
+  let decorated = story;
+  for (const addon of addons.values())
+    if (addon.decorator)
+      decorated = addon.decorator(decorated, ctx);
+  return decorated;
+}
+export function getAddonPanels() {
+  const panels = [];
+  for (const addon of addons.values())
+    if (addon.panel)
+      panels.push(addon.panel);
+  return panels;
+}
+export function getToolbarItems() {
+  const items = [];
+  for (const addon of addons.values())
+    if (addon.toolbar)
+      items.push(...addon.toolbar);
+  return items;
+}
+export const actionsAddon = {
+  name: "Actions",
+  id: "actions",
+  panel: {
+    id: "actions-panel",
+    title: "Actions",
+    icon: "ph:lightning",
+    render: (_ctx) => {
+      return `
+        <div class="addon-actions">
+          <div class="addon-actions-header">
+            <span>Event Log</span>
+            <button onclick="window.__stxStory.clearActions()">Clear</button>
+          </div>
+          <div class="addon-actions-list" id="actions-list">
+            <div class="addon-actions-empty">No actions logged yet</div>
+          </div>
+        </div>
+      `;
+    }
+  }
+}, viewportAddon = {
+  name: "Viewport",
+  id: "viewport",
+  toolbar: [
+    {
+      id: "viewport-select",
+      title: "Viewport",
+      icon: "ph:device-mobile",
+      render: (ctx) => {
+        return `
+          <select id="viewport-select" onchange="window.__stxStory.setViewport(this.value)">
+            <option value="">Responsive</option>
+            ${ctx.storyContext.config.responsivePresets.map((p) => `<option value="${p.width}">${p.label}</option>`).join("")}
+          </select>
+        `;
+      }
+    }
+  ]
+}, backgroundsAddon = {
+  name: "Backgrounds",
+  id: "backgrounds",
+  toolbar: [
+    {
+      id: "background-select",
+      title: "Background",
+      icon: "ph:paint-bucket",
+      render: (ctx) => {
+        return `
+          <select id="background-select" onchange="window.__stxStory.setBackground(this.value)">
+            ${ctx.storyContext.config.backgroundPresets.map((p) => `<option value="${p.color}">${p.label}</option>`).join("")}
+          </select>
+        `;
+      }
+    }
+  ]
+}, docsAddon = {
+  name: "Docs",
+  id: "docs",
+  panel: {
+    id: "docs-panel",
+    title: "Docs",
+    icon: "ph:book-open",
+    render: (_ctx) => {
+      return `
+        <div class="addon-docs">
+          <div class="addon-docs-content" id="docs-content">
+            Select a story to view documentation
+          </div>
+        </div>
+      `;
+    }
+  }
+}, measureAddon = {
+  name: "Measure",
+  id: "measure",
+  toolbar: [
+    {
+      id: "measure-toggle",
+      title: "Measure",
+      icon: "ph:ruler",
+      render: () => {
+        return `
+          <button
+            class="toolbar-btn"
+            onclick="window.__stxStory.toggleMeasure()"
+            title="Toggle measure overlay"
+          >
+            \uD83D\uDCCF
+          </button>
+        `;
+      }
+    }
+  ]
+}, outlineAddon = {
+  name: "Outline",
+  id: "outline",
+  toolbar: [
+    {
+      id: "outline-toggle",
+      title: "Outline",
+      icon: "ph:bounding-box",
+      render: () => {
+        return `
+          <button
+            class="toolbar-btn"
+            onclick="window.__stxStory.toggleOutline()"
+            title="Toggle outline overlay"
+          >
+            \u2B1C
+          </button>
+        `;
+      }
+    }
+  ]
+}, i18nAddon = {
+  name: "i18n",
+  id: "i18n",
+  toolbar: [
+    {
+      id: "locale-select",
+      title: "Locale",
+      icon: "ph:globe",
+      render: () => {
+        return `
+          <select id="locale-select" onchange="window.__stxStory.setLocale(this.value)">
+            ${["en", "es", "fr", "de", "ja", "zh"].map((l) => `<option value="${l}">${l.toUpperCase()}</option>`).join("")}
+          </select>
+        `;
+      }
+    }
+  ]
+}, performanceAddon = {
+  name: "Performance",
+  id: "performance",
+  panel: {
+    id: "performance-panel",
+    title: "Performance",
+    icon: "ph:timer",
+    render: () => {
+      return `
+        <div class="addon-performance">
+          <div class="addon-performance-metrics" id="perf-metrics">
+            <div class="perf-metric">
+              <span class="perf-label">Render Time</span>
+              <span class="perf-value" id="perf-render">-</span>
+            </div>
+            <div class="perf-metric">
+              <span class="perf-label">DOM Nodes</span>
+              <span class="perf-value" id="perf-nodes">-</span>
+            </div>
+            <div class="perf-metric">
+              <span class="perf-label">Memory</span>
+              <span class="perf-value" id="perf-memory">-</span>
+            </div>
+            <div class="perf-metric">
+              <span class="perf-label">Re-renders</span>
+              <span class="perf-value" id="perf-rerenders">0</span>
+            </div>
+          </div>
+          <button onclick="window.__stxStory.measurePerformance()">Measure</button>
+        </div>
+      `;
+    }
+  }
+}, stateAddon = {
+  name: "State",
+  id: "state",
+  panel: {
+    id: "state-panel",
+    title: "State",
+    icon: "ph:database",
+    render: () => {
+      return `
+        <div class="addon-state">
+          <div class="addon-state-header">
+            <span>Component State</span>
+            <button onclick="window.__stxStory.refreshState()">Refresh</button>
+          </div>
+          <div class="addon-state-tree" id="state-tree">
+            <pre>// Select a story to inspect state</pre>
+          </div>
+        </div>
+      `;
+    }
+  }
+}, a11yAddon = {
+  name: "Accessibility",
+  id: "a11y",
+  panel: {
+    id: "a11y-panel",
+    title: "A11y",
+    icon: "ph:wheelchair",
+    render: () => {
+      return `
+        <div class="addon-a11y">
+          <div class="addon-a11y-header">
+            <span>Accessibility Audit</span>
+            <button onclick="window.__stxStory.runA11yAudit()">Run Audit</button>
+          </div>
+          <div class="addon-a11y-results" id="a11y-results">
+            <div class="a11y-empty">Click "Run Audit" to check accessibility</div>
+          </div>
+        </div>
+      `;
+    }
+  }
+};
+export function registerBuiltinAddons() {
+  registerAddon(actionsAddon);
+  registerAddon(viewportAddon);
+  registerAddon(backgroundsAddon);
+  registerAddon(docsAddon);
+  registerAddon(measureAddon);
+  registerAddon(outlineAddon);
+  registerAddon(i18nAddon);
+  registerAddon(performanceAddon);
+  registerAddon(stateAddon);
+  registerAddon(a11yAddon);
+}