sileo-sveltekit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Cairo Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,490 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/shehabwaleedd/sileo-sveltekit/main/.github/logo.svg" alt="sileo-sveltekit" width="120" />
+</p>
+
+<h1 align="center">sileo-sveltekit</h1>
+
+<p align="center">
+  <strong>A physics-based toast notification library for SvelteKit</strong>
+</p>
+
+<p align="center">
+  Beautiful, animated toast notifications with spring physics, SVG morphing, and a delightful user experience.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/sileo-sveltekit">
+    <img src="https://img.shields.io/npm/v/sileo-sveltekit?style=flat-square&color=ff4b26" alt="npm version" />
+  </a>
+  <a href="https://www.npmjs.com/package/sileo-sveltekit">
+    <img src="https://img.shields.io/npm/dm/sileo-sveltekit?style=flat-square&color=ff4b26" alt="npm downloads" />
+  </a>
+  <a href="https://github.com/shehabwaleedd/sileo-sveltekit/blob/main/LICENSE">
+    <img src="https://img.shields.io/npm/l/sileo-sveltekit?style=flat-square&color=ff4b26" alt="license" />
+  </a>
+  <a href="https://kit.svelte.dev">
+    <img src="https://img.shields.io/badge/SvelteKit-5.0+-ff4b26?style=flat-square" alt="SvelteKit 5+" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#api-reference">API</a> •
+  <a href="#customization">Customization</a> •
+  <a href="#examples">Examples</a>
+</p>
+
+---
+
+## ✨ Features
+
+- **🎯 Physics-Based Animations** — Smooth spring animations powered by Svelte's motion stores
+- **🫧 SVG Gooey Morphing** — Organic blob-like shape transitions using SVG filters
+- **📍 6 Positions** — Place toasts anywhere: top/bottom + left/center/right
+- **🎨 5 States** — Success, error, warning, info, and action states (plus loading)
+- **🔄 Auto Expand/Collapse** — Toasts expand on hover to reveal descriptions
+- **👆 Swipe to Dismiss** — Touch-friendly gesture support
+- **📚 Stacking Animations** — New toasts push existing ones naturally
+- **♿ Accessible** — ARIA live regions for screen readers
+- **🎛️ Fully Customizable** — CSS variables for complete control
+- **📦 Tiny Bundle** — No external dependencies beyond Svelte
+- **💪 TypeScript** — Full type safety out of the box
+
+---
+
+## 📦 Installation
+
+```bash
+# npm
+npm install sileo-sveltekit
+
+# pnpm
+pnpm add sileo-sveltekit
+
+# yarn
+yarn add sileo-sveltekit
+
+# bun
+bun add sileo-sveltekit
+```
+
+### Requirements
+
+- **Svelte 5.0+**
+- **SvelteKit 2.0+**
+
+---
+
+## 🚀 Quick Start
+
+### 1. Add the Toaster to your layout
+
+Add the `Toaster` component to your root layout. This renders the toast container and sets up the global toast API.
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import { Toaster } from 'sileo-sveltekit';
+</script>
+
+<Toaster />
+
+<slot />
+```
+
+### 2. Show toasts from anywhere
+
+Use the global `window.toast` API to show notifications from any component:
+
+```svelte
+<script>
+  function handleClick() {
+    window.toast.success('Saved!', 'Your changes have been saved successfully.');
+  }
+</script>
+
+<button on:click={handleClick}>
+  Save Changes
+</button>
+```
+
+That's it! You're ready to show beautiful toast notifications.
+
+---
+
+## 📖 API Reference
+
+### Toaster Component
+
+The main component that renders the toast container.
+
+```svelte
+<Toaster position="bottom-right" />
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `position` | `SileoPosition` | `'bottom-right'` | Default position for all toasts |
+
+#### Position Options
+
+| Value | Description |
+|-------|-------------|
+| `'top-left'` | Top left corner |
+| `'top-center'` | Top center |
+| `'top-right'` | Top right corner |
+| `'bottom-left'` | Bottom left corner |
+| `'bottom-center'` | Bottom center |
+| `'bottom-right'` | Bottom right corner |
+
+---
+
+### Toast API
+
+The toast API is available globally via `window.toast`.
+
+#### Quick Methods
+
+```typescript
+// Success toast
+window.toast.success(title: string, description?: string, duration?: number): string
+
+// Error toast
+window.toast.error(title: string, description?: string, duration?: number): string
+
+// Warning toast
+window.toast.warning(title: string, description?: string, duration?: number): string
+
+// Info toast
+window.toast.info(title: string, description?: string, duration?: number): string
+
+// Action toast
+window.toast.action(title: string, description?: string, duration?: number): string
+```
+
+**Returns:** Toast ID (string) — useful for programmatic dismissal
+
+#### Show with Options
+
+For full control, use `toast.show()` with an options object:
+
+```typescript
+window.toast.show({
+  title: 'Custom Toast',
+  description: 'With all the options',
+  position: 'top-center',
+  duration: 5000,
+  fill: '#1a1a1a',
+  roundness: 20,
+  autopilot: true
+}): string
+```
+
+#### Options Object
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `title` | `string` | — | Toast title (required) |
+| `description` | `string` | — | Optional description text |
+| `position` | `SileoPosition` | Toaster default | Override position for this toast |
+| `duration` | `number \| null` | `6000` | Auto-dismiss delay in ms. Use `null` for persistent |
+| `fill` | `string` | `'#fff'` | Background color (CSS color value) |
+| `roundness` | `number` | `16` | Border radius in pixels |
+| `autopilot` | `boolean \| object` | `true` | Auto expand/collapse behavior |
+
+#### Autopilot Options
+
+Control automatic expand/collapse timing:
+
+```typescript
+window.toast.show({
+  title: 'Custom timing',
+  description: 'This toast has custom autopilot',
+  autopilot: {
+    expand: 500,    // Expand after 500ms
+    collapse: 3000  // Collapse after 3000ms
+  }
+})
+```
+
+Set `autopilot: false` to disable auto expand/collapse entirely.
+
+#### Dismiss Methods
+
+```typescript
+// Dismiss a specific toast by ID
+window.toast.dismiss(id: string): void
+
+// Clear all toasts
+window.toast.clear(): void
+
+// Clear toasts at a specific position
+window.toast.clear('top-right'): void
+```
+
+---
+
+## 🎨 Customization
+
+### CSS Variables
+
+Customize the appearance by overriding CSS variables in your global styles:
+
+```css
+:root {
+  /* Dimensions */
+  --sileo-height: 40px;
+  --sileo-width: 350px;
+
+  /* Animation */
+  --sileo-duration: 600ms;
+
+  /* Default colors */
+  --sileo-fill: #ffffff;
+  --sileo-text: currentColor;
+
+  /* State colors (using oklch for vibrant colors) */
+  --sileo-state-success: oklch(0.723 0.219 142.136);
+  --sileo-state-error: oklch(0.637 0.237 25.331);
+  --sileo-state-warning: oklch(0.795 0.184 86.047);
+  --sileo-state-info: oklch(0.685 0.169 237.323);
+  --sileo-state-action: oklch(0.623 0.214 259.815);
+  --sileo-state-loading: oklch(0.556 0 0);
+}
+```
+
+### Dark Mode
+
+Sileo automatically adapts to your color scheme. Override the fill color for dark mode:
+
+```css
+:root.dark {
+  --sileo-fill: #1a1a1a;
+  --sileo-text: #ffffff;
+}
+```
+
+Or set the fill per-toast:
+
+```typescript
+window.toast.success('Dark toast', 'With custom background', {
+  fill: '#1a1a1a'
+})
+```
+
+### Custom State Colors
+
+Change the colors for each toast state:
+
+```css
+:root {
+  /* Use your brand colors */
+  --sileo-state-success: #10b981;
+  --sileo-state-error: #ef4444;
+  --sileo-state-warning: #f59e0b;
+  --sileo-state-info: #3b82f6;
+  --sileo-state-action: #8b5cf6;
+}
+```
+
+---
+
+## 💡 Examples
+
+### Basic Usage
+
+```svelte
+<script>
+  function showToasts() {
+    window.toast.success('Success!', 'Operation completed');
+    window.toast.error('Error!', 'Something went wrong');
+    window.toast.warning('Warning!', 'Please check this');
+    window.toast.info('Info', 'Here is some information');
+  }
+</script>
+
+<button on:click={showToasts}>Show All Types</button>
+```
+
+### Persistent Toast
+
+```svelte
+<script>
+  let toastId;
+
+  function showPersistent() {
+    toastId = window.toast.show({
+      title: 'Uploading...',
+      description: 'Please wait while we upload your file',
+      duration: null // Never auto-dismiss
+    });
+  }
+
+  function dismiss() {
+    window.toast.dismiss(toastId);
+  }
+</script>
+
+<button on:click={showPersistent}>Start Upload</button>
+<button on:click={dismiss}>Cancel</button>
+```
+
+### Promise Pattern
+
+```svelte
+<script>
+  async function saveData() {
+    const id = window.toast.show({
+      title: 'Saving...',
+      description: 'Please wait',
+      duration: null
+    });
+
+    try {
+      await fetch('/api/save', { method: 'POST' });
+      window.toast.dismiss(id);
+      window.toast.success('Saved!', 'Your data has been saved');
+    } catch (error) {
+      window.toast.dismiss(id);
+      window.toast.error('Failed', 'Could not save your data');
+    }
+  }
+</script>
+```
+
+### Different Positions
+
+```svelte
+<script>
+  function topLeft() {
+    window.toast.show({
+      title: 'Top Left',
+      position: 'top-left'
+    });
+  }
+
+  function bottomCenter() {
+    window.toast.show({
+      title: 'Bottom Center',
+      position: 'bottom-center'
+    });
+  }
+</script>
+
+<button on:click={topLeft}>Top Left</button>
+<button on:click={bottomCenter}>Bottom Center</button>
+```
+
+### Custom Styling
+
+```svelte
+<script>
+  function customToast() {
+    window.toast.show({
+      title: 'Custom Toast',
+      description: 'With brand colors and rounded corners',
+      fill: '#ff4b26',
+      roundness: 24
+    });
+  }
+</script>
+```
+
+---
+
+## 📘 TypeScript
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  SileoState,      // 'success' | 'error' | 'warning' | 'info' | 'action' | 'loading'
+  SileoPosition,   // 'top-left' | 'top-center' | ... | 'bottom-right'
+  SileoOptions,    // Options for toast.show()
+  SileoToastAPI    // Type for window.toast
+} from 'sileo-sveltekit';
+```
+
+### Type-Safe Global Toast
+
+Add type safety to `window.toast`:
+
+```typescript
+// src/app.d.ts
+import type { SileoToastAPI } from 'sileo-sveltekit';
+
+declare global {
+  interface Window {
+    toast: SileoToastAPI;
+  }
+}
+
+export {};
+```
+
+---
+
+## 🔧 Advanced Configuration
+
+### Multiple Toaster Instances
+
+While one Toaster handles all positions, you can customize behavior:
+
+```svelte
+<script>
+  import { Toaster } from 'sileo-sveltekit';
+</script>
+
+<!-- Primary toaster for most notifications -->
+<Toaster position="bottom-right" />
+```
+
+### Disable Autopilot
+
+Prevent toasts from auto-expanding:
+
+```typescript
+window.toast.show({
+  title: 'Manual Only',
+  description: 'This only expands on hover',
+  autopilot: false
+});
+```
+
+### Reduced Motion
+
+Sileo respects `prefers-reduced-motion`. When enabled, animations are minimized for accessibility.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## 📄 License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙏 Credits
+
+- Original [sileo](https://github.com/hiaaryan/sileo) by [@hiaaryan](https://github.com/hiaaryan)
+- SvelteKit port by [Cairo Studio](https://cairostudio.com)
+
+---
+
+<p align="center">
+  Made with ❤️ for the Svelte community
+</p>