svelte-origin 0.0.0 → 1.0.0-next.49

package/LLM.md

@@ -0,0 +1,545 @@
+# svelte-origin - LLM Reference
+
+> Quick-reference documentation for LLM assistance with svelte-origin v3.0
+
+## Overview
+
+`svelte-origin` provides a macro-based system for defining reusable state + props + methods patterns in Svelte 5. Origins are factories that create reactive instances with props, state, derived values, and methods.
+
+**IMPORTANT**: This library uses **compile-time macros** (prefixed with `$`). These are transformed during build and do NOT exist at runtime.
+
+---
+
+## The `$origin` Namespace
+
+All macros live under the `$origin` namespace:
+
+| Macro | Context | Description |
+|-------|---------|-------------|
+| `$origin({...})` | `.svelte.ts` files | Define an origin factory |
+| `$origin.props({...})` | Anywhere | Define props schema with defaults |
+| `$origin.component(Factory)` | ⚠️ `.svelte` only | Create origin from component `$props()` |
+| `$origin.create(Factory, {...})` | ✅ Everywhere | Programmatic origin creation with reactivity |
+| `$origin.bind(variable)` | Inside `$origin.create()` | Bind prop to existing reactive variable |
+| `$origin.for(Factory)` | ⚠️ `.svelte` only | Forward props to child origin/element |
+| `$origin.Props<typeof Factory>` | Type context | Extract component props type |
+| `$origin.Of<typeof Factory>` | Type context | Extract origin instance type |
+| `$bindable(value)` | Inside `$origin.props({})` | Mark a prop as two-way bindable |
+
+### Context Restrictions
+
+- ⚠️ **Component-only macros** (`$origin.component()`, `$origin.for()`): Using these in `.svelte.ts` or `.svelte.js` module files will throw a helpful compile-time error
+- ✅ **Universal macros** (`$origin.create()`, `$origin.props()`): Work in any context
+
+---
+
+## Defining Origins (`.svelte.ts` files)
+
+Origins are defined in `.svelte.ts` files using the `$origin()` macro:
+
+```ts
+// counter.svelte.ts
+export const Counter = $origin({
+	props: $origin.props({
+		label: 'Counter',           // Default string
+		count: $bindable(0),        // Bindable number (two-way)
+		step: 1                     // Default number
+	}),
+
+	// Internal state (not exposed - prefix with _)
+	_history: [] as number[],
+
+	// Derived values (use getters + $derived)
+	get doubled() {
+		return $derived(this.props.count * 2)
+	},
+
+	// Methods
+	increment() {
+		this._history.push(this.props.count)
+		this.props.count += this.props.step
+	},
+
+	decrement() {
+		this._history.push(this.props.count)
+		this.props.count -= this.props.step
+	}
+})
+```
+
+### Key Rules for Origin Definitions
+
+1. **Use `this.props.*`** to access props (not `props.*`)
+2. **Use `$derived()`** for computed/derived values (must be inside a getter)
+3. **Use `$bindable(defaultValue)`** for two-way bindable props
+4. **Prefix with `_`** for internal/private state (convention - excluded from public types)
+5. **Never use `$state()`** for props - props are automatically reactive
+6. **Use `$state()`** for internal state (non-props) that needs reactivity
+
+---
+
+## Using Origins in Components
+
+### `$origin.component(Factory)` — Standard Component Usage
+
+**This is the ONLY way to use origins inside `.svelte` components when you want props to flow from the parent.**
+
+> ⚠️ **Component-only:** This macro throws an error if used in `.svelte.ts` module files.
+
+```svelte
+<!-- Counter.svelte -->
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+
+	let counter = $origin.component(Counter)
+</script>
+
+<div>
+	<span>{counter.props.label}: {counter.props.count}</span>
+	<button onclick={counter.increment}>+{counter.props.step}</button>
+	<button onclick={counter.decrement}>-{counter.props.step}</button>
+	<small>Doubled: {counter.doubled}</small>
+</div>
+```
+
+**What happens at compile time:**
+
+```svelte
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+
+	type $$Props = $origin.Props<typeof Counter>
+	let { label = 'Counter', count = $bindable(0), step = 1 } = $props()
+	let __attrs = { 
+		get label() { return label }, 
+		get count() { return count }, 
+		set count(v) { count = v },
+		get step() { return step }
+	}
+	let counter = Counter(__attrs)
+</script>
+```
+
+The component's props are **automatically extracted** from the origin's schema. The parent component can pass these props normally:
+
+```svelte
+<Counter label="My Counter" count={5} step={2} />
+```
+
+---
+
+## Programmatic Origin Creation
+
+### ⚠️ NEVER Call the Factory Directly
+
+**WRONG** - This DOES NOT maintain reactivity:
+
+```ts
+// ❌ BAD - Never do this!
+const counter = Counter({
+	count: 0,
+	label: 'Test'
+})
+// counter.props.count = 5  ← This WON'T trigger reactivity!
+```
+
+The input object `{ count: 0, label: 'Test' }` is a **plain object**, not a reactive proxy. Setting `counter.props.count` won't trigger Svelte's reactivity system.
+
+### ✅ Use `$origin.create()` Instead
+
+**CORRECT** - Use `$origin.create()` for programmatic creation:
+
+```ts
+// ✅ GOOD - Always use $origin.create()
+const counter = $origin.create(Counter, {
+	count: 0,
+	label: 'Test'
+})
+// counter.props.count ← Readable, but NOT settable (read-only)
+// counter.increment() ← Methods can still modify props internally!
+```
+
+> **Note:** Props passed directly are **read-only** (getter-only). To set props externally, use `$origin.bind()`.
+
+### `$origin.create()` Works Everywhere
+
+Unlike `$origin.component()` which only works in `.svelte` files, `$origin.create()` can be used in:
+
+- ✅ `.svelte` component scripts
+- ✅ `.svelte.ts` / `.svelte.js` module files
+- ✅ Inside `$origin()` init callbacks
+- ✅ Inside origin method bodies
+- ✅ Module scripts (`<script module>`)
+
+**What happens at compile time (regular props → getter-only):**
+
+```ts
+let __attrs = {
+	// Regular props are getter-only (read-only from outside)
+	get count() { return 0 },
+	get label() { return 'Test' }
+}
+const counter = Counter(__attrs)
+```
+
+**What happens with `$origin.bind()` (getter + setter):**
+
+```ts
+let myCount = $state(0)
+let __attrs = {
+	get count() { return myCount },
+	set count(v) { myCount = v }  // Two-way binding!
+}
+const counter = Counter(__attrs)
+```
+
+### `$origin.bind(variable)` — Required for Settable Props
+
+To set an origin's prop externally (or sync with existing state), you **must** use `$origin.bind()`:
+
+```ts
+// In an origin's init or .svelte.ts file
+let sharedItems = $state(['a', 'b', 'c'])
+
+const list = $origin.create(ListOrigin, {
+	items: $origin.bind(sharedItems)  // Two-way binding!
+})
+
+// Both are now in sync:
+sharedItems.push('d')        // list.props.items now includes 'd'
+list.props.items = ['x']     // sharedItems is now ['x']
+```
+
+Mix bound and unbound props:
+
+```ts
+let count = $state(0)
+
+const counter = $origin.create(Counter, {
+	count: $origin.bind(count),  // Settable (two-way)
+	label: 'My Counter',         // Read-only
+	step: 2                      // Read-only
+})
+
+counter.props.count = 10     // ✅ Works - updates `count` too
+counter.props.label = 'New'  // ❌ No effect (read-only)
+```
+
+---
+
+## Prop Forwarding
+
+### `$origin.for(Factory)` — Forward Props to Child
+
+> ⚠️ **Component-only:** This macro throws an error if used in `.svelte.ts` module files.
+
+Use in wrapper components that need to pass props through:
+
+```svelte
+<!-- Wrapper.svelte -->
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	import CounterComponent from './Counter.svelte'
+
+	let counterProps = $origin.for(Counter)
+</script>
+
+<div class="wrapper">
+	<CounterComponent {...counterProps} />
+</div>
+```
+
+### `$origin.for('element')` — Forward Props to HTML Elements
+
+```svelte
+<!-- CustomInput.svelte -->
+<script lang="ts">
+	let inputProps = $origin.for('input')
+</script>
+
+<input {...inputProps} class="custom-input" />
+```
+
+---
+
+## Inheritance
+
+Origins can extend other origins using array syntax:
+
+```ts
+// base.svelte.ts
+export const BaseCounter = $origin({
+	props: $origin.props({
+		count: $bindable(0)
+	}),
+
+	increment() {
+		this.props.count++
+	}
+})
+
+// extended.svelte.ts  
+export const ExtendedCounter = $origin([BaseCounter], {
+	props: $origin.props({
+		step: 1  // Additional prop (merged with parent)
+	}),
+
+	// Override with super call
+	increment() {
+		this.super.increment()  // Call parent
+		console.log('Incremented!')
+	},
+
+	// New method
+	incrementByStep() {
+		this.props.count += this.props.step
+	}
+})
+```
+
+### Inheritance Rules
+
+1. Child props are **merged** with parent props (left-to-right, child overrides)
+2. Use `this.super.*` to call parent methods
+3. Child methods override parent methods with same name
+4. Derived values can be overridden
+5. Multi-level inheritance works: `this.super.super.*` for grandparent
+
+### Standalone Props Inheritance
+
+Props can also inherit from other props schemas:
+
+```ts
+export const BaseAttrs = $origin.props({
+	id: '',
+	class: ''
+})
+
+export const WidgetAttrs = $origin.props([BaseAttrs], {
+	label: 'Widget',
+	active: false
+})
+// WidgetAttrs has: id, class, label, active
+```
+
+---
+
+## Type Helpers
+
+### `$origin.Props<typeof Factory>`
+
+Extract the component props type from an origin factory. Useful for typing in non-component contexts:
+
+```ts
+import { Counter } from './counter.svelte'
+
+// Use in utility functions or type definitions
+function processProps(props: $origin.Props<typeof Counter>) {
+	console.log(props.count)
+}
+```
+
+> ⚠️ **Anti-pattern:** Do NOT manually declare `type $$Props = ...` in `.svelte` components. 
+> `svelte-origin` automatically generates the correct `$$Props` type from the origin schema.
+> Manually declaring it can cause type mismatches and breaks the automatic prop extraction.
+
+### `$origin.Of<typeof Factory>`
+
+Extract the instance type from an origin factory:
+
+```ts
+import { Counter } from './counter.svelte'
+
+// Type a variable that will hold an origin instance
+let counter: $origin.Of<typeof Counter>
+
+// Useful for optional or lazy initialization
+let maybeCounter: $origin.Of<typeof Counter> | undefined = undefined
+
+// Also works with generic factories
+const List = <T>() => $origin({ props: $origin.props({ items: [] as T[] }) })
+type StringListInstance = $origin.Of<ReturnType<typeof List<string>>>
+```
+
+---
+
+## Reactivity Internals
+
+### How Props Become Reactive
+
+Origins use **getter/setter pairs** to maintain reactivity. The key distinction:
+
+| Source | Props become | Settable externally? |
+|--------|--------------|---------------------|
+| `$origin.component()` | Connected to `$props()` | ✅ Bindable props only |
+| `$origin.create({ prop: value })` | Getter-only | ❌ No |
+| `$origin.create({ prop: $origin.bind(var) })` | Getter + setter | ✅ Yes |
+
+**Getter-only props (default for `$origin.create`):**
+
+```ts
+// Input
+$origin.create(Counter, { count: 0 })
+
+// Output - getter-only
+let __attrs = { get count() { return 0 } }
+```
+
+**Getter + setter props (with `$origin.bind`):**
+
+```ts
+// Input
+let count = $state(0)
+$origin.create(Counter, { count: $origin.bind(count) })
+
+// Output - getter AND setter
+let __attrs = {
+	get count() { return count },
+	set count(v) { count = v }
+}
+```
+
+### Why Internal Methods Still Work
+
+Even though external setting doesn't work for regular props, **origin methods** can still modify props internally because they work through `this.props.*` which bypasses the external getter-only constraint:
+
+```ts
+// Origin method can modify props
+increment() {
+	this.props.count++  // ✅ Works - internal modification
+}
+```
+
+---
+
+## Common Patterns
+
+### State Machine Origin
+
+```ts
+export const StateMachine = $origin({
+	props: $origin.props({
+		initial: 'idle' as 'idle' | 'loading' | 'success' | 'error'
+	}),
+
+	_currentState: null as string | null,
+
+	get state() {
+		return $derived(this._currentState ?? this.props.initial)
+	},
+
+	transition(to: string) {
+		this._currentState = to
+	},
+
+	get isLoading() {
+		return $derived(this.state === 'loading')
+	}
+})
+```
+
+### Form Field Origin
+
+```ts
+export const FormField = $origin({
+	props: $origin.props({
+		value: $bindable(''),
+		label: '',
+		required: false,
+		validate: ((v: string) => true) as (v: string) => boolean | string
+	}),
+
+	_touched: false,
+
+	get error() {
+		if (!this._touched) return null
+		const result = this.props.validate(this.props.value)
+		return $derived(result === true ? null : result)
+	},
+
+	get isValid() {
+		return $derived(this.error === null)
+	},
+
+	touch() {
+		this._touched = true
+	},
+
+	reset() {
+		this.props.value = ''
+		this._touched = false
+	}
+})
+```
+
+### Composing Origins
+
+```ts
+// Create child origin inside parent using init callback
+export const Parent = $origin({
+	props: $origin.props({
+		items: [] as string[]
+	}),
+
+	// Child origin with bound props
+	_child: null as ReturnType<typeof ChildOrigin> | null
+}, function() {
+	// Init callback - runs when instance is created
+	this._child = $origin.create(ChildOrigin, {
+		items: $origin.bind(this.props.items)  // Sync with parent
+	})
+})
+```
+
+---
+
+## Quick Reference
+
+### File Types & Allowed Macros
+
+| Extension | Purpose | Macros Available |
+|-----------|---------|------------------|
+| `.svelte.ts` | Origin definitions | `$origin()`, `$origin.props()`, `$origin.create()`, `$origin.bind()`, `$bindable()` |
+| `.svelte` | Svelte components | `$origin.component()`, `$origin.for()`, `$origin.create()`, `$origin.bind()` |
+
+### Context-Specific Macros
+
+| Macro | `.svelte` | `.svelte.ts` | Init callbacks |
+|-------|:---------:|:------------:|:--------------:|
+| `$origin.component()` | ✅ | ❌ throws | ❌ throws |
+| `$origin.for()` | ✅ | ❌ throws | ❌ throws |
+| `$origin.create()` | ✅ | ✅ | ✅ |
+| `$origin.bind()` | ✅ | ✅ | ✅ |
+| `$origin.props()` | ✅ | ✅ | ✅ |
+
+### Do's and Don'ts
+
+| ✅ DO | ❌ DON'T |
+|-------|----------|
+| Use `$origin.component(Factory)` in `.svelte` components | Use `$origin.component()` in `.svelte.ts` files |
+| Use `$origin.create(Factory, props)` for programmatic creation | Call `Factory({...})` directly (breaks reactivity) |
+| Use `$origin.bind(variable)` for two-way shared state | Pass reactive variables without binding |
+| Use `$derived()` for computed values in getters | Use `$state()` for props (they're already reactive) |
+| Access props via `this.props.*` | Destructure props at top level of definition |
+| Prefix private state with `_` | Expose internal state publicly |
+| Let svelte-origin auto-generate `$$Props` | Manually declare `type $$Props = ...` |
+| Use `$origin.Of<typeof F>` for instance types | Use `ReturnType<typeof F>` (less inference) |
+| Use `$origin.Props<typeof F>` for type utilities | Use `$$Props` directly in component code |
+
+### Common LLM Pitfalls
+
+1. **Calling factory directly** - `Counter({...})` loses reactivity. Always use `$origin.create()` or `$origin.component()`.
+
+2. **Using `$origin.component()` in module files** - This only works in `.svelte` files. In `.svelte.ts`, use `$origin.create()`.
+
+3. **Using `$origin.for()` in module files** - This only works in `.svelte` files.
+
+4. **Forgetting `this.props`** - Inside origins, always use `this.props.count`, not just `count` or `props.count`.
+
+5. **Using `$state()` for props** - Props passed to `$origin.props({...})` are automatically reactive. Don't wrap defaults in `$state()`.
+
+6. **Missing `$derived()` in getters** - Computed values must use `$derived()` inside getters for reactivity.
+
+7. **Expecting settable props without `$origin.bind()`** - Props in `$origin.create({ prop: value })` are **read-only**. To set props externally, use `$origin.bind(variable)`.
+
+8. **Manually declaring `$$Props`** - Never write `type $$Props = ...` in components using `$origin.component()`. The transformer auto-generates this from the origin schema. Manual declarations cause type conflicts and may break prop extraction. Ensure `svelte.config.js` includes the svelte-origin preprocessor for proper type generation.