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

package/dist/story/bookmarks.js

@@ -0,0 +1,277 @@
+import fs from "node:fs";
+import path from "node:path";
+const BOOKMARKS_FILE = ".stx/story/bookmarks.json", STORAGE_VERSION = 1;
+
+export class BookmarksManager {
+  storage;
+  storagePath;
+  dirty = !1;
+  constructor(rootDir) {
+    this.storagePath = path.join(rootDir, BOOKMARKS_FILE);
+    this.storage = this.loadStorage();
+  }
+  loadStorage() {
+    try {
+      const content = fs.readFileSync(this.storagePath, "utf-8");
+      return JSON.parse(content);
+    } catch {
+      return { version: STORAGE_VERSION, bookmarks: [] };
+    }
+  }
+  async save() {
+    if (!this.dirty)
+      return;
+    const dir = path.dirname(this.storagePath);
+    await fs.promises.mkdir(dir, { recursive: !0 });
+    await fs.promises.writeFile(this.storagePath, JSON.stringify(this.storage, null, 2));
+    this.dirty = !1;
+  }
+  addBookmark(storyId, variantId, props, options = {}) {
+    const bookmark = {
+      id: generateId(),
+      name: options.name || `${storyId}/${variantId}`,
+      storyId,
+      variantId,
+      props,
+      created: Date.now(),
+      notes: options.notes,
+      color: options.color
+    };
+    this.storage.bookmarks.push(bookmark);
+    this.dirty = !0;
+    return bookmark;
+  }
+  getAllBookmarks() {
+    return [...this.storage.bookmarks];
+  }
+  getBookmarksForStory(storyId) {
+    return this.storage.bookmarks.filter((b) => b.storyId === storyId);
+  }
+  getBookmark(id) {
+    return this.storage.bookmarks.find((b) => b.id === id);
+  }
+  isBookmarked(storyId, variantId) {
+    return this.storage.bookmarks.some((b) => b.storyId === storyId && b.variantId === variantId);
+  }
+  updateBookmark(id, updates) {
+    const bookmark = this.getBookmark(id);
+    if (!bookmark)
+      return;
+    Object.assign(bookmark, updates);
+    this.dirty = !0;
+    return bookmark;
+  }
+  deleteBookmark(id) {
+    const index = this.storage.bookmarks.findIndex((b) => b.id === id);
+    if (index === -1)
+      return !1;
+    this.storage.bookmarks.splice(index, 1);
+    this.dirty = !0;
+    return !0;
+  }
+  toggleBookmark(storyId, variantId, props) {
+    const existing = this.storage.bookmarks.find((b) => b.storyId === storyId && b.variantId === variantId);
+    if (existing) {
+      this.deleteBookmark(existing.id);
+      return { added: !1 };
+    }
+    return { added: !0, bookmark: this.addBookmark(storyId, variantId, props) };
+  }
+  exportBookmarks() {
+    return JSON.stringify(this.storage, null, 2);
+  }
+  importBookmarks(json, merge = !0) {
+    const data = JSON.parse(json);
+    let imported = 0;
+    for (const bookmark of data.bookmarks) {
+      if (merge) {
+        const existing = this.storage.bookmarks.find((b) => b.id === bookmark.id);
+        if (existing)
+          Object.assign(existing, bookmark);
+        else
+          this.storage.bookmarks.push(bookmark);
+      } else
+        this.storage.bookmarks.push(bookmark);
+      imported++;
+    }
+    if (imported > 0)
+      this.dirty = !0;
+    return imported;
+  }
+}
+function generateId() {
+  return `bm-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export function getBookmarksPanelHtml(bookmarks) {
+  return `
+    <div class="bookmarks-panel">
+      <div class="bookmarks-header">
+        <h3>\uD83D\uDCD1 Bookmarks</h3>
+        <button onclick="addCurrentBookmark()" title="Bookmark current">+</button>
+      </div>
+      <div class="bookmarks-list">
+        ${bookmarks.map((b) => `
+    <div class="bookmark-item" data-bookmark-id="${b.id}" style="${b.color ? `border-left: 3px solid ${b.color}` : ""}">
+      <div class="bookmark-info">
+        <div class="bookmark-name">${b.name}</div>
+        <div class="bookmark-path">${b.storyId} / ${b.variantId}</div>
+        ${b.notes ? `<div class="bookmark-notes">${b.notes}</div>` : ""}
+      </div>
+      <div class="bookmark-actions">
+        <button onclick="loadBookmark('${b.id}')" title="Load">\u25B6</button>
+        <button onclick="deleteBookmark('${b.id}')" title="Delete">\xD7</button>
+      </div>
+    </div>
+  `).join("") || '<div class="bookmarks-empty">No bookmarks yet</div>'}
+      </div>
+    </div>
+  `;
+}
+export function getBookmarksPanelStyles() {
+  return `
+    .bookmarks-panel {
+      padding: 12px;
+      background: var(--bg-secondary);
+      border-radius: 8px;
+    }
+    .bookmarks-header {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      margin-bottom: 12px;
+    }
+    .bookmarks-header h3 {
+      margin: 0;
+      font-size: 14px;
+    }
+    .bookmarks-header button {
+      padding: 4px 8px;
+      background: var(--primary);
+      color: white;
+      border: none;
+      border-radius: 4px;
+      cursor: pointer;
+    }
+    .bookmarks-list {
+      display: flex;
+      flex-direction: column;
+      gap: 8px;
+      max-height: 300px;
+      overflow-y: auto;
+    }
+    .bookmark-item {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      padding: 8px;
+      background: var(--bg);
+      border-radius: 4px;
+      border: 1px solid var(--border);
+    }
+    .bookmark-name {
+      font-weight: 500;
+      font-size: 13px;
+    }
+    .bookmark-path {
+      font-size: 11px;
+      color: var(--text-secondary);
+    }
+    .bookmark-notes {
+      font-size: 11px;
+      color: var(--text-secondary);
+      font-style: italic;
+      margin-top: 4px;
+    }
+    .bookmark-actions {
+      display: flex;
+      gap: 4px;
+    }
+    .bookmark-actions button {
+      padding: 4px 8px;
+      background: transparent;
+      border: 1px solid var(--border);
+      border-radius: 4px;
+      cursor: pointer;
+      font-size: 12px;
+    }
+    .bookmark-actions button:hover {
+      background: var(--bg-secondary);
+    }
+    .bookmarks-empty {
+      text-align: center;
+      color: var(--text-secondary);
+      font-size: 13px;
+      padding: 20px;
+    }
+  `;
+}
+export function getBookmarksScript() {
+  return `
+<script>
+window.__stxBookmarks = {
+  async loadBookmark(id) {
+    const response = await fetch('/api/bookmarks/' + id);
+    const bookmark = await response.json();
+
+    if (bookmark) {
+      window.__stxHotSwap?.selectVariant(bookmark.storyId, bookmark.variantId);
+      if (bookmark.props) {
+        window.dispatchEvent(new CustomEvent('stx:props-change', {
+          detail: { props: bookmark.props }
+        }));
+      }
+    }
+  },
+
+  async addCurrentBookmark() {
+    const name = prompt('Bookmark name:');
+    if (!name) return;
+
+    const storyId = window.__stxHotSwap?.storyId;
+    const variantId = window.__stxHotSwap?.variantId;
+    const props = window.__stxProps || {};
+
+    if (!storyId || !variantId) {
+      alert('No story selected');
+      return;
+    }
+
+    await fetch('/api/bookmarks', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name, storyId, variantId, props })
+    });
+
+    window.__stxStory?.refreshBookmarks?.();
+  },
+
+  async deleteBookmark(id) {
+    if (!confirm('Delete this bookmark?')) return;
+
+    await fetch('/api/bookmarks/' + id, { method: 'DELETE' });
+    window.__stxStory?.refreshBookmarks?.();
+  },
+
+  async toggleCurrent() {
+    const storyId = window.__stxHotSwap?.storyId;
+    const variantId = window.__stxHotSwap?.variantId;
+    const props = window.__stxProps || {};
+
+    if (!storyId || !variantId) return;
+
+    await fetch('/api/bookmarks/toggle', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ storyId, variantId, props })
+    });
+
+    window.__stxStory?.refreshBookmarks?.();
+  }
+};
+
+window.loadBookmark = window.__stxBookmarks.loadBookmark.bind(window.__stxBookmarks);
+window.addCurrentBookmark = window.__stxBookmarks.addCurrentBookmark.bind(window.__stxBookmarks);
+window.deleteBookmark = window.__stxBookmarks.deleteBookmark.bind(window.__stxBookmarks);
+</script>
+`;
+}

package/dist/story/bun-test.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Create a Bun test suite for stories
+ * Usage in test file:
+ *
+ * ```typescript
+ * import { createStoryTestSuite } from '@stacksjs/stx/story'
+ *
+ * createStoryTestSuite({
+ *   filter: ['Button', 'Card'],
+ *   threshold: 0.01,
+ * })
+ * ```
+ */
+export declare function createStoryTestSuite(options?: BunTestOptions): Promise<void>;
+/**
+ * Create individual test cases for each story
+ */
+export declare function createStoryTests(options?: BunTestOptions): Promise<void>;
+/**
+ * Run story tests programmatically
+ */
+// eslint-disable-next-line pickier/no-unused-vars
+export declare function runStoryTests(options?: BunTestOptions): Promise<{
+  passed: number
+  failed: number
+  total: number
+  duration: number
+}>;
+/**
+ * Generate test file content for stories
+ */
+export declare function generateTestFile(storyNames: string[]): string;
+/**
+ * Watch mode for story tests
+ */
+export declare function watchStoryTests(options?: BunTestOptions): Promise<void>;
+/**
+ * Test options for Bun integration
+ */
+export declare interface BunTestOptions {
+  filter?: string[]
+  update?: boolean
+  threshold?: number
+  timeout?: number
+}

package/dist/story/bun-test.js

@@ -0,0 +1,102 @@
+import { createContext } from "./context.js";
+import { runVisualTests } from "./testing.js";
+export async function createStoryTestSuite(options = {}) {
+  const { describe, test, expect } = await import("bun:test"), ctx = await createContext({ mode: "build" });
+  describe("STX Story Visual Tests", () => {
+    test("should pass visual regression tests", async () => {
+      const results = await runVisualTests(ctx, {
+        filter: options.filter,
+        threshold: options.threshold,
+        update: options.update
+      });
+      console.log(`
+Visual Tests: ${results.passed}/${results.total} passed`);
+      if (results.failed > 0) {
+        console.log(`
+Failed tests:`);
+        for (const failure of results.failures) {
+          console.log(`  \u2717 ${failure.storyId} - ${failure.variantId}`);
+          console.log(`    Difference: ${(failure.difference ?? 0).toFixed(2)}%`);
+        }
+      }
+      expect(results.failed).toBe(0);
+    }, options.timeout || 30000);
+  });
+}
+export async function createStoryTests(options = {}) {
+  const { describe, test, expect } = await import("bun:test"), ctx = await createContext({ mode: "build" }), { scanStoryFiles } = await import("./collect/scanner.js"), storyFiles = await scanStoryFiles(ctx);
+  describe("STX Stories", () => {
+    for (const storyFile of storyFiles) {
+      if (options.filter && options.filter.length > 0) {
+        if (!options.filter.some((f) => storyFile.fileName.toLowerCase().includes(f.toLowerCase())))
+          continue;
+      }
+      describe(storyFile.fileName, () => {
+        test("should render without errors", async () => {
+          const content = await Bun.file(storyFile.path).text();
+          expect(content).toBeTruthy();
+          expect(content.length).toBeGreaterThan(0);
+        });
+        if (storyFile.story)
+          for (const variant of storyFile.story.variants)
+            test(`variant: ${variant.title}`, async () => {
+              expect(variant.title).toBeTruthy();
+              if (variant.source)
+                expect(variant.source.length).toBeGreaterThan(0);
+            });
+      });
+    }
+  });
+}
+export async function runStoryTests(options = {}) {
+  const startTime = Date.now(), ctx = await createContext({ mode: "build" }), results = await runVisualTests(ctx, {
+    filter: options.filter,
+    threshold: options.threshold,
+    update: options.update
+  });
+  return {
+    passed: results.passed,
+    failed: results.failed,
+    total: results.total,
+    duration: Date.now() - startTime
+  };
+}
+export function generateTestFile(storyNames) {
+  return `/**
+ * Auto-generated story tests
+ * Run with: bun test
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { createContext } from '@stacksjs/stx/story'
+import { runVisualTests } from '@stacksjs/stx/story'
+
+${storyNames.map((name) => `import './${name}.story.stx'`).join(`
+`)}
+
+describe('Story Visual Tests', () => {
+  test('all stories pass visual regression', async () => {
+    const ctx = await createContext({ mode: 'build' })
+    const results = await runVisualTests(ctx)
+
+    expect(results.failed).toBe(0)
+  })
+})
+`;
+}
+export async function watchStoryTests(options = {}) {
+  const { watchStoryFiles } = await import("./collect/scanner.js"), ctx = await createContext({ mode: "dev" });
+  console.log("Watching for story changes...");
+  watchStoryFiles(ctx, async (event, file) => {
+    console.log(`
+${event}: ${file}`);
+    console.log("Running tests...");
+    const results = await runStoryTests(options);
+    if (results.failed > 0)
+      console.log(`
+\u274C ${results.failed} test(s) failed`);
+    else
+      console.log(`
+\u2713 All ${results.total} tests passed (${results.duration}ms)`);
+  });
+}

package/dist/story/cli.d.ts

@@ -0,0 +1,132 @@
+/**
+ * STX Story - CLI Integration
+ * Provides CLI commands for the story feature
+ */
+/**
+ * CLI command definitions for integration with @stacksjs/clapp
+ */
+export declare const storyCommands: {
+    /**
+     * Main story command (defaults to dev)
+     */
+    story: {
+        description: string;
+        options: {
+            port: {
+                alias: string;
+                type: 'number';
+                description: string;
+            };
+            open: {
+                alias: string;
+                type: 'boolean';
+                description: string;
+            };
+            host: {
+                type: 'string';
+                description: string;
+            };
+        };
+        action: (options: {
+            port?: number;
+            open?: boolean;
+            host?: string;
+        }) => Promise<void>;
+    };
+    /**
+     * Story dev subcommand
+     */
+    'story:dev': {
+        description: string;
+        options: {
+            port: {
+                alias: string;
+                type: 'number';
+                description: string;
+            };
+            open: {
+                alias: string;
+                type: 'boolean';
+                description: string;
+            };
+            host: {
+                type: 'string';
+                description: string;
+            };
+        };
+        action: (options: {
+            port?: number;
+            open?: boolean;
+            host?: string;
+        }) => Promise<void>;
+    };
+    /**
+     * Story build subcommand
+     */
+    'story:build': {
+        description: string;
+        options: {
+            outDir: {
+                alias: string;
+                type: 'string';
+                description: string;
+            };
+        };
+        action: (options: {
+            outDir?: string;
+        }) => Promise<void>;
+    };
+    /**
+     * Story preview subcommand
+     */
+    'story:preview': {
+        description: string;
+        options: {
+            port: {
+                alias: string;
+                type: 'number';
+                description: string;
+            };
+            open: {
+                alias: string;
+                type: 'boolean';
+                description: string;
+            };
+        };
+        action: (options: {
+            port?: number;
+            open?: boolean;
+        }) => Promise<void>;
+    };
+    /**
+     * Story test subcommand
+     */
+    'story:test': {
+        description: string;
+        options: {
+            update: {
+                alias: string;
+                type: 'boolean';
+                description: string;
+            };
+            filter: {
+                alias: string;
+                type: 'string';
+                description: string;
+            };
+        };
+        action: (options: {
+            update?: boolean;
+            filter?: string;
+        }) => Promise<void>;
+    };
+};
+/**
+ * Register story commands with a CLI instance
+ * This is a helper for manual CLI integration
+ */
+export declare function registerStoryCommands(cli: any): void;
+/**
+ * Run story CLI directly (for standalone usage)
+ */
+export declare function runStoryCLI(args?: string[]): Promise<void>;

