@spaethtech/svelte-ui 0.1.10 → 0.3.1-dev.10.ff03a8d

package/docs/examples.md

@@ -0,0 +1,323 @@
+# Demo Page Standards
+
+This document defines the unified format for all component demo pages in the svelte-ui library.
+The live demo runs at **http://localhost:5173** (`npm run dev`).
+
+## Current State Analysis
+
+### Consistent Elements Found:
+
+- **Back navigation** - Button linking to main page
+- **Theme selector** - ThemeSelector component in header
+- **Component sections** - Grouped examples (variants, sizes, states)
+- **Code examples** - TextArea components showing code snippets
+
+### Inconsistencies Found:
+
+- **Import patterns** - Mixed usage of imports
+- **Layout structure** - Different container classes and layouts
+- **Header positioning** - Theme selector and back button placement varies
+- **Section organization** - Inconsistent section naming and ordering
+- **Code formatting** - Different TextArea configurations
+- **Missing elements** - Some pages lack back buttons or theme selectors
+
+## Standard Template
+
+All demo pages should follow this structure:
+
+### File Location
+
+```
+src/routes/[component-name]/+page.svelte
+```
+
+### Standard Template Structure
+
+```svelte
+<script lang="ts">
+  // IMPORTS - Use consistent library imports
+  import { ComponentName, Button, ThemeSelector, TextArea } from "$lib/index.js";
+  // Icons are MDI via unplugin-icons — import the ones this page uses.
+  import IconArrowLeft from "~icons/mdi/arrow-left";
+
+  // DEMO STATE - Component-specific state variables
+  let demoState = $state("initial");
+
+  // DEMO DATA - Static data for examples
+  const exampleData = [
+    { id: "1", name: "Example 1" },
+    { id: "2", name: "Example 2" },
+  ];
+</script>
+
+<!-- PAGE CONTAINER -->
+<div class="p-8 max-w-4xl mx-auto space-y-8">
+  <!-- HEADER -->
+  <div class="flex items-center justify-between flex-col sm:flex-row gap-4 mb-6">
+    <Button href="/" variant="ghost" text="Back to Components">
+      {#snippet icon()}<IconArrowLeft />{/snippet}
+    </Button>
+    <ThemeSelector />
+  </div>
+
+  <!-- PAGE TITLE -->
+  <h1 class="text-3xl font-bold mb-8">ComponentName Component</h1>
+
+  <!-- SECTION: Basic Usage -->
+  <section>
+    <h2 class="text-2xl font-semibold mb-4">Basic Usage</h2>
+    <div class="mb-6">
+      <!-- Example components -->
+      <ComponentName prop="value" />
+    </div>
+
+    <TextArea
+      value={`import { ComponentName } from '@spaethtech/svelte-ui';
+
+<ComponentName prop="value" />`}
+      readonly
+      textareaClass="font-mono text-sm"
+    />
+  </section>
+
+  <!-- SECTION: Variants (if applicable) -->
+  <section>
+    <h2 class="text-2xl font-semibold mb-4">Variants</h2>
+    <div class="flex gap-4 flex-wrap mb-6">
+      <ComponentName variant="primary" />
+      <ComponentName variant="secondary" />
+    </div>
+
+    <TextArea
+      value={`<ComponentName variant="primary" />
+<ComponentName variant="secondary" />`}
+      readonly
+      textareaClass="font-mono text-sm"
+    />
+  </section>
+
+  <!-- SECTION: Sizes (if applicable) -->
+  <section>
+    <h2 class="text-2xl font-semibold mb-4">Sizes</h2>
+    <div class="flex items-center gap-2 mb-6">
+      <ComponentName size="sm" />
+      <ComponentName size="md" />
+      <ComponentName size="lg" />
+    </div>
+
+    <TextArea
+      value={`<ComponentName size="sm" />
+<ComponentName size="md" />
+<ComponentName size="lg" />`}
+      readonly
+      textareaClass="font-mono text-sm"
+    />
+  </section>
+
+  <!-- SECTION: Interactive Examples -->
+  <section>
+    <h2 class="text-2xl font-semibold mb-4">Interactive Examples</h2>
+    <div class="mb-6">
+      <ComponentName bind:value={demoState} />
+    </div>
+
+    <TextArea
+      value={`<script>
+  let value = $state('');
+</script>
+
+<ComponentName bind:value />`}
+      readonly
+      textareaClass="font-mono text-sm"
+    />
+  </section>
+
+  <!-- SECTION: Advanced Features (if applicable) -->
+  <section>
+    <h2 class="text-2xl font-semibold mb-4">Advanced Features</h2>
+    <div class="mb-6">
+      <!-- Advanced examples -->
+    </div>
+
+    <TextArea value={`<!-- Advanced usage code -->`} readonly textareaClass="font-mono text-sm" />
+  </section>
+</div>
+```
+
+## Required Elements
+
+### 1. Container Structure
+
+```svelte
+<div class="p-8 max-w-4xl mx-auto space-y-8">
+```
+
+- **Padding**: `p-8` for consistent spacing
+- **Max width**: `max-w-4xl` for readability
+- **Centering**: `mx-auto` to center content
+- **Spacing**: `space-y-8` between sections
+
+### 2. Header Layout
+
+```svelte
+<div class="flex items-center justify-between flex-col sm:flex-row gap-4 mb-6">
+  <Button href="/" variant="ghost" text="Back to Components">
+    {#snippet icon()}<IconArrowLeft />{/snippet}
+  </Button>
+  <ThemeSelector />
+</div>
+```
+
+- **Responsive**: Stacks on mobile (`flex-col sm:flex-row`)
+- **Back button**: Links to main page with consistent styling
+- **Theme selector**: Always in top-right area
+
+### 3. Page Title
+
+```svelte
+<h1 class="text-3xl font-bold mb-8">ComponentName Component</h1>
+```
+
+- **Size**: `text-3xl` for prominence
+- **Weight**: `font-bold` for emphasis
+- **Spacing**: `mb-8` for separation
+
+### 4. Section Structure
+
+```svelte
+<section>
+  <h2 class="text-2xl font-semibold mb-4">Section Name</h2>
+  <div class="mb-6">
+    <!-- Examples -->
+  </div>
+
+  <TextArea value={`code example`} readonly textareaClass="font-mono text-sm" />
+</section>
+```
+
+### 5. Code Examples
+
+- **Always include** corresponding code for each example
+- **Use TextArea** component for code display
+- **Readonly**: Always `readonly`
+- **Styling**: `textareaClass="font-mono text-sm"`
+- **Import format**: Use `'@spaethtech/svelte-ui'` (not internal paths)
+
+## Standard Sections (in order)
+
+1. **Basic Usage** - Simplest implementation
+2. **Variants** - Different visual styles (if applicable)
+3. **Sizes** - Different size options (if applicable)
+4. **States** - Disabled, loading, error states (if applicable)
+5. **Interactive Examples** - Functional examples with state
+6. **Advanced Features** - Complex usage patterns
+7. **Accessibility** - A11y features demonstration (if notable)
+
+## Import Standards
+
+### Consistent Library Imports
+
+```svelte
+import {(ComponentName, Button, ThemeSelector, TextArea)} from '$lib/index.js';
+```
+
+### MDI Icons (unplugin-icons)
+
+Icons are MDI components imported from `~icons/mdi/*` and rendered into a component's `icon`
+snippet — there is no `Icon` component.
+
+```svelte
+import IconArrowLeft from '~icons/mdi/arrow-left'; import IconPencil from '~icons/mdi/pencil';
+```
+
+### Code Example Imports
+
+In TextArea code examples, always show:
+
+```javascript
+import { ComponentName } from "@spaethtech/svelte-ui";
+```
+
+## Responsive Design
+
+### Container Breakpoints
+
+- **Mobile**: Full width with padding
+- **Desktop**: Max-width container centered
+
+### Header Layout
+
+- **Mobile**: Stack vertically (back button top, theme selector bottom)
+- **Desktop**: Horizontal layout (back button left, theme selector right)
+
+### Example Layout
+
+- **Flex wrapping**: Use `flex-wrap` for button/badge groups
+- **Grid layouts**: Use responsive grids for complex examples
+
+## Code Example Best Practices
+
+### 1. Realistic Examples
+
+- Use meaningful prop values
+- Show practical use cases
+- Include realistic data
+
+### 2. Progressive Complexity
+
+- Start with simplest usage
+- Build up to more complex examples
+- Show common patterns
+
+### 3. Complete Code Snippets
+
+- Include necessary imports
+- Show complete functional examples
+- Include state management when relevant
+
+### 4. Consistent Formatting
+
+- Use 2-space indentation
+- Keep lines under 80 characters when possible
+- Use clear prop names
+
+## Component-Specific Guidelines
+
+### Form Components
+
+- Show validation examples
+- Demonstrate error states
+- Include accessibility attributes
+
+### Interactive Components
+
+- Show event handling
+- Demonstrate state binding
+- Include keyboard navigation
+
+### Layout Components
+
+- Show responsive behavior
+- Demonstrate different content types
+- Include slot usage
+
+### Theme Integration
+
+- Show theme-aware styling
+- Demonstrate CSS variable usage
+- Include light/dark mode examples
+
+## Quality Checklist
+
+Before considering a demo page complete:
+
+- [ ] Header with back button and theme selector
+- [ ] Consistent import statements
+- [ ] All major features demonstrated
+- [ ] Code examples for every visual example
+- [ ] Responsive layout tested
+- [ ] Accessibility considerations shown
+- [ ] Error-free TypeScript
+- [ ] Consistent styling and spacing
+- [ ] Realistic example data
+- [ ] Progressive complexity in examples

