@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/storybook-patterns.md

@@ -0,0 +1,330 @@
+---
+name: storybook-patterns
+description: Storybook patterns for CSF3 stories, args, decorators, play functions, visual regression testing, and addon configuration.
+---
+
+# Storybook Patterns
+
+## When to Use
+Use Storybook to develop, document, and test UI components in isolation. These patterns cover Component Story Format 3 (CSF3), args-based stories, decorators for context providers, play functions for interaction testing, and visual regression testing. Storybook is essential when building a component library, onboarding new developers, or establishing visual QA workflows.
+
+## How It Works
+
+### CSF3 Story Structure
+
+```typescript
+// components/Button/Button.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button } from './Button';
+
+const meta = {
+  title: 'Components/Button',
+  component: Button,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: { component: 'Primary UI button with multiple variants and sizes.' },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'ghost', 'danger'],
+      description: 'Visual style variant',
+      table: { defaultValue: { summary: 'primary' } },
+    },
+    size: {
+      control: 'radio',
+      options: ['sm', 'md', 'lg'],
+    },
+    disabled: { control: 'boolean' },
+    loading: { control: 'boolean' },
+    onClick: { action: 'clicked' },
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Primary: Story = {
+  args: { children: 'Button', variant: 'primary', size: 'md' },
+};
+
+export const Secondary: Story = {
+  args: { children: 'Button', variant: 'secondary' },
+};
+
+export const Loading: Story = {
+  args: { children: 'Saving...', loading: true },
+};
+
+export const Disabled: Story = {
+  args: { children: 'Unavailable', disabled: true },
+};
+```
+
+### Composite Stories (All Variants)
+
+```typescript
+export const AllVariants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <div className="flex gap-2 items-center">
+        {(['primary', 'secondary', 'ghost', 'danger'] as const).map((variant) => (
+          <Button key={variant} variant={variant}>{variant}</Button>
+        ))}
+      </div>
+      <div className="flex gap-2 items-center">
+        {(['sm', 'md', 'lg'] as const).map((size) => (
+          <Button key={size} size={size}>Size {size}</Button>
+        ))}
+      </div>
+    </div>
+  ),
+  parameters: { controls: { disable: true } },
+};
+
+export const DarkMode: Story = {
+  args: { children: 'Dark Mode', variant: 'primary' },
+  decorators: [
+    (Story) => (
+      <div className="dark bg-gray-900 p-8 rounded-lg">
+        <Story />
+      </div>
+    ),
+  ],
+};
+```
+
+### Decorators (Context Providers)
+
+```typescript
+// .storybook/preview.tsx
+import type { Preview } from '@storybook/react';
+import { ThemeProvider } from '../src/providers/ThemeProvider';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import '../src/styles/globals.css';
+
+const queryClient = new QueryClient({
+  defaultOptions: { queries: { retry: false, staleTime: Infinity } },
+});
+
+const preview: Preview = {
+  decorators: [
+    // Theme provider wrapper
+    (Story, context) => (
+      <ThemeProvider defaultTheme={context.globals.theme ?? 'light'}>
+        <Story />
+      </ThemeProvider>
+    ),
+    // React Query provider
+    (Story) => (
+      <QueryClientProvider client={queryClient}>
+        <Story />
+      </QueryClientProvider>
+    ),
+    // Layout padding
+    (Story) => (
+      <div className="p-4">
+        <Story />
+      </div>
+    ),
+  ],
+  globalTypes: {
+    theme: {
+      description: 'Global theme',
+      toolbar: {
+        title: 'Theme',
+        icon: 'circlehollow',
+        items: ['light', 'dark'],
+        dynamicTitle: true,
+      },
+    },
+  },
+  parameters: {
+    actions: { argTypesRegex: '^on[A-Z].*' },
+    controls: { matchers: { color: /(background|color)$/i, date: /Date$/i } },
+  },
+};
+
+export default preview;
+```
+
+### Play Functions (Interaction Testing)
+
+```typescript
+// components/LoginForm/LoginForm.stories.tsx
+import { within, userEvent, expect, waitFor } from '@storybook/test';
+
+export const FilledForm: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Type into email field
+    const emailInput = canvas.getByLabelText('Email');
+    await userEvent.clear(emailInput);
+    await userEvent.type(emailInput, 'user@example.com');
+
+    // Type into password field
+    const passwordInput = canvas.getByLabelText('Password');
+    await userEvent.clear(passwordInput);
+    await userEvent.type(passwordInput, 'SecurePass123');
+
+    // Verify values
+    expect(emailInput).toHaveValue('user@example.com');
+    expect(passwordInput).toHaveValue('SecurePass123');
+  },
+};
+
+export const SubmitWithValidation: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Submit empty form
+    const submitButton = canvas.getByRole('button', { name: /sign in/i });
+    await userEvent.click(submitButton);
+
+    // Check validation errors
+    await waitFor(() => {
+      expect(canvas.getByText('Email is required')).toBeInTheDocument();
+    });
+
+    // Fill and submit
+    await userEvent.type(canvas.getByLabelText('Email'), 'user@example.com');
+    await userEvent.type(canvas.getByLabelText('Password'), 'SecurePass123');
+    await userEvent.click(submitButton);
+
+    // Verify errors cleared
+    await waitFor(() => {
+      expect(canvas.queryByText('Email is required')).not.toBeInTheDocument();
+    });
+  },
+};
+```
+
+### MSW Integration (Mocked API)
+
+```typescript
+// components/UserProfile/UserProfile.stories.tsx
+import { http, HttpResponse } from 'msw';
+
+export const WithData: Story = {
+  parameters: {
+    msw: {
+      handlers: [
+        http.get('/api/user/profile', () =>
+          HttpResponse.json({
+            name: 'Jane Doe',
+            email: 'jane@example.com',
+            avatar: 'https://placekitten.com/200/200',
+          })
+        ),
+      ],
+    },
+  },
+};
+
+export const Loading: Story = {
+  parameters: {
+    msw: {
+      handlers: [
+        http.get('/api/user/profile', async () => {
+          await new Promise((r) => setTimeout(r, 999999)); // never resolves
+          return HttpResponse.json({});
+        }),
+      ],
+    },
+  },
+};
+
+export const Error: Story = {
+  parameters: {
+    msw: {
+      handlers: [
+        http.get('/api/user/profile', () =>
+          HttpResponse.json({ error: 'Unauthorized' }, { status: 401 })
+        ),
+      ],
+    },
+  },
+};
+```
+
+### Visual Regression with Chromatic
+
+```typescript
+// .storybook/main.ts
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(ts|tsx)'],
+  addons: [
+    '@storybook/addon-essentials',
+    '@storybook/addon-interactions',
+    '@storybook/addon-a11y',
+    '@chromatic-com/storybook',
+  ],
+  framework: '@storybook/react-vite',
+};
+
+export default config;
+```
+
+```yaml
+# .github/workflows/chromatic.yml
+name: Visual Tests
+on: push
+jobs:
+  chromatic:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: npm }
+      - run: npm ci
+      - uses: chromaui/action@latest
+        with:
+          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
+          exitOnceUploaded: true
+```
+
+### Accessibility Testing Addon
+
+```typescript
+// Per-story a11y configuration
+export const AccessibleButton: Story = {
+  args: { children: 'Click me', variant: 'primary' },
+  parameters: {
+    a11y: {
+      config: {
+        rules: [
+          { id: 'color-contrast', enabled: true },
+          { id: 'button-name', enabled: true },
+        ],
+      },
+    },
+  },
+};
+```
+
+## Examples
+
+| Story Type | Purpose | Key Feature |
+|------------|---------|-------------|
+| Args-based | Default prop permutations | Controls panel auto-generated |
+| Composite render | All variants at once | Visual comparison grid |
+| Play function | Interaction simulation | Click, type, assert in browser |
+| MSW handler | API state simulation | Loading, success, error states |
+| Chromatic snapshot | Visual regression | Pixel-diff on every PR |
+
+## Checklist
+- [ ] Stories use CSF3 format with `satisfies Meta<typeof Component>`
+- [ ] `argTypes` defined for every configurable prop with descriptions
+- [ ] `tags: ['autodocs']` enabled for automatic documentation generation
+- [ ] Decorators provide all necessary context (theme, router, query client)
+- [ ] Play functions test critical interaction flows with assertions
+- [ ] MSW handlers mock all API states (success, loading, error)
+- [ ] `@storybook/addon-a11y` enabled for accessibility violation detection
+- [ ] Visual regression testing configured (Chromatic or Percy) in CI

