@svelte-atoms/core 1.0.0-alpha.23 → 1.0.0-alpha.25

package/llm/philosophy.md

@@ -0,0 +1,23 @@
+The Atomic Svelte philosophy is centered around creating a modular, composable UI library that treats components as fundamental building blocks. Here are the core principles:
+
+# 🧱 Atomic Architecture
+
+The philosophy is built around the concept of "atoms" - self-contained, reusable UI components that encapsulate their own state and DOM management. Think of it like chemistry: components are the basic elements that can be combined to create more complex molecules (UI patterns).
+
+# Core Structure
+
+Atoms: The smallest composable UI pieces - fundamental building blocks
+Bonds: The logic that holds atoms together and enables synchronization between them
+Protons, Neutrons, Electrons: Functions that can be attached to atoms to add incremental functionality
+
+# Key Philosophy Points
+
+🔗 Context-Driven Communication: Components communicate through Svelte's context API, enabling powerful parent-child relationships without prop drilling.
+
+- ♿ Accessibility First: Every component includes proper ARIA attributes, keyboard navigation, and focus management out of the box.
+- 🎨 Headless & Stylable: Components are headless by default, giving you complete control over styling while providing sensible defaults.
+- ⚡ Reactive by Design: Leverages Svelte's fine-grained reactivity system for optimal performance and smooth user interactions.
+- 🔧 Highly Extensible: Easily extend components with custom behaviors, animations, and styling while maintaining core functionality.
+- 🎯 Type Safety: Fully written in TypeScript with comprehensive type definitions for a robust development experience.
+
+The philosophy treats the library as "raw material" - providing low-level, customizable, scalable UI components that teams can use to build their own custom design systems rather than prescriptive, opinionated components. This approach gives developers maximum flexibility while ensuring consistency and accessibility across their applications.

package/llm/preset-variant-integration.md

