svelte-origin 0.0.0 → 1.0.0-next.15

package/dist/generate-dts.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Generate .svelte.d.ts declaration files for svelte-origin components
+ *
+ * This module scans directories for Svelte components that use $attrs.origin()
+ * and generates sidecar .svelte.d.ts files. These files enable svelte-check
+ * to properly type-check components, working around the limitation that
+ * svelte-check doesn't apply preprocessor transformations for type inference.
+ */
+export interface GenerateDtsOptions {
+    /** Directory to scan */
+    dir: string;
+    /** Don't write files, just report */
+    dryRun?: boolean;
+    /** Print verbose output */
+    verbose?: boolean;
+    /** Remove generated files instead of creating */
+    clean?: boolean;
+}
+export interface GenerateDtsResult {
+    /** Number of files processed */
+    filesProcessed: number;
+    /** List of files that were generated/removed */
+    files: string[];
+    /** Any errors encountered */
+    errors: string[];
+}
+/**
+ * Generate .svelte.d.ts files for all components using $attrs.origin()
+ */
+export declare function generateDtsFiles(options: GenerateDtsOptions): Promise<GenerateDtsResult>;
+export default generateDtsFiles;

package/dist/globals.d.ts

@@ -0,0 +1,576 @@
+/**
+ * Global type declarations for svelte-origin macros
+ * 
+ * Add "svelte-origin/globals" to your tsconfig.json compilerOptions.types
+ * to enable type-checking for svelte-origin macros.
+ */
+
+// ============================================================================
+// Bindable Marker Type
+// ============================================================================
+
+/**
+ * Marker type for bindable attrs.
+ */
+interface SvelteOriginBindable<T = unknown> {
+	readonly __bindable: true
+	readonly default: T
+}
+
+// ============================================================================
+// Origin Definition & Factory Types
+// ============================================================================
+
+interface SvelteOriginDefinition {
+	attrs?: Record<string, any>
+	props?: Record<string, any>
+	[key: string]: any
+}
+
+/**
+ * Extract attrs from an origin definition.
+ * Supports both 'attrs' and 'props' property names.
+ * Strips away SvelteOriginAttrsFactory interface if present.
+ */
+type SvelteOriginExtractAttrs<T extends SvelteOriginDefinition> =
+	T['props'] extends Record<string, any>
+		? SvelteOriginStripFactoryProps<T['props']>
+		: T['attrs'] extends Record<string, any>
+			? SvelteOriginStripFactoryProps<T['attrs']>
+			: {}
+
+interface SvelteOriginAttrSchemaEntry {
+	default: unknown
+	bindable: boolean
+	hasDefault: boolean
+}
+
+interface SvelteOriginAttrSchema {
+	[key: string]: SvelteOriginAttrSchemaEntry
+}
+
+/**
+ * Origin factory type.
+ * 
+ * TDef: The origin's own definition
+ * TAllAttrs: All attrs including inherited from parents (for component props)
+ */
+interface SvelteOriginFactory<
+	TDef extends SvelteOriginDefinition = SvelteOriginDefinition,
+	TAllAttrs extends Record<string, any> = TDef['attrs'] extends Record<string, any> ? TDef['attrs'] : {}
+> {
+	(inputAttrs: SvelteOriginAllAttrsInput<TAllAttrs>): SvelteOriginInstance<TDef>
+	readonly __origin: true
+	readonly __attrSchema: SvelteOriginAttrSchema
+	readonly __parents: SvelteOriginFactory<any, any>[]
+	/** Type-level marker for all attrs (including inherited) */
+	readonly __allAttrs: TAllAttrs
+}
+
+/**
+ * Filter out private keys (those starting with _) from an object type
+ */
+type SvelteOriginPublicKeys<T> = {
+	[K in keyof T as K extends `_${string}` ? never : K]: T[K]
+}
+
+/**
+ * Attachments object type - can be spread onto elements to attach behaviors.
+ * Uses createAttachmentKey() symbols as keys.
+ */
+type SvelteOriginAttachments = {
+	[key: symbol]: (element: Element) => void | (() => void)
+}
+
+/**
+ * Origin instance type - the public interface exposed to components.
+ * Properties prefixed with _ are treated as private and not accessible.
+ * Props/attrs are unwrapped (SvelteOriginBindable<T> → T).
+ */
+type SvelteOriginInstance<T extends SvelteOriginDefinition> = {
+	props: SvelteOriginReactiveAttrs<T['props']>
+	attrs: SvelteOriginReactiveAttrs<T['attrs']>
+	super?: any
+	/**
+	 * Attachments object that can be spread onto elements.
+	 * When spread, registers attachment behaviors defined in the origin.
+	 * 
+	 * @example
+	 * <div {...counter.$attachments}>...</div>
+	 */
+	readonly $attachments: SvelteOriginAttachments
+} & SvelteOriginPublicKeys<Omit<T, 'attrs' | 'props'>>
+
+/** Extract input type from attrs (unwrap bindables, make optional) */
+type SvelteOriginAllAttrsInput<T> = T extends Record<string, any>
+	? { [K in keyof T]?: SvelteOriginUnwrapBindable<T[K]> }
+	: Record<string, never>
+
+type SvelteOriginAttrsInput<T extends SvelteOriginDefinition> = T['attrs'] extends Record<string, any>
+	? { [K in keyof T['attrs']]?: SvelteOriginUnwrapBindable<T['attrs'][K]> }
+	: Record<string, never>
+
+/**
+ * Widen literal types to their base types.
+ * E.g. 0 -> number, 'hello' -> string, true -> boolean
+ */
+type SvelteOriginWiden<T> = 
+	T extends number ? number :
+	T extends string ? string :
+	T extends boolean ? boolean :
+	T extends bigint ? bigint :
+	T
+
+/**
+ * Unwrap bindable types, handling both direct and intersection types.
+ * 
+ * The key insight: `0 & SvelteOriginBindable<0>` DOES extend SvelteOriginBindable<infer U>
+ * because the intersection inherits from both sides.
+ * 
+ * Cases:
+ * - SvelteOriginBindable<T> -> widen(T)
+ * - T & SvelteOriginBindable<T> -> widen(T) (intersection inherits from SvelteOriginBindable)
+ * - T (non-bindable) -> widen(T)
+ */
+type SvelteOriginUnwrapBindable<T> = 
+	T extends SvelteOriginBindable<infer U>
+		? SvelteOriginWiden<U>
+		: SvelteOriginWiden<T>
+
+type SvelteOriginReactiveAttrs<T> = T extends Record<string, any>
+	? { [K in keyof T]: SvelteOriginUnwrapBindable<T[K]> }
+	: Record<string, never>
+
+/**
+ * Transform a definition type to have unwrapped props for use as `this` inside the definition.
+ * This ensures methods can access `this.props.count` as `number` instead of `SvelteOriginBindable<number>`.
+ */
+type SvelteOriginDefinitionThis<T extends SvelteOriginDefinition> = {
+	[K in keyof T]: K extends 'props' | 'attrs'
+		? SvelteOriginReactiveAttrs<T[K]>
+		: T[K]
+}
+
+/**
+ * The `this` context available inside an extended origin definition
+ */
+type SvelteOriginExtendedThis<
+	Parents extends SvelteOriginFactory<any, any>[],
+	Child extends SvelteOriginDefinition
+> = Child & {
+	super: Parents extends [SvelteOriginFactory<infer P, any>]
+		? SvelteOriginInstance<P>
+		: Parents extends [SvelteOriginFactory<infer P1, any>, ...infer _Rest]
+			? SvelteOriginInstance<P1>
+			: never
+}
+
+/**
+ * Merge parent attrs with child attrs (child overrides parent)
+ */
+type SvelteOriginMergeAttrs<
+	Parents extends SvelteOriginFactory<any, any>[],
+	ChildAttrs
+> = SvelteOriginExtractParentAttrs<Parents> & SvelteOriginStripFactoryProps<ChildAttrs>
+
+/**
+ * Recursively extract all attrs from parent factories
+ */
+type SvelteOriginExtractParentAttrs<Parents extends SvelteOriginFactory<any, any>[]> =
+	Parents extends [SvelteOriginFactory<any, infer A>, ...infer Rest]
+		? Rest extends SvelteOriginFactory<any, any>[]
+			? SvelteOriginStripFactoryProps<A> & SvelteOriginExtractParentAttrs<Rest>
+			: SvelteOriginStripFactoryProps<A>
+		: {}
+
+/**
+ * Extract the instance type from the first parent factory (for this.super)
+ */
+type SvelteOriginExtractParentInstance<Parents extends SvelteOriginFactory<any, any>[]> =
+	Parents extends [SvelteOriginFactory<infer P, any>, ...any[]]
+		? SvelteOriginInstance<P>
+		: never
+
+/**
+ * Merged origin definition (child + super access)
+ */
+type SvelteOriginMerged<
+	Parents extends SvelteOriginFactory<any, any>[],
+	Child extends SvelteOriginDefinition
+> = Child & {
+	super: Parents extends [SvelteOriginFactory<infer P, any>]
+		? SvelteOriginInstance<P>
+		: Parents extends [SvelteOriginFactory<infer P1, any>, ...infer _Rest]
+			? SvelteOriginInstance<P1>
+			: never
+}
+
+// ============================================================================
+// Standalone Attrs Factory Types
+// ============================================================================
+
+/**
+ * Standalone attrs factory type.
+ * Created by $attrs({...}) outside of $origin.
+ */
+interface SvelteOriginAttrsFactory<TAttrs extends Record<string, any> = Record<string, any>> {
+	readonly __attrs: true
+	readonly __attrSchema: SvelteOriginAttrSchema
+	readonly __parents: SvelteOriginAttrsFactory<any>[]
+	/** Type-level marker for attrs */
+	readonly __allAttrs: TAttrs
+}
+
+/**
+ * Strip AttrsFactory interface properties from a type.
+ * This is needed because $attrs({...}) returns SvelteOriginAttrsFactory<T> & T
+ * but we only want T when extracting attrs for component props.
+ * 
+ * Handles:
+ * - Direct SvelteOriginAttrsFactory<A> → A
+ * - Intersection SvelteOriginAttrsFactory<A> & A → A (via extracting from __allAttrs)
+ * - Other types → pass through unchanged (identity, no Omit)
+ */
+type SvelteOriginStripFactoryProps<T> = 
+	T extends { __allAttrs: infer A }
+		? A
+		: T extends SvelteOriginAttrsFactory<infer A>
+			? A
+			: T
+
+/**
+ * Extract attrs from an AttrsFactory
+ */
+type SvelteOriginExtractAttrsFromFactory<T> = 
+	T extends SvelteOriginAttrsFactory<infer A> ? A : never
+
+/**
+ * Merge attrs from multiple parent factories
+ */
+type SvelteOriginMergeAttrFactories<Parents extends SvelteOriginAttrsFactory<any>[]> =
+	Parents extends [SvelteOriginAttrsFactory<infer A>, ...infer Rest]
+		? Rest extends SvelteOriginAttrsFactory<any>[]
+			? A & SvelteOriginMergeAttrFactories<Rest>
+			: A
+		: {}
+
+// ============================================================================
+// Origin Init Callback Types
+// ============================================================================
+
+/**
+ * Cleanup function returned from init callback
+ */
+type SvelteOriginCleanupFn = () => void
+
+/**
+ * Init callback type - runs on component creation
+ * Uses the full definition type (not SvelteOriginInstance) to allow access to private members
+ */
+type SvelteOriginInitCallback<TDef extends SvelteOriginDefinition> = (
+	this: SvelteOriginFullInstance<TDef>
+) => void | SvelteOriginCleanupFn
+
+/**
+ * Full origin instance type - includes ALL members (including private _ prefixed).
+ * Used for the init callback `this` context.
+ */
+type SvelteOriginFullInstance<T extends SvelteOriginDefinition> = {
+	props: SvelteOriginReactiveAttrs<T['props']>
+	attrs: SvelteOriginReactiveAttrs<T['attrs']>
+	super?: any
+	/**
+	 * Attachments object that can be spread onto elements.
+	 */
+	readonly $attachments: SvelteOriginAttachments
+} & Omit<T, 'attrs' | 'props'>
+
+// ============================================================================
+// $attrs Global Type
+// ============================================================================
+
+/**
+ * Extract ALL component props from a factory (including inherited attrs)
+ */
+type SvelteOriginComponentProps<T> = 
+	T extends SvelteOriginFactory<any, infer AllAttrs>
+		? SvelteOriginAllAttrsInput<AllAttrs>
+		: Record<string, never>
+
+/**
+ * Extract attrs input type from a factory (what the component receives as props)
+ */
+type SvelteOriginFactoryAttrs<T> = T extends SvelteOriginFactory<infer D, any>
+	? SvelteOriginAttrsInput<D>
+	: Record<string, any>
+
+/**
+ * Combined $attrs interface with all call signatures and methods
+ */
+interface SvelteOriginAttrsGlobal {
+	/**
+	 * Create attrs extending parent(s) - 2 argument version (must come first)
+	 */
+	<
+		Parents extends SvelteOriginAttrsFactory<any>[],
+		T extends Record<string, any>
+	>(parents: [...Parents], schema: T): SvelteOriginAttrsFactory<SvelteOriginMergeAttrFactories<Parents> & T> & (SvelteOriginMergeAttrFactories<Parents> & T)
+	
+	/**
+	 * Create attrs - returns AttrsFactory for standalone use, or inline schema
+	 */
+	<T extends Record<string, any>>(schema: T): SvelteOriginAttrsFactory<T> & T
+
+	/**
+	 * Create origin instance from component attrs
+	 * 
+	 * Expands to $props() destructuring + factory call.
+	 * When using this macro, the component will accept the factory's attrs as props.
+	 * 
+	 * @example
+	 * // Non-generic origin
+	 * let counter = $attrs.origin(Counter)
+	 * 
+	 * // Generic origin (both syntaxes work)
+	 * let list = $attrs.origin(List<T>)      // auto-invoked
+	 * let list = $attrs.origin(List<T>())    // explicit call
+	 */
+	origin<T extends SvelteOriginFactory<any, any>>(
+		factory: T
+	): SvelteOriginInstance<T extends SvelteOriginFactory<infer D, any> ? D : never>
+	
+	/**
+	 * Create origin instance from a generic factory function
+	 * 
+	 * For generic factories like `const List = <T>() => $origin({...})`,
+	 * you can pass the type without calling: `$attrs.origin(List<T>)`
+	 */
+	origin<T extends () => SvelteOriginFactory<any, any>>(
+		factoryFn: T
+	): SvelteOriginInstance<ReturnType<T> extends SvelteOriginFactory<infer D, any> ? D : never>
+
+	/**
+	 * Forward attrs for child origin
+	 * 
+	 * Creates an attrs object containing only the keys needed by the child origin.
+	 * 
+	 * @example
+	 * let childAttrs = $attrs.for(ChildOrigin)
+	 */
+	for<T extends SvelteOriginFactory<any, any>>(
+		factory: T,
+		mapping?: Partial<Record<string, (source: any) => any>>
+	): SvelteOriginComponentProps<T>
+
+	/**
+	 * Typed rest attrs for HTML element wrapper
+	 * 
+	 * @example
+	 * let inputAttrs = $attrs.for('input')
+	 */
+	for<K extends keyof HTMLElementTagNameMap>(element: K): Partial<HTMLElementTagNameMap[K]>
+	for(element: string): Record<string, any>
+
+	/**
+	 * Type helper to extract component props from an origin factory.
+	 * Use this to manually declare $$Props when auto-injection is not sufficient.
+	 * 
+	 * @example
+	 * type $$Props = $attrs.Of<typeof Counter>
+	 */
+	Of: SvelteOriginOfTypeHelper
+}
+
+/**
+ * Type helper interface for $attrs.Of<T>
+ * This uses the namespace + const merging trick to allow $attrs.Of<typeof Factory>
+ */
+interface SvelteOriginOfTypeHelper {
+	// This is a phantom interface - the actual type extraction happens via the namespace below
+}
+
+/**
+ * Extract the return type of a generic factory function.
+ * Handles: typeof List<T> -> () => SvelteOriginFactory<...> -> SvelteOriginFactory<...>
+ */
+type SvelteOriginUnwrapFactoryFn<T> =
+	T extends SvelteOriginFactory<any, any>
+		? T
+		: T extends () => infer R
+			? SvelteOriginUnwrapFactoryFn<R>
+			: T extends (...args: any[]) => infer R
+				? SvelteOriginUnwrapFactoryFn<R>
+				: never
+
+// ============================================================================
+// Global Declarations
+// ============================================================================
+
+declare global {
+	/**
+	 * Define an origin (state + attrs + methods)
+	 * 
+	 * @example
+	 * export const Counter = $origin({
+	 *   props: $attrs({
+	 *     label: 'Counter',
+	 *     count: $bindable(0)
+	 *   }),
+	 *   _internal: $state(0),
+	 *   get double() { return $derived(this.props.count * 2) },
+	 *   increment() { this.props.count++ }
+	 * })
+	 */
+	function $origin<T extends SvelteOriginDefinition>(
+		definition: T & ThisType<SvelteOriginDefinitionThis<T>>
+	): SvelteOriginFactory<T, SvelteOriginExtractAttrs<T>>
+	
+	/**
+	 * Define an origin with an init callback
+	 * 
+	 * The callback runs when the component is created and has access to
+	 * the full instance via `this`. Return a cleanup function to run on unmount.
+	 * 
+	 * @example
+	 * export const Counter = $origin({
+	 *   props: $attrs({ count: $bindable(0) }),
+	 *   increment() { this.props.count++ }
+	 * }, function() {
+	 *   console.log('Created with count:', this.props.count)
+	 *   return () => console.log('Unmounting')
+	 * })
+	 */
+	function $origin<T extends SvelteOriginDefinition>(
+		definition: T & ThisType<SvelteOriginDefinitionThis<T>>,
+		onInit: SvelteOriginInitCallback<T>
+	): SvelteOriginFactory<T, SvelteOriginExtractAttrs<T>>
+	
+	/**
+	 * Define an origin extending parent(s)
+	 * 
+	 * @example
+	 * export const SuperCounter = $origin([Counter], {
+	 *   increment() {
+	 *     this.super.increment()
+	 *     console.log('Incremented!')
+	 *   }
+	 * })
+	 */
+	function $origin<
+		Parents extends SvelteOriginFactory<any, any>[],
+		T extends SvelteOriginDefinition
+	>(
+		parents: [...Parents],
+		definition: T & ThisType<SvelteOriginDefinitionThis<T> & { super: SvelteOriginExtractParentInstance<Parents> }>
+	): SvelteOriginFactory<
+		SvelteOriginMerged<Parents, T>,
+		SvelteOriginMergeAttrs<Parents, SvelteOriginExtractAttrs<T>>
+	>
+	
+	/**
+	 * Define an origin extending parent(s) with an init callback
+	 * 
+	 * @example
+	 * export const SuperCounter = $origin([Counter], {
+	 *   increment() { this.super.increment() }
+	 * }, function() {
+	 *   console.log('SuperCounter created')
+	 *   return () => console.log('SuperCounter unmounting')
+	 * })
+	 */
+	function $origin<
+		Parents extends SvelteOriginFactory<any, any>[],
+		T extends SvelteOriginDefinition
+	>(
+		parents: [...Parents],
+		definition: T & ThisType<SvelteOriginDefinitionThis<T> & { super: SvelteOriginExtractParentInstance<Parents> }>,
+		onInit: SvelteOriginInitCallback<SvelteOriginMerged<Parents, T>>
+	): SvelteOriginFactory<
+		SvelteOriginMerged<Parents, T>,
+		SvelteOriginMergeAttrs<Parents, SvelteOriginExtractAttrs<T>>
+	>
+	
+	/**
+	 * $attrs global for svelte-origin macros
+	 * 
+	 * Can be used as:
+	 * - A function: $attrs({...}) to create standalone attrs factory or inline schema
+	 * - A function with parents: $attrs([Parent], {...}) to extend attrs
+	 * - An object: $attrs.origin(...), $attrs.for(...), $attrs.Of<T>
+	 */
+	const $attrs: SvelteOriginAttrsGlobal
+
+	/**
+	 * Mark a prop as bindable (two-way binding) with an optional default value.
+	 * 
+	 * Returns the value type (T) for compatibility with Svelte's $bindable,
+	 * but also acts as a marker for the origin's attr schema.
+	 * 
+	 * @example
+	 * props: $attrs({
+	 *   count: $bindable(0),      // bindable with default 0
+	 *   name: $bindable<string>() // bindable, required (no default)
+	 * })
+	 */
+	function $bindable<T>(defaultValue: T): T & SvelteOriginBindable<T>
+	function $bindable<T>(): (T | undefined) & SvelteOriginBindable<T | undefined>
+
+	/**
+	 * Namespace for $attrs.Of<T> type helper.
+	 * This enables the syntax: type $$Props = $attrs.Of<typeof Factory>
+	 */
+	namespace $attrs {
+		/**
+		 * Extract ALL component props from an origin factory (including inherited attrs).
+		 * 
+		 * Supports:
+		 * - Direct factories: `$attrs.Of<typeof Counter>`
+		 * - Generic factory functions: `$attrs.Of<typeof List<T>>` or `$attrs.Of<ReturnType<typeof List<T>>>`
+		 * 
+		 * @example
+		 * type $$Props = $attrs.Of<typeof Counter>
+		 * type $$Props = $attrs.Of<typeof ExtendedCounter>  // Includes parent attrs!
+		 * type $$Props = $attrs.Of<typeof Counter> & { extraProp?: string }
+		 * 
+		 * // Generic origins
+		 * const List = <T>() => $origin({ attrs: $attrs({ items: [] as T[] }) })
+		 * type $$Props = $attrs.Of<ReturnType<typeof List<T>>>
+		 */
+		type Of<T> = 
+			SvelteOriginUnwrapFactoryFn<T> extends SvelteOriginFactory<any, infer AllAttrs>
+				? SvelteOriginAllAttrsInput<SvelteOriginStripFactoryProps<AllAttrs>>
+				: T extends (attrs: infer A) => any
+					? A & Record<string, any>
+					: Record<string, any>
+	}
+}
+
+export type {
+	SvelteOriginBindable,
+	SvelteOriginDefinition,
+	SvelteOriginFactory,
+	SvelteOriginInstance,
+	SvelteOriginFullInstance,
+	SvelteOriginAttrSchema,
+	SvelteOriginAttrSchemaEntry,
+	SvelteOriginAttrsGlobal,
+	SvelteOriginAttrsInput,
+	SvelteOriginAllAttrsInput,
+	SvelteOriginReactiveAttrs,
+	SvelteOriginUnwrapBindable,
+	SvelteOriginExtractAttrs,
+	SvelteOriginStripFactoryProps,
+	SvelteOriginComponentProps,
+	SvelteOriginFactoryAttrs,
+	SvelteOriginMergeAttrs,
+	SvelteOriginMerged,
+	SvelteOriginExtendedThis,
+	SvelteOriginPublicKeys,
+	SvelteOriginExtractParentAttrs,
+	SvelteOriginUnwrapFactoryFn,
+	SvelteOriginAttrsFactory,
+	SvelteOriginExtractAttrsFromFactory,
+	SvelteOriginMergeAttrFactories,
+	SvelteOriginCleanupFn,
+	SvelteOriginInitCallback
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * svelte-origin
+ *
+ * Compiler-assisted state and prop ergonomics for Svelte 5
+ */
+export * from './runtime';
+export type { SvelteOriginBindable, SvelteOriginDefinition, SvelteOriginFactory, SvelteOriginInstance, SvelteOriginAttrSchema, SvelteOriginAttrSchemaEntry, SvelteOriginAttrsGlobal, SvelteOriginAttrsInput, SvelteOriginAllAttrsInput, SvelteOriginReactiveAttrs, SvelteOriginUnwrapBindable, SvelteOriginExtractAttrs, SvelteOriginStripFactoryProps, SvelteOriginComponentProps, SvelteOriginFactoryAttrs, SvelteOriginMergeAttrs, SvelteOriginMerged, SvelteOriginExtendedThis, SvelteOriginPublicKeys, SvelteOriginExtractParentAttrs, SvelteOriginUnwrapFactoryFn } from './globals';
+export { transformScript, type TransformOptions, type TransformResult } from './transform/core';
+export { svelteOriginDts, type DtsGeneratorOptions } from './vite-dts';