svelte-origin 0.0.0 → 1.0.0-next.15

package/LLM.md

@@ -0,0 +1,754 @@
+# svelte-origin - AI/LLM Reference
+
+This document provides comprehensive documentation for AI coding assistants working with `svelte-origin`, a compiler-assisted state and prop ergonomics library for Svelte 5.
+
+## Overview
+
+`svelte-origin` provides compile-time macros that transform into standard Svelte 5 code:
+
+- **`$origin({ ... })`** - Define reusable state + props + methods in `.svelte.ts` files
+- **`$attrs({ ... })`** - Define the props schema inside an origin
+- **`$bindable(value)`** - Mark a prop as bindable (two-way binding)
+- **`$attrs.origin(Factory)`** - Create an origin instance from component props
+- **`$attrs.for(Factory)`** - Forward props to child components
+- **`$attrs.Of<typeof Factory>`** - Type helper to extract component props
+
+## Quick Reference
+
+### Origin Definition (`.svelte.ts` file)
+
+```ts
+// counter.svelte.ts
+export const Counter = $origin({
+	// Props schema - these become component props
+	props: $attrs({
+		label: 'Counter',                    // Default value: 'Counter'
+		count: $bindable(0),                 // Bindable with default 0
+		step: 1 as number,                   // Typed with default
+		optional: undefined as string | undefined  // Optional prop
+	}),
+	
+	// Private state (prefixed with _)
+	_clickCount: $state(0),
+	
+	// Derived values (getters with $derived)
+	get double() {
+		return $derived(this.props.count * 2)
+	},
+	
+	// Methods
+	increment() {
+		this._clickCount++
+		this.props.count += this.props.step
+	},
+	
+	decrement() {
+		this.props.count -= this.props.step
+	},
+	
+	reset() {
+		this.props.count = 0
+	}
+})
+```
+
+### Component Usage (`.svelte` file)
+
+```svelte
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	
+	// Optional: Explicit $$Props for svelte-check compatibility
+	type $$Props = $attrs.Of<typeof Counter>
+	
+	// Create instance from component props
+	let counter = $attrs.origin(Counter)
+</script>
+
+<h3>{counter.props.label}</h3>
+<p>Count: {counter.props.count} (Double: {counter.double})</p>
+<button onclick={() => counter.increment()}>+{counter.props.step}</button>
+<button onclick={() => counter.decrement()}>-{counter.props.step}</button>
+<button onclick={() => counter.reset()}>Reset</button>
+```
+
+### Parent Component Using Child
+
+```svelte
+<script lang="ts">
+	import CounterComponent from './CounterComponent.svelte'
+</script>
+
+<!-- All props from Counter origin are available -->
+<CounterComponent label="My Counter" count={10} step={5} />
+
+<!-- Two-way binding works for $bindable props -->
+<CounterComponent bind:count={myCount} />
+```
+
+## API Reference
+
+### `$origin(definition)`
+
+Creates an origin factory from a definition object.
+
+**Signature:**
+```ts
+function $origin<T>(definition: T): OriginFactory<T>
+function $origin<Parents extends OriginFactory[], T>(parents: Parents, definition: T): OriginFactory<Merged<Parents, T>>
+```
+
+**Definition Object Properties:**
+
+| Property | Description |
+|----------|-------------|
+| `props: $attrs({...})` | Props schema (becomes component props) |
+| `attrs: $attrs({...})` | Alternative name for props schema |
+| `_privateField` | Private state/method (not exposed on instance) |
+| `get propertyName()` | Derived value (use `$derived` inside) |
+| `methodName()` | Method accessible on the instance |
+
+**Context (`this`) inside definition:**
+- `this.props` - Access props (reactive)
+- `this.super` - Parent instance (when extending)
+- `this._privateField` - Access private state
+
+### `$attrs(schema)`
+
+Defines the props schema inside an origin.
+
+**Example:**
+```ts
+props: $attrs({
+	// With default value (optional prop)
+	label: 'Default Label',
+	
+	// Bindable with default
+	count: $bindable(0),
+	
+	// Bindable without default (required)
+	value: $bindable(),
+	
+	// Type annotation with default
+	step: 1 as number,
+	
+	// Optional prop (no default)
+	optional: undefined as string | undefined,
+	
+	// Required prop (typed, no default)
+	required: '' as string,
+})
+```
+
+### `$bindable(defaultValue?)`
+
+Marks a prop as bindable for two-way binding.
+
+```ts
+props: $attrs({
+	// Bindable with default - optional prop
+	count: $bindable(0),
+	
+	// Bindable without default - required prop
+	value: $bindable(),
+	
+	// Bindable with typed default
+	text: $bindable('') as string,
+})
+```
+
+### `$attrs.origin(Factory)`
+
+Creates an origin instance from component props. Use inside `.svelte` components.
+
+**Example:**
+```svelte
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	
+	let counter = $attrs.origin(Counter)
+</script>
+```
+
+**Transformation:**
+```svelte
+<!-- Before (user writes) -->
+let counter = $attrs.origin(Counter)
+
+<!-- After (plugin transforms to) -->
+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)
+```
+
+### `$attrs.for(Factory)`
+
+Forwards props for child origin components.
+
+```svelte
+<script lang="ts">
+	import { ChildOrigin } from './child.svelte'
+	import ChildComponent from './ChildComponent.svelte'
+	
+	let childProps = $attrs.for(ChildOrigin)
+</script>
+
+<ChildComponent {...childProps} />
+```
+
+### `$attrs.for('element')`
+
+Gets typed rest props for HTML element wrappers.
+
+```svelte
+<script lang="ts">
+	let inputProps = $attrs.for('input')
+</script>
+
+<input {...inputProps} />
+```
+
+### `$attrs.Of<typeof Factory>`
+
+Type helper to extract component props from an origin factory.
+
+```svelte
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	
+	// Explicit $$Props declaration for svelte-check
+	type $$Props = $attrs.Of<typeof Counter>
+	
+	let counter = $attrs.origin(Counter)
+</script>
+```
+
+## Origin Inheritance
+
+Origins can extend other origins using array syntax:
+
+```ts
+// base.svelte.ts
+export const Counter = $origin({
+	props: $attrs({
+		label: 'Counter',
+		count: $bindable(0),
+		step: 1
+	}),
+	
+	increment() {
+		this.props.count += this.props.step
+	},
+	
+	decrement() {
+		this.props.count -= this.props.step
+	}
+})
+
+// extended.svelte.ts
+import { Counter } from './base.svelte'
+
+export const ExtendedCounter = $origin([Counter], {
+	props: $attrs({
+		bonus: 10  // Additional prop
+	}),
+	
+	// Override method - call parent with this.super
+	increment() {
+		this.super.increment()
+		console.log('Incremented!')
+	},
+	
+	// New method using parent
+	incrementWithBonus() {
+		this.super.increment()
+		this.super.props.count += this.props.bonus
+	},
+	
+	// Delegate derived value
+	get double() {
+		return $derived(this.super.double)
+	}
+})
+```
+
+**Inheritance Rules:**
+- Child inherits all parent props (merged with child's own props)
+- Access parent instance via `this.super`
+- Access parent props via `this.super.props`
+- Child props are on `this.props`
+- Override methods by redefining them
+- Call parent method with `this.super.methodName()`
+
+## Init Callbacks
+
+Origins can have an optional init callback that runs when the instance is created:
+
+```ts
+export const Timer = $origin({
+	props: $attrs({
+		interval: 1000
+	}),
+	
+	_count: $state(0),
+	
+	get count() {
+		return $derived(this._count)
+	}
+}, function() {
+	// Runs when the component is created
+	const id = setInterval(() => {
+		this._count++
+	}, this.props.interval)
+	
+	// Return cleanup function (runs on unmount)
+	return () => clearInterval(id)
+})
+```
+
+**Init Callback Rules:**
+- Second argument to `$origin()` (or third when extending)
+- Runs after the instance is created
+- Has access to `this` (full instance including private `_` prefixed members)
+- Can return a cleanup function that runs when the component is destroyed
+- Useful for side effects, subscriptions, or DOM interactions
+
+## 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.
+
+### Defining Attachment Methods
+
+```ts
+// widget.svelte.ts
+export const Widget = $origin({
+	props: $attrs({
+		color: 'blue',
+		tooltipText: 'Hello'
+	}),
+
+	/** Attachment: adds a tooltip to an element */
+	$tooltip(element: Element) {
+		const tooltip = document.createElement('div')
+		tooltip.className = 'tooltip'
+		tooltip.textContent = this.props.tooltipText
+		element.appendChild(tooltip)
+		
+		// Return cleanup function (runs on unmount or re-attach)
+		return () => tooltip.remove()
+	},
+
+	/** Attachment: highlights the element with the color prop */
+	$highlight(element: Element) {
+		const el = element as HTMLElement
+		const original = el.style.backgroundColor
+		el.style.backgroundColor = this.props.color
+		return () => { el.style.backgroundColor = original }
+	}
+})
+```
+
+**Key Points:**
+- Attachment methods are prefixed with `$` (e.g., `$tooltip`, `$highlight`)
+- They receive the DOM `Element` as their first argument
+- They can access `this.props`, `this.super`, and other instance members
+- Return a cleanup function to run on unmount or when the attachment re-runs
+- They are NOT exposed on the public instance type
+
+### Using `$attachments`
+
+Every origin instance has a `$attachments` getter that returns an object suitable for spreading onto elements:
+
+```svelte
+<script lang="ts">
+	import { Widget } from './widget.svelte'
+	let widget = $attrs.origin(Widget)
+</script>
+
+<!-- All attachment methods ($tooltip, $highlight) are applied -->
+<div {...widget.$attachments}>
+	Content with tooltip and highlight
+</div>
+
+<!-- Can also apply to multiple elements -->
+<button {...widget.$attachments}>Button with attachments</button>
+```
+
+### Forwarding Incoming Attachments
+
+When a parent component uses Svelte's `{@attach ...}` directive on your component, those attachments are automatically merged into `$attachments`:
+
+```svelte
+<!-- Parent.svelte -->
+<script lang="ts">
+	function logElement(el: Element) {
+		console.log('Attached to:', el)
+		return () => console.log('Detached from:', el)
+	}
+</script>
+
+<WidgetComponent {@attach logElement} color="red" />
+```
+
+```svelte
+<!-- WidgetComponent.svelte -->
+<script lang="ts">
+	import { Widget } from './widget.svelte'
+	let widget = $attrs.origin(Widget)
+</script>
+
+<!-- Both origin-defined ($tooltip, $highlight) AND incoming (logElement) attachments are applied -->
+<div {...widget.$attachments}>...</div>
+```
+
+**How it works:**
+1. Incoming attachments from `{@attach ...}` are passed as Symbol-keyed props
+2. The `$attachments` getter collects both origin-defined and incoming attachments
+3. Each attachment gets a unique Symbol key (via `createAttachmentKey()` from Svelte)
+4. When spread onto an element, Svelte's runtime registers all attachments
+
+### Attachment Type
+
+```ts
+type AttachmentFn = (this: any, element: Element) => void | (() => void)
+```
+
+The `$attachments` getter returns:
+```ts
+type SvelteOriginAttachments = {
+	[key: symbol]: (element: Element) => void | (() => void)
+}
+```
+
+## Project Setup
+
+### Installation
+
+```bash
+npm install svelte-origin
+# or
+bun add svelte-origin
+```
+
+### Vite Configuration
+
+```ts
+// vite.config.ts
+import { sveltekit } from '@sveltejs/kit/vite'
+import { svelteOrigin } from 'svelte-origin/plugin'
+
+export default {
+	plugins: [
+		svelteOrigin(),  // MUST come BEFORE sveltekit/svelte
+		sveltekit()
+	]
+}
+```
+
+### Svelte Configuration
+
+```js
+// svelte.config.js
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
+import { svelteOriginPreprocess } from 'svelte-origin/preprocess'
+
+export default {
+	preprocess: [
+		svelteOriginPreprocess(),  // MUST come BEFORE vitePreprocess
+		vitePreprocess()
+	]
+}
+```
+
+### TypeScript Configuration
+
+```json
+{
+	"compilerOptions": {
+		"types": ["svelte-origin/globals"]
+	}
+}
+```
+
+## File Naming Conventions
+
+| File Pattern | Description |
+|--------------|-------------|
+| `*.svelte.ts` | Origin definition files (runes enabled) |
+| `*.svelte` | Svelte components using origins |
+| `*.origin.svelte.ts` | Alternative pattern for origin files |
+
+## Type System
+
+### Core Types
+
+```ts
+import type {
+	SvelteOriginFactory,
+	SvelteOriginInstance,
+	SvelteOriginBindable,
+	SvelteOriginDefinition,
+	SvelteOriginComponentProps,
+} from 'svelte-origin'
+```
+
+### Factory Type
+
+```ts
+interface SvelteOriginFactory<TDef, TAllAttrs> {
+	(inputAttrs: TAllAttrs): SvelteOriginInstance<TDef>
+	readonly __origin: true
+	readonly __attrSchema: AttrSchema
+	readonly __parents: SvelteOriginFactory[]
+}
+```
+
+### Instance Type
+
+```ts
+type SvelteOriginInstance<T> = {
+	props: ReactiveAttrs<T['props']>  // Or 'attrs' if that's what you named it
+	super?: ParentInstance
+	$attachments: SvelteOriginAttachments
+} & PublicMembers<T>
+```
+
+**Note:** The `props`/`attrs` property name matches what you use in your origin definition.
+
+## Common Patterns
+
+### Counter with Two-Way Binding
+
+```ts
+// counter.svelte.ts
+export const Counter = $origin({
+	props: $attrs({
+		count: $bindable(0)
+	}),
+	
+	increment() { this.props.count++ },
+	decrement() { this.props.count-- }
+})
+```
+
+```svelte
+<!-- CounterComponent.svelte -->
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	type $$Props = $attrs.Of<typeof Counter>
+	let counter = $attrs.origin(Counter)
+</script>
+
+<button onclick={() => counter.increment()}>{counter.props.count}</button>
+```
+
+```svelte
+<!-- Parent using CounterComponent -->
+<script lang="ts">
+	let count = $state(0)
+</script>
+
+<CounterComponent bind:count />
+<p>Count in parent: {count}</p>
+```
+
+### Form Input Wrapper
+
+```ts
+// input.svelte.ts
+export const TextInput = $origin({
+	props: $attrs({
+		value: $bindable(''),
+		label: '',
+		placeholder: ''
+	}),
+	
+	handleInput(e: Event) {
+		this.props.value = (e.target as HTMLInputElement).value
+	}
+})
+```
+
+```svelte
+<!-- TextInput.svelte -->
+<script lang="ts">
+	import { TextInput } from './input.svelte'
+	type $$Props = $attrs.Of<typeof TextInput>
+	let input = $attrs.origin(TextInput)
+</script>
+
+<label>
+	{input.props.label}
+	<input 
+		type="text"
+		value={input.props.value}
+		placeholder={input.props.placeholder}
+		oninput={(e) => input.handleInput(e)}
+	/>
+</label>
+```
+
+### Toggle with Derived State
+
+```ts
+// toggle.svelte.ts
+export const Toggle = $origin({
+	props: $attrs({
+		checked: $bindable(false),
+		label: 'Toggle'
+	}),
+	
+	get labelText() {
+		return $derived(this.props.checked ? 'On' : 'Off')
+	},
+	
+	toggle() {
+		this.props.checked = !this.props.checked
+	}
+})
+```
+
+### List with Generic Types
+
+```ts
+// list.svelte.ts
+export const List = <T>() => $origin({
+	props: $attrs({
+		items: [] as T[],
+		selected: $bindable<T | null>(null)
+	}),
+	
+	get isEmpty() {
+		return $derived(this.props.items.length === 0)
+	},
+	
+	select(item: T) {
+		this.props.selected = item
+	},
+	
+	clear() {
+		this.props.selected = null
+	}
+})
+```
+
+```svelte
+<!-- Usage with generics -->
+<script lang="ts">
+	import { List } from './list.svelte'
+	
+	type Item = { id: number; name: string }
+	const ItemList = List<Item>
+	
+	type $$Props = $attrs.Of<ReturnType<typeof ItemList>>
+	let list = $attrs.origin(ItemList())
+</script>
+```
+
+## Known Limitations
+
+### svelte-check Type Inference
+
+The `svelte-check` CLI runs `svelte2tsx` on the **original** source, not the transformed output. This means:
+
+- Components using `$attrs.origin()` may show type errors
+- Runtime behavior is always correct
+- Two-way binding and reactivity work as expected
+
+**Workarounds:**
+1. Declare `type $$Props = $attrs.Of<typeof Factory>` explicitly
+2. Use `// @ts-expect-error` comments when needed
+3. Enable `outputTransformed: true` in plugin options for debugging
+
+### File Requirements
+
+- Origin definitions must be in `.svelte.ts` files (runes enabled)
+- Components using origins must import from `.svelte` or `.svelte.ts` extensions
+- Plugin must be placed **before** svelte/sveltekit plugins
+
+## Debugging
+
+### Enable Debug Output
+
+```ts
+// vite.config.ts
+svelteOrigin({
+	debug: true,
+	outputTransformed: true  // Writes .transformed.txt files
+})
+```
+
+### View Transformed Code
+
+With `outputTransformed: true`, the plugin writes `*.transformed.txt` files showing the macro expansion results.
+
+## CLI Commands
+
+The `svelte-origin` CLI provides utilities for library authors and type generation.
+
+### generate-dts
+
+Generate `.svelte.d.ts` declaration files for svelte-check compatibility:
+
+```bash
+# Generate .d.ts files for all components using $attrs.origin()
+svelte-origin generate-dts [src-dir]
+
+# Show what would be generated without writing
+svelte-origin generate-dts --dry-run
+
+# Remove generated .d.ts files
+svelte-origin generate-dts --clean
+```
+
+### post-process
+
+Transform macros in svelte-package output for library distribution:
+
+```bash
+# Run after svelte-package to transform macros in dist/
+svelte-package && svelte-origin post-process [dist-dir]
+
+# Preview what would be transformed
+svelte-origin post-process --dry-run --verbose
+```
+
+## Package Exports
+
+```ts
+// Main entry
+import { transformScript, svelteOriginDts } from 'svelte-origin'
+
+// Runtime functions
+import { __createOrigin, bindable, __attrsFor } from 'svelte-origin/runtime'
+
+// Vite/Rollup plugin
+import { svelteOrigin } from 'svelte-origin/plugin'
+
+// Svelte preprocessor
+import { svelteOriginPreprocess } from 'svelte-origin/preprocess'
+
+// Type globals (use in tsconfig.json)
+// "types": ["svelte-origin/globals"]
+```
+
+## Architecture
+
+```
+User Code                     Transformation                  Output
+─────────                     ──────────────                  ──────
+
+$origin({                     Vite Plugin                     __createOrigin({
+  props: $attrs({...}),       ─────────────►                   __attrSchema: {...},
+  ...                                                          __create: (attrs) => {...}
+})                                                            })
+
+$attrs.origin(Factory)        Plugin + Preprocessor           let {...} = $props()
+                              ─────────────────────►          let counter = Factory(...)
+```
+
+The transformation ensures:
+1. Origins compile to factory functions with schema metadata
+2. Components use standard `$props()` for proper Svelte integration
+3. Runtime behavior matches Svelte 5 expectations
+4. Two-way binding works through `$bindable()` markers