claude-code-templates 1.21.12 → 1.21.13

package/cli-tool/components/commands/svelte/svelte:storybook-mock.md

@@ -0,0 +1,213 @@
+# /svelte:storybook-mock
+
+Mock SvelteKit modules and functionality in Storybook stories for isolated component development.
+
+## Instructions
+
+You are acting as the Svelte Storybook Specialist Agent focused on mocking SvelteKit modules. When setting up mocks:
+
+1. **Module Mocking Overview**:
+   
+   **Fully Supported**:
+   - `$app/environment` - Browser and version info
+   - `$app/paths` - Base paths configuration
+   - `$lib` - Library imports
+   - `@sveltejs/kit/*` - Kit utilities
+   
+   **Experimental (Requires Mocking)**:
+   - `$app/stores` - Page, navigating, updated stores
+   - `$app/navigation` - Navigation functions
+   - `$app/forms` - Form enhancement
+   
+   **Not Supported**:
+   - `$env/dynamic/private` - Server-only
+   - `$env/static/private` - Server-only
+   - `$service-worker` - Service worker context
+
+2. **Store Mocking**:
+   ```javascript
+   export const Default = {
+     parameters: {
+       sveltekit_experimental: {
+         stores: {
+           // Page store
+           page: {
+             url: new URL('https://example.com/products/123'),
+             params: { id: '123' },
+             route: {
+               id: '/products/[id]'
+             },
+             status: 200,
+             error: null,
+             data: {
+               product: {
+                 id: '123',
+                 name: 'Sample Product',
+                 price: 99.99
+               }
+             },
+             form: null
+           },
+           // Navigating store
+           navigating: {
+             from: {
+               params: { id: '122' },
+               route: { id: '/products/[id]' },
+               url: new URL('https://example.com/products/122')
+             },
+             to: {
+               params: { id: '123' },
+               route: { id: '/products/[id]' },
+               url: new URL('https://example.com/products/123')
+             },
+             type: 'link',
+             delta: 1
+           },
+           // Updated store
+           updated: true
+         }
+       }
+     }
+   };
+   ```
+
+3. **Navigation Mocking**:
+   ```javascript
+   parameters: {
+     sveltekit_experimental: {
+       navigation: {
+         goto: (url, options) => {
+           console.log('Navigating to:', url);
+           action('goto')(url, options);
+         },
+         pushState: (url, state) => {
+           console.log('Push state:', url, state);
+           action('pushState')(url, state);
+         },
+         replaceState: (url, state) => {
+           console.log('Replace state:', url, state);
+           action('replaceState')(url, state);
+         },
+         invalidate: (url) => {
+           console.log('Invalidate:', url);
+           action('invalidate')(url);
+         },
+         invalidateAll: () => {
+           console.log('Invalidate all');
+           action('invalidateAll')();
+         },
+         afterNavigate: {
+           from: null,
+           to: { url: new URL('https://example.com') },
+           type: 'enter'
+         }
+       }
+     }
+   }
+   ```
+
+4. **Form Enhancement Mocking**:
+   ```javascript
+   parameters: {
+     sveltekit_experimental: {
+       forms: {
+         enhance: (form) => {
+           console.log('Form enhanced:', form);
+           // Return cleanup function
+           return {
+             destroy() {
+               console.log('Form enhancement cleaned up');
+             }
+           };
+         }
+       }
+     }
+   }
+   ```
+
+5. **Link Handling**:
+   ```javascript
+   parameters: {
+     sveltekit_experimental: {
+       hrefs: {
+         // Exact match
+         '/products': (to, event) => {
+           console.log('Products link clicked');
+           event.preventDefault();
+         },
+         // Regex pattern
+         '/product/.*': {
+           callback: (to, event) => {
+             console.log('Product detail:', to);
+           },
+           asRegex: true
+         },
+         // API routes
+         '/api/.*': {
+           callback: (to, event) => {
+             event.preventDefault();
+             console.log('API call intercepted:', to);
+           },
+           asRegex: true
+         }
+       }
+     }
+   }
+   ```
+
+6. **Complex Mocking Scenarios**:
+   
+   **Auth State**:
+   ```javascript
+   const mockAuthenticatedUser = {
+     parameters: {
+       sveltekit_experimental: {
+         stores: {
+           page: {
+             data: {
+               user: {
+                 id: '123',
+                 email: 'user@example.com',
+                 role: 'admin'
+               },
+               session: {
+                 token: 'mock-jwt-token',
+                 expiresAt: '2024-12-31'
+               }
+             }
+           }
+         }
+       }
+     }
+   };
+   ```
+   
+   **Loading States**:
+   ```javascript
+   const mockLoadingState = {
+     parameters: {
+       sveltekit_experimental: {
+         stores: {
+           navigating: {
+             from: { url: new URL('https://example.com') },
+             to: { url: new URL('https://example.com/products') }
+           }
+         }
+       }
+     }
+   };
+   ```
+
+## Example Usage
+
+User: "Mock SvelteKit stores for my ProductDetail component"
+
+Assistant will:
+- Analyze component's store dependencies
+- Create comprehensive store mocks
+- Mock page data with product info
+- Set up navigation mocks
+- Configure link handling
+- Add form enhancement if needed
+- Create multiple story variants
+- Test different states (loading, error, success)

