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

package/dist/story/setup.d.ts

@@ -0,0 +1,56 @@
+/**
+ * STX Story - Setup file support
+ * Handles global story setup configuration
+ */
+import type { StoryContext } from './types';
+/**
+ * Setup function signature
+ */
+export type SetupFunction = (ctx: SetupContext) => void | Promise<void>;
+/**
+ * Context passed to setup function
+ */
+export interface SetupContext {
+    /** Story context */
+    storyContext: StoryContext;
+    /** Register a global component */
+    registerComponent: (name: string, component: any) => void;
+    /** Add global CSS */
+    addCSS: (css: string) => void;
+    /** Add global script */
+    addScript: (script: string) => void;
+    /** Set global state */
+    setState: (key: string, value: any) => void;
+}
+/**
+ * Load and execute the setup file
+ */
+export declare function loadSetupFile(ctx: StoryContext): Promise<void>;
+/**
+ * Get all registered global components
+ */
+export declare function getGlobalComponents(): Map<string, any>;
+/**
+ * Get all global CSS
+ */
+export declare function getGlobalCSS(): string;
+/**
+ * Get all global scripts
+ */
+export declare function getGlobalScripts(): string;
+/**
+ * Get global state
+ */
+export declare function getGlobalState(): Map<string, any>;
+/**
+ * Get a specific global state value
+ */
+export declare function getState<T = any>(key: string): T | undefined;
+/**
+ * Reset all global setup (for testing)
+ */
+export declare function resetSetup(): void;
+/**
+ * Generate HTML for global setup (CSS + scripts)
+ */
+export declare function getSetupHTML(): string;

package/dist/story/setup.js

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import path from "node:path";
+const globalComponents = new Map;
+let globalCSS = [], globalScripts = [];
+const globalState = new Map;
+export async function loadSetupFile(ctx) {
+  const setupFile = ctx.config.setupFile;
+  if (!setupFile)
+    return;
+  const setupPath = path.resolve(ctx.root, setupFile);
+  try {
+    await fs.promises.access(setupPath);
+  } catch {
+    return;
+  }
+  const setupCtx = {
+    storyContext: ctx,
+    registerComponent: (name, component) => {
+      globalComponents.set(name, component);
+    },
+    addCSS: (css) => {
+      globalCSS.push(css);
+    },
+    addScript: (script) => {
+      globalScripts.push(script);
+    },
+    setState: (key, value) => {
+      globalState.set(key, value);
+    }
+  };
+  try {
+    const setupModule = await import(setupPath);
+    if (typeof setupModule.default === "function")
+      await setupModule.default(setupCtx);
+    else if (typeof setupModule.setupStory === "function")
+      await setupModule.setupStory(setupCtx);
+  } catch (error) {
+    console.warn(`Warning: Failed to load setup file: ${error}`);
+  }
+}
+export function getGlobalComponents() {
+  return globalComponents;
+}
+export function getGlobalCSS() {
+  return globalCSS.join(`
+`);
+}
+export function getGlobalScripts() {
+  return globalScripts.join(`
+`);
+}
+export function getGlobalState() {
+  return globalState;
+}
+export function getState(key) {
+  return globalState.get(key);
+}
+export function resetSetup() {
+  globalComponents.clear();
+  globalCSS = [];
+  globalScripts = [];
+  globalState.clear();
+}
+export function getSetupHTML() {
+  const css = getGlobalCSS(), scripts = getGlobalScripts();
+  let html = "";
+  if (css)
+    html += `<style>
+${css}
+</style>
+`;
+  if (scripts)
+    html += `<script>
+${scripts}
+</script>
+`;
+  return html;
+}

package/dist/story/snapshots.d.ts