package/assets/skills/svelte-patterns.md

@@ -0,0 +1,258 @@
+---
+name: svelte-patterns
+description: Svelte patterns for reactivity, stores, actions, transitions, SvelteKit routing, and load functions.
+---
+
+# Svelte Patterns
+
+## When to Use
+
+Apply these patterns when building Svelte 4/5 or SvelteKit applications. Use this
+skill for understanding Svelte's reactivity model, creating and using stores,
+adding DOM behavior with actions, animating with transitions, and structuring
+SvelteKit routes with load functions.
+
+## How It Works
+
+### Reactivity
+
+Svelte's reactivity is compile-time. In Svelte 4, use `$:` for reactive
+declarations. In Svelte 5 (runes), use `$state`, `$derived`, and `$effect`.
+
+```svelte
+<!-- Svelte 5 (runes) -->
+<script lang="ts">
+  let count = $state(0)
+  let doubled = $derived(count * 2)
+  let items = $state<string[]>([])
+
+  $effect(() => {
+    console.log(`Count changed to ${count}`)
+    // cleanup returned automatically on re-run
+    return () => console.log('cleaning up')
+  })
+
+  function addItem(text: string) {
+    items.push(text) // mutations tracked automatically with runes
+  }
+</script>
+
+<button onclick={() => count++}>
+  {count} (doubled: {doubled})
+</button>
+```
+
+```svelte
+<!-- Svelte 4 (legacy reactive) -->
+<script lang="ts">
+  let count = 0
+  $: doubled = count * 2
+  $: if (count > 10) {
+    console.log('count is high')
+  }
+</script>
+```
+
+### Stores
+
+Use writable stores for shared state. Use derived stores for computed values.
+Use readable stores for external data sources. Subscribe with `$store` syntax.
+
+```typescript
+// stores/auth.ts
+import { writable, derived } from 'svelte/store'
+
+interface User { id: string; name: string; role: string }
+
+export const currentUser = writable<User | null>(null)
+export const isAuthenticated = derived(currentUser, $user => $user !== null)
+export const isAdmin = derived(currentUser, $user => $user?.role === 'admin')
+
+export function login(credentials: Credentials) {
+  return api.login(credentials).then(user => {
+    currentUser.set(user)
+  })
+}
+
+export function logout() {
+  currentUser.set(null)
+}
+```
+
+```svelte
+<script>
+  import { currentUser, isAuthenticated, logout } from '$lib/stores/auth'
+</script>
+
+{#if $isAuthenticated}
+  <p>Welcome, {$currentUser.name}</p>
+  <button onclick={logout}>Logout</button>
+{:else}
+  <a href="/login">Sign in</a>
+{/if}
+```
+
+### Actions
+
+Actions add reusable DOM behavior to elements. Use them for click-outside
+detection, tooltips, focus traps, and intersection observers.
+
+```typescript
+// actions/clickOutside.ts
+export function clickOutside(node: HTMLElement, callback: () => void) {
+  function handleClick(event: MouseEvent) {
+    if (!node.contains(event.target as Node)) {
+      callback()
+    }
+  }
+
+  document.addEventListener('click', handleClick, true)
+
+  return {
+    destroy() {
+      document.removeEventListener('click', handleClick, true)
+    }
+  }
+}
+
+// actions/lazyLoad.ts
+export function lazyLoad(node: HTMLImageElement) {
+  const observer = new IntersectionObserver((entries) => {
+    entries.forEach(entry => {
+      if (entry.isIntersecting) {
+        const src = node.dataset.src
+        if (src) node.src = src
+        observer.unobserve(node)
+      }
+    })
+  })
+  observer.observe(node)
+  return { destroy: () => observer.disconnect() }
+}
+```
+
+```svelte
+<div use:clickOutside={() => menuOpen = false}>
+  <DropdownMenu bind:open={menuOpen} />
+</div>
+
+<img use:lazyLoad data-src="/large-image.jpg" alt="Lazy loaded" />
+```
+
+### Transitions
+
+Svelte has built-in transition directives. Use `transition:` for enter+leave,
+`in:` and `out:` for separate control. Combine with `animate:flip` for list
+reordering.
+
+```svelte
+<script>
+  import { fade, slide, fly } from 'svelte/transition'
+  import { flip } from 'svelte/animate'
+
+  let items = $state([...])
+  let visible = $state(true)
+</script>
+
+{#if visible}
+  <div transition:fade={{ duration: 200 }}>
+    Fades in and out
+  </div>
+{/if}
+
+{#each items as item (item.id)}
+  <div
+    animate:flip={{ duration: 300 }}
+    in:fly={{ y: 20, duration: 200 }}
+    out:fade={{ duration: 150 }}
+  >
+    {item.text}
+  </div>
+{/each}
+```
+
+### SvelteKit Routing
+
+File-based routing with `+page.svelte`, `+layout.svelte`, `+page.server.ts`.
+Use `+page.ts` for universal load, `+page.server.ts` for server-only load.
+
+```
+routes/
+  +layout.svelte          # root layout
+  +page.svelte            # home page
+  projects/
+    +page.svelte          # /projects
+    +page.server.ts       # server load for /projects
+    [id]/
+      +page.svelte        # /projects/:id
+      +page.ts            # universal load
+      +error.svelte       # error boundary
+```
+
+### Load Functions
+
+Use `load` functions to fetch data before rendering. Return data as plain objects.
+Use `depends` for invalidation. Throw `error()` for error pages.
+
+```typescript
+// routes/projects/[id]/+page.server.ts
+import { error } from '@sveltejs/kit'
+import type { PageServerLoad } from './$types'
+
+export const load: PageServerLoad = async ({ params, locals }) => {
+  const project = await db.project.findUnique({
+    where: { id: params.id, ownerId: locals.userId }
+  })
+
+  if (!project) {
+    throw error(404, 'Project not found')
+  }
+
+  return {
+    project,
+    tasks: await db.task.findMany({ where: { projectId: params.id } })
+  }
+}
+```
+
+```svelte
+<!-- routes/projects/[id]/+page.svelte -->
+<script lang="ts">
+  import type { PageData } from './$types'
+  let { data }: { data: PageData } = $props()
+</script>
+
+<h1>{data.project.name}</h1>
+{#each data.tasks as task}
+  <TaskCard {task} />
+{/each}
+```
+
+## Examples
+
+**Pattern: Form action with progressive enhancement**
+```typescript
+// +page.server.ts
+export const actions = {
+  default: async ({ request }) => {
+    const data = await request.formData()
+    const name = data.get('name') as string
+    if (!name) return fail(400, { name, missing: true })
+    await db.project.create({ data: { name } })
+    throw redirect(303, '/projects')
+  }
+}
+```
+
+## Checklist
+
+- [ ] Svelte 5 runes (`$state`, `$derived`, `$effect`) over `$:` reactive statements
+- [ ] Stores for shared cross-component state; `$store` for auto-subscriptions
+- [ ] Actions (`use:action`) for reusable DOM behavior with proper `destroy` cleanup
+- [ ] Transitions use built-in directives (`transition:`, `in:`, `out:`)
+- [ ] `animate:flip` on `{#each}` blocks with keyed items for smooth reordering
+- [ ] SvelteKit load functions return plain objects, throw `error()` for error pages
+- [ ] Server-only data in `+page.server.ts`, universal data in `+page.ts`
+- [ ] Form actions with `fail()` for validation errors, `redirect()` for success
+- [ ] `$effect` cleanup functions returned for subscriptions and listeners
+- [ ] `{#snippet}` blocks (Svelte 5) for reusable template fragments