package/docs/paradigm.md

@@ -0,0 +1,240 @@
+# Development Paradigm
+
+This project uses **specification-driven development** (a form of behavior-driven development) where specifications are written before implementation. This paradigm ensures clear requirements, consistent implementation, and better testing.
+
+## Workflow Overview
+
+```mermaid
+graph LR
+    A[Write Spec] --> B[Review & Approve]
+    B --> C[Implement Component]
+    C --> D[Validate Against Spec]
+    D --> E[Write Tests]
+```
+
+## Interactive Commands
+
+### `/specify <component-name>`
+
+Creates a new component specification interactively.
+
+- Prompts for purpose, API, behavior, etc.
+- Generates `.spec.md` file
+- Sets up component folder structure
+
+### `/implement <component-name>`
+
+Implements a component from its specification.
+
+- Reads existing `.spec.md` file
+- Creates Svelte component following spec
+- Optionally creates tests and demo page
+
+### `/validate <component-name>`
+
+Validates implementation against specification.
+
+- Compares implementation with spec
+- Checks acceptance criteria
+- Reports discrepancies
+- Can auto-fix issues
+
+## Manual Workflow
+
+### 1. Write Specification
+
+Create `src/lib/components/ComponentName/ComponentName.spec.md`:
+
+```markdown
+# Component Specification: ComponentName
+
+## Overview
+
+- **Purpose**: What the component does
+- **User Story**: As a [user], I want to [action] so that [benefit]
+
+## API Contract
+
+### Props
+
+- `propName` (type, required/optional): Description
+- Default values and constraints
+
+### Events
+
+- `eventName`: When triggered, payload structure
+
+### Slots
+
+- Slot name and purpose
+
+## Behavior Specifications
+
+### Visual States
+
+- Default appearance
+- Interactive states (hover, focus, active)
+- Variant appearances
+
+### User Interactions
+
+- Click behavior
+- Keyboard navigation
+- Touch interactions
+
+### Accessibility Requirements
+
+- ARIA attributes
+- Keyboard support
+- Screen reader behavior
+
+## Performance Constraints
+
+- Bundle size limits
+- Rendering performance
+- Memory usage
+
+## Edge Cases
+
+- Empty states
+- Error states
+- Boundary conditions
+
+## Acceptance Criteria
+
+- [ ] Specific, testable requirements
+- [ ] Each item should be verifiable
+- [ ] Clear pass/fail conditions
+```
+
+### 2. Implement Component
+
+Create `src/lib/components/ComponentName/ComponentName.svelte`:
+
+```svelte
+<script lang="ts">
+  // Follow the specification exactly
+  interface Props {
+    // Props as defined in spec
+  }
+
+  let {} /* props */ : Props = $props();
+</script>
+
+<!-- Implementation matching spec -->
+```
+
+### 3. Create Tests
+
+Tests use **Playwright** (the project's test runner — `npm run test`). Create
+`src/lib/components/ComponentName/ComponentName.test.ts`:
+
+```typescript
+import { test, expect } from "@playwright/test";
+
+test.describe("ComponentName - Spec Validation", () => {
+  // Test each acceptance criterion against the rendered demo page.
+  test("meets acceptance criterion 1", async ({ page }) => {
+    await page.goto("/component-name");
+    // assertions…
+  });
+});
+```
+
+### 4. Export Component
+
+Add to `src/lib/index.ts`:
+
+```typescript
+export { default as ComponentName } from "./components/ComponentName/ComponentName.svelte";
+```
+
+## Component Structure
+
+### Colocated Structure (Recommended)
+
+```
+src/lib/components/
+└── ComponentName/
+    ├── ComponentName.spec.md    # Write first
+    ├── ComponentName.svelte     # Implement second
+    ├── ComponentName.test.ts    # Test third
+    └── index.ts                 # Export
+```
+
+### Benefits
+
+1. **Clear Requirements**: Specs define exactly what to build
+2. **Consistent Implementation**: All components follow same pattern
+3. **Better Testing**: Tests validate against documented requirements
+4. **Living Documentation**: Specs serve as component documentation
+5. **Reduced Iterations**: Clear specs mean fewer revisions
+
+## Example: Badge Component
+
+### 1. Specification (Badge.spec.md)
+
+```markdown
+# Component Specification: Badge
+
+## Overview
+
+- **Purpose**: Display status indicators or labels
+- **User Story**: As a developer, I want to display badges with consistent styling
+
+## API Contract
+
+### Props
+
+- `text` (string, required): Display text
+- `variant` (string, optional): Visual style
+- `size` (string, optional): Size variant
+- `dismissible` (boolean, optional): Show dismiss button
+```
+
+### 2. Implementation (Badge.svelte)
+
+```svelte
+<script lang="ts">
+  interface Props {
+    text: string;
+    variant?: "default" | "primary" | "success";
+    size?: "sm" | "md" | "lg";
+    dismissible?: boolean;
+  }
+
+  let { text, variant = "default", size = "md", dismissible = false }: Props = $props();
+</script>
+
+<span class="badge badge-{variant} badge-{size}">
+  {text}
+  {#if dismissible}
+    <button onclick={() => dispatch("dismiss")}>×</button>
+  {/if}
+</span>
+```
+
+## Best Practices
+
+1. **Write specs before code** - Never implement without a spec
+2. **Include acceptance criteria** - Make requirements testable
+3. **Update specs when requirements change** - Keep documentation current
+4. **Use `/validate` after changes** - Ensure compliance
+5. **Reference specs in PRs** - Link implementation to requirements
+
+## Tips for Writing Good Specs
+
+- Be specific about behavior, not implementation
+- Include all edge cases
+- Define clear acceptance criteria
+- Consider accessibility from the start
+- Think about theme compatibility
+- Document performance requirements
+
+## Common Pitfalls to Avoid
+
+- Don't skip the spec phase
+- Don't implement features not in the spec
+- Don't modify specs after implementation (unless updating both)
+- Don't write vague acceptance criteria
+- Don't forget accessibility requirements