@@ -0,0 +1,516 @@
+# Preset-Variant Integration
+
+## Overview
+
+The variant system is deeply integrated with the preset system in @svelte-atoms/core, providing a powerful theming architecture that combines:
+
+- **Global variants** via presets (app-level theming)
+- **Local variants** via component props (component-level customization)
+- **Intelligent merging** that respects the hierarchy
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Theme Layer (Preset System)                         │
+│                                                      │
+│ setPreset({                                          │
+│   button: () => ({                                   │
+│     class: 'font-medium',  // Base styling           │
+│     variants: {            // Global variant defs    │
+│       base: 'rounded-md',                            │
+│       variants: {                                    │
+│         variant: { primary: '...', secondary: '...' }│
+│         size: { sm: '...', md: '...', lg: '...' }   │
+│       }                                              │
+│     }                                                │
+│   })                                                 │
+│ })                                                   │
+└─────────────────────────────────────────────────────┘
+                          ↓
+                    [MERGE STRATEGY]
+                          ↓
+┌─────────────────────────────────────────────────────┐
+│ Component Layer (Local Variants)                    │
+│                                                      │
+│ <HtmlAtom                                            │
+│   preset="button"                                    │
+│   variants={localVariants} // Overrides/extends     │
+│   variant="primary"                                  │
+│   size="lg"                                          │
+│ />                                                   │
+└─────────────────────────────────────────────────────┘
+                          ↓
+                    [RESOLUTION]
+                          ↓
+┌─────────────────────────────────────────────────────┐
+│ Final Output                                         │
+│                                                      │
+│ class: merged classes from preset + local + props   │
+│ attributes: aria-*, data-*, role, etc.              │
+└─────────────────────────────────────────────────────┘
+```
+
+## Merge Strategy
+
+### 1. Variant Definition Merging
+
+When both preset and component define variants, they merge as follows:
+
+```typescript
+{
+  base: localVariants.base ?? presetVariants.base,
+
+  variants: merge(
+    presetVariants.variants ?? {},
+    localVariants.variants ?? {}
+  ),
+
+  compoundVariants: [
+    ...(presetVariants.compoundVariants ?? []),
+    ...(localVariants.compoundVariants ?? [])
+  ],
+
+  defaultVariants: merge(
+    presetVariants.defaultVariants ?? {},
+    localVariants.defaultVariants ?? {}
+  )
+}
+```
+
+**Rules:**
+
+- Local `base` overrides preset `base`
+- Local variants **merge** with preset variants (not replace)
+- Compound variants from both are **concatenated**
+- Default variants **merge** (local overrides preset)
+
+### 2. Class Resolution Order
+
+```
+Final Class = [
+  preset.class,              // 1. Preset base class
+  preset.variants.base,      // 2. Preset variant base
+  mergedVariants.base,       // 3. Merged variant base (local overrides)
+  variantClasses,            // 4. Resolved variant classes
+  compoundClasses,           // 5. Compound variant classes
+  component.class            // 6. Component class prop (highest priority)
+]
+```
+
+### 3. Props Merging
+
+```typescript
+{
+  ...preset (excluding: class, base, as, variants),
+  ...variantAttributes (aria-*, data-*, role, etc.),
+  ...componentProps (user-provided props - highest priority)
+}
+```
+
+## Usage Patterns
+
+### Pattern 1: Pure Preset (No Local Variants)
+
+**Best for:** Consistent components that don't need customization
+
+```typescript
+// Theme.svelte
+setPreset({
+	badge: () => ({
+		variants: {
+			base: 'inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-semibold',
+			variants: {
+				variant: {
+					default: 'bg-primary text-primary-foreground',
+					secondary: 'bg-secondary text-secondary-foreground',
+					destructive: 'bg-destructive text-destructive-foreground',
+					outline: 'border border-input'
+				}
+			},
+			defaultVariants: {
+				variant: 'default'
+			}
+		}
+	})
+});
+```
+
+```svelte
+<!-- Badge.svelte -->
+<HtmlAtom preset="badge" {variant} {...props}>
+	{@render children?.()}
+</HtmlAtom>
+```
+
+**Result:** Uses 100% preset variants, no local customization
+
+---
+
+### Pattern 2: Preset + Local Extension
+
+**Best for:** Components that need additional variants beyond theme
+
+```typescript
+// Theme.svelte
+setPreset({
+	button: () => ({
+		variants: {
+			base: 'rounded-md font-medium',
+			variants: {
+				variant: {
+					default: 'bg-primary text-primary-foreground',
+					secondary: 'bg-secondary text-secondary-foreground'
+				},
+				size: {
+					sm: 'h-8 px-3',
+					md: 'h-10 px-4',
+					lg: 'h-12 px-6'
+				}
+			},
+			defaultVariants: {
+				variant: 'default',
+				size: 'md'
+			}
+		}
+	})
+});
+```
+
+```svelte
+<!-- IconButton.svelte -->
+<script>
+	import { defineVariants } from '@svelte-atoms/core/utils';
+
+	// Extend preset with icon-specific variants
+	const iconVariants = defineVariants({
+		variants: {
+			// Add new variant key not in preset
+			iconPosition: {
+				left: 'flex-row',
+				right: 'flex-row-reverse',
+				top: 'flex-col',
+				bottom: 'flex-col-reverse'
+			}
+		},
+		defaultVariants: {
+			iconPosition: 'left'
+		}
+	});
+</script>
+
+<HtmlAtom preset="button" variants={iconVariants} {variant} {size} {iconPosition} {...props}>
+	{@render children?.()}
+</HtmlAtom>
+```
+
+**Result:** Gets `variant` and `size` from preset, adds `iconPosition` locally
+
+---
+
+### Pattern 3: Preset Override
+
+**Best for:** Special cases that need to completely override preset variants
+
+```typescript
+// Theme.svelte
+setPreset({
+	button: () => ({
+		variants: {
+			base: 'rounded-md',
+			variants: {
+				variant: {
+					default: 'bg-primary text-primary-foreground',
+					destructive: 'bg-destructive text-destructive-foreground'
+				}
+			}
+		}
+	})
+});
+```
+
+```svelte
+<!-- GradientButton.svelte -->
+<script>
+	import { defineVariants } from '@svelte-atoms/core/utils';
+
+	// Override preset variants completely
+	const gradientVariants = defineVariants({
+		base: 'rounded-full', // Overrides preset base
+		variants: {
+			variant: {
+				// Overrides preset variants
+				purple: 'bg-gradient-to-r from-purple-500 to-pink-500',
+				blue: 'bg-gradient-to-r from-blue-500 to-cyan-500',
+				green: 'bg-gradient-to-r from-green-500 to-emerald-500'
+			}
+		},
+		defaultVariants: {
+			variant: 'purple'
+		}
+	});
+</script>
+
+<HtmlAtom preset="button" variants={gradientVariants} {variant} {...props}>
+	{@render children?.()}
+</HtmlAtom>
+```
+
+**Result:** Local variants completely replace preset variants for matching keys
+
+---
+
+### Pattern 4: Pure Local (No Preset)
+
+**Best for:** One-off components that don't need global theming
+
+```svelte
+<script>
+	import { defineVariants } from '@svelte-atoms/core/utils';
+
+	const customVariants = defineVariants({
+		base: 'custom-base-class',
+		variants: {
+			custom: {
+				a: 'class-a',
+				b: 'class-b'
+			}
+		}
+	});
+</script>
+
+<HtmlAtom variants={customVariants} custom="a" {...props}>
+	{@render children?.()}
+</HtmlAtom>
+```
+
+**Result:** No preset used, 100% local variant definition
+
+---
+
+### Pattern 5: Dynamic Variants with Bond
+
+**Best for:** Reactive variants that change based on component state
+
+```typescript
+// Theme.svelte
+setPreset({
+	accordion: () => ({
+		variants: {
+			base: 'border rounded-md',
+			variants: {
+				state: {
+					// Function receives bond for reactive styling
+					open: (bond) => ({
+						class: bond?.state?.isOpen ? 'bg-accent' : 'bg-background',
+						'aria-expanded': bond?.state?.isOpen,
+						'data-state': bond?.state?.isOpen ? 'open' : 'closed'
+					})
+				}
+			}
+		}
+	})
+});
+```
+
+```svelte
+<!-- Accordion.svelte -->
+<script>
+	import { AccordionBond } from './bond.svelte';
+
+	const bond = new AccordionBond(state).share();
+</script>
+
+<HtmlAtom preset="accordion" {bond} state="open" {...props}>
+	{@render children?.({ accordion: bond })}
+</HtmlAtom>
+```
+
+**Result:** Variants reactively update when `bond.state.isOpen` changes
+
+## Advanced Features
+
+### 1. Nested Preset Keys
+
+Organize related components with dot notation:
+
+```typescript
+setPreset({
+	card: () => ({
+		/* ... */
+	}),
+	'card.header': () => ({
+		/* ... */
+	}),
+	'card.body': () => ({
+		/* ... */
+	}),
+	'card.footer': () => ({
+		/* ... */
+	})
+});
+```
+
+```svelte
+<HtmlAtom preset="card.header" />
+```
+
+### 2. Compound Variants
+
+Apply classes when multiple conditions match:
+
+```typescript
+setPreset({
+	button: () => ({
+		variants: {
+			variants: {
+				variant: { default: '...', destructive: '...' },
+				size: { sm: '...', lg: '...' }
+			},
+			compoundVariants: [
+				{
+					variant: 'destructive',
+					size: 'lg',
+					class: 'font-bold uppercase', // Applied ONLY when both match
+					'aria-label': 'Warning'
+				}
+			]
+		}
+	})
+});
+```
+
+### 3. Variant Attributes
+
+Variants can return more than just classes:
+
+```typescript
+variants: {
+  variant: {
+    destructive: {
+      class: 'bg-destructive text-destructive-foreground',
+      role: 'alert',
+      'aria-label': 'Destructive action',
+      'data-variant': 'destructive'
+    }
+  }
+}
+```
+
+### 4. Preset Class + Variant Base
+
+Use both for layered styling:
+
+```typescript
+setPreset({
+	button: () => ({
+		class: 'inline-flex items-center justify-center', // Always applied
+		variants: {
+			base: 'rounded-md transition-colors', // Variant base (can be overridden)
+			variants: {
+				/* ... */
+			}
+		}
+	})
+});
+```
+
+**Final class order:**
+
+1. `preset.class`
+2. `preset.variants.base`
+3. Local variant base (if overriding)
+4. Variant classes
+5. Component class prop
+
+## Migration from Old System
+
+### Before (Old Function-based)
+
+```svelte
+<script>
+	const variants = (bond, props) => {
+		const { variant, size } = props;
+		const classes = [];
+
+		if (variant === 'primary') classes.push('bg-blue-500');
+		if (size === 'sm') classes.push('px-2 py-1');
+
+		return { class: classes.join(' ') };
+	};
+</script>
+
+<HtmlAtom {variants} {variant} {size} />
+```
+
+### After (New Variant System)
+
+```typescript
+// In preset (recommended)
+setPreset({
+	button: () => ({
+		variants: {
+			variants: {
+				variant: {
+					primary: 'bg-blue-500'
+				},
+				size: {
+					sm: 'px-2 py-1'
+				}
+			}
+		}
+	})
+});
+```
+
+```svelte
+<HtmlAtom preset="button" {variant} {size} />
+```
+
+**OR** local only:
+
+```svelte
+<script>
+	import { defineVariants } from '@svelte-atoms/core/utils';
+
+	const buttonVariants = defineVariants({
+		variants: {
+			variant: { primary: 'bg-blue-500' },
+			size: { sm: 'px-2 py-1' }
+		}
+	});
+</script>
+
+<HtmlAtom variants={buttonVariants} {variant} {size} />
+```
+
+## Best Practices
+
+### ✅ DO
+
+1. **Use presets for global variants** that should be consistent across the app
+2. **Use local variants** to extend or override for special cases
+3. **Use `class` prop in preset** for base styling that always applies
+4. **Use `variants.base`** for styling that can be overridden locally
+5. **Return attributes from variants** (aria-_, data-_, role) for accessibility
+
+### ❌ DON'T
+
+1. **Don't duplicate variants** in both preset and local unless overriding
+2. **Don't use `base` prop for CSS classes** (conflicts with component/snippet prop)
+3. **Don't over-nest presets** - keep hierarchy shallow
+4. **Don't forget default variants** - they make components easier to use
+
+## Summary
+
+The preset-variant integration provides:
+
+✅ **Global theming** via preset system  
+✅ **Local customization** via component variants  
+✅ **Intelligent merging** that respects hierarchy  
+✅ **Type safety** with TypeScript  
+✅ **Reactive variants** with bond state access  
+✅ **Attribute support** beyond just classes  
+✅ **Backward compatible** with function-based variants
+
+This architecture gives you the flexibility of both global consistency and local control.