mantle-lit 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,358 @@
+import { TemplateResult, LitElement } from 'lit';
+import { IObservableValue } from 'mobx';
+
+/** Options for the watch method */
+interface WatchOptions {
+    /** Debounce the callback by N milliseconds */
+    delay?: number;
+    /** Run callback immediately with current value */
+    fireImmediately?: boolean;
+}
+/**
+ * Error context passed to the onError handler
+ */
+interface MantleErrorContext {
+    /** The lifecycle phase where the error occurred */
+    phase: 'onCreate' | 'onMount' | 'onUnmount' | 'watch';
+    /** The View or Behavior class name */
+    name: string;
+    /** Whether the error came from a Behavior (true) or a View (false) */
+    isBehavior: boolean;
+}
+/**
+ * Global configuration options for mantle-lit
+ */
+interface MantleConfig {
+    /** Whether to automatically make View/Behavior instances observable (default: true) */
+    autoObservable?: boolean;
+    /** Global error handler for lifecycle errors. Defaults to console.error. */
+    onError?: (error: unknown, context: MantleErrorContext) => void;
+}
+/**
+ * Configure global defaults for mantle-lit.
+ * Settings can still be overridden per-view in createView options.
+ */
+declare function configure(config: MantleConfig): void;
+
+/**
+ * Base class for behaviors. Provides lifecycle method signatures for IDE autocomplete.
+ * Extend this class and wrap with createBehavior() to create a factory.
+ *
+ * @example
+ * ```ts
+ * class WindowSizeBehavior extends Behavior {
+ *   width = window.innerWidth;
+ *   onCreate(breakpoint = 768) { ... }
+ *   onMount() { ... }
+ * }
+ * export const withWindowSize = createBehavior(WindowSizeBehavior);
+ * ```
+ */
+declare class Behavior {
+    /** @internal */
+    _watchDisposers: (() => void)[];
+    onCreate?(...args: any[]): void;
+    onMount?(): void | (() => void);
+    onUnmount?(): void;
+    /**
+     * Watch a reactive expression and run a callback when it changes.
+     * Automatically disposed on unmount.
+     *
+     * @param expr - Reactive expression (getter) to watch
+     * @param callback - Called when the expression result changes
+     * @param options - Optional configuration (delay, fireImmediately)
+     * @returns Dispose function for early teardown
+     *
+     * @example
+     * ```ts
+     * onCreate(url: string) {
+     *   this.url = url;
+     *   this.watch(() => this.url, () => this.fetchData());
+     * }
+     * ```
+     */
+    watch<T>(expr: () => T, callback: (value: T, prevValue: T | undefined) => void, options?: WatchOptions): () => void;
+    /** @internal */
+    _disposeWatchers(): void;
+}
+/** @internal */
+interface BehaviorEntry {
+    instance: any;
+    cleanup?: () => void;
+}
+/**
+ * Extracts parameter types from onCreate method
+ */
+type OnCreateParams<T> = T extends {
+    onCreate(...args: infer A): any;
+} ? A : [];
+/**
+ * Extracts constructor parameter types
+ */
+type ConstructorParams<T> = T extends new (...args: infer A) => any ? A : [];
+/**
+ * Determines the args for createBehavior:
+ * - If constructor has args, use those
+ * - Otherwise, if onCreate has args, use those
+ */
+type BehaviorArgs<T extends new (...args: any[]) => any> = ConstructorParams<T> extends [] ? OnCreateParams<InstanceType<T>> : ConstructorParams<T>;
+/**
+ * Type that supports both `new` and direct call syntax
+ */
+type BehaviorFactory<Args extends any[], Instance> = {
+    new (...args: Args): Instance;
+    (...args: Args): Instance;
+};
+/**
+ * Creates a behavior factory with automatic observable wrapping and lifecycle management.
+ *
+ * Returns a factory function (not a class) — use without `new`:
+ *
+ * @example Defining a behavior
+ * ```ts
+ * class DragBehavior extends Behavior {
+ *   ref!: HTMLElement | null;
+ *
+ *   onCreate(ref: HTMLElement | null) {
+ *     this.ref = ref;
+ *   }
+ *
+ *   onMount() {
+ *     this.ref?.addEventListener('pointerdown', this.onPointerDown);
+ *     return () => this.ref?.removeEventListener('pointerdown', this.onPointerDown);
+ *   }
+ * }
+ *
+ * export const withDrag = createBehavior(DragBehavior);
+ * ```
+ *
+ * @example Using in a View
+ * ```ts
+ * class Editor extends View<Props> {
+ *   canvasRef: HTMLCanvasElement | null = null;
+ *
+ *   // No `new` keyword — factory function
+ *   drag = withDrag(this.canvasRef);
+ * }
+ * export const EditorElement = createView(Editor, { tag: 'x-editor' });
+ * ```
+ *
+ * The `with` prefix convention signals that the view manages this behavior's lifecycle.
+ */
+declare function createBehavior<T extends new (...args: any[]) => any>(Def: T, options?: {
+    autoObservable?: boolean;
+}): BehaviorFactory<BehaviorArgs<T>, InstanceType<T>>;
+
+/**
+ * Decorator context type for TC39 decorators
+ */
+interface DecoratorContext {
+    kind: 'field' | 'method' | 'getter' | 'setter' | 'accessor' | 'class';
+    name: string | symbol;
+    metadata: Record<symbol, unknown>;
+}
+/**
+ * Marks a field as observable. No `accessor` keyword needed.
+ *
+ * @example
+ * ```ts
+ * class Counter extends View {
+ *   @observable count = 0;
+ * }
+ * export const CounterElement = createView(Counter, { tag: 'x-counter' });
+ * ```
+ */
+declare function observable(_value: undefined, context: DecoratorContext): void;
+declare namespace observable {
+    var ref: (_value: undefined, context: DecoratorContext) => void;
+    var shallow: (_value: undefined, context: DecoratorContext) => void;
+    var struct: (_value: undefined, context: DecoratorContext) => void;
+    var deep: (_value: undefined, context: DecoratorContext) => void;
+}
+/**
+ * Marks a method as an action. Auto-bound by default.
+ *
+ * @example
+ * ```ts
+ * class Counter extends View {
+ *   @observable count = 0;
+ *
+ *   @action increment() {
+ *     this.count++;
+ *   }
+ * }
+ * export const CounterElement = createView(Counter, { tag: 'x-counter' });
+ * ```
+ */
+declare function action(_value: Function, context: DecoratorContext): void;
+/**
+ * Marks a getter as computed.
+ * Note: Getters are automatically computed in autoObservable mode,
+ * but this decorator is useful for explicit annotation.
+ *
+ * @example
+ * ```ts
+ * class Counter extends View {
+ *   @observable count = 0;
+ *
+ *   @computed get doubled() {
+ *     return this.count * 2;
+ *   }
+ * }
+ * export const CounterElement = createView(Counter, { tag: 'x-counter' });
+ * ```
+ */
+declare function computed(_value: Function, context: DecoratorContext): void;
+
+/**
+ * Base class for Views. Extend this and use createView() to create a custom element.
+ *
+ * @example
+ * ```ts
+ * import { View, createView } from 'mantle-lit';
+ * import { html } from 'lit';
+ *
+ * class CounterView extends View<{ initial: number }> {
+ *   count = 0;
+ *
+ *   onCreate() {
+ *     this.count = this.props.initial;
+ *   }
+ *
+ *   increment() {
+ *     this.count++;
+ *   }
+ *
+ *   render() {
+ *     return html`
+ *       <button @click=${this.increment}>
+ *         Count: ${this.count}
+ *       </button>
+ *     `;
+ *   }
+ * }
+ *
+ * export const Counter = createView(CounterView, { tag: 'x-counter' });
+ * ```
+ */
+declare class View<P extends object = {}> {
+    /** @internal */
+    _propsBox: IObservableValue<P>;
+    /** Access current props (reactive) */
+    get props(): P;
+    /** @internal — called by the element to update props */
+    _syncProps(value: P): void;
+    /** @internal */
+    _behaviors: BehaviorEntry[];
+    /** @internal */
+    _watchDisposers: (() => void)[];
+    /** @internal - MobX reaction disposer for auto-render */
+    _reactionDisposer?: () => void;
+    /** @internal - Callback to request a render from the element */
+    _requestRender?: () => void;
+    onCreate?(): void;
+    onMount?(): void | (() => void);
+    onUnmount?(): void;
+    /**
+     * Watch a reactive expression and run a callback when it changes.
+     * Automatically disposed on unmount.
+     *
+     * @param expr - Reactive expression (getter) to watch
+     * @param callback - Called when the expression result changes
+     * @param options - Optional configuration (delay, fireImmediately)
+     * @returns Dispose function for early teardown
+     *
+     * @example
+     * ```ts
+     * onCreate() {
+     *   this.watch(
+     *     () => this.query,
+     *     async (query) => {
+     *       if (query.length > 2) {
+     *         this.results = await searchApi(query);
+     *       }
+     *     },
+     *     { delay: 300 }
+     *   );
+     * }
+     * ```
+     */
+    watch<T>(expr: () => T, callback: (value: T, prevValue: T | undefined) => void, options?: WatchOptions): () => void;
+    /** @internal */
+    _disposeWatchers(): void;
+    /** @internal - Scan own properties for behavior instances and register them */
+    _collectBehaviors(): void;
+    /** @internal */
+    _mountBehaviors(): void;
+    /** @internal */
+    _unmountBehaviors(): void;
+    render?(): TemplateResult | null;
+}
+
+interface CreateViewOptions {
+    /** Custom element tag name (required, must contain a hyphen) */
+    tag: string;
+    /** Whether to automatically make View instances observable (default: true) */
+    autoObservable?: boolean;
+    /** Whether to use Shadow DOM (default: true). Set to false to render in light DOM. */
+    shadow?: boolean;
+}
+/**
+ * Creates a Lit custom element from a View class.
+ *
+ * @param ViewClass - The View class to wrap
+ * @param options - Configuration options including the tag name
+ * @returns The custom element class (also registers it)
+ *
+ * @example
+ * ```ts
+ * class CounterView extends View<{ initial: number }> {
+ *   count = 0;
+ *
+ *   onCreate() {
+ *     this.count = this.props.initial;
+ *   }
+ *
+ *   increment() {
+ *     this.count++;
+ *   }
+ *
+ *   render() {
+ *     return html`<button @click=${this.increment}>Count: ${this.count}</button>`;
+ *   }
+ * }
+ *
+ * export const Counter = createView(CounterView, { tag: 'x-counter' });
+ *
+ * // Usage in HTML: <x-counter .initial=${5}></x-counter>
+ * ```
+ */
+declare function createView<V extends View<any>>(ViewClass: new () => V, options: CreateViewOptions): typeof LitElement;
+/**
+ * Helper type for defining props that will be passed as properties (not attributes).
+ * Use with .prop=${value} syntax in Lit templates.
+ */
+type Props<T> = T;
+/**
+ * Mount a view to the DOM with props.
+ *
+ * @param tag - The custom element tag name
+ * @param props - Props to pass to the component
+ * @param container - DOM element or selector to mount into (default: document.body)
+ * @returns The created element
+ *
+ * @example
+ * ```ts
+ * import { mount } from 'mantle-lit';
+ * import './Todo'; // registers x-todo
+ *
+ * mount('x-todo', {
+ *   title: 'My Tasks',
+ *   initialTodos: [{ id: 1, text: 'Learn mantle', done: false }],
+ *   onCountChange: (count) => console.log(count)
+ * });
+ * ```
+ */
+declare function mount<P extends object>(tag: string, props?: P, container?: Element | string): HTMLElement & P;
+
+export { Behavior, type CreateViewOptions, type MantleConfig, type MantleErrorContext, type Props, View, View as ViewModel, type WatchOptions, action, computed, configure, createBehavior, createView, mount, observable };