@@ -0,0 +1,65 @@
+import type { StoryContext } from './types';
+/**
+ * Get snapshot directory
+ */
+export declare function getSnapshotDir(ctx: StoryContext): string;
+/**
+ * Load snapshot versions
+ */
+export declare function loadSnapshotVersions(ctx: StoryContext, storyId: string): Promise<VersionedSnapshot | null>;
+/**
+ * Save snapshot version
+ */
+export declare function saveSnapshotVersion(ctx: StoryContext, storyId: string, description?: string): Promise<SnapshotVersion>;
+/**
+ * Restore snapshot to a previous version
+ */
+export declare function restoreSnapshotVersion(ctx: StoryContext, storyId: string, version: number): Promise<boolean>;
+/**
+ * Generate diff between two HTML snapshots
+ * Returns a simple text-based diff (for actual image diff, you'd need canvas/image processing)
+ */
+export declare function generateTextDiff(oldHtml: string, newHtml: string): DiffResult;
+/**
+ * Generate visual diff HTML
+ */
+export declare function generateDiffHTML(oldHtml: string, newHtml: string): string;
+/**
+ * Get diff styles
+ */
+export declare function getDiffStyles(): string;
+/**
+ * List all snapshot versions for a story
+ */
+export declare function listSnapshotVersions(ctx: StoryContext, storyId: string): Promise<SnapshotVersion[]>;
+/**
+ * Delete old snapshot versions
+ */
+export declare function pruneSnapshotVersions(ctx: StoryContext, storyId: string, keepCount?: number): Promise<number>;
+/**
+ * Snapshot version info
+ */
+export declare interface SnapshotVersion {
+  version: number
+  timestamp: number
+  commit?: string
+  description?: string
+}
+/**
+ * Snapshot with version history
+ */
+export declare interface VersionedSnapshot {
+  current: SnapshotVersion
+  history: SnapshotVersion[]
+  maxVersions: number
+}
+/**
+ * Diff result
+ */
+export declare interface DiffResult {
+  hasDiff: boolean
+  percentage: number
+  diffImagePath?: string
+  changedPixels: number
+  totalPixels: number
+}

package/dist/story/snapshots.js

