svelte-toggle-switch 1.0.0 → 2.0.0

package/CLAUDE.md

@@ -0,0 +1,165 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is an NPM package providing a comprehensive, accessible toggle switch component for Svelte applications. The package has been completely rewritten in version 2.0 with TypeScript support, multiple design variants, extensive customization options, and enhanced accessibility features.
+
+## Development Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server with hot reload
+npm run dev
+
+# Build the package for distribution
+npm run build
+
+# Preview production build
+npm run preview
+
+# Run TypeScript type checking
+npm run check
+```
+
+## Tech Stack
+
+- **Svelte 5.16.0**: Latest Svelte with runes support
+- **TypeScript 5.7.3**: Full type safety
+- **Vite 6.0.5**: Fast build tooling
+- **svelte-check**: TypeScript checking for Svelte files
+
+## Architecture
+
+### Component Structure
+
+The main component is located at `src/lib/Switch.svelte`. This single component supports five distinct design variants controlled by the `design` prop:
+
+- **slider/ios**: iOS-style toggle switch (default)
+- **inner**: Toggle button with visible ON/OFF text
+- **modern**: Enhanced slider with optional track icons
+- **material**: Google Material Design inspired toggle
+- **multi**: Radio group styled as a segmented control
+
+### Component API Design
+
+The component uses a comprehensive props-based API with full TypeScript support:
+
+#### Core Props
+- `value`: Two-way bound state (boolean or string for multi design)
+- `label`: Accessible label text
+- `design`: Design variant selector
+
+#### Styling System
+- **Color Schemes**: 6 built-in schemes (blue, green, red, purple, orange, pink) + custom
+- **Size Variants**: xs, sm, md, lg, xl (mapped to rem values) or custom number
+- **Visual Options**: shadow, outline, rounded, labelPosition
+
+#### State Management
+- `disabled`: Prevents interaction, shows disabled UI
+- `loading`: Shows spinner animation, prevents interaction
+- `readonly`: Prevents changes but shows current state
+
+#### Icon System
+- `showIcons`: Enable icon display
+- `onIcon`/`offIcon`: Customizable icons (text/emoji/symbols)
+- Icons displayed differently per design variant
+
+#### Animation Customization
+- `animationDuration`: Transition duration in ms (default 300)
+- `animationEasing`: CSS easing function (default 'ease-in-out')
+
+#### Accessibility
+- `ariaLabel`: Custom ARIA label
+- `ariaDescribedBy`: Links to description element
+- `id`: Custom element ID (auto-generated if not provided)
+
+### State Management
+
+The component uses Svelte's reactive statements (`$:`) to sync internal and external state:
+
+1. **For slider/inner/modern/material designs**:
+   - Internal `checked` boolean tracks state
+   - Syncs with `value` prop (boolean or 'on'/'off' string)
+   - Two-way binding via `bind:value`
+
+2. **For multi design**:
+   - Uses native radio input `bind:group`
+   - Value is one of the strings from `options` array
+   - No internal checked state needed
+
+3. **Unique IDs**:
+   - Auto-generated using `Math.floor(Math.random() * 1000000)`
+   - Used for ARIA attributes (`aria-labelledby`, `id` attributes)
+   - Can be overridden via `id` prop
+
+### Accessibility Implementation
+
+Comprehensive ARIA and keyboard support:
+
+- **ARIA Roles**: `role="switch"` for toggles, `role="radiogroup"` for multi
+- **State Attributes**: `aria-checked` reflects current state
+- **Labeling**: `aria-labelledby` connects visual labels, `aria-describedby` for descriptions
+- **Keyboard Navigation**: Space and Enter keys toggle state
+- **Focus Management**: `:focus-visible` for keyboard-only focus rings
+- **Disabled State**: Properly communicated to assistive technologies
+
+### Styling Architecture
+
+All styles are scoped within the component using Svelte's `<style>` block:
+
+- **CSS Custom Properties**: Used for theming (`--active-color`, `--off-color`, `--animation-duration`, `--animation-easing`)
+- **Design-Specific Classes**: `.switch--slider`, `.switch--inner`, `.switch--modern`, `.switch--material`, `.switch-multi`
+- **State Classes**: `.checked`, `.disabled`, `.loading`, `.shadow`, `.outline`
+- **Conditional Rendering**: `{#if design === 'variant'}` blocks for each design
+- **No External Dependencies**: Self-contained styling, no CSS framework required
+
+### TypeScript Integration
+
+The component is written in TypeScript (`<script lang="ts">`):
+
+- All props have explicit type annotations
+- Union types for variant options (design, size, colorScheme)
+- Event handlers properly typed (MouseEvent, KeyboardEvent)
+- Exported types available for consumers
+
+### Demo Application
+
+`src/App.svelte` serves as a comprehensive showcase of all component features:
+
+- Organized into sections by feature category
+- Interactive examples with state display
+- Beautiful gradient background with card-based layout
+- Responsive design for mobile devices
+- Not included in the distributed package (development only)
+
+## Build Configuration
+
+### Vite Config
+- Library mode enabled with entry point `src/lib/Switch.svelte`
+- Package name: 'SvelteToggleSwitch'
+- Standard Svelte plugin configuration
+
+### TypeScript Config
+- Extends `@tsconfig/svelte` base configuration
+- ESNext target for modern JavaScript
+- Includes all `.svelte`, `.ts`, `.js`, and `.d.ts` files in `src/`
+- Composite project with references to `tsconfig.node.json`
+
+### Package Configuration
+- Version 2.0.0 (major rewrite)
+- Peer dependency: Svelte 3.x, 4.x, or 5.x
+- Development dependencies all on latest versions
+- MIT licensed
+
+## Key Design Decisions
+
+1. **Single Component Approach**: All variants in one component file for easier maintenance
+2. **CSS-in-JS via Custom Properties**: Enables dynamic theming without style duplication
+3. **Progressive Enhancement**: Basic functionality without JavaScript, enhanced with interactivity
+4. **Accessibility First**: ARIA and keyboard support built-in, not added later
+5. **TypeScript Throughout**: Type safety for better DX and fewer runtime errors
+6. **Zero Dependencies**: No runtime dependencies beyond Svelte peer dependency

package/README.md

@@ -1,54 +1,399 @@
 # Svelte Toggle Switch
 
-## Install
+A comprehensive, accessible, and highly customizable toggle switch component for Svelte applications. Built with TypeScript and designed with accessibility in mind.
 
-Install using NPM
+## Features
 
-```js
-npm i svelte-toggle-switch
-```
+✨ **5 Design Variants**: Slider (iOS), Inner, Modern, Material, and Multi-option\
+🎨 **Multiple Color Schemes**: 6 built-in schemes + custom colors\
+📏 **5 Size Options**: From extra small to extra large\
+♿ **Fully Accessible**: ARIA attributes, keyboard navigation, screen reader support\
+🔄 **State Management**: Disabled, loading, and read-only states\
+🎯 **Icon Support**: Custom icons with flexible positioning\
+⚡ **Smooth Animations**: Customizable duration and easing\
+📦 **TypeScript**: Full TypeScript support with proper types\
+🎭 **Flexible Styling**: Shadow, outline, and label positioning options\
+🚀 **Modern Stack**: Built with Svelte 5, Vite 6, and TypeScript 5
+
+## Installation
 
-Install using YARN
+### NPM
+```bash
+npm install svelte-toggle-switch
+```
 
-```js
+### Yarn
+```bash
 yarn add svelte-toggle-switch
 ```
 
-## How to use
+### PNPM
+```bash
+pnpm add svelte-toggle-switch
+```
+
+## Quick Start
+
+```svelte
+<script>
+  import Switch from 'svelte-toggle-switch';
+
+  let enabled = false;
+</script>
+
+<Switch bind:value={enabled} label="Enable notifications" />
+```
+
+## Design Variants
+
+### Slider (iOS Style)
+The default design, inspired by iOS toggles.
+
+```svelte
+<Switch bind:value={enabled} label="Enable dark mode" design="slider" />
+```
+
+### Inner
+Toggle with visible ON/OFF text inside the button.
+
+```svelte
+<Switch bind:value={enabled} label="Auto-save" design="inner" />
+```
+
+### Modern
+Enhanced slider with optional icon displays on the track.
+
+```svelte
+<Switch
+  bind:value={enabled}
+  label="Wi-Fi"
+  design="modern"
+  showIcons={true}
+  onIcon="✓"
+  offIcon="✕"
+/>
+```
+
+### Material
+Google Material Design inspired toggle.
+
+```svelte
+<Switch bind:value={enabled} label="Bluetooth" design="material" />
+```
+
+### Multi-option
+Radio group styled as a segmented control.
+
+```svelte
+<Switch
+  bind:value={selectedOption}
+  label="View mode"
+  design="multi"
+  options={['Grid', 'List', 'Table']}
+/>
+```
+
+## Color Schemes
+
+6 built-in color schemes plus custom color support.
+
+```svelte
+<!-- Built-in schemes -->
+<Switch bind:value={enabled} colorScheme="blue" />
+<Switch bind:value={enabled} colorScheme="green" />
+<Switch bind:value={enabled} colorScheme="red" />
+<Switch bind:value={enabled} colorScheme="purple" />
+<Switch bind:value={enabled} colorScheme="orange" />
+<Switch bind:value={enabled} colorScheme="pink" />
+
+<!-- Custom colors -->
+<Switch
+  bind:value={enabled}
+  colorScheme="custom"
+  color="#FF6B6B"
+  offColor="#F0F0F0"
+/>
+```
+
+## Size Variants
+
+```svelte
+<Switch bind:value={enabled} size="xs" label="Extra Small" />
+<Switch bind:value={enabled} size="sm" label="Small" />
+<Switch bind:value={enabled} size="md" label="Medium (Default)" />
+<Switch bind:value={enabled} size="lg" label="Large" />
+<Switch bind:value={enabled} size="xl" label="Extra Large" />
+
+<!-- Custom size (in rem) -->
+<Switch bind:value={enabled} size={2} label="Custom Size" />
+```
+
+## States
+
+### Disabled
+```svelte
+<Switch bind:value={enabled} label="Disabled" disabled />
+```
+
+### Loading
+Shows a spinner animation.
+
+```svelte
+<Switch bind:value={enabled} label="Loading..." loading />
+```
+
+### Read-only
+Displays current state without allowing changes.
+
+```svelte
+<Switch bind:value={enabled} label="Read-only" readonly />
+```
+
+## Icons
+
+Add custom icons to your toggles.
+
+```svelte
+<!-- Slider with icons -->
+<Switch
+  bind:value={enabled}
+  label="Theme"
+  showIcons={true}
+  onIcon="🌙"
+  offIcon="☀"
+/>
+
+<!-- Modern design with track icons -->
+<Switch
+  bind:value={enabled}
+  label="Airplane Mode"
+  design="modern"
+  showIcons={true}
+  onIcon="✈"
+  offIcon="✕"
+/>
+```
+
+## Advanced Customization
+
+### Label Position
+```svelte
+<Switch
+  bind:value={enabled}
+  label="Label on left"
+  labelPosition="left"
+/>
+```
+
+### Visual Enhancements
+```svelte
+<!-- With shadow -->
+<Switch bind:value={enabled} label="Shadow effect" shadow />
+
+<!-- With outline -->
+<Switch bind:value={enabled} label="Outline style" outline />
+
+<!-- Without rounded corners (inner design only) -->
+<Switch bind:value={enabled} design="inner" rounded={false} />
+```
+
+### Custom Animations
+```svelte
+<Switch
+  bind:value={enabled}
+  label="Custom animation"
+  animationDuration={800}
+  animationEasing="cubic-bezier(0.68, -0.55, 0.265, 1.55)"
+/>
+```
+
+### Accessibility Props
+```svelte
+<Switch
+  bind:value={enabled}
+  id="custom-id"
+  ariaLabel="Toggle notifications"
+  ariaDescribedBy="notification-description"
+/>
+```
+
+## Complete API Reference
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `boolean \| string` | `false` | Current value (use with `bind:value`) |
+| `label` | `string` | `''` | Label text displayed next to the switch |
+| `design` | `'inner' \| 'slider' \| 'modern' \| 'ios' \| 'material' \| 'multi'` | `'slider'` | Visual design variant |
+| `options` | `string[]` | `[]` | Options array (required for `multi` design) |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number` | `'md'` | Size variant or custom size in rem |
+| `color` | `string` | `'#007AFF'` | Custom active color (CSS color value) |
+| `offColor` | `string` | `'#E5E7EB'` | Custom inactive color (CSS color value) |
+| `colorScheme` | `'blue' \| 'green' \| 'red' \| 'purple' \| 'orange' \| 'pink' \| 'custom'` | `'blue'` | Built-in color scheme |
+| `disabled` | `boolean` | `false` | Disables interaction |
+| `loading` | `boolean` | `false` | Shows loading spinner |
+| `readonly` | `boolean` | `false` | Makes switch read-only |
+| `showIcons` | `boolean` | `false` | Display icons on the switch |
+| `onIcon` | `string` | `'✓'` | Icon shown when active |
+| `offIcon` | `string` | `'✕'` | Icon shown when inactive |
+| `animationDuration` | `number` | `300` | Animation duration in milliseconds |
+| `animationEasing` | `string` | `'ease-in-out'` | CSS easing function |
+| `ariaLabel` | `string` | `''` | ARIA label for accessibility |
+| `ariaDescribedBy` | `string` | `''` | ARIA described-by attribute |
+| `id` | `string` | auto-generated | Custom element ID |
+| `labelPosition` | `'left' \| 'right'` | `'right'` | Position of the label |
+| `rounded` | `boolean` | `true` | Use rounded corners (inner design) |
+| `shadow` | `boolean` | `false` | Add box shadow |
+| `outline` | `boolean` | `false` | Add border outline |
+
+## Accessibility
+
+This component follows WAI-ARIA best practices:
+
+- Proper `role="switch"` and `role="radiogroup"` attributes
+- `aria-checked` state management
+- `aria-labelledby` and `aria-describedby` support
+- Full keyboard navigation (Space and Enter keys)
+- Focus indicators with `:focus-visible`
+- Screen reader friendly
+- Disabled state properly communicated
+
+## Browser Support
+
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- iOS Safari (latest)
+- Chrome for Android (latest)
+
+## TypeScript
+
+This package includes TypeScript definitions. All props are fully typed for the best development experience.
+
+```typescript
+import type { ComponentProps } from 'svelte';
+import Switch from 'svelte-toggle-switch';
+
+type SwitchProps = ComponentProps<Switch>;
+```
 
-```js
+## Examples
+
+### Dark Mode Toggle
+```svelte
+<script>
+  let darkMode = false;
+
+  $: if (darkMode) {
+    document.documentElement.classList.add('dark');
+  } else {
+    document.documentElement.classList.remove('dark');
+  }
+</script>
+
+<Switch
+  bind:value={darkMode}
+  label="Dark mode"
+  showIcons={true}
+  onIcon="🌙"
+  offIcon="☀"
+  colorScheme="purple"
+/>
+```
+
+### Form Integration
+```svelte
+<script>
+  let formData = {
+    notifications: false,
+    marketing: false,
+    newsletter: true
+  };
+</script>
+
+<form>
+  <Switch bind:value={formData.notifications} label="Push notifications" />
+  <Switch bind:value={formData.marketing} label="Marketing emails" />
+  <Switch bind:value={formData.newsletter} label="Newsletter" />
+</form>
+```
+
+### Async Toggle
+```svelte
 <script>
-import Select from 'svelte-toggle-switch';
+  let enabled = false;
+  let loading = false;
 
-let switchValue;
-let sliderValue;
-let multiValue;
+  async function handleToggle() {
+    loading = true;
+    try {
+      await api.updateSetting(enabled);
+    } catch (error) {
+      // Revert on error
+      enabled = !enabled;
+    } finally {
+      loading = false;
+    }
+  }
 
+  $: if (enabled !== undefined) {
+    handleToggle();
+  }
 </script>
 
-<Switch bind:value={switchValue} label="Enable Toggle" design="inner" />
-<p>
-	Switch is {switchValue}
-</p>
+<Switch bind:value={enabled} {loading} label="Enable feature" />
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
 
-<Switch bind:value={sliderValue} label="Enable Toggle" fontSize={24} design="slider" />
-<p>
-	Switch is {sliderValue}
-</p>
+# Start development server
+npm run dev
 
-<Switch bind:value={multiValue} label="Choose an Option" design="multi" options={['true', 'false']} fontSize={12}/>
-<p>
-	Switch is {multiValue}
-</p>
+# Build for production
+npm run build
 
+# Type checking
+npm run check
 ```
 
-### Options
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT © [Ishan Karunaratne](https://github.com/ishansasika)
+
+## Repository
+
+[GitHub Repository](https://github.com/ishansasika/svelte-toggle-switch)
+
+## Changelog
+
+### Version 2.0.0 (Latest)
+
+**Major Rewrite** - Complete redesign with modern features:
+
+- ✨ Added TypeScript support
+- ✨ Added 3 new design variants (Modern, Material, Multi)
+- ✨ Added 6 built-in color schemes + custom colors
+- ✨ Added 5 size variants (xs, sm, md, lg, xl)
+- ✨ Added loading state with spinner animation
+- ✨ Added icon support with custom positioning
+- ✨ Added disabled and read-only states
+- ✨ Added customizable animations
+- ✨ Added shadow and outline options
+- ✨ Added label positioning (left/right)
+- ✨ Enhanced accessibility (ARIA, keyboard navigation)
+- 📦 Updated to Svelte 5, Vite 6, TypeScript 5
+- 🎨 Complete UI/UX improvements
+- 📚 Comprehensive documentation
 
-| API | Value | 
-| --- | --- |
-| `label` | `Your Text` | 
-| `design` | `inner`, `slider`, `multi` | 
-| `fontSize` | `16px` | 
-| `options` | `['true', 'false']` | 
+### Version 1.0.0
 
+- Initial release with basic toggle functionality

package/package.json

@@ -1,17 +1,24 @@
 {
   "name": "svelte-toggle-switch",
   "private": false,
-  "version": "1.0.0",
+  "version": "2.0.0",
   "type": "module",
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "check": "svelte-check --tsconfig ./tsconfig.json"
   },
   "devDependencies": {
-    "@sveltejs/vite-plugin-svelte": "^1.0.0-next.30",
-    "svelte": "^3.44.0",
-    "vite": "^2.9.9"
+    "@sveltejs/vite-plugin-svelte": "^5.0.4",
+    "@tsconfig/svelte": "^5.0.4",
+    "svelte": "^5.16.0",
+    "svelte-check": "^4.1.1",
+    "typescript": "^5.7.3",
+    "vite": "^6.4.1"
+  },
+  "peerDependencies": {
+    "svelte": "^3.0.0 || ^4.0.0 || ^5.0.0"
   },
   "repository": {
     "type": "git",
@@ -23,7 +30,11 @@
     "toggle",
     "svelte switch",
     "toggle switch",
-    "svelte-toggle-switch"
+    "svelte-toggle-switch",
+    "svelte component",
+    "ui component",
+    "accessible",
+    "typescript"
   ],
   "author": "Ishan Karunaratne <ishansasika@gmail.com> (https://ishansasika.mn.co/)",
   "license": "MIT",