package/dist/story/cli.js

@@ -0,0 +1,155 @@
+import { buildCommand } from "./commands/build.js";
+import { devCommand } from "./commands/dev.js";
+import { previewCommand } from "./commands/preview.js";
+export const storyCommands = {
+  story: {
+    description: "Component showcase and testing",
+    options: {
+      port: {
+        alias: "p",
+        type: "number",
+        description: "Server port (default: 6006)"
+      },
+      open: {
+        alias: "o",
+        type: "boolean",
+        description: "Open browser automatically"
+      },
+      host: {
+        type: "string",
+        description: "Host to bind to"
+      }
+    },
+    action: async (options) => {
+      await devCommand(options);
+    }
+  },
+  "story:dev": {
+    description: "Start story development server",
+    options: {
+      port: {
+        alias: "p",
+        type: "number",
+        description: "Server port (default: 6006)"
+      },
+      open: {
+        alias: "o",
+        type: "boolean",
+        description: "Open browser automatically"
+      },
+      host: {
+        type: "string",
+        description: "Host to bind to"
+      }
+    },
+    action: async (options) => {
+      await devCommand(options);
+    }
+  },
+  "story:build": {
+    description: "Build static story site",
+    options: {
+      outDir: {
+        alias: "o",
+        type: "string",
+        description: "Output directory"
+      }
+    },
+    action: async (options) => {
+      await buildCommand(options);
+    }
+  },
+  "story:preview": {
+    description: "Preview built story site",
+    options: {
+      port: {
+        alias: "p",
+        type: "number",
+        description: "Server port (default: 4173)"
+      },
+      open: {
+        alias: "o",
+        type: "boolean",
+        description: "Open browser automatically"
+      }
+    },
+    action: async (options) => {
+      await previewCommand(options);
+    }
+  },
+  "story:test": {
+    description: "Run visual regression tests",
+    options: {
+      update: {
+        alias: "u",
+        type: "boolean",
+        description: "Update snapshots"
+      },
+      filter: {
+        alias: "f",
+        type: "string",
+        description: "Filter components by name"
+      }
+    },
+    action: async (options) => {
+      const { createContext } = await import("./context.js"), { runVisualTests, updateSnapshots, formatTestResults } = await import("./testing.js"), ctx = await createContext({ mode: "build" });
+      if (options.update) {
+        const count = await updateSnapshots(ctx, {
+          filter: options.filter ? [options.filter] : void 0
+        });
+        console.log(`Updated ${count} snapshots`);
+      } else {
+        const result = await runVisualTests(ctx, {
+          filter: options.filter ? [options.filter] : void 0
+        });
+        console.log(formatTestResults(result));
+        if (result.failed > 0)
+          process.exit(1);
+      }
+    }
+  }
+};
+export function registerStoryCommands(cli) {
+  cli.command("story", storyCommands.story.description).option("-p, --port <port>", storyCommands.story.options.port.description).option("-o, --open", storyCommands.story.options.open.description).option("--host <host>", storyCommands.story.options.host.description).action(storyCommands.story.action);
+  cli.command("story dev", storyCommands["story:dev"].description).option("-p, --port <port>", storyCommands["story:dev"].options.port.description).option("-o, --open", storyCommands["story:dev"].options.open.description).option("--host <host>", storyCommands["story:dev"].options.host.description).action(storyCommands["story:dev"].action);
+  cli.command("story build", storyCommands["story:build"].description).option("-o, --outDir <dir>", storyCommands["story:build"].options.outDir.description).action(storyCommands["story:build"].action);
+  cli.command("story preview", storyCommands["story:preview"].description).option("-p, --port <port>", storyCommands["story:preview"].options.port.description).option("-o, --open", storyCommands["story:preview"].options.open.description).action(storyCommands["story:preview"].action);
+  cli.command("story test", storyCommands["story:test"].description).option("-u, --update", storyCommands["story:test"].options.update.description).option("-f, --filter <name>", storyCommands["story:test"].options.filter.description).action(storyCommands["story:test"].action);
+}
+export async function runStoryCLI(args = process.argv.slice(2)) {
+  const command = args[0] || "dev", options = {};
+  for (let i = 1;i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-p" || arg === "--port")
+      options.port = Number.parseInt(args[++i], 10);
+    else if (arg === "-o" || arg === "--open")
+      options.open = !0;
+    else if (arg === "--host")
+      options.host = args[++i];
+    else if (arg === "-u" || arg === "--update")
+      options.update = !0;
+    else if (arg === "-f" || arg === "--filter")
+      options.filter = args[++i];
+    else if (arg === "--outDir")
+      options.outDir = args[++i];
+  }
+  switch (command) {
+    case "dev":
+    case "":
+      await devCommand(options);
+      break;
+    case "build":
+      await buildCommand(options);
+      break;
+    case "preview":
+      await previewCommand(options);
+      break;
+    case "test":
+      await storyCommands["story:test"].action(options);
+      break;
+    default:
+      console.log("Unknown command:", command);
+      console.log("Available commands: dev, build, preview, test");
+      process.exit(1);
+  }
+}