svelte-origin 1.0.0-next.23 → 1.0.0-next.25

package/LLM.md

@@ -102,8 +102,7 @@ function $origin<Parents extends OriginFactory[], T>(parents: Parents, definitio
 
 | Property | Description |
 |----------|-------------|
-| `props: $attrs({...})` | Props schema (becomes component props) |
-| `attrs: $attrs({...})` | Alternative name for props schema |
+| `props: $attrs({...})` | Props schema (recommended name) |
 | `_privateField` | Private state/method (not exposed on instance) |
 | `get propertyName()` | Derived value (use `$derived` inside) |
 | `methodName()` | Method accessible on the instance |
@@ -313,6 +312,99 @@ export const Timer = $origin({
 - Can return a cleanup function that runs when the component is destroyed
 - Useful for side effects, subscriptions, or DOM interactions
 
+## Origin Destructuring
+
+Destructure methods and props from origin instances with automatic handling.
+
+### Method Destructuring
+
+Methods are automatically bound to preserve `this` context:
+
+```svelte
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	let counter = $attrs.origin(Counter)
+	
+	// Destructure methods - automatically bound
+	let { increment, decrement } = counter
+	
+	// Transforms to:
+	// let increment = counter.increment.bind(counter)
+	// let decrement = counter.decrement.bind(counter)
+</script>
+
+<button onclick={increment}>+</button>
+<button onclick={decrement}>-</button>
+```
+
+### Props Destructuring
+
+Props are automatically wrapped in `$derived` for reactivity:
+
+```svelte
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	let counter = $attrs.origin(Counter)
+	
+	// Destructure props - automatically reactive
+	let { count, label } = counter.props
+	
+	// Transforms to:
+	// let count = $derived(counter.props.count)
+	// let label = $derived(counter.props.label)
+</script>
+
+<p>{label}: {count}</p>
+```
+
+### Nested Props Destructuring
+
+Combine method and props destructuring in a single pattern:
+
+```svelte
+<script lang="ts">
+	let { increment, props: { count, label } } = counter
+	
+	// Transforms to:
+	// let increment = counter.increment.bind(counter)
+	// let count = $derived(counter.props.count)
+	// let label = $derived(counter.props.label)
+</script>
+```
+
+### Aliases and Defaults
+
+```svelte
+<script lang="ts">
+	// Alias methods
+	let { increment: inc } = counter
+	
+	// Alias props with defaults
+	let { count: counterValue = 0 } = counter.props
+	
+	// Transforms to:
+	// let inc = counter.increment.bind(counter)
+	// let counterValue = $derived(counter.props.count ?? 0)
+</script>
+```
+
+### Coexistence with $props()
+
+When you have your own `$props()` and also use `$attrs.origin()`:
+
+```svelte
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	
+	let { myOwnProp = 'hello' } = $props()
+	let counter = $attrs.origin(Counter)
+	
+	// Transforms to:
+	// let { myOwnProp = 'hello', ...___originAttrs } = $props()
+	// let counter = Counter(__attrsFor(Counter, ___originAttrs))
+</script>
+```
+
 ## Attachments
 
 Origins can define **attachment methods** that run when an element is attached to the DOM. These are methods prefixed with `$` that receive the element and optionally return a cleanup function.
@@ -507,13 +599,13 @@ interface SvelteOriginFactory<TDef, TAllAttrs> {
 
 ```ts
 type SvelteOriginInstance<T> = {
-	props: ReactiveAttrs<T['props']>  // Or 'attrs' if that's what you named it
+	props: ReactiveAttrs<T['props']>
 	super?: ParentInstance
 	$attachments: SvelteOriginAttachments
 } & PublicMembers<T>
 ```
 
-**Note:** The `props`/`attrs` property name matches what you use in your origin definition.
+**Note:** The property name `props` is the recommended convention for the props schema.
 
 ## Common Patterns
 

package/README.md

@@ -121,8 +121,6 @@ svelteOrigin({
 
 Write origins in a file where runes are allowed (e.g. `.svelte.ts`).
 
-This README describes the **macro** style (preferred direction):
-
 ```ts
 // counter.svelte.ts
 export const Counter = $origin({
@@ -164,11 +162,11 @@ export const Counter = $origin({
 Notes:
 
 - `$origin(...)` is a **compile-time macro** provided by `svelte-origin` (not a Svelte rune)
-- `props: $attrs({...})` is also a macro in origin definitions
-	- this uses `$attrs` to avoid conflict with Svelte's `$props()` rune
-	- it compiles into the origin's prop schema and default/bindable handling
-	- the property name (`props`) is arbitrary—you can name it `attrs`, `options`, or anything else
-- `$bindable(...)` inside `props: $attrs({...})` is treated as a marker (macro) and compiles away
+- `props: $attrs({...})` defines the component props schema
+	- uses `$attrs` to avoid conflict with Svelte's `$props()` rune
+	- compiles into the origin's prop schema with defaults and bindable handling
+	- the property name (`props`) is the recommended convention
+- `$bindable(...)` inside `props: $attrs({...})` marks props for two-way binding
 - `$state`/`$derived` are real Svelte runes
 - Properties prefixed with `_` (like `_incrementCount`) are private and not exposed on the instance type
 
@@ -393,6 +391,62 @@ svelte-package && svelte-origin post-process [dist-dir]
 
 See `svelte-origin --help` for all options.
 
+## Origin Destructuring
+
+Destructure methods and props from origin instances with automatic handling:
+
+### Method Destructuring
+
+Methods are automatically bound to preserve `this` context:
+
+```svelte
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	let counter = $attrs.origin(Counter)
+	
+	// Destructure methods - automatically bound
+	let { increment, decrement } = counter
+</script>
+
+<button onclick={increment}>+</button>
+<button onclick={decrement}>-</button>
+```
+
+### Props Destructuring
+
+Props are automatically wrapped in `$derived` for reactivity:
+
+```svelte
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	let counter = $attrs.origin(Counter)
+	
+	// Destructure props - automatically reactive
+	let { count, label } = counter.props
+</script>
+
+<p>{label}: {count}</p>
+```
+
+### Nested Destructuring
+
+Combine method and props destructuring:
+
+```svelte
+<script lang="ts">
+	let { increment, props: { count, label } } = counter
+</script>
+```
+
+### Aliases and Defaults
+
+```svelte
+<script lang="ts">
+	let { increment: inc } = counter
+	let { count: counterValue = 0 } = counter.props
+</script>
+```
+
 ## Known limitations
 
 ### svelte-check type inference