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

package/dist/story/analytics.d.ts

@@ -0,0 +1,163 @@
+/**
+ * STX Story - Component Usage Analytics
+ * Track which components are viewed most, which props are changed most
+ */
+/**
+ * Analytics event types
+ */
+export type AnalyticsEventType = 'view' | 'prop_change' | 'variant_switch' | 'search' | 'bookmark' | 'copy_code' | 'test_run';
+/**
+ * Analytics event
+ */
+export interface AnalyticsEvent {
+    /** Event type */
+    type: AnalyticsEventType;
+    /** Timestamp */
+    timestamp: number;
+    /** Component ID */
+    componentId?: string;
+    /** Variant ID */
+    variantId?: string;
+    /** Prop name (for prop_change) */
+    propName?: string;
+    /** Search query (for search) */
+    query?: string;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Component analytics summary
+ */
+export interface ComponentAnalytics {
+    /** Component ID */
+    componentId: string;
+    /** Component name */
+    componentName: string;
+    /** Total views */
+    viewCount: number;
+    /** Unique view sessions */
+    uniqueViews: number;
+    /** Last viewed timestamp */
+    lastViewed?: number;
+    /** Prop change counts */
+    propChanges: Record<string, number>;
+    /** Most changed props */
+    topChangedProps: string[];
+    /** Variant view counts */
+    variantViews: Record<string, number>;
+    /** Average time spent (ms) */
+    avgTimeSpent: number;
+}
+/**
+ * Analytics storage
+ */
+export interface AnalyticsStorage {
+    version: number;
+    events: AnalyticsEvent[];
+    sessions: AnalyticsSession[];
+}
+/**
+ * Analytics session
+ */
+export interface AnalyticsSession {
+    id: string;
+    startTime: number;
+    endTime?: number;
+    componentViews: string[];
+}
+/**
+ * Analytics tracker
+ */
+export declare class AnalyticsTracker {
+    private storage;
+    private storagePath;
+    private currentSession;
+    private dirty;
+    private viewStartTimes;
+    constructor(rootDir: string);
+    private loadStorage;
+    save(): Promise<void>;
+    /**
+     * Start a new session
+     */
+    startSession(): void;
+    /**
+     * End current session
+     */
+    endSession(): void;
+    /**
+     * Track an event
+     */
+    track(event: Omit<AnalyticsEvent, 'timestamp'>): void;
+    /**
+     * Track component view
+     */
+    trackView(componentId: string, variantId?: string): void;
+    /**
+     * End view timing for a component
+     */
+    private endViewTiming;
+    /**
+     * Track prop change
+     */
+    trackPropChange(componentId: string, propName: string, value: any): void;
+    /**
+     * Track variant switch
+     */
+    trackVariantSwitch(componentId: string, variantId: string): void;
+    /**
+     * Track search
+     */
+    trackSearch(query: string, resultCount: number): void;
+    /**
+     * Get analytics for a component
+     */
+    getComponentAnalytics(componentId: string, componentName: string): ComponentAnalytics;
+    /**
+     * Get most viewed components
+     */
+    getMostViewedComponents(limit?: number): Array<{
+        componentId: string;
+        viewCount: number;
+    }>;
+    /**
+     * Get most changed props across all components
+     */
+    getMostChangedProps(limit?: number): Array<{
+        propName: string;
+        changeCount: number;
+    }>;
+    /**
+     * Get search analytics
+     */
+    getSearchAnalytics(): {
+        totalSearches: number;
+        topQueries: Array<{
+            query: string;
+            count: number;
+        }>;
+        avgResultCount: number;
+    };
+    /**
+     * Clear all analytics
+     */
+    clear(): void;
+    /**
+     * Export analytics as JSON
+     */
+    exportAnalytics(): string;
+}
+/**
+ * Generate analytics dashboard HTML
+ */
+export declare function getAnalyticsDashboardHtml(mostViewed: Array<{
+    componentId: string;
+    viewCount: number;
+}>, mostChangedProps: Array<{
+    propName: string;
+    changeCount: number;
+}>): string;
+/**
+ * Generate analytics styles
+ */
+export declare function getAnalyticsStyles(): string;

package/dist/story/analytics.js

@@ -0,0 +1,235 @@
+import fs from "node:fs";
+import path from "node:path";
+const ANALYTICS_FILE = ".stx/story/analytics.json", STORAGE_VERSION = 1, MAX_EVENTS = 1e4;
+
+export class AnalyticsTracker {
+  storage;
+  storagePath;
+  currentSession = null;
+  dirty = !1;
+  viewStartTimes = new Map;
+  constructor(rootDir) {
+    this.storagePath = path.join(rootDir, ANALYTICS_FILE);
+    this.storage = this.loadStorage();
+    this.startSession();
+  }
+  loadStorage() {
+    try {
+      const content = fs.readFileSync(this.storagePath, "utf-8");
+      return JSON.parse(content);
+    } catch {
+      return { version: STORAGE_VERSION, events: [], sessions: [] };
+    }
+  }
+  async save() {
+    if (!this.dirty)
+      return;
+    const dir = path.dirname(this.storagePath);
+    await fs.promises.mkdir(dir, { recursive: !0 });
+    if (this.storage.events.length > MAX_EVENTS)
+      this.storage.events = this.storage.events.slice(-MAX_EVENTS);
+    await fs.promises.writeFile(this.storagePath, JSON.stringify(this.storage, null, 2));
+    this.dirty = !1;
+  }
+  startSession() {
+    this.endSession();
+    this.currentSession = {
+      id: generateId(),
+      startTime: Date.now(),
+      componentViews: []
+    };
+    this.storage.sessions.push(this.currentSession);
+    this.dirty = !0;
+  }
+  endSession() {
+    if (this.currentSession) {
+      this.currentSession.endTime = Date.now();
+      this.currentSession = null;
+    }
+  }
+  track(event) {
+    this.storage.events.push({
+      ...event,
+      timestamp: Date.now()
+    });
+    this.dirty = !0;
+  }
+  trackView(componentId, variantId) {
+    this.endViewTiming(componentId);
+    this.viewStartTimes.set(componentId, Date.now());
+    this.track({
+      type: "view",
+      componentId,
+      variantId
+    });
+    if (this.currentSession && !this.currentSession.componentViews.includes(componentId))
+      this.currentSession.componentViews.push(componentId);
+  }
+  endViewTiming(componentId) {
+    const startTime = this.viewStartTimes.get(componentId);
+    if (startTime) {
+      const duration = Date.now() - startTime;
+      this.track({
+        type: "view",
+        componentId,
+        metadata: { duration, endView: !0 }
+      });
+      this.viewStartTimes.delete(componentId);
+    }
+  }
+  trackPropChange(componentId, propName, value) {
+    this.track({
+      type: "prop_change",
+      componentId,
+      propName,
+      metadata: { value }
+    });
+  }
+  trackVariantSwitch(componentId, variantId) {
+    this.track({
+      type: "variant_switch",
+      componentId,
+      variantId
+    });
+  }
+  trackSearch(query, resultCount) {
+    this.track({
+      type: "search",
+      query,
+      metadata: { resultCount }
+    });
+  }
+  getComponentAnalytics(componentId, componentName) {
+    const events = this.storage.events.filter((e) => e.componentId === componentId), viewEvents = events.filter((e) => e.type === "view" && !e.metadata?.endView), propChangeEvents = events.filter((e) => e.type === "prop_change"), variantEvents = events.filter((e) => e.type === "variant_switch"), propChanges = {};
+    for (const event of propChangeEvents)
+      if (event.propName)
+        propChanges[event.propName] = (propChanges[event.propName] || 0) + 1;
+    const variantViews = {};
+    for (const event of variantEvents)
+      if (event.variantId)
+        variantViews[event.variantId] = (variantViews[event.variantId] || 0) + 1;
+    const sessionsWithView = new Set(this.storage.sessions.filter((s) => s.componentViews.includes(componentId)).map((s) => s.id)), durations = events.filter((e) => e.metadata?.duration).map((e) => e.metadata.duration), avgTimeSpent = durations.length > 0 ? durations.reduce((a, b) => a + b, 0) / durations.length : 0, topChangedProps = Object.entries(propChanges).sort((a, b) => b[1] - a[1]).slice(0, 5).map(([name]) => name);
+    return {
+      componentId,
+      componentName,
+      viewCount: viewEvents.length,
+      uniqueViews: sessionsWithView.size,
+      lastViewed: viewEvents[viewEvents.length - 1]?.timestamp,
+      propChanges,
+      topChangedProps,
+      variantViews,
+      avgTimeSpent
+    };
+  }
+  getMostViewedComponents(limit = 10) {
+    const viewCounts = new Map;
+    for (const event of this.storage.events)
+      if (event.type === "view" && event.componentId && !event.metadata?.endView)
+        viewCounts.set(event.componentId, (viewCounts.get(event.componentId) || 0) + 1);
+    return Array.from(viewCounts.entries()).map(([componentId, viewCount]) => ({ componentId, viewCount })).sort((a, b) => b.viewCount - a.viewCount).slice(0, limit);
+  }
+  getMostChangedProps(limit = 10) {
+    const propCounts = new Map;
+    for (const event of this.storage.events)
+      if (event.type === "prop_change" && event.propName)
+        propCounts.set(event.propName, (propCounts.get(event.propName) || 0) + 1);
+    return Array.from(propCounts.entries()).map(([propName, changeCount]) => ({ propName, changeCount })).sort((a, b) => b.changeCount - a.changeCount).slice(0, limit);
+  }
+  getSearchAnalytics() {
+    const searchEvents = this.storage.events.filter((e) => e.type === "search"), queryCounts = new Map;
+    let totalResults = 0;
+    for (const event of searchEvents) {
+      if (event.query)
+        queryCounts.set(event.query, (queryCounts.get(event.query) || 0) + 1);
+      if (event.metadata?.resultCount !== void 0)
+        totalResults += event.metadata.resultCount;
+    }
+    const topQueries = Array.from(queryCounts.entries()).map(([query, count]) => ({ query, count })).sort((a, b) => b.count - a.count).slice(0, 10);
+    return {
+      totalSearches: searchEvents.length,
+      topQueries,
+      avgResultCount: searchEvents.length > 0 ? totalResults / searchEvents.length : 0
+    };
+  }
+  clear() {
+    this.storage.events = [];
+    this.storage.sessions = [];
+    this.dirty = !0;
+    this.startSession();
+  }
+  exportAnalytics() {
+    return JSON.stringify({
+      exportedAt: Date.now(),
+      ...this.storage
+    }, null, 2);
+  }
+}
+function generateId() {
+  return `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export function getAnalyticsDashboardHtml(mostViewed, mostChangedProps) {
+  const viewedRows = mostViewed.map((c) => `
+    <tr>
+      <td>${c.componentId}</td>
+      <td>${c.viewCount}</td>
+    </tr>
+  `).join(""), propsRows = mostChangedProps.map((p) => `
+    <tr>
+      <td>${p.propName}</td>
+      <td>${p.changeCount}</td>
+    </tr>
+  `).join("");
+  return `
+    <div class="analytics-dashboard">
+      <h3>\uD83D\uDCCA Usage Analytics</h3>
+
+      <div class="analytics-section">
+        <h4>Most Viewed Components</h4>
+        <table>
+          <thead><tr><th>Component</th><th>Views</th></tr></thead>
+          <tbody>${viewedRows || '<tr><td colspan="2">No data</td></tr>'}</tbody>
+        </table>
+      </div>
+
+      <div class="analytics-section">
+        <h4>Most Changed Props</h4>
+        <table>
+          <thead><tr><th>Prop</th><th>Changes</th></tr></thead>
+          <tbody>${propsRows || '<tr><td colspan="2">No data</td></tr>'}</tbody>
+        </table>
+      </div>
+    </div>
+  `;
+}
+export function getAnalyticsStyles() {
+  return `
+    .analytics-dashboard {
+      padding: 16px;
+      background: var(--bg-secondary);
+      border-radius: 8px;
+    }
+    .analytics-dashboard h3 {
+      margin: 0 0 16px;
+      font-size: 14px;
+    }
+    .analytics-section {
+      margin-bottom: 16px;
+    }
+    .analytics-section h4 {
+      margin: 0 0 8px;
+      font-size: 12px;
+      color: var(--text-secondary);
+    }
+    .analytics-dashboard table {
+      width: 100%;
+      border-collapse: collapse;
+      font-size: 12px;
+    }
+    .analytics-dashboard th,
+    .analytics-dashboard td {
+      padding: 6px 8px;
+      text-align: left;
+      border-bottom: 1px solid var(--border);
+    }
+  `;
+}

package/dist/story/auto-stories.d.ts

@@ -0,0 +1,38 @@
+import type { AnalyzedComponent } from './types';
+/**
+ * Auto-generate stories for components
+ */
+export declare function autoGenerateStories(options: AutoGenerateOptions): Promise<GeneratedStory[]>;
+/**
+ * Generate story content for a component
+ */
+export declare function generateStoryContent(analysis: AnalyzedComponent, options?: { generateVariants?: boolean, includeDefaults?: boolean }): string;
+/**
+ * Generate story for a single component
+ */
+export declare function generateStoryForComponent(componentPath: string, options?: { generateVariants?: boolean, includeDefaults?: boolean }): Promise<string>;
+/**
+ * CLI command for auto-generating stories
+ */
+export declare function autoGenerateCommand(args: string[]): Promise<void>;
+/**
+ * Auto-generation options
+ */
+export declare interface AutoGenerateOptions {
+  componentsDir: string
+  outputDir?: string
+  include?: string[]
+  exclude?: string[]
+  generateVariants?: boolean
+  includeDefaults?: boolean
+  overwrite?: boolean
+}
+/**
+ * Generated story result
+ */
+export declare interface GeneratedStory {
+  componentPath: string
+  storyPath: string
+  content: string
+  status: 'created' | 'skipped' | 'updated'
+}

package/dist/story/auto-stories.js

@@ -0,0 +1,158 @@
+import fs from "node:fs";
+import path from "node:path";
+import { analyzeComponentFile } from "./collect/analyzer.js";
+export async function autoGenerateStories(options) {
+  const {
+    componentsDir,
+    outputDir = componentsDir,
+    include = ["**/*.stx"],
+    exclude = ["**/*.story.stx", "**/node_modules/**"],
+    generateVariants = !0,
+    includeDefaults = !0,
+    overwrite = !1
+  } = options, results = [], componentFiles = await findComponentFiles(componentsDir, include, exclude);
+  for (const componentPath of componentFiles) {
+    const storyPath = componentPath.replace(/\.stx$/, ".story.stx"), storyExists = await fileExists(storyPath);
+    if (storyExists && !overwrite) {
+      results.push({
+        componentPath,
+        storyPath,
+        content: "",
+        status: "skipped"
+      });
+      continue;
+    }
+    const analysis = await analyzeComponentFile(componentPath), content = generateStoryContent(analysis, {
+      generateVariants,
+      includeDefaults
+    }), actualStoryPath = outputDir === componentsDir ? storyPath : path.join(outputDir, path.basename(storyPath));
+    await fs.promises.mkdir(path.dirname(actualStoryPath), { recursive: !0 });
+    await fs.promises.writeFile(actualStoryPath, content);
+    results.push({
+      componentPath,
+      storyPath: actualStoryPath,
+      content,
+      status: storyExists ? "updated" : "created"
+    });
+  }
+  return results;
+}
+export function generateStoryContent(analysis, options = {}) {
+  const { generateVariants = !0, includeDefaults = !0 } = options, variants = [], defaultProps = {};
+  if (includeDefaults) {
+    for (const prop of analysis.props)
+      if (prop.default !== void 0)
+        defaultProps[prop.name] = prop.default;
+  }
+  variants.push({
+    id: "default",
+    title: "Default",
+    state: defaultProps
+  });
+  if (generateVariants) {
+    for (const prop of analysis.props)
+      if (prop.type === "boolean") {
+        variants.push({
+          id: `${prop.name}-true`,
+          title: `${formatPropName(prop.name)} (true)`,
+          state: { ...defaultProps, [prop.name]: !0 }
+        });
+        variants.push({
+          id: `${prop.name}-false`,
+          title: `${formatPropName(prop.name)} (false)`,
+          state: { ...defaultProps, [prop.name]: !1 }
+        });
+      }
+    for (const prop of analysis.props)
+      if (prop.options && prop.options.length > 0)
+        for (const option of prop.options)
+          variants.push({
+            id: `${prop.name}-${option}`,
+            title: `${formatPropName(prop.name)}: ${option}`,
+            state: { ...defaultProps, [prop.name]: option }
+          });
+  }
+  const componentName = analysis.name, description = analysis.description || `Stories for ${componentName} component`, variantBlocks = variants.map((v) => {
+    const propsStr = Object.entries(v.state).map(([key, value]) => {
+      if (typeof value === "string")
+        return `${key}="${value}"`;
+      return `:${key}="${JSON.stringify(value)}"`;
+    }).join(" ");
+    return `
+@story('${v.title}')
+<${componentName} ${propsStr} />
+@endstory`;
+  }).join(`
+`);
+  return `<!--
+  ${description}
+  Auto-generated by STX Story
+-->
+
+<script>
+import ${componentName} from './${componentName}.stx'
+
+// Story metadata
+const meta = {
+  title: '${componentName}',
+  component: ${componentName},
+}
+</script>
+
+${variantBlocks}
+`;
+}
+export async function generateStoryForComponent(componentPath, options = {}) {
+  const analysis = await analyzeComponentFile(componentPath);
+  return generateStoryContent(analysis, options);
+}
+async function findComponentFiles(dir, include, exclude) {
+  const files = [];
+  async function walk(currentDir) {
+    const entries = await fs.promises.readdir(currentDir, { withFileTypes: !0 });
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name), relativePath = path.relative(dir, fullPath);
+      if (exclude.some((pattern) => matchGlob(relativePath, pattern)))
+        continue;
+      if (entry.isDirectory())
+        await walk(fullPath);
+      else if (entry.isFile()) {
+        if (include.some((pattern) => matchGlob(relativePath, pattern)))
+          files.push(fullPath);
+      }
+    }
+  }
+  await walk(dir);
+  return files;
+}
+function matchGlob(str, pattern) {
+  const regex = pattern.replace(/\*\*/g, "{{GLOBSTAR}}").replace(/\*/g, "[^/]*").replace(/\?/g, ".").replace(/\{\{GLOBSTAR\}\}/g, ".*");
+  return new RegExp(`^${regex}$`).test(str);
+}
+async function fileExists(filePath) {
+  try {
+    await fs.promises.access(filePath);
+    return !0;
+  } catch {
+    return !1;
+  }
+}
+function formatPropName(name) {
+  return name.replace(/([A-Z])/g, " $1").replace(/^./, (s) => s.toUpperCase()).trim();
+}
+export async function autoGenerateCommand(args) {
+  const componentsDir = args[0] || "./src/components", outputDir = args[1] || componentsDir;
+  console.log(`Scanning for components in ${componentsDir}...`);
+  const results = await autoGenerateStories({
+    componentsDir,
+    outputDir,
+    generateVariants: !0,
+    includeDefaults: !0
+  }), created = results.filter((r) => r.status === "created").length, updated = results.filter((r) => r.status === "updated").length, skipped = results.filter((r) => r.status === "skipped").length;
+  console.log(`
+Results:`);
+  console.log(`  Created: ${created}`);
+  console.log(`  Updated: ${updated}`);
+  console.log(`  Skipped: ${skipped}`);
+  console.log(`  Total: ${results.length}`);
+}

package/dist/story/bookmarks.d.ts

@@ -0,0 +1,102 @@
+/**
+ * STX Story - Bookmarks
+ * Bookmark component+variant+props combinations for quick access
+ */
+/**
+ * Bookmark entry
+ */
+export interface Bookmark {
+    /** Bookmark ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Story ID */
+    storyId: string;
+    /** Variant ID */
+    variantId: string;
+    /** Props state */
+    props: Record<string, any>;
+    /** Created timestamp */
+    created: number;
+    /** Notes */
+    notes?: string;
+    /** Color label */
+    color?: string;
+}
+/**
+ * Bookmarks storage
+ */
+export interface BookmarksStorage {
+    version: number;
+    bookmarks: Bookmark[];
+}
+/**
+ * Bookmarks manager
+ */
+export declare class BookmarksManager {
+    private storage;
+    private storagePath;
+    private dirty;
+    constructor(rootDir: string);
+    private loadStorage;
+    save(): Promise<void>;
+    /**
+     * Add a bookmark
+     */
+    addBookmark(storyId: string, variantId: string, props: Record<string, any>, options?: {
+        name?: string;
+        notes?: string;
+        color?: string;
+    }): Bookmark;
+    /**
+     * Get all bookmarks
+     */
+    getAllBookmarks(): Bookmark[];
+    /**
+     * Get bookmarks for a story
+     */
+    getBookmarksForStory(storyId: string): Bookmark[];
+    /**
+     * Get a bookmark by ID
+     */
+    getBookmark(id: string): Bookmark | undefined;
+    /**
+     * Check if a combination is bookmarked
+     */
+    isBookmarked(storyId: string, variantId: string): boolean;
+    /**
+     * Update a bookmark
+     */
+    updateBookmark(id: string, updates: Partial<Omit<Bookmark, 'id' | 'created'>>): Bookmark | undefined;
+    /**
+     * Delete a bookmark
+     */
+    deleteBookmark(id: string): boolean;
+    /**
+     * Toggle bookmark for a combination
+     */
+    toggleBookmark(storyId: string, variantId: string, props: Record<string, any>): {
+        added: boolean;
+        bookmark?: Bookmark;
+    };
+    /**
+     * Export bookmarks
+     */
+    exportBookmarks(): string;
+    /**
+     * Import bookmarks
+     */
+    importBookmarks(json: string, merge?: boolean): number;
+}
+/**
+ * Generate bookmarks panel HTML
+ */
+export declare function getBookmarksPanelHtml(bookmarks: Bookmark[]): string;
+/**
+ * Generate bookmarks panel styles
+ */
+export declare function getBookmarksPanelStyles(): string;
+/**
+ * Generate bookmarks client script
+ */
+export declare function getBookmarksScript(): string;