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

package/dist/story/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Create a story error
+ */
+export declare function createStoryError(type: StoryErrorType, message: string, details?: Partial<StoryError>): StoryError;
+/**
+ * Format error for display
+ */
+export declare function formatStoryError(error: StoryError): string;
+/**
+ * Generate error display HTML
+ */
+export declare function generateErrorHTML(error: StoryError): string;
+/**
+ * Get error styles
+ */
+export declare function getErrorStyles(): string;
+/**
+ * Create error boundary wrapper
+ */
+export declare function createErrorBoundary(content: string, componentName: string): string;
+/**
+ * Story error
+ */
+export declare interface StoryError {
+  type: StoryErrorType
+  message: string
+  file?: string
+  line?: number
+  column?: number
+  stack?: string
+  suggestions?: string[]
+}
+/**
+ * STX Story - Error Handling
+ * Graceful error display and recovery suggestions
+ */
+/**
+ * Story error types
+ */
+export type StoryErrorType = | 'parse_error'
+  | 'component_error'
+  | 'render_error'
+  | 'config_error'
+  | 'file_not_found'
+  | 'circular_dependency'
+  | 'prop_type_error'
+  | 'unknown';

package/dist/story/errors.js

@@ -0,0 +1,239 @@
+export function createStoryError(type, message, details) {
+  const suggestions = getRecoverySuggestions(type, message);
+  return {
+    type,
+    message,
+    suggestions,
+    ...details
+  };
+}
+function getRecoverySuggestions(type, message) {
+  const suggestions = [];
+  switch (type) {
+    case "parse_error":
+      suggestions.push("Check for syntax errors in your .story.stx file");
+      suggestions.push("Ensure all tags are properly closed");
+      suggestions.push("Verify that <Story> and <Variant> components are used correctly");
+      break;
+    case "component_error":
+      suggestions.push("Check that the component file exists");
+      suggestions.push("Verify the import path is correct");
+      suggestions.push("Ensure all required props are provided");
+      break;
+    case "render_error":
+      suggestions.push("Check the browser console for more details");
+      suggestions.push("Verify that all dependencies are available");
+      suggestions.push("Try simplifying the component to isolate the issue");
+      break;
+    case "config_error":
+      suggestions.push("Check your stx.config.ts file for syntax errors");
+      suggestions.push("Verify that all required config options are set");
+      suggestions.push("Try using the default configuration");
+      break;
+    case "file_not_found":
+      suggestions.push("Check that the file path is correct");
+      suggestions.push("Verify the file exists in the specified location");
+      suggestions.push("Check for case sensitivity in the file path");
+      break;
+    case "circular_dependency":
+      suggestions.push("Review your component imports for circular references");
+      suggestions.push("Consider restructuring your components");
+      suggestions.push("Use lazy loading for problematic dependencies");
+      break;
+    case "prop_type_error":
+      suggestions.push("Check that the prop value matches the expected type");
+      suggestions.push("Review the component's prop definitions");
+      if (message.includes("required"))
+        suggestions.push("Ensure all required props are provided");
+      break;
+    default:
+      suggestions.push("Check the console for more details");
+      suggestions.push("Try restarting the story server");
+      suggestions.push("Report this issue if it persists");
+  }
+  return suggestions;
+}
+export function formatStoryError(error) {
+  const lines = [];
+  lines.push(`\u274C ${getErrorTitle(error.type)}`);
+  lines.push("");
+  lines.push(error.message);
+  lines.push("");
+  if (error.file) {
+    let location = `\uD83D\uDCC1 ${error.file}`;
+    if (error.line) {
+      location += `:${error.line}`;
+      if (error.column)
+        location += `:${error.column}`;
+    }
+    lines.push(location);
+    lines.push("");
+  }
+  if (error.suggestions && error.suggestions.length > 0) {
+    lines.push("\uD83D\uDCA1 Suggestions:");
+    for (const suggestion of error.suggestions)
+      lines.push(`   \u2022 ${suggestion}`);
+    lines.push("");
+  }
+  return lines.join(`
+`);
+}
+function getErrorTitle(type) {
+  return {
+    parse_error: "Parse Error",
+    component_error: "Component Error",
+    render_error: "Render Error",
+    config_error: "Configuration Error",
+    file_not_found: "File Not Found",
+    circular_dependency: "Circular Dependency",
+    prop_type_error: "Prop Type Error",
+    unknown: "Unknown Error"
+  }[type];
+}
+export function generateErrorHTML(error) {
+  const suggestionsHtml = error.suggestions ? error.suggestions.map((s) => `<li>${escapeHtml(s)}</li>`).join("") : "";
+  return `
+    <div class="stx-error">
+      <div class="stx-error-header">
+        <span class="stx-error-icon">\u274C</span>
+        <span class="stx-error-title">${getErrorTitle(error.type)}</span>
+      </div>
+      <div class="stx-error-message">${escapeHtml(error.message)}</div>
+      ${error.file ? `
+        <div class="stx-error-location">
+          \uD83D\uDCC1 ${escapeHtml(error.file)}${error.line ? `:${error.line}` : ""}${error.column ? `:${error.column}` : ""}
+        </div>
+      ` : ""}
+      ${suggestionsHtml ? `
+        <div class="stx-error-suggestions">
+          <div class="stx-error-suggestions-title">\uD83D\uDCA1 Suggestions:</div>
+          <ul>${suggestionsHtml}</ul>
+        </div>
+      ` : ""}
+      <div class="stx-error-actions">
+        <button onclick="window.__stxStory.dismissError()">Dismiss</button>
+        <button onclick="window.__stxStory.retryRender()">Retry</button>
+      </div>
+    </div>
+  `;
+}
+export function getErrorStyles() {
+  return `
+    .stx-error {
+      background: #fef2f2;
+      border: 1px solid #fecaca;
+      border-radius: 8px;
+      padding: 16px;
+      margin: 16px;
+      font-family: var(--font-family);
+    }
+    .dark .stx-error {
+      background: #450a0a;
+      border-color: #7f1d1d;
+    }
+    .stx-error-header {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      margin-bottom: 12px;
+    }
+    .stx-error-icon {
+      font-size: 20px;
+    }
+    .stx-error-title {
+      font-weight: 600;
+      font-size: 16px;
+      color: #dc2626;
+    }
+    .dark .stx-error-title {
+      color: #f87171;
+    }
+    .stx-error-message {
+      color: #991b1b;
+      margin-bottom: 12px;
+      font-family: var(--code-font-family);
+      font-size: 13px;
+      white-space: pre-wrap;
+    }
+    .dark .stx-error-message {
+      color: #fca5a5;
+    }
+    .stx-error-location {
+      color: #6b7280;
+      font-size: 12px;
+      margin-bottom: 12px;
+    }
+    .stx-error-suggestions {
+      margin-bottom: 12px;
+    }
+    .stx-error-suggestions-title {
+      font-weight: 500;
+      margin-bottom: 8px;
+      color: #374151;
+    }
+    .dark .stx-error-suggestions-title {
+      color: #d1d5db;
+    }
+    .stx-error-suggestions ul {
+      margin: 0;
+      padding-left: 20px;
+      color: #4b5563;
+      font-size: 13px;
+    }
+    .dark .stx-error-suggestions ul {
+      color: #9ca3af;
+    }
+    .stx-error-suggestions li {
+      margin-bottom: 4px;
+    }
+    .stx-error-actions {
+      display: flex;
+      gap: 8px;
+      margin-top: 16px;
+    }
+    .stx-error-actions button {
+      padding: 8px 16px;
+      border: 1px solid #d1d5db;
+      border-radius: 4px;
+      background: white;
+      color: #374151;
+      cursor: pointer;
+      font-size: 13px;
+    }
+    .stx-error-actions button:hover {
+      background: #f3f4f6;
+    }
+    .dark .stx-error-actions button {
+      background: #374151;
+      border-color: #4b5563;
+      color: #f3f4f6;
+    }
+    .dark .stx-error-actions button:hover {
+      background: #4b5563;
+    }
+  `;
+}
+export function createErrorBoundary(content, componentName) {
+  return `
+    <div class="stx-error-boundary" data-component="${escapeHtml(componentName)}">
+      ${content}
+    </div>
+    <script>
+      (function() {
+        const boundary = document.currentScript.previousElementSibling;
+        window.addEventListener('error', function(e) {
+          if (boundary.contains(e.target)) {
+            boundary.innerHTML = window.__stxStory.renderError({
+              type: 'render_error',
+              message: e.message,
+              file: '${escapeHtml(componentName)}'
+            });
+          }
+        });
+      })();
+    </script>
+  `;
+}
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+}