package/dist/index.d.ts

@@ -0,0 +1,358 @@
+import { TemplateResult, LitElement } from 'lit';
+import { IObservableValue } from 'mobx';
+
+/** Options for the watch method */
+interface WatchOptions {
+    /** Debounce the callback by N milliseconds */
+    delay?: number;
+    /** Run callback immediately with current value */
+    fireImmediately?: boolean;
+}
+/**
+ * Error context passed to the onError handler
+ */
+interface MantleErrorContext {
+    /** The lifecycle phase where the error occurred */
+    phase: 'onCreate' | 'onMount' | 'onUnmount' | 'watch';
+    /** The View or Behavior class name */
+    name: string;
+    /** Whether the error came from a Behavior (true) or a View (false) */
+    isBehavior: boolean;
+}
+/**
+ * Global configuration options for mantle-lit
+ */
+interface MantleConfig {
+    /** Whether to automatically make View/Behavior instances observable (default: true) */
+    autoObservable?: boolean;
+    /** Global error handler for lifecycle errors. Defaults to console.error. */
+    onError?: (error: unknown, context: MantleErrorContext) => void;
+}
+/**
+ * Configure global defaults for mantle-lit.
+ * Settings can still be overridden per-view in createView options.
+ */
+declare function configure(config: MantleConfig): void;
+
+/**
+ * Base class for behaviors. Provides lifecycle method signatures for IDE autocomplete.
+ * Extend this class and wrap with createBehavior() to create a factory.
+ *
+ * @example
+ * ```ts
+ * class WindowSizeBehavior extends Behavior {
+ *   width = window.innerWidth;
+ *   onCreate(breakpoint = 768) { ... }
+ *   onMount() { ... }
+ * }
+ * export const withWindowSize = createBehavior(WindowSizeBehavior);
+ * ```
+ */
+declare class Behavior {
+    /** @internal */
+    _watchDisposers: (() => void)[];
+    onCreate?(...args: any[]): void;
+    onMount?(): void | (() => void);
+    onUnmount?(): void;
+    /**
+     * Watch a reactive expression and run a callback when it changes.
+     * Automatically disposed on unmount.
+     *
+     * @param expr - Reactive expression (getter) to watch
+     * @param callback - Called when the expression result changes
+     * @param options - Optional configuration (delay, fireImmediately)
+     * @returns Dispose function for early teardown
+     *
+     * @example
+     * ```ts
+     * onCreate(url: string) {
+     *   this.url = url;
+     *   this.watch(() => this.url, () => this.fetchData());
+     * }
+     * ```
+     */
+    watch<T>(expr: () => T, callback: (value: T, prevValue: T | undefined) => void, options?: WatchOptions): () => void;
+    /** @internal */
+    _disposeWatchers(): void;
+}
+/** @internal */
+interface BehaviorEntry {
+    instance: any;
+    cleanup?: () => void;
+}
+/**
+ * Extracts parameter types from onCreate method
+ */
+type OnCreateParams<T> = T extends {
+    onCreate(...args: infer A): any;
+} ? A : [];
+/**
+ * Extracts constructor parameter types
+ */
+type ConstructorParams<T> = T extends new (...args: infer A) => any ? A : [];
+/**
+ * Determines the args for createBehavior:
+ * - If constructor has args, use those
+ * - Otherwise, if onCreate has args, use those
+ */
+type BehaviorArgs<T extends new (...args: any[]) => any> = ConstructorParams<T> extends [] ? OnCreateParams<InstanceType<T>> : ConstructorParams<T>;
+/**
+ * Type that supports both `new` and direct call syntax
+ */
+type BehaviorFactory<Args extends any[], Instance> = {
+    new (...args: Args): Instance;
+    (...args: Args): Instance;
+};
+/**
+ * Creates a behavior factory with automatic observable wrapping and lifecycle management.
+ *
+ * Returns a factory function (not a class) — use without `new`:
+ *
+ * @example Defining a behavior
+ * ```ts
+ * class DragBehavior extends Behavior {
+ *   ref!: HTMLElement | null;
+ *
+ *   onCreate(ref: HTMLElement | null) {
+ *     this.ref = ref;
+ *   }
+ *
+ *   onMount() {
+ *     this.ref?.addEventListener('pointerdown', this.onPointerDown);
+ *     return () => this.ref?.removeEventListener('pointerdown', this.onPointerDown);
+ *   }
+ * }
+ *
+ * export const withDrag = createBehavior(DragBehavior);
+ * ```
+ *
+ * @example Using in a View
+ * ```ts
+ * class Editor extends View<Props> {
+ *   canvasRef: HTMLCanvasElement | null = null;
+ *
+ *   // No `new` keyword — factory function
+ *   drag = withDrag(this.canvasRef);
+ * }
+ * export const EditorElement = createView(Editor, { tag: 'x-editor' });
+ * ```
+ *
+ * The `with` prefix convention signals that the view manages this behavior's lifecycle.
+ */
+declare function createBehavior<T extends new (...args: any[]) => any>(Def: T, options?: {
+    autoObservable?: boolean;
+}): BehaviorFactory<BehaviorArgs<T>, InstanceType<T>>;
+
+/**
+ * Decorator context type for TC39 decorators
+ */
+interface DecoratorContext {
+    kind: 'field' | 'method' | 'getter' | 'setter' | 'accessor' | 'class';
+    name: string | symbol;
+    metadata: Record<symbol, unknown>;
+}
+/**
+ * Marks a field as observable. No `accessor` keyword needed.
+ *
+ * @example
+ * ```ts
+ * class Counter extends View {
+ *   @observable count = 0;
+ * }
+ * export const CounterElement = createView(Counter, { tag: 'x-counter' });
+ * ```
+ */
+declare function observable(_value: undefined, context: DecoratorContext): void;
+declare namespace observable {
+    var ref: (_value: undefined, context: DecoratorContext) => void;
+    var shallow: (_value: undefined, context: DecoratorContext) => void;
+    var struct: (_value: undefined, context: DecoratorContext) => void;
+    var deep: (_value: undefined, context: DecoratorContext) => void;
+}
+/**
+ * Marks a method as an action. Auto-bound by default.
+ *
+ * @example
+ * ```ts
+ * class Counter extends View {
+ *   @observable count = 0;
+ *
+ *   @action increment() {
+ *     this.count++;
+ *   }
+ * }
+ * export const CounterElement = createView(Counter, { tag: 'x-counter' });
+ * ```
+ */
+declare function action(_value: Function, context: DecoratorContext): void;
+/**
+ * Marks a getter as computed.
+ * Note: Getters are automatically computed in autoObservable mode,
+ * but this decorator is useful for explicit annotation.
+ *
+ * @example
+ * ```ts
+ * class Counter extends View {
+ *   @observable count = 0;
+ *
+ *   @computed get doubled() {
+ *     return this.count * 2;
+ *   }
+ * }
+ * export const CounterElement = createView(Counter, { tag: 'x-counter' });
+ * ```
+ */
+declare function computed(_value: Function, context: DecoratorContext): void;
+
+/**
+ * Base class for Views. Extend this and use createView() to create a custom element.
+ *
+ * @example
+ * ```ts
+ * import { View, createView } from 'mantle-lit';
+ * import { html } from 'lit';
+ *
+ * class CounterView extends View<{ initial: number }> {
+ *   count = 0;
+ *
+ *   onCreate() {
+ *     this.count = this.props.initial;
+ *   }
+ *
+ *   increment() {
+ *     this.count++;
+ *   }
+ *
+ *   render() {
+ *     return html`
+ *       <button @click=${this.increment}>
+ *         Count: ${this.count}
+ *       </button>
+ *     `;
+ *   }
+ * }
+ *
+ * export const Counter = createView(CounterView, { tag: 'x-counter' });
+ * ```
+ */
+declare class View<P extends object = {}> {
+    /** @internal */
+    _propsBox: IObservableValue<P>;
+    /** Access current props (reactive) */
+    get props(): P;
+    /** @internal — called by the element to update props */
+    _syncProps(value: P): void;
+    /** @internal */
+    _behaviors: BehaviorEntry[];
+    /** @internal */
+    _watchDisposers: (() => void)[];
+    /** @internal - MobX reaction disposer for auto-render */
+    _reactionDisposer?: () => void;
+    /** @internal - Callback to request a render from the element */
+    _requestRender?: () => void;
+    onCreate?(): void;
+    onMount?(): void | (() => void);
+    onUnmount?(): void;
+    /**
+     * Watch a reactive expression and run a callback when it changes.
+     * Automatically disposed on unmount.
+     *
+     * @param expr - Reactive expression (getter) to watch
+     * @param callback - Called when the expression result changes
+     * @param options - Optional configuration (delay, fireImmediately)
+     * @returns Dispose function for early teardown
+     *
+     * @example
+     * ```ts
+     * onCreate() {
+     *   this.watch(
+     *     () => this.query,
+     *     async (query) => {
+     *       if (query.length > 2) {
+     *         this.results = await searchApi(query);
+     *       }
+     *     },
+     *     { delay: 300 }
+     *   );
+     * }
+     * ```
+     */
+    watch<T>(expr: () => T, callback: (value: T, prevValue: T | undefined) => void, options?: WatchOptions): () => void;
+    /** @internal */
+    _disposeWatchers(): void;
+    /** @internal - Scan own properties for behavior instances and register them */
+    _collectBehaviors(): void;
+    /** @internal */
+    _mountBehaviors(): void;
+    /** @internal */
+    _unmountBehaviors(): void;
+    render?(): TemplateResult | null;
+}
+
+interface CreateViewOptions {
+    /** Custom element tag name (required, must contain a hyphen) */
+    tag: string;
+    /** Whether to automatically make View instances observable (default: true) */
+    autoObservable?: boolean;
+    /** Whether to use Shadow DOM (default: true). Set to false to render in light DOM. */
+    shadow?: boolean;
+}
+/**
+ * Creates a Lit custom element from a View class.
+ *
+ * @param ViewClass - The View class to wrap
+ * @param options - Configuration options including the tag name
+ * @returns The custom element class (also registers it)
+ *
+ * @example
+ * ```ts
+ * class CounterView extends View<{ initial: number }> {
+ *   count = 0;
+ *
+ *   onCreate() {
+ *     this.count = this.props.initial;
+ *   }
+ *
+ *   increment() {
+ *     this.count++;
+ *   }
+ *
+ *   render() {
+ *     return html`<button @click=${this.increment}>Count: ${this.count}</button>`;
+ *   }
+ * }
+ *
+ * export const Counter = createView(CounterView, { tag: 'x-counter' });
+ *
+ * // Usage in HTML: <x-counter .initial=${5}></x-counter>
+ * ```
+ */
+declare function createView<V extends View<any>>(ViewClass: new () => V, options: CreateViewOptions): typeof LitElement;
+/**
+ * Helper type for defining props that will be passed as properties (not attributes).
+ * Use with .prop=${value} syntax in Lit templates.
+ */
+type Props<T> = T;
+/**
+ * Mount a view to the DOM with props.
+ *
+ * @param tag - The custom element tag name
+ * @param props - Props to pass to the component
+ * @param container - DOM element or selector to mount into (default: document.body)
+ * @returns The created element
+ *
+ * @example
+ * ```ts
+ * import { mount } from 'mantle-lit';
+ * import './Todo'; // registers x-todo
+ *
+ * mount('x-todo', {
+ *   title: 'My Tasks',
+ *   initialTodos: [{ id: 1, text: 'Learn mantle', done: false }],
+ *   onCountChange: (count) => console.log(count)
+ * });
+ * ```
+ */
+declare function mount<P extends object>(tag: string, props?: P, container?: Element | string): HTMLElement & P;
+
+export { Behavior, type CreateViewOptions, type MantleConfig, type MantleErrorContext, type Props, View, View as ViewModel, type WatchOptions, action, computed, configure, createBehavior, createView, mount, observable };