package/cli-tool/components/commands/svelte/svelte:storybook-setup.md

@@ -0,0 +1,113 @@
+# /svelte:storybook-setup
+
+Initialize and configure Storybook for SvelteKit projects with optimal settings and structure.
+
+## Instructions
+
+You are acting as the Svelte Storybook Specialist Agent focused on Storybook setup. When setting up Storybook:
+
+1. **Installation Process**:
+   
+   **New Installation**:
+   ```bash
+   npx storybook@latest init
+   ```
+   
+   **Manual Setup**:
+   - Install core dependencies
+   - Configure @storybook/sveltekit framework
+   - Add essential addons
+   - Set up Svelte CSF addon
+
+2. **Configuration Files**:
+   
+   **.storybook/main.js**:
+   ```javascript
+   export default {
+     stories: ['../src/**/*.stories.@(js|ts|svelte)'],
+     addons: [
+       '@storybook/addon-essentials',
+       '@storybook/addon-svelte-csf',
+       '@storybook/addon-a11y',
+       '@storybook/addon-interactions'
+     ],
+     framework: {
+       name: '@storybook/sveltekit',
+       options: {}
+     },
+     staticDirs: ['../static']
+   };
+   ```
+   
+   **.storybook/preview.js**:
+   ```javascript
+   import '../src/app.css'; // Global styles
+   
+   export const parameters = {
+     actions: { argTypesRegex: '^on[A-Z].*' },
+     controls: {
+       matchers: {
+         color: /(background|color)$/i,
+         date: /Date$/i
+       }
+     },
+     layout: 'centered'
+   };
+   ```
+
+3. **Project Structure**:
+   ```
+   src/
+   ├── lib/
+   │   └── components/
+   │       ├── Button/
+   │       │   ├── Button.svelte
+   │       │   ├── Button.stories.svelte
+   │       │   └── Button.test.ts
+   │       └── Card/
+   │           ├── Card.svelte
+   │           └── Card.stories.svelte
+   └── stories/
+       ├── Introduction.mdx
+       └── Configure.mdx
+   ```
+
+4. **Essential Addons**:
+   - **@storybook/addon-essentials**: Core functionality
+   - **@storybook/addon-svelte-csf**: Native Svelte stories
+   - **@storybook/addon-a11y**: Accessibility testing
+   - **@storybook/addon-interactions**: Play functions
+   - **@chromatic-com/storybook**: Visual testing
+
+5. **Scripts Configuration**:
+   ```json
+   {
+     "scripts": {
+       "storybook": "storybook dev -p 6006",
+       "build-storybook": "storybook build",
+       "test-storybook": "test-storybook",
+       "chromatic": "chromatic --exit-zero-on-changes"
+     }
+   }
+   ```
+
+6. **SvelteKit Integration**:
+   - Configure module mocking
+   - Set up path aliases
+   - Handle SSR considerations
+   - Configure static assets
+
+## Example Usage
+
+User: "Set up Storybook for my new SvelteKit project"
+
+Assistant will:
+- Check project structure and dependencies
+- Run Storybook init command
+- Configure for SvelteKit framework
+- Add Svelte CSF addon
+- Set up proper file structure
+- Create example stories
+- Configure preview settings
+- Add helpful npm scripts
+- Set up GitHub Actions for Chromatic

package/cli-tool/components/commands/svelte/svelte:storybook-story.md

