@svelte-atoms/core 1.0.0-alpha.29 → 1.0.0-alpha.31

package/llm/preset.md

@@ -1,383 +0,0 @@
-# Global Component Configuration with Presets
-
-## Overview
-
-Presets in @svelte-atoms/core allow you to configure component styling, props, and behavior **globally** across your application. Instead of repeating the same classes or props on every component, define them once at the top level and have all components inherit those configurations automatically.
-
-Presets can be:
-
-- Declared at the **app root** for global configuration
-- Overridden at the **route level** for section-specific styling
-- Overridden at the **component level** for local customization
-
-## How Presets Work
-
-Each component has a `preset` prop that references a key in the preset configuration:
-
-```svelte
-<HtmlAtom preset="button" class={['default-button-classes', '$preset', klass]} />
-```
-
-The `$preset` placeholder gets replaced with classes/props from the preset configuration at that context level.
-
-## Setting Up Presets
-
-### 1. Global Preset (App Root)
-
-Set presets at the app root to apply them everywhere:
-
-```svelte
-<!-- +layout.svelte or App.svelte -->
-<script lang="ts">
-	import { setPreset, type Preset } from '@svelte-atoms/core/context';
-	import { Root } from '@svelte-atoms/core/components/root';
-
-	const globalPreset: Partial<Preset> = {
-		button: () => ({
-			class: 'rounded-lg px-4 py-2 font-semibold transition-colors'
-		}),
-		card: () => ({
-			class: 'rounded-xl border border-gray-200 shadow-sm'
-		}),
-		'card.title': () => ({
-			class: 'text-xl font-bold text-gray-900'
-		}),
-		dialog: () => ({
-			class: 'max-w-2xl rounded-2xl'
-		})
-	};
-
-	setPreset(globalPreset);
-</script>
-
-<Root>
-	<slot />
-</Root>
-```
-
-Now all `Button`, `Card`, and `Dialog` components automatically inherit these styles.
-
-### 2. Route-Level Override
-
-Override presets for specific routes:
-
-```svelte
-<!-- routes/dashboard/+layout.svelte -->
-<script lang="ts">
-	import { setPreset } from '@svelte-atoms/core/context';
-
-	const dashboardPreset = {
-		button: () => ({
-			class: 'rounded-md px-3 py-1.5 text-sm' // Smaller buttons for dashboard
-		}),
-		card: () => ({
-			class: 'bg-slate-50 border-slate-200' // Different card style
-		})
-	};
-
-	setPreset(dashboardPreset);
-</script>
-
-<div>
-	<slot />
-</div>
-```
-
-Components in `/dashboard/*` routes now use the dashboard preset, **merging** with the global preset.
-
-### 3. Component-Level Override
-
-Override presets in a parent component for its children:
-
-```svelte
-<!-- components/SettingsPanel.svelte -->
-<script lang="ts">
-	import { setPreset } from '@svelte-atoms/core/context';
-	import { Card } from '@svelte-atoms/core/components/card';
-
-	const settingsPreset = {
-		'card.title': () => ({
-			class: 'text-lg text-purple-600' // Purple titles in settings
-		})
-	};
-
-	setPreset(settingsPreset);
-</script>
-
-<Card.Root>
-	<Card.Header>
-		<Card.Title>Settings</Card.Title>
-		<!-- Purple text -->
-	</Card.Header>
-	<Card.Content>
-		<!-- Content here -->
-	</Card.Content>
-</Card.Root>
-```
-
-## Preset Structure
-
-### Basic Preset Entry
-
-Return an object with `class`, `as`, or other props:
-
-```typescript
-const preset: Partial<Preset> = {
-	button: () => ({
-		class: 'px-4 py-2 rounded-lg',
-		type: 'button'
-	}),
-
-	accordion: () => ({
-		as: 'ul', // Change element type
-		class: 'space-y-2'
-	})
-};
-```
-
-### Dynamic Preset with Bond State
-
-Access component state via bond to create reactive presets:
-
-```typescript
-const preset: Partial<Preset> = {
-	'accordion.item.header': (bond) => {
-		// Access bond.state to make preset reactive
-		return {
-			class: bond?.state?.isActive ? 'text-foreground bg-accent' : 'text-muted-foreground'
-		};
-	}
-};
-```
-
-### Using defineState for Reactive Props
-
-For more complex reactive logic, use `defineState` and `defineProperty`:
-
-```typescript
-import { defineState, defineProperty } from '@svelte-atoms/core/utils';
-
-const preset: Partial<Preset> = {
-	'collapsible.header': (bond) => {
-		return defineState([
-			defineProperty('class', () => [
-				'px-4 py-2 cursor-pointer transition-colors',
-				bond?.state?.isOpen ? 'bg-blue-50' : 'hover:bg-gray-50'
-			]),
-			defineProperty('aria-expanded', () => bond?.state?.isOpen)
-		]);
-	}
-};
-```
-
-## Preset Merging
-
-Presets **merge** across context levels using deep merge:
-
-```svelte
-<!-- App root -->
-<script>
-  setPreset({
-    button: () => ({
-      class: 'px-4 py-2 rounded-lg font-semibold'
-    })
-  });
-</script>
-
-<!-- Route level -->
-<script>
-  setPreset({
-    button: () => ({
-      class: 'text-sm' // Merges with root
-    })
-  });
-</script>
-
-<!-- Result: Button has both classes -->
-<!-- class="px-4 py-2 rounded-lg font-semibold text-sm" -->
-```
-
-## Available Preset Keys
-
-Components use dot notation for sub-components:
-
-```typescript
-type PresetModuleName =
-	| 'button'
-	| 'card'
-	| 'card.title'
-	| 'card.content'
-	| 'card.header'
-	| 'card.footer'
-	| 'accordion'
-	| 'accordion.item'
-	| 'accordion.item.header'
-	| 'accordion.item.body'
-	| 'dialog'
-	| 'dialog.content'
-	| 'dialog.title'
-	| 'popover.content'
-	| 'popover.trigger'
-	| 'datagrid'
-	| 'datagrid.th'
-	| 'datagrid.td';
-// ... and many more
-```
-
-Check `src/lib/context/preset.svelte.ts` for the complete list.
-
-## Real-World Examples
-
-### Example 1: Global Theme Setup
-
-```svelte
-<!-- +layout.svelte -->
-<script lang="ts">
-	import { setPreset } from '@svelte-atoms/core/context';
-
-	const theme = {
-		// Base components
-		button: () => ({
-			class: 'rounded-lg px-4 py-2 font-medium transition-all duration-200'
-		}),
-		input: () => ({
-			class: 'rounded-md border border-gray-300 px-3 py-2 focus:border-blue-500'
-		}),
-
-		// Card system
-		card: () => ({
-			class: 'rounded-xl border border-gray-200 bg-white shadow-sm'
-		}),
-		'card.title': () => ({
-			class: 'text-lg font-semibold text-gray-900'
-		}),
-		'card.content': () => ({
-			class: 'p-6'
-		}),
-
-		// Dialog system
-		dialog: () => ({
-			class: 'max-w-lg rounded-2xl'
-		}),
-		'dialog.content': () => ({
-			class: 'p-6'
-		}),
-		'dialog.title': () => ({
-			class: 'text-xl font-bold'
-		})
-	};
-
-	setPreset(theme);
-</script>
-```
-
-### Example 2: Dashboard Route Override
-
-```svelte
-<!-- routes/dashboard/+layout.svelte -->
-<script lang="ts">
-	import { setPreset } from '@svelte-atoms/core/context';
-
-	// Override for compact dashboard UI
-	const dashboardTheme = {
-		button: () => ({
-			class: 'rounded-md px-3 py-1.5 text-sm'
-		}),
-		card: () => ({
-			class: 'rounded-lg bg-slate-50'
-		}),
-		'datagrid.th': () => ({
-			class: 'text-xs uppercase text-slate-500'
-		})
-	};
-
-	setPreset(dashboardTheme);
-</script>
-```
-
-### Example 3: Component-Specific Styling
-
-```svelte
-<!-- components/PricingCards.svelte -->
-<script lang="ts">
-	import { setPreset } from '@svelte-atoms/core/context';
-	import { Card } from '@svelte-atoms/core/components/card';
-
-	// Custom styling just for pricing cards
-	setPreset({
-		card: () => ({
-			class: 'rounded-2xl border-2 border-purple-200 hover:border-purple-400 transition-all'
-		}),
-		'card.title': () => ({
-			class: 'text-2xl font-bold text-purple-900'
-		})
-	});
-</script>
-
-<div class="grid grid-cols-3 gap-4">
-	<Card.Root>
-		<Card.Header>
-			<Card.Title>Basic</Card.Title>
-		</Card.Header>
-		<Card.Content>$9/month</Card.Content>
-	</Card.Root>
-
-	<!-- More pricing cards... -->
-</div>
-```
-
-### Example 4: Reactive State-Based Styling
-
-```svelte
-<script lang="ts">
-	import { setPreset } from '@svelte-atoms/core/context';
-	import { defineState, defineProperty } from '@svelte-atoms/core/utils';
-
-	setPreset({
-		'accordion.item.header': (bond) => {
-			return defineState([
-				defineProperty('class', () => [
-					'px-4 py-3 cursor-pointer transition-all duration-200',
-					bond?.state?.isOpen
-						? 'bg-blue-50 text-blue-900 font-semibold'
-						: 'hover:bg-gray-50 text-gray-700'
-				])
-			]);
-		},
-
-		'collapsible.indicator': (bond) => ({
-			class: bond?.state?.isOpen
-				? 'rotate-180 transition-transform duration-200'
-				: 'transition-transform duration-200'
-		})
-	});
-</script>
-```
-
-## Best Practices
-
-1. **Set global presets at app root** - Define your base theme in `+layout.svelte` or `App.svelte`
-
-2. **Override at route level** - Use route layouts (`+layout.svelte`) to customize sections
-
-3. **Use component-level overrides sparingly** - Only when a specific component tree needs unique styling
-
-4. **Use dot notation for specificity** - `'card.title'` is more specific than `'card'`
-
-5. **Access bond state for reactivity** - Use bond parameter in preset functions to create dynamic styles
-
-6. **Merge, don't replace** - Presets merge across contexts, so you can build up configurations gradually
-
-7. **Keep presets simple** - Presets are for common patterns; use component props for one-off customizations
-
-## Summary
-
-Presets provide a powerful way to configure components globally:
-
-- **Global**: Set at app root for consistent styling across your app
-- **Route-level**: Override in route layouts for section-specific themes
-- **Component-level**: Override in parent components for localized styling
-- **Reactive**: Access bond state to create dynamic, state-based configurations
-- **Merging**: Presets deep-merge across contexts, allowing gradual customization
-
-Instead of repeating classes on every component, define them once in presets and let components inherit the configuration automatically.

