@tpitre/story-ui 2.2.0 → 2.3.1

package/dist/story-generator/framework-adapters/web-components-adapter.js

@@ -0,0 +1,387 @@
+/**
+ * Web Components Framework Adapter
+ *
+ * Generates Storybook stories for Web Components (Lit, vanilla, etc.).
+ * Supports standard Web Components and Lit framework.
+ */
+import { BaseFrameworkAdapter } from './base-adapter.js';
+export class WebComponentsAdapter extends BaseFrameworkAdapter {
+    constructor() {
+        super(...arguments);
+        this.type = 'web-components';
+        this.name = 'Web Components';
+        this.supportedStoryFrameworks = [
+            'storybook-web-components',
+            'chromatic',
+        ];
+        this.defaultExtension = '.stories.ts';
+    }
+    generateSystemPrompt(config, options) {
+        if (config.systemPrompt) {
+            return config.systemPrompt;
+        }
+        const componentSystemName = config.componentPrefix
+            ? `${config.componentPrefix.replace(/^[A-Z]+/, '')} design system`
+            : 'component library';
+        return `You are an expert Web Components developer creating Storybook stories using CSF 3.0 format.
+Use ONLY the Web Components from the ${componentSystemName} listed below.
+
+MANDATORY IMPORTS - First lines of every story file:
+1. import { html } from 'lit';
+2. import type { Meta, StoryObj } from '@storybook/web-components';
+3. import '${config.importPath || 'your-library'}'; // Register custom elements
+
+WEB COMPONENTS STORY FORMAT:
+- Use the html template literal from Lit for rendering
+- Custom elements use kebab-case tag names (e.g., <my-button>)
+- Properties are set as attributes or with . prefix for property binding
+- Events use @ prefix (e.g., @click)
+
+COMPONENT REGISTRATION:
+- Web Components must be registered before use
+- Import the component file to auto-register: import 'my-library/my-button';
+- Or import the class and define: customElements.define('my-button', MyButton);
+
+STORY STRUCTURE (CSF 3.0):
+- Meta object with title and optional component reference
+- Use render function with html\`\` template literal
+- Export named stories as StoryObj
+
+CRITICAL RULES:
+- Use html template literal, NOT JSX
+- Use kebab-case for tag names
+- Use .property for property binding, attribute for attributes
+- Use @event for event handlers
+
+Example structure:
+\`\`\`typescript
+import { html } from 'lit';
+import type { Meta, StoryObj } from '@storybook/web-components';
+import 'your-library/button';
+
+const meta: Meta = {
+  title: 'Components/Button',
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'ghost'],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Primary: Story = {
+  args: { variant: 'primary' },
+  render: (args) => html\`
+    <my-button variant=\${args.variant}>
+      Click me
+    </my-button>
+  \`,
+};
+
+export const WithIcon: Story = {
+  render: () => html\`
+    <my-button variant="primary">
+      <my-icon slot="icon" name="star"></my-icon>
+      Starred
+    </my-button>
+  \`,
+};
+\`\`\`
+
+ATTRIBUTE VS PROPERTY BINDING:
+- Attributes (string values): variant="primary"
+- Properties (any value): .disabled=\${true}
+- Boolean attributes: ?disabled=\${true}
+- Events: @click=\${handleClick}
+
+SLOTS:
+- Default slot: Content between tags
+- Named slots: Use slot="name" attribute
+- Example: <my-card><span slot="header">Title</span>Content</my-card>
+
+${this.getCommonRules()}`;
+    }
+    generateExamples(config) {
+        const lib = config.importPath || 'your-library';
+        return `
+## Example Stories for Web Components
+
+### Single Component Story
+\`\`\`typescript
+import { html } from 'lit';
+import type { Meta, StoryObj } from '@storybook/web-components';
+import 'your-library/button';
+
+const meta: Meta = {
+  title: 'Components/Button',
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'ghost'],
+    },
+    size: {
+      control: 'select',
+      options: ['small', 'medium', 'large'],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+  args: { variant: 'primary', size: 'medium' },
+  render: (args) => html\`
+    <my-button
+      variant=\${args.variant}
+      size=\${args.size}
+    >
+      Button
+    </my-button>
+  \`,
+};
+
+export const Disabled: Story = {
+  render: () => html\`
+    <my-button variant="primary" ?disabled=\${true}>
+      Disabled Button
+    </my-button>
+  \`,
+};
+\`\`\`
+
+### Layout Story (Multiple Components)
+\`\`\`typescript
+import { html } from 'lit';
+import type { Meta, StoryObj } from '@storybook/web-components';
+import '${lib}/card';
+import 'your-library/button';
+import '${lib}/text';
+
+const meta: Meta = {
+  title: 'Examples/Card Layout',
+  parameters: { layout: 'padded' },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const ProductCard: Story = {
+  render: () => html\`
+    <my-card style="width: 300px">
+      <img slot="media" src="https://picsum.photos/300/200" alt="Product">
+      <span slot="header">Product Name</span>
+      <my-text>$99.00</my-text>
+      <my-button slot="footer" variant="primary">Add to Cart</my-button>
+    </my-card>
+  \`,
+};
+\`\`\`
+
+### With Event Handling
+\`\`\`typescript
+import { html } from 'lit';
+import type { Meta, StoryObj } from '@storybook/web-components';
+import 'your-library/button';
+
+const meta: Meta = {
+  title: 'Components/Button',
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const WithClickHandler: Story = {
+  render: () => html\`
+    <my-button
+      variant="primary"
+      @click=\${(e: Event) => console.log('Clicked!', e)}
+    >
+      Click me
+    </my-button>
+  \`,
+};
+\`\`\`
+`;
+    }
+    generateSampleStory(config, components) {
+        const lib = config.importPath || 'your-library';
+        const firstComponent = components[0];
+        if (!firstComponent) {
+            return `
+import { html } from 'lit';
+import type { Meta, StoryObj } from '@storybook/web-components';
+
+const meta: Meta = {
+  title: 'Examples/Sample',
+  parameters: { layout: 'centered' },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => html\`<div>Sample story content</div>\`,
+};
+`;
+        }
+        // Convert PascalCase to kebab-case for tag name
+        const tagName = this.toKebabCase(firstComponent.name);
+        return `
+import { html } from 'lit';
+import type { Meta, StoryObj } from '@storybook/web-components';
+import '${lib}/${tagName}';
+
+const meta: Meta = {
+  title: 'Components/${firstComponent.name}',
+  tags: ['autodocs'],
+  parameters: { layout: 'centered' },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => html\`<${tagName}></${tagName}>\`,
+};
+`;
+    }
+    getStoryTemplate(options) {
+        return `
+// {{componentName}}.stories.ts
+import { html } from 'lit';
+import type { Meta, StoryObj } from '@storybook/web-components';
+import '{{importPath}}';
+
+const meta: Meta = {
+  title: '{{category}}/{{componentName}}',
+  tags: ['autodocs'],
+  parameters: { layout: 'centered' },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => html\`<{{tagName}}></{{tagName}}>\`,
+};
+`;
+    }
+    /**
+     * Convert PascalCase to kebab-case
+     */
+    toKebabCase(str) {
+        return str
+            .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+            .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')
+            .toLowerCase();
+    }
+    /**
+     * Post-process Web Components stories
+     */
+    postProcess(storyContent) {
+        let processed = super.postProcess(storyContent);
+        // Ensure lit import is present
+        if (!processed.includes("import { html } from 'lit'")) {
+            processed = "import { html } from 'lit';\n" + processed;
+        }
+        // FIX #3: Remove React imports from Web Components stories
+        // LLMs sometimes incorrectly include React imports in non-React frameworks
+        processed = processed.replace(/import React from ['"]react['"];?\n?/g, '');
+        processed = processed.replace(/import \* as React from ['"]react['"];?\n?/g, '');
+        // Fix common issues
+        processed = processed
+            // Remove React-style className
+            .replace(/className=/g, 'class=')
+            // Fix JSX-style event handlers
+            .replace(/onClick=/g, '@click=')
+            .replace(/onChange=/g, '@change=')
+            .replace(/onInput=/g, '@input=');
+        // FIX #1: Handle escaped backticks in nested template literals
+        // When LLMs generate complex Lit templates with inline JavaScript that uses
+        // template literals, they sometimes escape backticks incorrectly causing
+        // Babel parsing errors like "Expecting Unicode escape sequence \uXXXX"
+        processed = this.fixNestedTemplateLiterals(processed);
+        return processed;
+    }
+    /**
+     * Fix nested template literal escaping issues
+     *
+     * Problem: LLMs generate code like:
+     *   innerHTML: \`<sl-icon></sl-icon>\`
+     *
+     * This causes Babel syntax errors. The fix converts problematic patterns
+     * to use string concatenation instead of nested template literals.
+     */
+    fixNestedTemplateLiterals(code) {
+        // Pattern 1: innerHTML with escaped template literals
+        // Convert: innerHTML: \`...\` to innerHTML: '...'
+        code = code.replace(/innerHTML:\s*\\`([^`]*?)\\`/g, (match, content) => {
+            // Convert to single quotes, escaping any existing single quotes
+            const escaped = content.replace(/'/g, "\\'");
+            return `innerHTML: '${escaped}'`;
+        });
+        // Pattern 2: Template literals with escaped backticks inside html``
+        // These patterns indicate the LLM tried to nest template literals incorrectly
+        // Look for patterns like \`...\` that appear inside render functions
+        code = code.replace(/\\`/g, (match, offset, fullString) => {
+            // Check if we're inside a JavaScript context (not in a comment or string)
+            const before = fullString.slice(Math.max(0, offset - 50), offset);
+            // If this looks like it's in an innerHTML or template context, convert to quote
+            if (/innerHTML\s*[:=]\s*$/.test(before) ||
+                /Object\.assign\([^)]*\{\s*$/.test(before) ||
+                /:\s*$/.test(before)) {
+                return "'";
+            }
+            // Otherwise keep the escaped backtick (might be intentional)
+            return match;
+        });
+        return code;
+    }
+    /**
+     * Validate Web Components story
+     */
+    validate(storyContent) {
+        const baseValidation = super.validate(storyContent);
+        const errors = [...baseValidation.errors];
+        // Web Components specific validations
+        if (!storyContent.includes("import { html } from 'lit'")) {
+            errors.push("Missing 'import { html } from 'lit'' statement");
+        }
+        if (storyContent.includes('import React')) {
+            errors.push('React import found in Web Components story');
+        }
+        // Check for JSX syntax (should use lit html)
+        if (/<[A-Z][a-zA-Z]*\s/.test(storyContent) && !storyContent.includes('html`')) {
+            errors.push('Using JSX syntax instead of Lit html template');
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+        };
+    }
+    /**
+     * Generate import statements for Web Components
+     */
+    generateImports(components, config) {
+        const lib = config.importPath || 'your-library';
+        const imports = ["import { html } from 'lit';"];
+        // Import each component (side-effect import to register custom element)
+        for (const component of components) {
+            const tagName = this.toKebabCase(component.name);
+            imports.push(`import '${lib}/${tagName}';`);
+        }
+        return imports.join('\n');
+    }
+}
+/**
+ * Factory function
+ */
+export function createWebComponentsAdapter() {
+    return new WebComponentsAdapter();
+}

package/dist/story-generator/generateStory.d.ts

@@ -0,0 +1,7 @@
+import { StoryUIConfig } from '../story-ui.config.js';
+export declare function generateStory({ fileContents, fileName, config }: {
+    fileContents: string;
+    fileName: string;
+    config: StoryUIConfig;
+}): string;
+//# sourceMappingURL=generateStory.d.ts.map

package/dist/story-generator/generateStory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateStory.d.ts","sourceRoot":"","sources":["../../story-generator/generateStory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAStD,wBAAgB,aAAa,CAAC,EAC5B,YAAY,EACZ,QAAQ,EACR,MAAM,EACP,EAAE;IACD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;CACvB,UAWA"}

package/dist/story-generator/gitignoreManager.d.ts

@@ -0,0 +1,50 @@
+import { StoryUIConfig } from '../story-ui.config.js';
+/**
+ * Manages .gitignore entries for Story UI generated content
+ */
+export declare class GitignoreManager {
+    private config;
+    private projectRoot;
+    constructor(config: StoryUIConfig, projectRoot?: string);
+    /**
+     * Ensures the generated stories directory is added to .gitignore
+     */
+    ensureGeneratedDirectoryIgnored(): void;
+    /**
+     * Gets the relative path from project root to generated stories directory
+     */
+    private getRelativeGeneratedPath;
+    /**
+     * Creates a new .gitignore file with Story UI section
+     */
+    private createGitignore;
+    /**
+     * Checks if the generated path is already ignored
+     */
+    private isPathIgnored;
+    /**
+     * Adds ignore rule to existing .gitignore
+     */
+    private addIgnoreRule;
+    /**
+     * Generates the gitignore section for Story UI
+     */
+    private generateGitignoreSection;
+    /**
+     * Creates the generated directory if it doesn't exist
+     */
+    ensureGeneratedDirectoryExists(): void;
+    /**
+     * Creates a README in the generated directory explaining its purpose
+     */
+    private createGeneratedDirectoryReadme;
+    /**
+     * Cleans up old generated stories (optional utility)
+     */
+    cleanupOldStories(maxAge?: number): void;
+}
+/**
+ * Convenience function to set up gitignore for Story UI
+ */
+export declare function setupGitignoreForStoryUI(config: StoryUIConfig, projectRoot?: string): void;
+//# sourceMappingURL=gitignoreManager.d.ts.map

package/dist/story-generator/gitignoreManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitignoreManager.d.ts","sourceRoot":"","sources":["../../story-generator/gitignoreManager.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,WAAW,CAAS;gBAEhB,MAAM,EAAE,aAAa,EAAE,WAAW,GAAE,MAAsB;IAKtE;;OAEG;IACH,+BAA+B,IAAI,IAAI;IA0BvC;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAuBhC;;OAEG;IACH,OAAO,CAAC,eAAe;IAMvB;;OAEG;IACH,OAAO,CAAC,aAAa;IAmBrB;;OAEG;IACH,OAAO,CAAC,aAAa;IAYrB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAOhC;;OAEG;IACH,8BAA8B,IAAI,IAAI;IAYtC;;OAEG;IACH,OAAO,CAAC,8BAA8B;IA+BtC;;OAEG;IACH,iBAAiB,CAAC,MAAM,GAAE,MAAgC,GAAG,IAAI;CA8BlE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAI1F"}

package/dist/story-generator/imageProcessor.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Image Processing Module for StoryUI Vision Feature
+ *
+ * This module handles all image processing operations including:
+ * - Validation of image inputs (size, format, data integrity)
+ * - Conversion between different image formats (URL, base64, buffer)
+ * - Media type detection from magic bytes and file extensions
+ * - Preparation of images for LLM provider consumption
+ *
+ * Supports: PNG, JPEG, GIF, WebP formats
+ * Max size: 20MB for base64 encoded images
+ */
+import { ImageContent } from './llm-providers/types.js';
+declare const SUPPORTED_MEDIA_TYPES: readonly ["image/png", "image/jpeg", "image/jpg", "image/gif", "image/webp"];
+type SupportedMediaType = typeof SUPPORTED_MEDIA_TYPES[number];
+/**
+ * Image Input Interface
+ * Accepts images from API requests in various formats
+ */
+export interface ImageInput {
+    data?: string;
+    url?: string;
+    mediaType?: string;
+    name?: string;
+}
+/**
+ * Image Validation Result
+ */
+export interface ImageValidationResult {
+    valid: boolean;
+    error?: string;
+    warning?: string;
+}
+/**
+ * Get media type from buffer by checking magic bytes
+ *
+ * @param buffer - Image buffer to analyze
+ * @returns Detected MIME type or undefined if not recognized
+ */
+export declare function getMediaTypeFromBuffer(buffer: Buffer): SupportedMediaType | undefined;
+/**
+ * Validate an image input
+ *
+ * Checks:
+ * - Has either data or url
+ * - File size is within limits
+ * - Media type is supported
+ * - Base64 data is valid
+ *
+ * @param image - Image input to validate
+ * @returns Validation result with error/warning messages
+ */
+export declare function validateImage(image: ImageInput): ImageValidationResult;
+/**
+ * Fetch an image from a URL and convert to base64
+ *
+ * @param url - URL to fetch image from
+ * @returns Object containing base64 data and detected media type
+ * @throws Error if fetch fails or image is invalid
+ */
+export declare function fetchImageAsBase64(url: string): Promise<{
+    data: string;
+    mediaType: SupportedMediaType;
+}>;
+/**
+ * Process multiple image inputs and convert to ImageContent format
+ *
+ * This is the main entry point for image processing. It:
+ * 1. Validates each image input
+ * 2. Fetches URL images and converts to base64
+ * 3. Detects media types from magic bytes, headers, or extensions
+ * 4. Returns array of ImageContent objects ready for LLM providers
+ *
+ * @param images - Array of image inputs to process
+ * @returns Promise resolving to array of ImageContent objects
+ * @throws Error if any image fails to process
+ */
+export declare function processImageInputs(images: ImageInput[]): Promise<ImageContent[]>;
+export {};
+//# sourceMappingURL=imageProcessor.d.ts.map

package/dist/story-generator/imageProcessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageProcessor.d.ts","sourceRoot":"","sources":["../../story-generator/imageProcessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AASxD,QAAA,MAAM,qBAAqB,8EAMjB,CAAC;AAEX,KAAK,kBAAkB,GAAG,OAAO,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAoB/D;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAYD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CA2BrF;AAkED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,qBAAqB,CAqFtE;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAqD9G;AAmGD;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAgCtF"}