@@ -0,0 +1,145 @@
+# /svelte:storybook-story
+
+Create comprehensive Storybook stories for Svelte components using modern patterns and best practices.
+
+## Instructions
+
+You are acting as the Svelte Storybook Specialist Agent focused on creating stories. When creating stories:
+
+1. **Analyze the Component**:
+   - Review component props and types
+   - Identify all possible states
+   - Find interactive elements
+   - Check for slots and events
+   - Note accessibility requirements
+
+2. **Story Structure (Svelte CSF)**:
+   ```svelte
+   <script>
+     import { defineMeta } from '@storybook/addon-svelte-csf';
+     import { within, userEvent, expect } from '@storybook/test';
+     import Component from './Component.svelte';
+
+     const { Story } = defineMeta({
+       component: Component,
+       title: 'Category/Component',
+       tags: ['autodocs'],
+       parameters: {
+         layout: 'centered',
+         docs: {
+           description: {
+             component: 'Component description for docs'
+           }
+         }
+       },
+       argTypes: {
+         variant: {
+           control: 'select',
+           options: ['primary', 'secondary'],
+           description: 'Visual style variant'
+         },
+         size: {
+           control: 'radio',
+           options: ['small', 'medium', 'large']
+         },
+         disabled: {
+           control: 'boolean'
+         }
+       }
+     });
+   </script>
+   ```
+
+3. **Story Patterns**:
+   
+   **Basic Story**:
+   ```svelte
+   <Story name="Default" args={{ label: 'Click me' }} />
+   ```
+   
+   **With Children/Slots**:
+   ```svelte
+   <Story name="WithIcon">
+     {#snippet template(args)}
+       <Component {...args}>
+         <Icon slot="icon" />
+         Custom content
+       </Component>
+     {/snippet}
+   </Story>
+   ```
+   
+   **Interactive Story**:
+   ```svelte
+   <Story 
+     name="Interactive"
+     play={async ({ canvasElement }) => {
+       const canvas = within(canvasElement);
+       const button = canvas.getByRole('button');
+       
+       await userEvent.click(button);
+       await expect(button).toHaveTextContent('Clicked!');
+     }}
+   />
+   ```
+
+4. **Common Story Types**:
+   - **Default**: Basic component usage
+   - **Variants**: All visual variations
+   - **States**: Loading, error, success, empty
+   - **Sizes**: All size options
+   - **Interactive**: User interactions
+   - **Responsive**: Different viewports
+   - **Accessibility**: Focus and ARIA states
+   - **Edge Cases**: Long text, missing data
+
+5. **Advanced Features**:
+   
+   **Custom Render**:
+   ```svelte
+   <Story name="Grid">
+     {#snippet template()}
+       <div class="grid grid-cols-3 gap-4">
+         <Component variant="primary" />
+         <Component variant="secondary" />
+         <Component variant="tertiary" />
+       </div>
+     {/snippet}
+   </Story>
+   ```
+   
+   **With Decorators**:
+   ```javascript
+   export const DarkMode = {
+     decorators: [
+       (Story) => ({
+         Component: Story,
+         props: {
+           style: 'background: #333; padding: 2rem;'
+         }
+       })
+     ]
+   };
+   ```
+
+6. **Documentation**:
+   - Use JSDoc for props
+   - Add story descriptions
+   - Include usage examples
+   - Document accessibility
+   - Add design notes
+
+## Example Usage
+
+User: "Create stories for my Button component"
+
+Assistant will:
+- Analyze Button.svelte component
+- Create comprehensive stories file
+- Add all visual variants
+- Include interactive states
+- Test keyboard navigation
+- Add accessibility tests
+- Create responsive stories
+- Document all props
+- Add play functions for interactions

package/cli-tool/components/commands/svelte/svelte:storybook-troubleshoot.md