@@ -0,0 +1,171 @@
+import fs from "node:fs";
+import path from "node:path";
+import { stateDir } from "../state-dir.js";
+export function getSnapshotDir(ctx) {
+  return stateDir(ctx.root, "story", "snapshots");
+}
+function getVersionFilePath(snapshotDir, storyId) {
+  return path.join(snapshotDir, `${storyId}.versions.json`);
+}
+export async function loadSnapshotVersions(ctx, storyId) {
+  const snapshotDir = getSnapshotDir(ctx), versionFile = getVersionFilePath(snapshotDir, storyId);
+  try {
+    const content = await fs.promises.readFile(versionFile, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+export async function saveSnapshotVersion(ctx, storyId, description) {
+  const snapshotDir = getSnapshotDir(ctx), versionFile = getVersionFilePath(snapshotDir, storyId);
+  await fs.promises.mkdir(snapshotDir, { recursive: !0 });
+  let versioned = await loadSnapshotVersions(ctx, storyId);
+  if (!versioned)
+    versioned = {
+      current: { version: 0, timestamp: 0 },
+      history: [],
+      maxVersions: 10
+    };
+  const newVersion = {
+    version: versioned.current.version + 1,
+    timestamp: Date.now(),
+    commit: await getGitCommit(ctx.root),
+    description
+  };
+  if (versioned.current.version > 0) {
+    versioned.history.unshift(versioned.current);
+    if (versioned.history.length > versioned.maxVersions)
+      versioned.history = versioned.history.slice(0, versioned.maxVersions);
+  }
+  versioned.current = newVersion;
+  await fs.promises.writeFile(versionFile, JSON.stringify(versioned, null, 2));
+  return newVersion;
+}
+async function getGitCommit(root) {
+  try {
+    const gitHeadPath = path.join(root, ".git", "HEAD"), head = await fs.promises.readFile(gitHeadPath, "utf-8");
+    if (head.startsWith("ref:")) {
+      const refPath = path.join(root, ".git", head.slice(5).trim());
+      return (await fs.promises.readFile(refPath, "utf-8")).trim().slice(0, 8);
+    }
+    return head.trim().slice(0, 8);
+  } catch {
+    return;
+  }
+}
+export async function restoreSnapshotVersion(ctx, storyId, version) {
+  const versioned = await loadSnapshotVersions(ctx, storyId);
+  if (!versioned)
+    return !1;
+  const targetVersion = versioned.history.find((v) => v.version === version);
+  if (!targetVersion)
+    return !1;
+  const snapshotDir = getSnapshotDir(ctx), versionedPath = path.join(snapshotDir, `${storyId}.v${version}.html`), currentPath = path.join(snapshotDir, `${storyId}.html`);
+  try {
+    await fs.promises.copyFile(versionedPath, currentPath);
+    versioned.current = targetVersion;
+    const versionFile = getVersionFilePath(snapshotDir, storyId);
+    await fs.promises.writeFile(versionFile, JSON.stringify(versioned, null, 2));
+    return !0;
+  } catch {
+    return !1;
+  }
+}
+export function generateTextDiff(oldHtml, newHtml) {
+  const oldLines = oldHtml.split(`
+`), newLines = newHtml.split(`
+`);
+  let changedLines = 0;
+  const maxLines = Math.max(oldLines.length, newLines.length);
+  for (let i = 0;i < maxLines; i++)
+    if (oldLines[i] !== newLines[i])
+      changedLines++;
+  const percentage = maxLines > 0 ? changedLines / maxLines * 100 : 0;
+  return {
+    hasDiff: changedLines > 0,
+    percentage,
+    changedPixels: changedLines,
+    totalPixels: maxLines
+  };
+}
+export function generateDiffHTML(oldHtml, newHtml) {
+  const oldLines = oldHtml.split(`
+`), newLines = newHtml.split(`
+`), diffLines = [], maxLines = Math.max(oldLines.length, newLines.length);
+  for (let i = 0;i < maxLines; i++) {
+    const oldLine = oldLines[i] || "", newLine = newLines[i] || "";
+    if (oldLine === newLine)
+      diffLines.push(`<div class="diff-line diff-same">${escapeHtml(oldLine)}</div>`);
+    else if (!oldLine)
+      diffLines.push(`<div class="diff-line diff-added">+ ${escapeHtml(newLine)}</div>`);
+    else if (!newLine)
+      diffLines.push(`<div class="diff-line diff-removed">- ${escapeHtml(oldLine)}</div>`);
+    else {
+      diffLines.push(`<div class="diff-line diff-removed">- ${escapeHtml(oldLine)}</div>`);
+      diffLines.push(`<div class="diff-line diff-added">+ ${escapeHtml(newLine)}</div>`);
+    }
+  }
+  return `
+    <div class="stx-diff-view">
+      <div class="diff-content">
+        ${diffLines.join(`
+`)}
+      </div>
+    </div>
+  `;
+}
+export function getDiffStyles() {
+  return `
+    .stx-diff-view {
+      font-family: var(--code-font-family);
+      font-size: 12px;
+      line-height: 1.5;
+      overflow: auto;
+    }
+    .diff-content {
+      padding: 12px;
+    }
+    .diff-line {
+      padding: 2px 8px;
+      white-space: pre;
+    }
+    .diff-same {
+      color: var(--text);
+    }
+    .diff-added {
+      background: rgba(34, 197, 94, 0.2);
+      color: #22c55e;
+    }
+    .diff-removed {
+      background: rgba(239, 68, 68, 0.2);
+      color: #ef4444;
+    }
+  `;
+}
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+export async function listSnapshotVersions(ctx, storyId) {
+  const versioned = await loadSnapshotVersions(ctx, storyId);
+  if (!versioned)
+    return [];
+  return [versioned.current, ...versioned.history];
+}
+export async function pruneSnapshotVersions(ctx, storyId, keepCount = 5) {
+  const versioned = await loadSnapshotVersions(ctx, storyId);
+  if (!versioned)
+    return 0;
+  const toDelete = versioned.history.slice(keepCount), snapshotDir = getSnapshotDir(ctx);
+  let deleted = 0;
+  for (const version of toDelete) {
+    const versionPath = path.join(snapshotDir, `${storyId}.v${version.version}.html`);
+    try {
+      await fs.promises.unlink(versionPath);
+      deleted++;
+    } catch {}
+  }
+  versioned.history = versioned.history.slice(0, keepCount);
+  const versionFile = getVersionFilePath(snapshotDir, storyId);
+  await fs.promises.writeFile(versionFile, JSON.stringify(versioned, null, 2));
+  return deleted;
+}

package/dist/story/testing.d.ts

@@ -0,0 +1,83 @@
+/**
+ * STX Story - Visual Regression Testing
+ * Snapshot-based testing for component renders
+ */
+import type { StoryContext } from './types';
+/**
+ * Test options
+ */
+export interface TestOptions {
+    /** Update snapshots instead of comparing */
+    update?: boolean;
+    /** Only test specific components */
+    filter?: string[];
+    /** Threshold for pixel difference (0-1) */
+    threshold?: number;
+    /** Directory to store snapshots */
+    snapshotDir?: string;
+}
+/**
+ * Test result
+ */
+export interface TestResult {
+    /** Total number of tests */
+    total: number;
+    /** Number of passed tests */
+    passed: number;
+    /** Number of failed tests */
+    failed: number;
+    /** Number of new snapshots */
+    new: number;
+    /** Test failures */
+    failures: TestFailure[];
+    /** Duration in milliseconds */
+    duration: number;
+}
+/**
+ * Test failure details
+ */
+export interface TestFailure {
+    /** Story ID */
+    storyId: string;
+    /** Variant ID */
+    variantId: string;
+    /** Component name */
+    component: string;
+    /** Error message */
+    message: string;
+    /** Path to diff image (if applicable) */
+    diffPath?: string;
+    /** Difference percentage */
+    difference?: number;
+}
+/**
+ * Snapshot metadata
+ */
+export interface SnapshotMeta {
+    /** Story ID */
+    storyId: string;
+    /** Variant ID */
+    variantId: string;
+    /** Component name */
+    component: string;
+    /** Timestamp of snapshot creation */
+    timestamp: number;
+    /** Hash of the rendered content */
+    hash: string;
+}
+/**
+ * Run visual regression tests
+ */
+export declare function runVisualTests(ctx: StoryContext, options?: TestOptions): Promise<TestResult>;
+/**
+ * Update all snapshots
+ */
+export declare function updateSnapshots(ctx: StoryContext, options?: TestOptions): Promise<number>;
+/**
+ * Format test results for console output
+ */
+export declare function formatTestResults(result: TestResult): string;
+/**
+ * Run accessibility tests on stories
+ */
+export declare function runA11yTests(ctx: StoryContext, _options?: TestOptions): Promise<TestResult>;

package/dist/story/testing.js

@@ -0,0 +1,164 @@
+import fs from "node:fs";
+import path from "node:path";
+import { checkA11y } from "../a11y.js";
+import { stateDir } from "../state-dir.js";
+export async function runVisualTests(ctx, options = {}) {
+  const startTime = Date.now(), result = {
+    total: 0,
+    passed: 0,
+    failed: 0,
+    new: 0,
+    failures: [],
+    duration: 0
+  }, snapshotDir = options.snapshotDir || stateDir(ctx.root, "story", "snapshots");
+  await fs.promises.mkdir(snapshotDir, { recursive: !0 });
+  let storyFiles = ctx.storyFiles;
+  if (options.filter && options.filter.length > 0)
+    storyFiles = storyFiles.filter((f) => options.filter.some((filter) => f.fileName.toLowerCase().includes(filter.toLowerCase())));
+  for (const storyFile of storyFiles)
+    await testStoryFile(storyFile, snapshotDir, options, result);
+  result.duration = Date.now() - startTime;
+  return result;
+}
+async function testStoryFile(storyFile, snapshotDir, options, result) {
+  const story = storyFile.story;
+  if (!story)
+    return;
+  for (const variant of story.variants) {
+    result.total++;
+    const snapshotPath = path.join(snapshotDir, `${storyFile.id}-${variant.id}.snap`), currentHash = generateHash(variant.source || ""), snapshotExists = await fileExists(snapshotPath);
+    if (options.update || !snapshotExists) {
+      const meta = {
+        storyId: storyFile.id,
+        variantId: variant.id,
+        component: storyFile.fileName,
+        timestamp: Date.now(),
+        hash: currentHash
+      };
+      await fs.promises.writeFile(snapshotPath, JSON.stringify(meta, null, 2));
+      if (!snapshotExists)
+        result.new++;
+      result.passed++;
+    } else
+      try {
+        const snapshotContent = await fs.promises.readFile(snapshotPath, "utf-8"), snapshot = JSON.parse(snapshotContent);
+        if (snapshot.hash === currentHash)
+          result.passed++;
+        else {
+          result.failed++;
+          result.failures.push({
+            storyId: storyFile.id,
+            variantId: variant.id,
+            component: storyFile.fileName,
+            message: "Snapshot mismatch",
+            difference: calculateDifference(snapshot.hash, currentHash)
+          });
+        }
+      } catch (error) {
+        result.failed++;
+        result.failures.push({
+          storyId: storyFile.id,
+          variantId: variant.id,
+          component: storyFile.fileName,
+          message: `Error reading snapshot: ${error}`
+        });
+      }
+  }
+}
+export async function updateSnapshots(ctx, options = {}) {
+  return (await runVisualTests(ctx, { ...options, update: !0 })).total;
+}
+function generateHash(content) {
+  let hash = 0;
+  for (let i = 0;i < content.length; i++) {
+    const char = content.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return hash.toString(16);
+}
+function calculateDifference(hash1, hash2) {
+  if (hash1 === hash2)
+    return 0;
+  const diff = Math.abs(Number.parseInt(hash1, 16) - Number.parseInt(hash2, 16));
+  return Math.min(diff / 1e6, 1);
+}
+async function fileExists(filePath) {
+  try {
+    await fs.promises.access(filePath);
+    return !0;
+  } catch {
+    return !1;
+  }
+}
+export function formatTestResults(result) {
+  const lines = [];
+  lines.push("");
+  lines.push("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+  lines.push("  STX Story Visual Regression Tests");
+  lines.push("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+  lines.push("");
+  if (result.failures.length > 0) {
+    lines.push("  \u274C Failures:");
+    lines.push("");
+    for (const failure of result.failures) {
+      lines.push(`    \u2022 ${failure.component} / ${failure.variantId}`);
+      lines.push(`      ${failure.message}`);
+      if (failure.difference !== void 0)
+        lines.push(`      Difference: ${(failure.difference * 100).toFixed(2)}%`);
+      lines.push("");
+    }
+  }
+  lines.push("  Summary:");
+  lines.push(`    Total:  ${result.total}`);
+  lines.push(`    Passed: ${result.passed} \u2713`);
+  lines.push(`    Failed: ${result.failed} \u2717`);
+  if (result.new > 0)
+    lines.push(`    New:    ${result.new} \u26A1`);
+  lines.push(`    Time:   ${result.duration}ms`);
+  lines.push("");
+  lines.push("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+  lines.push("");
+  return lines.join(`
+`);
+}
+export async function runA11yTests(ctx, _options = {}) {
+  const startTime = performance.now(), failures = [];
+  let passed = 0, failed = 0;
+  for (const storyFile of ctx.storyFiles)
+    try {
+      const htmlContent = await Bun.file(storyFile.path).text(), violations = await checkA11y(htmlContent, storyFile.path);
+      if (violations.length > 0) {
+        for (const violation of violations)
+          failures.push({
+            storyId: storyFile.id,
+            variantId: "default",
+            component: storyFile.component,
+            message: `A11y: ${violation.message}`,
+            expected: "No accessibility violations",
+            actual: `${violation.type}: ${violation.message} (impact: ${violation.impact})`
+          });
+        failed++;
+      } else
+        passed++;
+    } catch (error) {
+      failures.push({
+        storyId: storyFile.id,
+        variantId: "default",
+        component: storyFile.component,
+        message: `Failed to check a11y: ${error instanceof Error ? error.message : String(error)}`,
+        expected: "File readable for a11y check",
+        actual: "File read error"
+      });
+      failed++;
+    }
+  const duration = performance.now() - startTime;
+  return {
+    total: ctx.storyFiles.length,
+    passed,
+    failed,
+    new: 0,
+    failures,
+    duration
+  };
+}

package/dist/story/theme.d.ts

@@ -0,0 +1,68 @@
+import type { StoryContext } from './types';
+/**
+ * Get current theme
+ */
+export declare function getCurrentTheme(): ThemeConfig;
+/**
+ * Check if dark mode is active
+ */
+export declare function isDark(): boolean;
+/**
+ * Toggle dark mode
+ */
+export declare function toggleDarkMode(): void;
+/**
+ * Set theme
+ */
+export declare function setTheme(theme: Partial<ThemeConfig>): void;
+/**
+ * Initialize theme from context
+ */
+export declare function initializeTheme(ctx: StoryContext): void;
+/**
+ * Generate CSS variables from theme
+ */
+export declare function generateThemeCSS(theme?: ThemeConfig): string;
+/**
+ * Generate theme toggle button HTML
+ */
+export declare function generateThemeToggle(): string;
+/**
+ * Get theme toggle script
+ */
+export declare function getThemeToggleScript(): string;
+/**
+ * Export theme tokens to JSON
+ */
+export declare function exportThemeTokensJSON(theme?: ThemeConfig): string;
+/**
+ * Export theme tokens to CSS custom properties
+ */
+export declare function exportThemeTokensCSS(theme?: ThemeConfig): string;
+/**
+ * Get theme styles
+ */
+export declare function getThemeStyles(): string;
+/**
+ * Default light theme
+ */
+export declare const lightTheme: ThemeConfig;
+/**
+ * Default dark theme
+ */
+export declare const darkTheme: ThemeConfig;
+/**
+ * Theme configuration
+ */
+export declare interface ThemeConfig {
+  colorScheme: 'light' | 'dark' | 'auto'
+  primaryColor: string
+  backgroundColor: string
+  textColor: string
+  borderColor: string
+  secondaryBackground: string
+  secondaryText: string
+  fontFamily: string
+  codeFontFamily: string
+  borderRadius: string
+}