svelte-origin 0.0.0 → 1.0.0-next.15

package/README.md

@@ -1 +1,412 @@
-Something great is being built here✨
+# svelte-origin
+
+Compiler-assisted state and prop ergonomics for **Svelte 5**.
+
+`svelte-origin` is intentionally **tooling-first**:
+
+- you write small, declarative “origins” using Svelte 5 runes (`$state`, `$derived`, ...)
+- you create instances explicitly **from props** (`$attrs.origin(...)`)
+- you forward props ergonomically (`$attrs.for(...)`)
+
+Everything “macro-like” compiles down to plain Svelte 5 code.
+
+
+## Why this exists
+
+Svelte 5 already has great primitives.
+
+The pain is when you want:
+
+- a *single* place to describe a prop surface (including defaults + bindables)
+- predictable, explicit “create state from props” code
+- clean prop forwarding without manually spelling every prop
+- editor inference that matches what the build does
+
+`svelte-origin` solves this with a **Svelte preprocessor** (and optionally a Vite plugin).
+
+## Installation
+
+```bash
+npm install svelte-origin
+# or
+bun add svelte-origin
+```
+
+## Setup
+
+### 1. Add the Vite plugin
+
+The plugin works with **Vite**, **Rollup**, and **Rolldown**. It transforms macros in both origin files (`.svelte.ts`) and Svelte components.
+
+```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()
+	]
+}
+```
+
+For **Rollup**:
+
+```js
+// rollup.config.js
+import svelte from 'rollup-plugin-svelte'
+import { svelteOrigin } from 'svelte-origin/plugin'
+
+export default {
+	plugins: [
+		svelteOrigin(),  // Must come BEFORE svelte
+		svelte()
+	]
+}
+```
+
+### 2. Add the Svelte preprocessor
+
+The preprocessor is required to suppress editor warnings about `$attrs` being an "illegal variable name" (since `$` is reserved for Svelte runes).
+
+```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()
+	]
+}
+```
+
+### 3. Add TypeScript globals
+
+Add `svelte-origin/globals` to your `tsconfig.json` to enable types for `$origin`, `$attrs.origin`, etc.
+
+```json
+{
+	"compilerOptions": {
+		"types": [
+			"svelte-origin/globals"
+		]
+	}
+}
+```
+
+### Plugin options
+
+```ts
+svelteOrigin({
+	// File extensions for origin definitions
+	extensions: ['.svelte.ts', '.svelte.js', '.origin.svelte.ts'],
+	
+	// Enable debug logging
+	debug: false,
+	
+	// Output transformed code to .transformed.txt files for debugging
+	outputTransformed: false,
+	
+	// Directory for transformed output files (defaults to same as source)
+	outputDir: undefined
+})
+```
+
+## The core idea
+
+### 1) Define an origin
+
+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({
+	props: $attrs({
+		/** The label for the counter */
+		label: 'Counter',
+		/** The current count value (bindable for two-way binding) */
+		count: $bindable(0),
+		/** Step value for increment/decrement (optional) */
+		step: 1 as number
+	}),
+
+	/** Internal counter (private - not exposed) */
+	_incrementCount: $state(0),
+
+	/** Get double the current count */
+	get double() {
+		return $derived(this.props.count * 2)
+	},
+
+	/** Increment by step */
+	increment() {
+		this._incrementCount++
+		this.props.count += this.props.step
+	},
+
+	/** Decrement by step */
+	decrement() {
+		this.props.count -= this.props.step
+	},
+
+	/** Reset to zero */
+	reset() {
+		this.props.count = 0
+	}
+})
+```
+
+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
+- `$state`/`$derived` are real Svelte runes
+- Properties prefixed with `_` (like `_incrementCount`) are private and not exposed on the instance type
+
+### 2) Create an instance from component props
+
+Inside a component, be explicit that the instance is derived from the component's props:
+
+```svelte
+<!-- CounterComponent.svelte -->
+<script lang="ts">
+	import { Counter } from './counter.svelte'
+	
+	// Optional: Declare $$Props for svelte-check/IDE type validation
+	type $$Props = $attrs.Of<typeof Counter>
+	
+	// Create the counter instance from component props
+	let counter = $attrs.origin(Counter)
+</script>
+
+<div class="counter">
+	<h3>{counter.props.label}</h3>
+	<p>{counter.props.count}</p>
+	<p>Double: {counter.double}</p>
+	<div class="controls">
+		<button onclick={() => counter.decrement()}>-{counter.props.step}</button>
+		<button onclick={() => counter.reset()}>Reset</button>
+		<button onclick={() => counter.increment()}>+{counter.props.step}</button>
+	</div>
+</div>
+```
+
+Key points:
+
+- We do **not** rely on "calling `Counter()` magically reads `$props()`"
+- We make the props dependency explicit via `$attrs.origin(Counter)`
+- Use `$attrs.Of<typeof Counter>` to get the component's prop types for manual `$$Props` declaration
+
+Under the hood, the macro expands to canonical `$props()` usage, so the component's prop types remain inferable.
+
+## Passing to subcomponents
+
+The rule of thumb is:
+
+- each component owns its own origin instance
+- parents forward values via props
+
+We make forwarding ergonomic using `$attrs.for(...)`. This helper forwards the intersection of the parent's props and the child's origin requirements.
+
+```svelte
+<script lang='ts'>
+	let childProps = $attrs.for(ChildOrigin)
+</script>
+
+<Child {...childProps} />
+```
+
+Notes:
+
+- `$attrs.for(...)` is intentionally about forwarding **from `$props()`**, not from an origin instance
+
+## Wrapper components / element props
+
+If you’re forwarding attributes onto a native element, the type you want is an **attribute type**, not `HTMLInputElement`.
+
+Svelte’s recommended types live in `svelte/elements`.
+
+To make this ergonomic, we can provide:
+
+```svelte
+<script lang='ts'>
+	let inputProps = $attrs.for('input')
+</script>
+
+<input {...inputProps} />
+```
+
+(`$attrs.for` is a macro that expands to a typed `$props()` + rest pattern.)
+
+
+
+## Extending origins
+
+You can extend existing origins by passing them as an array in the first argument. To access the parent implementation, use `this.super`.
+
+```ts
+export const Counter = $origin({
+	// ... base implementation
+	increment() {
+		this.props.count += 1
+	}
+})
+
+export const SuperCounter = $origin([Counter], {
+	increment() {
+		// Call the parent implementation
+		this.super.increment()
+		console.log('Incremented!')
+	}
+})
+```
+
+## 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 attachments
+
+```ts
+// widget.svelte.ts
+export const Widget = $origin({
+	props: $attrs({
+		color: 'blue'
+	}),
+
+	/** Attachment: adds a tooltip to an element */
+	$tooltip(element: Element) {
+		const tooltip = document.createElement('div')
+		tooltip.textContent = 'Tooltip for ' + this.props.color
+		element.appendChild(tooltip)
+		
+		// Return cleanup function
+		return () => tooltip.remove()
+	},
+
+	/** Attachment: highlights the element */
+	$highlight(element: Element) {
+		element.classList.add('highlighted')
+		return () => element.classList.remove('highlighted')
+	}
+})
+```
+
+### Using attachments
+
+Spread `$attachments` onto any element to apply all defined attachment behaviors:
+
+```svelte
+<script lang="ts">
+	import { Widget } from './widget.svelte'
+	let widget = $attrs.origin(Widget)
+</script>
+
+<!-- All attachment methods are applied to this div -->
+<div {...widget.$attachments}>
+	Content with tooltip and highlight
+</div>
+```
+
+### Forwarding incoming attachments
+
+When a parent uses Svelte's `{@attach ...}` directive on your component, those attachments are automatically included in `$attachments`:
+
+```svelte
+<!-- Parent.svelte -->
+<WidgetComponent {@attach myCustomAttachment} />
+```
+
+```svelte
+<!-- WidgetComponent.svelte -->
+<script lang="ts">
+	import { Widget } from './widget.svelte'
+	let widget = $attrs.origin(Widget)
+</script>
+
+<!-- Both origin-defined AND incoming attachments are applied -->
+<div {...widget.$attachments}>...</div>
+```
+
+This enables composable attachment behavior where parents can add behaviors to child component elements.
+
+## Init Callbacks
+
+Origins support an optional init callback that runs when the origin 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)
+})
+```
+
+The callback:
+- Runs after the instance is created
+- Has access to `this` (the full instance including private members)
+- Can return a cleanup function that runs when the component is destroyed
+
+## 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
+svelte-origin generate-dts [src-dir]
+svelte-origin generate-dts --clean  # Remove generated files
+```
+
+### post-process
+
+Transform macros in svelte-package output for library distribution:
+
+```bash
+svelte-package && svelte-origin post-process [dist-dir]
+```
+
+See `svelte-origin --help` for all options.
+
+## Known limitations
+
+### svelte-check type inference
+
+The `svelte-check` CLI analyzes the original source code, not the plugin-transformed output. This means it may report type errors for components using `$attrs.origin()` even though the runtime behavior is correct.
+
+**Workarounds:**
+
+1. **Use debug output** - Enable `outputTransformed: true` in the plugin options to see what the code looks like after transformation
+2. **Suppress errors** with `@ts-ignore` or `@ts-expect-error` comments where needed
+3. **Runtime works correctly** - Despite any type errors from `svelte-check`, two-way binding, reactivity, and all features work as expected
+
+For more details on the root cause, see [SVELTE-TOOLING-ARCHITECTURE.md](.docs/SVELTE-TOOLING-ARCHITECTURE.md).
+
+## License
+
+MIT

package/dist/aliases.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Comprehensive alias resolution for SvelteKit and TypeScript projects
+ *
+ * Supports:
+ * - Manual aliases passed via options
+ * - SvelteKit kit.alias from svelte.config.js
+ * - TypeScript paths from tsconfig.json (with extends support)
+ * - Auto-generated .svelte-kit/tsconfig.json
+ */
+export interface AliasConfig {
+    /** Manually provided aliases (highest priority) */
+    aliases?: Record<string, string>;
+    /** Project root directory */
+    root?: string;
+    /** Whether to auto-detect aliases from tsconfig.json and svelte.config.js */
+    autoDetect?: boolean;
+    /** Path to tsconfig.json (relative to root or absolute) */
+    tsconfig?: string;
+    /** Path to svelte.config.js (relative to root or absolute) */
+    svelteConfig?: string;
+}
+export interface ResolvedAliases {
+    /** Merged aliases from all sources */
+    aliases: Record<string, string>;
+    /** Project root */
+    root: string;
+}
+/**
+ * Resolve all aliases from various sources
+ */
+export declare function resolveAliases(config?: AliasConfig): ResolvedAliases;
+/**
+ * Resolve an import path using aliases
+ *
+ * Handles:
+ * - Exact matches: "$lib" -> "src/lib"
+ * - Prefix matches: "$lib/utils" -> "src/lib/utils"
+ * - Longest match wins: "$lib/components" before "$lib"
+ */
+export declare function resolveImportPath(importPath: string, aliases: Record<string, string>, importerDir: string): string | null;
+/**
+ * Try to resolve a file path, adding extensions if needed
+ */
+export declare function resolveFilePath(basePath: string): string | null;

package/dist/cli.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * svelte-origin CLI
+ *
+ * Commands:
+ *   post-process  Post-process svelte-package output (default)
+ *   generate-dts  Generate .svelte.d.ts files for svelte-check compatibility
+ *
+ * Usage:
+ *   svelte-origin [command] [options]
+ *   svelte-origin post-process [dist-dir]
+ *   svelte-origin generate-dts [src-dir]
+ *
+ * Options:
+ *   --help    Show help
+ *   --dry-run Show what would be done without writing
+ *   --verbose Show detailed info
+ */
+export {};