@@ -0,0 +1,191 @@
+# /svelte:storybook-troubleshoot
+
+Diagnose and fix common Storybook issues in SvelteKit projects, including build errors, module problems, and configuration issues.
+
+## Instructions
+
+You are acting as the Svelte Storybook Specialist Agent focused on troubleshooting. When diagnosing issues:
+
+1. **Common Build Errors**:
+   
+   **"__esbuild_register_import_meta_url__ already declared"**:
+   - Remove `svelteOptions` from `.storybook/main.js`
+   - This is a v6 to v7 migration issue
+   - Ensure using @storybook/sveltekit framework
+   
+   **Module Resolution Errors**:
+   ```javascript
+   // .storybook/main.js
+   export default {
+     framework: {
+       name: '@storybook/sveltekit',
+       options: {
+         builder: {
+           viteConfigPath: './vite.config.js'
+         }
+       }
+     },
+     viteFinal: async (config) => {
+       config.resolve.alias = {
+         ...config.resolve.alias,
+         $lib: path.resolve('./src/lib'),
+         $app: path.resolve('./.storybook/mocks/app')
+       };
+       return config;
+     }
+   };
+   ```
+
+2. **SvelteKit Module Issues**:
+   
+   **"Cannot find module '$app/stores'"**:
+   - These modules need mocking
+   - Use `parameters.sveltekit_experimental`
+   - Create mock files if needed:
+   ```javascript
+   // .storybook/mocks/app/stores.js
+   import { writable } from 'svelte/store';
+   
+   export const page = writable({
+     url: new URL('http://localhost:6006'),
+     params: {},
+     route: { id: '/' },
+     data: {}
+   });
+   
+   export const navigating = writable(null);
+   export const updated = writable(false);
+   ```
+
+3. **CSS and Styling Issues**:
+   
+   **Global Styles Not Loading**:
+   ```javascript
+   // .storybook/preview.js
+   import '../src/app.css';
+   import '../src/app.postcss';
+   import '../src/styles/global.css';
+   ```
+   
+   **Tailwind Not Working**:
+   ```javascript
+   // .storybook/main.js
+   export default {
+     addons: [
+       {
+         name: '@storybook/addon-postcss',
+         options: {
+           postcssLoaderOptions: {
+             implementation: require('postcss')
+           }
+         }
+       }
+     ]
+   };
+   ```
+
+4. **Component Import Issues**:
+   
+   **SSR Components**:
+   ```javascript
+   // Mark stories as client-only if needed
+   export const Default = {
+     parameters: {
+       storyshots: { disable: true } // Skip for SSR-incompatible
+     }
+   };
+   ```
+   
+   **Dynamic Imports**:
+   ```javascript
+   // Use lazy loading for heavy components
+   const HeavyComponent = lazy(() => import('./HeavyComponent.svelte'));
+   ```
+
+5. **Environment Variables**:
+   
+   **PUBLIC_ Variables Not Available**:
+   ```javascript
+   // .storybook/main.js
+   export default {
+     env: (config) => ({
+       ...config,
+       PUBLIC_API_URL: process.env.PUBLIC_API_URL || 'http://localhost:3000'
+     })
+   };
+   ```
+   
+   **Create .env for Storybook**:
+   ```bash
+   # .env.storybook
+   PUBLIC_API_URL=http://localhost:3000
+   PUBLIC_FEATURE_FLAG=true
+   ```
+
+6. **Performance Issues**:
+   
+   **Slow Build Times**:
+   - Exclude large dependencies
+   - Use production builds
+   - Enable caching
+   ```javascript
+   export default {
+     features: {
+       buildStoriesJson: true,
+       storyStoreV7: true
+     },
+     core: {
+       disableTelemetry: true
+     }
+   };
+   ```
+
+7. **Addon Conflicts**:
+   
+   **Version Mismatches**:
+   ```bash
+   # Check for version conflicts
+   npm ls @storybook/svelte
+   npm ls @storybook/sveltekit
+   
+   # Update all Storybook packages
+   npx storybook@latest upgrade
+   ```
+
+8. **Testing Issues**:
+   
+   **Play Functions Not Working**:
+   ```javascript
+   // Ensure testing library is set up
+   import { within, userEvent, expect } from '@storybook/test';
+   ```
+   
+   **Interaction Tests Failing**:
+   - Check element selectors
+   - Add proper waits
+   - Use data-testid attributes
+
+## Debugging Checklist
+
+1. [ ] Check Storybook and SvelteKit versions
+2. [ ] Verify framework configuration
+3. [ ] Check for module mocking needs
+4. [ ] Validate Vite configuration
+5. [ ] Review addon compatibility
+6. [ ] Test in isolation mode
+7. [ ] Check browser console errors
+8. [ ] Review build output
+
+## Example Usage
+
+User: "Storybook won't start, getting module errors"
+
+Assistant will:
+- Check error messages
+- Identify missing module mocks
+- Set up proper aliases
+- Configure module mocking
+- Fix import paths
+- Test the solution
+- Provide debugging steps
+- Document the fix for team

package/cli-tool/components/commands/svelte/svelte:storybook.md

@@ -0,0 +1,48 @@
+# /svelte:storybook
+
+General-purpose Storybook assistance for SvelteKit projects, including setup guidance, best practices, and common tasks.
+
+## Instructions
+
+You are acting as the Svelte Storybook Specialist Agent. Provide comprehensive assistance with Storybook for SvelteKit projects.
+
+1. **Assess the Request**:
+   - Determine if it's about setup, story creation, configuration, or troubleshooting
+   - Check the current Storybook setup in the project
+   - Identify specific Storybook version and addons
+
+2. **Common Tasks**:
+   - Setting up Storybook in a SvelteKit project
+   - Creating stories for components
+   - Configuring Storybook for SvelteKit modules
+   - Adding addons and customizations
+   - Optimizing Storybook performance
+   - Setting up visual testing
+
+3. **Best Practices**:
+   - Use Svelte CSF format for native syntax
+   - Implement proper mocking for SvelteKit modules
+   - Structure stories for maintainability
+   - Document components with controls and docs
+   - Set up accessibility testing
+
+4. **Guidance Areas**:
+   - Project structure for stories
+   - Naming conventions
+   - Story organization
+   - Addon selection
+   - Testing integration
+   - CI/CD setup
+
+## Example Usage
+
+User: "Help me set up Storybook for my component library"
+
+Assistant will:
+- Check if Storybook is already installed
+- Guide through installation if needed
+- Set up proper configuration
+- Create example stories
+- Configure essential addons
+- Provide project structure recommendations
+- Set up build and deployment scripts