package/llm/styling.md

@@ -1,216 +0,0 @@
-# Styling Guide for @svelte-atoms/core
-
-> **Audience**: LLMs and developers working with @svelte-atoms/core
-
-## Core Concepts
-
-All components accept a `class` prop that supports:
-
-```svelte
-<!-- String -->
-<Button class="bg-blue-500 px-4 py-2 text-white">Click me</Button>
-
-<!-- Array with conditionals -->
-<Button class={['base-class', isActive && 'active-class', klass]}>Click me</Button>
-
-<!-- Object -->
-<Button class={{ 'bg-blue-500': isPrimary, 'bg-gray-500': !isPrimary }}>Click me</Button>
-```
-
-## 1. TailwindCSS (Primary Method)
-
-Use Tailwind utility classes for all styling needs:
-
-```svelte
-<!-- Layout & spacing -->
-<Card.Root class="max-w-sm p-4">
-	<Card.Header>
-		<Card.Title class="text-lg font-semibold">Title</Card.Title>
-	</Card.Header>
-</Card.Root>
-
-<!-- Interactive states -->
-<button class="bg-blue-500 px-4 py-2 text-white hover:bg-blue-600 active:bg-blue-700">
-	Action
-</button>
-
-<!-- Responsive -->
-<h2 class="text-2xl md:text-3xl lg:text-4xl">Responsive heading</h2>
-
-<!-- With opacity -->
-<div class="bg-foreground/10">Subtle background</div>
-```
-
-### Class Order Pattern
-
-```svelte
-<HtmlAtom
-	class={[
-		'base-layout-classes', // flex, grid, etc.
-		'sizing-classes', // w-full, px-4, etc.
-		'visual-classes', // bg-blue-500, border, etc.
-		isOpen && 'conditional', // Conditional classes
-		'$preset', // Preset placeholder (if using presets)
-		klass // User overrides (highest priority)
-	]}
-/>
-```
-
-## 2. Preset System
-
-Define default styles once, use everywhere:
-
-```svelte
-<script lang="ts">
-	import { setPreset } from '@svelte-atoms/core/context';
-
-	const preset = {
-		// Simple preset
-		button: () => ({
-			class: 'bg-primary text-primary-foreground px-4 py-2 rounded'
-		}),
-
-		// With custom element
-		accordion: () => ({
-			as: 'ul',
-			class: 'w-full max-w-md rounded-md border'
-		}),
-
-		// Dynamic with state
-		'accordion.item.header': (bond) => ({
-			class: bond?.state?.isActive ? 'text-foreground' : 'text-foreground/50'
-		})
-	};
-
-	setPreset(preset);
-</script>
-```
-
-**Using the `$preset` placeholder:**
-
-```svelte
-<!-- In your component -->
-<HtmlAtom
-	preset="button"
-	class={[
-		'component-defaults',
-		'$preset', // Replaced with preset classes
-		klass // User classes override
-	]}
-/>
-```
-
-## 3. CSS Custom Properties
-
-Use design tokens from `root.css`:
-
-```svelte
-<!-- Color tokens -->
-<div class="bg-background text-foreground">Background color</div>
-<Button class="bg-primary text-primary-foreground">Primary button</Button>
-
-<!-- With opacity -->
-<div class="bg-foreground/10 text-foreground/50">Subtle styling</div>
-
-<!-- Borders and shadows -->
-<Card.Root class="border-border border shadow-lg">Card</Card.Root>
-```
-
-**Available tokens:**
-
-- Colors: `background`, `foreground`, `primary`, `secondary`, `muted`, `accent`, `destructive`, `border`
-- Each color has `-foreground` variant
-- Shadows: `shadow-sm`, `shadow-md`, `shadow-lg`, `shadow-xl`
-
-## 4. Conditional Classes
-
-Most common pattern from stories:
-
-```svelte
-<script>
-	let isOpen = $state(false);
-</script>
-
-<!-- Array with conditions -->
-<Collapsible.Body class={['pointer-events-none h-0 opacity-0', isOpen && 'pointer-events-auto']}>
-	Content
-</Collapsible.Body>
-
-<!-- Ternary -->
-<Tab.Root class={isActive ? 'opacity-100' : 'opacity-50'}>Tab content</Tab.Root>
-```
-
-## 5. Component Variants
-
-Create reusable variants:
-
-```svelte
-<script lang="ts">
-	let { variant = 'primary', size = 'md', class: klass = '' } = $props();
-
-	const variants = {
-		primary: 'bg-blue-500 text-white hover:bg-blue-600',
-		secondary: 'bg-gray-200 text-gray-800 hover:bg-gray-300'
-	};
-
-	const sizes = {
-		sm: 'px-3 py-1.5 text-xs',
-		md: 'px-4 py-2 text-sm',
-		lg: 'px-6 py-3 text-base'
-	};
-</script>
-
-<Button class="{variants[variant]} {sizes[size]} {klass}">
-	{@render children?.()}
-</Button>
-```
-
-## 6. Inline Styles
-
-Use for dynamic values only:
-
-```svelte
-<script>
-	let width = $state(240);
-</script>
-
-<!-- ✅ Good: Dynamic values -->
-<div style="width: {width}px; opacity: {isOpen ? 1 : 0}">Dynamic sizing</div>
-
-<!-- ❌ Avoid: Static styling -->
-<div style="padding: 16px; background: blue;">Use Tailwind instead</div>
-```
-
-## Quick Reference
-
-| Need           | Use                                  |
-| -------------- | ------------------------------------ |
-| Static styling | TailwindCSS classes                  |
-| Theme/defaults | Preset system                        |
-| Conditional    | Array syntax with `&&`               |
-| Responsive     | Tailwind breakpoints (`md:`, `lg:`)  |
-| Colors         | CSS custom properties (`bg-primary`) |
-| Dynamic values | Inline styles                        |
-| Variants       | Computed class objects               |
-
-## Best Practices
-
-1. **Prefer Tailwind** - Use utility classes for 90% of styling
-2. **Class order matters** - Base → Conditionals → `$preset` → User classes
-3. **Use presets for consistency** - Define theme defaults once
-4. **Avoid inline styles** - Use only for truly dynamic values
-5. **Keep specificity low** - Avoid `!important`, let cascade work
-
-## Class Merging
-
-The `cn()` utility merges classes intelligently:
-
-```typescript
-import { cn } from '@svelte-atoms/core/utils';
-
-// Resolves conflicts automatically
-cn('px-2 py-1', 'px-4'); // Result: 'py-1 px-4'
-
-// Handles conditionals
-cn('base', isActive && 'active', false && 'ignored');
-```

