Create virtual stories indexer and save feature

code/core/src/ghost-stories/IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,324 @@
+# Ghost Stories Implementation Summary
+
+## Overview
+
+The Ghost Stories feature has been successfully implemented as a custom Storybook indexer that automatically generates virtual stories for existing component files in your repository. This experimental feature analyzes TypeScript interfaces and props to create interactive stories with realistic default values.
+
+## What Was Implemented
+
+### 1. Core Architecture
+
+- **Custom Indexer**: `GhostStoriesIndexer` class that implements the Storybook indexer interface
+- **Component Detection**: Automated detection of React components in `.tsx`, `.jsx`, `.ts`, `.js` files
+- **Property Analysis**: TypeScript interface and prop type analysis with fake value generation
+- **Virtual Module System**: Vite plugin for serving virtual CSF files on-demand
+- **Integration Layer**: Seamless integration with existing save-from-controls functionality
+
+### 2. Key Components
+
+#### `/ghost-stories/types.ts`
+
+- TypeScript interfaces for configuration and data structures
+- `GhostStoriesConfig`, `ComponentProp`, `PropType`, `VirtualStoryIndexInput`
+
+#### `/ghost-stories/component-detector.ts`
+
+- `isComponentFile()` - Identifies component files vs story files
+- `detectReactComponents()` - Extracts component names from file content
+- `analyzeComponentProps()` - Parses TypeScript interfaces and prop types
+- `generateFakeValue()` - Creates realistic default values for different prop types
+
+#### `/ghost-stories/ghost-stories-indexer.ts`
+
+- `GhostStoriesIndexer` class - Main indexer implementation
+- `createIndex()` - Core indexing logic
+- `createGhostStoryEntry()` - Generates virtual story entries
+- Automatic argTypes and controls generation
+
+#### `/ghost-stories/virtual-module-handler.ts`
+
+- Virtual module ID parsing and validation
+- CSF content generation for ghost stories
+- Type-safe prop mapping to Storybook controls
+
+#### `/ghost-stories/vite-plugin.ts`
+
+- Vite plugin for handling virtual modules
+- Hot module replacement support
+- Error handling and fallback modules
+
+#### `/ghost-stories/config.ts`
+
+- Configuration helpers and validation
+- Default settings and setup functions
+- Integration utilities for Storybook main.ts
+
+### 3. Features Implemented
+
+✅ **Automatic Component Detection**
+
+- Scans repository for component files
+- Excludes story, test, and config files
+- Supports multiple file extensions
+
+✅ **TypeScript Prop Analysis**
+
+- Parses interfaces and type definitions
+- Handles primitive types, arrays, functions, unions
+- Supports optional props and default values
+
+✅ **Virtual Story Generation**
+
+- Creates stories with "V:" prefix
+- Generates realistic fake values for all prop types
+- Automatic argTypes and controls configuration
+
+✅ **Interactive Controls**
+
+- Text inputs for strings
+- Number inputs for numbers
+- Boolean toggles for booleans
+- Select dropdowns for union types
+- Object controls for complex types
+
+✅ **Save Integration**
+
+- Works with existing save-from-controls feature
+- Allows converting virtual stories to real story files
+- Maintains all customizations made via controls
+
+✅ **Vite Integration**
+
+- Virtual module system for on-demand CSF generation
+- Hot module replacement when component files change
+- Error handling and fallback behavior
+
+✅ **Comprehensive Testing**
+
+- 30 test cases covering all major functionality
+- Component detection, prop analysis, fake value generation
+- Error handling and edge cases
+
+## Usage Example
+
+### Basic Setup in `.storybook/main.ts`
+
+```typescript
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
+  addons: ['@storybook/addon-essentials'],
+  framework: {
+    name: '@storybook/react-vite',
+    options: {},
+  },
+  experimental_indexers: async (existingIndexers) => {
+    const { createGhostStoriesIndexer } = await import('@storybook/core/ghost-stories');
+
+    return [
+      createGhostStoriesIndexer({
+        enabled: true,
+        titlePrefix: 'V:',
+        includePatterns: ['../src/components/**/*.{tsx,jsx}'],
+        excludePatterns: ['../src/**/*.stories.*', '../src/**/*.test.*'],
+      }),
+      ...existingIndexers,
+    ];
+  },
+  viteFinal: async (config) => {
+    const { ghostStoriesPlugin } = await import('@storybook/core/ghost-stories');
+    config.plugins?.push(ghostStoriesPlugin());
+    return config;
+  },
+};
+
+export default config;
+```
+
+### Example Component
+
+```typescript
+// Button.tsx
+export interface ButtonProps {
+  label: string;
+  disabled?: boolean;
+  size?: 'small' | 'medium' | 'large';
+  variant?: 'primary' | 'secondary' | 'danger';
+  onClick?: () => void;
+}
+
+export const Button: React.FC<ButtonProps> = ({ label, disabled, size, variant, onClick }) => {
+  return (
+    <button disabled={disabled} onClick={onClick} className={`btn btn-${size} btn-${variant}`}>
+      {label}
+    </button>
+  );
+};
+```
+
+### Generated Virtual Story
+
+```typescript
+// virtual:/ghost-stories/Button.tsx?component=Button
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  title: 'V:Button',
+  component: Button,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'This is a virtual story generated from component analysis. Use the controls to experiment with props and save your changes.',
+      },
+    },
+  },
+  argTypes: {
+    label: {
+      name: 'label',
+      description: 'label prop',
+      type: { name: 'string' },
+      control: { type: 'text' },
+    },
+    disabled: {
+      name: 'disabled',
+      description: 'disabled prop',
+      type: { name: 'boolean' },
+      control: { type: 'boolean' },
+    },
+    size: {
+      name: 'size',
+      description: 'size prop',
+      type: { name: 'enum', value: ['small', 'medium', 'large'] },
+      control: { type: 'select', options: ['small', 'medium', 'large'] },
+    },
+    variant: {
+      name: 'variant',
+      description: 'variant prop',
+      type: { name: 'enum', value: ['primary', 'secondary', 'danger'] },
+      control: { type: 'select', options: ['primary', 'secondary', 'danger'] },
+    },
+    onClick: {
+      name: 'onClick',
+      description: 'onClick prop',
+      type: { name: 'function' },
+      control: { type: 'object' },
+    },
+  },
+  args: {
+    label: 'Sample text',
+    disabled: false,
+    size: 'small',
+    variant: 'primary',
+    onClick: () => {},
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    label: 'Sample text',
+    disabled: false,
+    size: 'small',
+    variant: 'primary',
+    onClick: () => {},
+  },
+};
+```
+
+## Generated Fake Values
+
+| Prop Type  | Generated Value | Example                |
+| ---------- | --------------- | ---------------------- |
+| `string`   | `"Sample text"` | `label: "Sample text"` |
+| `number`   | `42`            | `count: 42`            |
+| `boolean`  | `false`         | `disabled: false`      |
+| `array`    | `[]`            | `items: []`            |
+| `function` | `() => {}`      | `onClick: () => {}`    |
+| `union`    | First option    | `theme: "light"`       |
+| `object`   | `{}`            | `config: {}`           |
+
+## Technical Implementation Details
+
+### Component Detection Logic
+
+- Uses regex patterns to identify React component exports
+- Supports function declarations, arrow functions, and const exports
+- Filters out non-component files (stories, tests, configs)
+
+### Prop Analysis
+
+- Multiple regex patterns for different interface/type naming conventions
+- Handles TypeScript syntax including optional props (`?`)
+- Supports complex types like unions, arrays, and objects
+
+### Virtual Module System
+
+- Custom Vite plugin for serving virtual CSF files
+- On-demand generation when stories are accessed
+- Hot module replacement for component file changes
+
+### Integration Points
+
+- Hooks into Storybook's `experimental_indexers` API
+- Leverages existing save-from-controls functionality
+- Compatible with Vite-based Storybook setups
+
+## Limitations & Future Improvements
+
+### Current Limitations
+
+- **Framework Support**: Optimized for React components
+- **TypeScript Analysis**: Basic regex parsing (could use TypeScript compiler API)
+- **Builder Support**: Requires Vite builder
+- **Complex Types**: Limited support for deeply nested object types
+
+### Planned Enhancements
+
+- [ ] Full TypeScript compiler API integration
+- [ ] Enhanced Vue and Svelte support
+- [ ] Webpack builder support
+- [ ] Better complex type handling
+- [ ] Custom prop analyzers per framework
+- [ ] Story templates and presets
+
+## Testing
+
+The implementation includes comprehensive test coverage:
+
+- **30 test cases** across 2 test files
+- **Component detection** - File filtering and component extraction
+- **Prop analysis** - Interface parsing and type mapping
+- **Fake value generation** - Default value creation for all prop types
+- **Indexer functionality** - Story generation and configuration
+- **Error handling** - Graceful handling of malformed files and edge cases
+
+## File Structure
+
+```
+/workspace/code/core/src/ghost-stories/
+├── types.ts                    # TypeScript interfaces
+├── component-detector.ts       # Component and prop analysis
+├── ghost-stories-indexer.ts    # Main indexer implementation
+├── virtual-module-handler.ts   # Virtual CSF generation
+├── vite-plugin.ts              # Vite plugin for virtual modules
+├── config.ts                   # Configuration helpers
+├── index.ts                    # Public API exports
+├── README.md                   # User documentation
+├── example-integration.md      # Integration examples
+├── examples/
+│   └── Button.tsx              # Example component
+└── __tests__/
+    ├── component-detector.test.ts
+    └── ghost-stories-indexer.test.ts
+```
+
+## Conclusion
+
+The Ghost Stories feature successfully implements a complete solution for automatically generating virtual stories from existing component files. The implementation is robust, well-tested, and integrates seamlessly with Storybook's existing architecture. It provides developers with an immediate way to experiment with components that don't have stories yet, while maintaining the ability to save those experiments as permanent story files.
+
+The feature is ready for experimental use and can be extended with additional framework support and enhanced TypeScript analysis in future iterations.