package/dist/story/figma-export.d.ts

@@ -0,0 +1,169 @@
+import type { AnalyzedComponent } from './types';
+/**
+ * Export components to Figma format
+ */
+export declare function exportToFigma(components: AnalyzedComponent[], options?: FigmaExportOptions): FigmaDocument;
+/**
+ * Export to Figma JSON file
+ */
+export declare function exportToFigmaFile(components: AnalyzedComponent[], outputPath: string, options?: FigmaExportOptions): Promise<void>;
+/**
+ * Convert CSS color to Figma color
+ */
+export declare function cssColorToFigma(cssColor: string): FigmaColor;
+/**
+ * Convert Figma color to CSS
+ */
+export declare function figmaColorToCss(color: FigmaColor): string;
+/**
+ * Generate Figma plugin manifest
+ */
+export declare function generateFigmaPluginManifest(name: string): object;
+/**
+ * Generate Figma import code snippet
+ */
+export declare function generateFigmaImportCode(components: AnalyzedComponent[]): string;
+/**
+ * Figma color
+ */
+export declare interface FigmaColor {
+  r: number
+  g: number
+  b: number
+  a: number
+}
+/**
+ * Figma paint (fill/stroke)
+ */
+export declare interface FigmaPaint {
+  type: 'SOLID' | 'GRADIENT_LINEAR' | 'GRADIENT_RADIAL' | 'IMAGE'
+  color?: FigmaColor
+  opacity?: number
+}
+/**
+ * Figma text style
+ */
+export declare interface FigmaTextStyle {
+  fontFamily: string
+  fontWeight: number
+  fontSize: number
+  lineHeight?: { value: number, unit: 'PIXELS' | 'PERCENT' | 'AUTO' }
+  letterSpacing?: { value: number, unit: 'PIXELS' | 'PERCENT' }
+  textAlign?: 'LEFT' | 'CENTER' | 'RIGHT' | 'JUSTIFIED'
+}
+/**
+ * Figma node base
+ */
+export declare interface FigmaNodeBase {
+  id: string
+  name: string
+  type: FigmaNodeType
+  visible?: boolean
+  locked?: boolean
+}
+/**
+ * Figma frame node
+ */
+export declare interface FigmaFrameNode extends FigmaNodeBase {
+  type: 'FRAME' | 'COMPONENT' | 'COMPONENT_SET'
+  children: FigmaNode[]
+  absoluteBoundingBox?: { x: number, y: number, width: number, height: number }
+  constraints?: { horizontal: string, vertical: string }
+  fills?: FigmaPaint[]
+  strokes?: FigmaPaint[]
+  strokeWeight?: number
+  cornerRadius?: number
+  paddingLeft?: number
+  paddingRight?: number
+  paddingTop?: number
+  paddingBottom?: number
+  itemSpacing?: number
+  layoutMode?: 'NONE' | 'HORIZONTAL' | 'VERTICAL'
+  primaryAxisAlignItems?: 'MIN' | 'CENTER' | 'MAX' | 'SPACE_BETWEEN'
+  counterAxisAlignItems?: 'MIN' | 'CENTER' | 'MAX'
+}
+/**
+ * Figma text node
+ */
+export declare interface FigmaTextNode extends FigmaNodeBase {
+  type: 'TEXT'
+  characters: string
+  style?: FigmaTextStyle
+  fills?: FigmaPaint[]
+}
+/**
+ * Figma rectangle node
+ */
+export declare interface FigmaRectangleNode extends FigmaNodeBase {
+  type: 'RECTANGLE'
+  absoluteBoundingBox?: { x: number, y: number, width: number, height: number }
+  fills?: FigmaPaint[]
+  strokes?: FigmaPaint[]
+  strokeWeight?: number
+  cornerRadius?: number
+}
+/**
+ * Figma document
+ */
+export declare interface FigmaDocument {
+  name: string
+  lastModified: string
+  version: string
+  document: {
+    id: string
+    name: string
+    type: 'DOCUMENT'
+    children: FigmaNode[]
+  }
+  components: Record<string, FigmaComponentMeta>
+  styles: Record<string, FigmaStyleMeta>
+}
+/**
+ * Figma component metadata
+ */
+export declare interface FigmaComponentMeta {
+  key: string
+  name: string
+  description: string
+}
+/**
+ * Figma style metadata
+ */
+export declare interface FigmaStyleMeta {
+  key: string
+  name: string
+  styleType: 'FILL' | 'TEXT' | 'EFFECT' | 'GRID'
+}
+/**
+ * Export options
+ */
+export declare interface FigmaExportOptions {
+  includeVariants?: boolean
+  includeProps?: boolean
+  frameWidth?: number
+  frameHeight?: number
+  componentSpacing?: number
+}
+/**
+ * Figma node types
+ */
+export type FigmaNodeType = | 'DOCUMENT'
+  | 'CANVAS'
+  | 'FRAME'
+  | 'GROUP'
+  | 'VECTOR'
+  | 'BOOLEAN_OPERATION'
+  | 'STAR'
+  | 'LINE'
+  | 'ELLIPSE'
+  | 'REGULAR_POLYGON'
+  | 'RECTANGLE'
+  | 'TEXT'
+  | 'SLICE'
+  | 'COMPONENT'
+  | 'COMPONENT_SET'
+  | 'INSTANCE';
+/**
+ * Union of all Figma node types
+ */
+export type FigmaNode = FigmaFrameNode | FigmaTextNode | FigmaRectangleNode | FigmaNodeBase;