package/llm/usage.md

@@ -1,46 +0,0 @@
-# Component Usage Patterns
-
-## Namespace.Atom Pattern
-
-Components follow a hierarchical naming pattern using dot notation:
-
-```svelte
-<Form.Root>
-	<Form.Field>
-		<Form.Label />
-		<Form.Control />
-	</Form.Field>
-</Form.Root>
-```
-
-## Naming Convention
-
-- **Namespace** = Component family (e.g., `Form`, `Button`, `Dropdown`)
-- **Atom** = Specific component within the family (e.g., `Root`, `Field`, `Label`)
-
-## Import Pattern
-
-```javascript
-import { Form } from '$lib/components/form';
-
-// Usage
-<Form.Root>
-	<Form.Field>
-		<Form.Label>Username</Form.Label>
-		<Form.Control type="text" />
-	</Form.Field>
-</Form.Root>;
-```
-
-## Benefits
-
-- **Clear hierarchy** - Components group logically
-- **Namespace isolation** - Prevents naming conflicts
-- **Discoverable API** - IDE autocomplete shows related components
-- **Consistent patterns** - Same structure across all component families
-
-## Examples
-
-- `Button.Root`, `Button.Icon`, `Button.Text`
-- `Dropdown.Root`, `Dropdown.Trigger`, `Dropdown.Content`
-- `Form.Root`, `Form.Field`, `Form.Label`, `Form.Control`