package/dist/story/figma-export.js

@@ -0,0 +1,224 @@
+export function exportToFigma(components, options = {}) {
+  const {
+    includeVariants: _includeVariants = !0,
+    includeProps = !0,
+    frameWidth = 400,
+    frameHeight = 300,
+    componentSpacing = 40
+  } = options, figmaComponents = {}, figmaStyles = {}, canvasChildren = [];
+  let xOffset = 0;
+  for (const component of components) {
+    const componentId = generateId(), componentFrame = createComponentFrame(component, componentId, xOffset, 0, frameWidth, frameHeight, includeProps);
+    canvasChildren.push(componentFrame);
+    figmaComponents[componentId] = {
+      key: componentId,
+      name: component.name,
+      description: component.description || ""
+    };
+    xOffset += frameWidth + componentSpacing;
+  }
+  return {
+    name: "STX Components",
+    lastModified: new Date().toISOString(),
+    version: "1.0.0",
+    document: {
+      id: "0:0",
+      name: "Document",
+      type: "DOCUMENT",
+      children: [
+        {
+          id: "0:1",
+          name: "Components",
+          type: "CANVAS",
+          children: canvasChildren
+        }
+      ]
+    },
+    components: figmaComponents,
+    styles: figmaStyles
+  };
+}
+function createComponentFrame(component, id, x, y, width, height, includeProps) {
+  const children = [];
+  children.push({
+    id: `${id}:title`,
+    name: "Title",
+    type: "TEXT",
+    characters: component.name,
+    style: {
+      fontFamily: "Inter",
+      fontWeight: 600,
+      fontSize: 16
+    },
+    fills: [{ type: "SOLID", color: { r: 0, g: 0, b: 0, a: 1 } }]
+  });
+  if (component.description)
+    children.push({
+      id: `${id}:desc`,
+      name: "Description",
+      type: "TEXT",
+      characters: component.description,
+      style: {
+        fontFamily: "Inter",
+        fontWeight: 400,
+        fontSize: 12
+      },
+      fills: [{ type: "SOLID", color: { r: 0.4, g: 0.4, b: 0.4, a: 1 } }]
+    });
+  if (includeProps && component.props.length > 0) {
+    const propsFrame = createPropsFrame(component.props, `${id}:props`);
+    children.push(propsFrame);
+  }
+  children.push({
+    id: `${id}:preview`,
+    name: "Preview",
+    type: "RECTANGLE",
+    absoluteBoundingBox: { x: 0, y: 0, width: width - 32, height: 150 },
+    fills: [{ type: "SOLID", color: { r: 0.95, g: 0.95, b: 0.95, a: 1 } }],
+    strokes: [{ type: "SOLID", color: { r: 0.9, g: 0.9, b: 0.9, a: 1 } }],
+    strokeWeight: 1,
+    cornerRadius: 8
+  });
+  return {
+    id,
+    name: component.name,
+    type: "COMPONENT",
+    children,
+    absoluteBoundingBox: { x, y, width, height },
+    fills: [{ type: "SOLID", color: { r: 1, g: 1, b: 1, a: 1 } }],
+    strokes: [{ type: "SOLID", color: { r: 0.9, g: 0.9, b: 0.9, a: 1 } }],
+    strokeWeight: 1,
+    cornerRadius: 12,
+    paddingLeft: 16,
+    paddingRight: 16,
+    paddingTop: 16,
+    paddingBottom: 16,
+    itemSpacing: 12,
+    layoutMode: "VERTICAL",
+    primaryAxisAlignItems: "MIN",
+    counterAxisAlignItems: "MIN"
+  };
+}
+function createPropsFrame(props, id) {
+  const children = [];
+  children.push({
+    id: `${id}:header`,
+    name: "Props Header",
+    type: "TEXT",
+    characters: "Props",
+    style: {
+      fontFamily: "Inter",
+      fontWeight: 600,
+      fontSize: 12
+    },
+    fills: [{ type: "SOLID", color: { r: 0.4, g: 0.4, b: 0.4, a: 1 } }]
+  });
+  for (let i = 0;i < props.length; i++) {
+    const prop = props[i];
+    children.push({
+      id: `${id}:prop:${i}`,
+      name: prop.name,
+      type: "TEXT",
+      characters: `${prop.name}: ${prop.type}${prop.required ? " (required)" : ""}`,
+      style: {
+        fontFamily: "SF Mono",
+        fontWeight: 400,
+        fontSize: 11
+      },
+      fills: [{ type: "SOLID", color: { r: 0.2, g: 0.2, b: 0.2, a: 1 } }]
+    });
+  }
+  return {
+    id,
+    name: "Props",
+    type: "FRAME",
+    children,
+    fills: [{ type: "SOLID", color: { r: 0.98, g: 0.98, b: 0.98, a: 1 } }],
+    cornerRadius: 6,
+    paddingLeft: 12,
+    paddingRight: 12,
+    paddingTop: 8,
+    paddingBottom: 8,
+    itemSpacing: 4,
+    layoutMode: "VERTICAL",
+    primaryAxisAlignItems: "MIN",
+    counterAxisAlignItems: "MIN"
+  };
+}
+function generateId() {
+  return `${Date.now()}:${Math.random().toString(36).slice(2, 8)}`;
+}
+export async function exportToFigmaFile(components, outputPath, options = {}) {
+  const figmaDoc = exportToFigma(components, options), json = JSON.stringify(figmaDoc, null, 2), fs = await import("node:fs"), path = await import("node:path");
+  await fs.promises.mkdir(path.dirname(outputPath), { recursive: !0 });
+  await fs.promises.writeFile(outputPath, json);
+}
+export function cssColorToFigma(cssColor) {
+  if (cssColor.startsWith("#")) {
+    const hex = cssColor.slice(1), r = Number.parseInt(hex.slice(0, 2), 16) / 255, g = Number.parseInt(hex.slice(2, 4), 16) / 255, b = Number.parseInt(hex.slice(4, 6), 16) / 255, a = hex.length === 8 ? Number.parseInt(hex.slice(6, 8), 16) / 255 : 1;
+    return { r, g, b, a };
+  }
+  const rgbMatch = cssColor.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/);
+  if (rgbMatch)
+    return {
+      r: Number.parseInt(rgbMatch[1]) / 255,
+      g: Number.parseInt(rgbMatch[2]) / 255,
+      b: Number.parseInt(rgbMatch[3]) / 255,
+      a: rgbMatch[4] ? Number.parseFloat(rgbMatch[4]) : 1
+    };
+  return { r: 0, g: 0, b: 0, a: 1 };
+}
+export function figmaColorToCss(color) {
+  const r = Math.round(color.r * 255), g = Math.round(color.g * 255), b = Math.round(color.b * 255);
+  if (color.a === 1)
+    return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+  return `rgba(${r}, ${g}, ${b}, ${color.a})`;
+}
+export function generateFigmaPluginManifest(name) {
+  return {
+    name,
+    id: `stx-story-${name.toLowerCase().replace(/\s+/g, "-")}`,
+    api: "1.0.0",
+    main: "code.js",
+    ui: "ui.html",
+    editorType: ["figma"],
+    capabilities: ["inspect"],
+    permissions: ["currentuser"]
+  };
+}
+export function generateFigmaImportCode(components) {
+  const componentNames = components.map((c) => c.name).join(", ");
+  return `
+// Figma Plugin Code to import STX components
+// Run this in Figma's plugin console
+
+const components = ${JSON.stringify(components.map((c) => ({
+    name: c.name,
+    props: c.props.map((p) => ({ name: p.name, type: p.type }))
+  })), null, 2)};
+
+async function importComponents() {
+  for (const comp of components) {
+    const frame = figma.createFrame();
+    frame.name = comp.name;
+    frame.resize(400, 300);
+
+    // Add title
+    const title = figma.createText();
+    await figma.loadFontAsync({ family: "Inter", style: "Semi Bold" });
+    title.fontName = { family: "Inter", style: "Semi Bold" };
+    title.characters = comp.name;
+    title.fontSize = 16;
+    frame.appendChild(title);
+
+    // Position on canvas
+    frame.x = figma.viewport.center.x;
+    frame.y = figma.viewport.center.y;
+  }
+
+  figma.notify('Imported ${componentNames}');
+}
+
+importComponents();
+`;
+}

package/dist/story/generator.d.ts

@@ -0,0 +1,21 @@
+import type { AnalyzedComponent, ControlConfig, ServerStory, StoryAnalyzedProp } from './types';
+/**
+ * Generate a story from analyzed component metadata
+ */
+export declare function generateAutoStory(component: AnalyzedComponent): ServerStory;
+/**
+ * Infer control configuration from a prop
+ */
+export declare function inferControl(prop: StoryAnalyzedProp): ControlConfig;
+/**
+ * Generate controls for all props
+ */
+export declare function generateControls(props: StoryAnalyzedProp[]): ControlConfig[];
+/**
+ * Generate story source code from component and state
+ */
+export declare function generateStorySource(componentName: string, state: Record<string, any>): string;
+/**
+ * Generate a complete story file content
+ */
+export declare function generateStoryFileContent(component: AnalyzedComponent): string;