mobx-mantle 0.3.6 → 0.6.1

package/dist/behaviors/index.d.cts

@@ -0,0 +1,275 @@
+import { Behavior, MaybeGetter } from 'mobx-mantle';
+export { M as MaybeGetter, t as toValue } from '../reactive-args-BBucrU54.cjs';
+
+/**
+ * Standard library of built-in behaviors. Every argument documented as
+ * MaybeGetter accepts either a plain value (frozen at construction) or a
+ * getter (a live connection — re-resolved whenever its observable sources
+ * change):
+ *
+ * ```tsx
+ * media = withMediaQuery('(max-width: 768px)');        // static
+ * media = withMediaQuery(() => this.props.breakpoint); // live
+ * ```
+ *
+ * Author-side conventions on display throughout this file:
+ * - `this.sync(arg)` — normalize a MaybeGetter into an ordinary field that
+ *   stays current (see withFetch, withAutosave)
+ * - `this.watch(arg, cb)` — a MaybeGetter is a valid watch source directly
+ *   (see withDebounce, withThrottle)
+ * - `toValue(arg)` — one-off reads inside effect bodies, where the getter
+ *   call doubles as dependency tracking (see withEventListener, withInterval)
+ *
+ * Several of these behaviors are themselves compositions of the others
+ * (withFetch = withAsync + watch, withWindowSize = withEventListener + state,
+ * withAutosave = withInterval + withAsync) — the same nesting available to
+ * user-defined behaviors.
+ */
+
+declare class EventListenerBehavior extends Behavior {
+    onCreate(target: MaybeGetter<EventTarget | null | undefined>, type: MaybeGetter<string>, handler: (event: Event) => void, options?: AddEventListenerOptions): void;
+}
+/**
+ * Attach an event listener for the mounted lifetime of the host. Re-attaches
+ * when a getter target or type changes.
+ *
+ * @example keys = withEventListener(window, 'keydown', (e) => this.handleKey(e));
+ */
+declare const withEventListener: {
+    (target: MaybeGetter<EventTarget | null | undefined>, type: MaybeGetter<string>, handler: (event: Event) => void, options?: AddEventListenerOptions | undefined): EventListenerBehavior;
+    new (target: MaybeGetter<EventTarget | null | undefined>, type: MaybeGetter<string>, handler: (event: Event) => void, options?: AddEventListenerOptions | undefined): EventListenerBehavior;
+};
+declare class IntervalBehavior extends Behavior {
+    onCreate(callback: () => void, delay?: MaybeGetter<number | null>): void;
+}
+/**
+ * Run a callback on an interval for the mounted lifetime of the host.
+ * A getter delay reschedules on change; resolving to null pauses.
+ *
+ * @example poll = withInterval(() => this.refresh(), 10_000);
+ */
+declare const withInterval: {
+    (callback: () => void, delay?: MaybeGetter<number | null> | undefined): IntervalBehavior;
+    new (callback: () => void, delay?: MaybeGetter<number | null> | undefined): IntervalBehavior;
+};
+declare class TimeoutBehavior extends Behavior {
+    /** True while the timeout is scheduled and hasn't fired */
+    pending: boolean;
+    onCreate(callback: () => void, delay: MaybeGetter<number | null>): void;
+}
+/**
+ * Run a callback once after a delay (measured from mount). A getter delay
+ * reschedules on change; resolving to null cancels.
+ *
+ * @example toast = withTimeout(() => (this.visible = false), 3000);
+ */
+declare const withTimeout: {
+    (callback: () => void, delay: MaybeGetter<number | null>): TimeoutBehavior;
+    new (callback: () => void, delay: MaybeGetter<number | null>): TimeoutBehavior;
+};
+declare class AsyncBehavior<T = unknown> extends Behavior {
+    value: T | undefined;
+    error: unknown;
+    loading: boolean;
+    private _fn;
+    private _runId;
+    onCreate(fn: (...args: any[]) => Promise<T>): void;
+    /**
+     * Run the async function. Out-of-order completions are discarded: only the
+     * most recent run may write value/error/loading.
+     */
+    run(...args: any[]): Promise<T | undefined>;
+    /** Discard any in-flight run's result */
+    cancel(): void;
+}
+/**
+ * Track an async function's latest run as observable value/error/loading state.
+ *
+ * @example search = withAsync((q: string) => api.search(q)); // later: this.search.run(this.query)
+ */
+declare const withAsync: {
+    <T>(fn: (...args: any[]) => Promise<T>): AsyncBehavior<T>;
+    new <T>(fn: (...args: any[]) => Promise<T>): AsyncBehavior<T>;
+};
+declare class FetchBehavior<T = unknown> extends Behavior {
+    /** Current URL — a one-way mirror of the url argument (this.sync) */
+    url: string | null | undefined;
+    /** The request state machine is a nested withAsync behavior */
+    request: AsyncBehavior<T>;
+    private _init?;
+    onCreate(url: MaybeGetter<string | null | undefined>, init?: RequestInit): void;
+    get data(): T | undefined;
+    get loading(): boolean;
+    get error(): unknown;
+}
+/**
+ * Fetch JSON from a URL. A getter URL refetches on change (the first fetch
+ * fires at mount); a URL resolving to null/undefined skips fetching.
+ * Out-of-order responses are discarded by the underlying withAsync.
+ *
+ * @example user = withFetch<User>(() => `/api/users/${this.props.userId}`);
+ */
+declare const withFetch: {
+    <T = unknown>(url: MaybeGetter<string | null | undefined>, init?: RequestInit): FetchBehavior<T>;
+    new <T = unknown>(url: MaybeGetter<string | null | undefined>, init?: RequestInit): FetchBehavior<T>;
+};
+declare class LocalStorageBehavior<T = unknown> extends Behavior {
+    value: T;
+    /** Cross-tab sync rides on a nested withEventListener */
+    storageSync: EventListenerBehavior;
+    onCreate(key: string, initialValue: T): void;
+}
+/**
+ * An observable value persisted to localStorage under `key`, hydrated from
+ * storage at construction and kept in sync across tabs. Values must be
+ * JSON-serializable.
+ *
+ * @example theme = withLocalStorage('theme', 'dark'); // read/write this.theme.value
+ */
+declare const withLocalStorage: {
+    <T>(key: string, initialValue: T): LocalStorageBehavior<T>;
+    new <T>(key: string, initialValue: T): LocalStorageBehavior<T>;
+};
+interface ElementSizeRef {
+    readonly current: Element | null;
+}
+/**
+ * Observe one ref's border-box dimensions for the mounted lifetime of its
+ * host. Setup and teardown both live in onLayoutMount so React StrictMode's
+ * effect replay always reacquires the observer against the retained DOM node.
+ */
+declare class ElementSizeBehavior extends Behavior {
+    width: number | null;
+    height: number | null;
+    private target;
+    onCreate(target: ElementSizeRef): void;
+    measure(entry?: ResizeObserverEntry): void;
+    onLayoutMount(): (() => void) | undefined;
+}
+/**
+ * Reactive layout-space border-box width and height for an element ref.
+ * CSS transforms on the element or its ancestors do not affect the reported
+ * size, so responsive components behave consistently inside scaled containers.
+ * Values are null before layout mount, while no element is attached, and
+ * after cleanup.
+ *
+ * @example
+ * root = this.ref<HTMLDivElement>();
+ * size = withElementSize(this.root);
+ */
+declare const withElementSize: {
+    (target: ElementSizeRef): ElementSizeBehavior;
+    new (target: ElementSizeRef): ElementSizeBehavior;
+};
+declare class WindowSizeBehavior extends Behavior {
+    width: number;
+    height: number;
+    resize: EventListenerBehavior;
+    measure(): void;
+}
+/**
+ * Observable window inner width/height (0×0 during SSR).
+ *
+ * @example size = withWindowSize(); // this.size.width × this.size.height
+ */
+declare const withWindowSize: {
+    (): WindowSizeBehavior;
+    new (): WindowSizeBehavior;
+};
+declare class MediaQueryBehavior extends Behavior {
+    matches: boolean;
+    onCreate(query: MaybeGetter<string>): void;
+}
+/**
+ * Observable match state for a media query (false during SSR).
+ *
+ * @example isMobile = withMediaQuery('(max-width: 768px)'); // this.isMobile.matches
+ */
+declare const withMediaQuery: {
+    (query: MaybeGetter<string>): MediaQueryBehavior;
+    new (query: MaybeGetter<string>): MediaQueryBehavior;
+};
+declare class DebounceBehavior<T = unknown> extends Behavior {
+    value: T;
+    private _timer;
+    onCreate(source: MaybeGetter<T>, delay?: number): void;
+    onUnmount(): void;
+}
+/**
+ * A debounced mirror of a reactive source: updates settle after `delay` ms of quiet.
+ *
+ * @example debouncedQuery = withDebounce(() => this.query, 300);
+ */
+declare const withDebounce: {
+    <T>(source: MaybeGetter<T>, delay?: number): DebounceBehavior<T>;
+    new <T>(source: MaybeGetter<T>, delay?: number): DebounceBehavior<T>;
+};
+declare class ThrottleBehavior<T = unknown> extends Behavior {
+    value: T;
+    private _timer;
+    private _lastEmit;
+    onCreate(source: MaybeGetter<T>, delay?: number): void;
+    onUnmount(): void;
+}
+/**
+ * A throttled mirror of a reactive source: at most one update per `delay` ms, trailing edge included.
+ *
+ * @example scrollY = withThrottle(() => this.rawScrollY, 100);
+ */
+declare const withThrottle: {
+    <T>(source: MaybeGetter<T>, delay?: number): ThrottleBehavior<T>;
+    new <T>(source: MaybeGetter<T>, delay?: number): ThrottleBehavior<T>;
+};
+declare class DocumentTitleBehavior extends Behavior {
+    onCreate(title: MaybeGetter<string>): void;
+}
+/**
+ * Set document.title for the mounted lifetime; restores the previous title on unmount.
+ *
+ * @example title = withDocumentTitle(() => `Inbox (${this.unread})`);
+ */
+declare const withDocumentTitle: {
+    (title: MaybeGetter<string>): DocumentTitleBehavior;
+    new (title: MaybeGetter<string>): DocumentTitleBehavior;
+};
+declare class PageVisibilityBehavior extends Behavior {
+    visible: boolean;
+    visibilityListener: EventListenerBehavior;
+}
+/**
+ * Observable page visibility (true during SSR).
+ *
+ * @example page = withPageVisibility(); // pause work when !this.page.visible
+ */
+declare const withPageVisibility: {
+    (): PageVisibilityBehavior;
+    new (): PageVisibilityBehavior;
+};
+declare class AutosaveBehavior extends Behavior {
+    /** Posting rides on withAsync (out-of-order completions discarded) */
+    saver: AsyncBehavior<Response>;
+    /** Scheduling rides on withInterval (assigned in onCreate, still collected) */
+    timer: IntervalBehavior;
+    /** Current save endpoint — a one-way mirror of the url argument (this.sync) */
+    url: string;
+    private _data;
+    private _lastSaved;
+    onCreate(url: MaybeGetter<string>, data: () => unknown, interval?: MaybeGetter<number | null>): void;
+    /** Save now. Skipped when the payload hasn't changed since the last save. */
+    save(): void;
+    get saving(): boolean;
+    get error(): unknown;
+}
+/**
+ * Periodically POST a data snapshot as JSON while mounted, skipping saves
+ * when nothing changed. A getter interval reschedules on change; resolving
+ * to null pauses autosaving. Call save() for an immediate flush.
+ *
+ * @example autosave = withAutosave('/api/draft', () => this.doc, 5000);
+ */
+declare const withAutosave: {
+    (url: MaybeGetter<string>, data: () => unknown, interval?: MaybeGetter<number | null> | undefined): AutosaveBehavior;
+    new (url: MaybeGetter<string>, data: () => unknown, interval?: MaybeGetter<number | null> | undefined): AutosaveBehavior;
+};
+
+export { AsyncBehavior, AutosaveBehavior, DebounceBehavior, DocumentTitleBehavior, ElementSizeBehavior, type ElementSizeRef, EventListenerBehavior, FetchBehavior, IntervalBehavior, LocalStorageBehavior, MediaQueryBehavior, PageVisibilityBehavior, ThrottleBehavior, TimeoutBehavior, WindowSizeBehavior, withAsync, withAutosave, withDebounce, withDocumentTitle, withElementSize, withEventListener, withFetch, withInterval, withLocalStorage, withMediaQuery, withPageVisibility, withThrottle, withTimeout, withWindowSize };

package/dist/behaviors/index.d.ts

@@ -0,0 +1,275 @@
+import { Behavior, MaybeGetter } from 'mobx-mantle';
+export { M as MaybeGetter, t as toValue } from '../reactive-args-BBucrU54.js';
+
+/**
+ * Standard library of built-in behaviors. Every argument documented as
+ * MaybeGetter accepts either a plain value (frozen at construction) or a
+ * getter (a live connection — re-resolved whenever its observable sources
+ * change):
+ *
+ * ```tsx
+ * media = withMediaQuery('(max-width: 768px)');        // static
+ * media = withMediaQuery(() => this.props.breakpoint); // live
+ * ```
+ *
+ * Author-side conventions on display throughout this file:
+ * - `this.sync(arg)` — normalize a MaybeGetter into an ordinary field that
+ *   stays current (see withFetch, withAutosave)
+ * - `this.watch(arg, cb)` — a MaybeGetter is a valid watch source directly
+ *   (see withDebounce, withThrottle)
+ * - `toValue(arg)` — one-off reads inside effect bodies, where the getter
+ *   call doubles as dependency tracking (see withEventListener, withInterval)
+ *
+ * Several of these behaviors are themselves compositions of the others
+ * (withFetch = withAsync + watch, withWindowSize = withEventListener + state,
+ * withAutosave = withInterval + withAsync) — the same nesting available to
+ * user-defined behaviors.
+ */
+
+declare class EventListenerBehavior extends Behavior {
+    onCreate(target: MaybeGetter<EventTarget | null | undefined>, type: MaybeGetter<string>, handler: (event: Event) => void, options?: AddEventListenerOptions): void;
+}
+/**
+ * Attach an event listener for the mounted lifetime of the host. Re-attaches
+ * when a getter target or type changes.
+ *
+ * @example keys = withEventListener(window, 'keydown', (e) => this.handleKey(e));
+ */
+declare const withEventListener: {
+    (target: MaybeGetter<EventTarget | null | undefined>, type: MaybeGetter<string>, handler: (event: Event) => void, options?: AddEventListenerOptions | undefined): EventListenerBehavior;
+    new (target: MaybeGetter<EventTarget | null | undefined>, type: MaybeGetter<string>, handler: (event: Event) => void, options?: AddEventListenerOptions | undefined): EventListenerBehavior;
+};
+declare class IntervalBehavior extends Behavior {
+    onCreate(callback: () => void, delay?: MaybeGetter<number | null>): void;
+}
+/**
+ * Run a callback on an interval for the mounted lifetime of the host.
+ * A getter delay reschedules on change; resolving to null pauses.
+ *
+ * @example poll = withInterval(() => this.refresh(), 10_000);
+ */
+declare const withInterval: {
+    (callback: () => void, delay?: MaybeGetter<number | null> | undefined): IntervalBehavior;
+    new (callback: () => void, delay?: MaybeGetter<number | null> | undefined): IntervalBehavior;
+};
+declare class TimeoutBehavior extends Behavior {
+    /** True while the timeout is scheduled and hasn't fired */
+    pending: boolean;
+    onCreate(callback: () => void, delay: MaybeGetter<number | null>): void;
+}
+/**
+ * Run a callback once after a delay (measured from mount). A getter delay
+ * reschedules on change; resolving to null cancels.
+ *
+ * @example toast = withTimeout(() => (this.visible = false), 3000);
+ */
+declare const withTimeout: {
+    (callback: () => void, delay: MaybeGetter<number | null>): TimeoutBehavior;
+    new (callback: () => void, delay: MaybeGetter<number | null>): TimeoutBehavior;
+};
+declare class AsyncBehavior<T = unknown> extends Behavior {
+    value: T | undefined;
+    error: unknown;
+    loading: boolean;
+    private _fn;
+    private _runId;
+    onCreate(fn: (...args: any[]) => Promise<T>): void;
+    /**
+     * Run the async function. Out-of-order completions are discarded: only the
+     * most recent run may write value/error/loading.
+     */
+    run(...args: any[]): Promise<T | undefined>;
+    /** Discard any in-flight run's result */
+    cancel(): void;
+}
+/**
+ * Track an async function's latest run as observable value/error/loading state.
+ *
+ * @example search = withAsync((q: string) => api.search(q)); // later: this.search.run(this.query)
+ */
+declare const withAsync: {
+    <T>(fn: (...args: any[]) => Promise<T>): AsyncBehavior<T>;
+    new <T>(fn: (...args: any[]) => Promise<T>): AsyncBehavior<T>;
+};
+declare class FetchBehavior<T = unknown> extends Behavior {
+    /** Current URL — a one-way mirror of the url argument (this.sync) */
+    url: string | null | undefined;
+    /** The request state machine is a nested withAsync behavior */
+    request: AsyncBehavior<T>;
+    private _init?;
+    onCreate(url: MaybeGetter<string | null | undefined>, init?: RequestInit): void;
+    get data(): T | undefined;
+    get loading(): boolean;
+    get error(): unknown;
+}
+/**
+ * Fetch JSON from a URL. A getter URL refetches on change (the first fetch
+ * fires at mount); a URL resolving to null/undefined skips fetching.
+ * Out-of-order responses are discarded by the underlying withAsync.
+ *
+ * @example user = withFetch<User>(() => `/api/users/${this.props.userId}`);
+ */
+declare const withFetch: {
+    <T = unknown>(url: MaybeGetter<string | null | undefined>, init?: RequestInit): FetchBehavior<T>;
+    new <T = unknown>(url: MaybeGetter<string | null | undefined>, init?: RequestInit): FetchBehavior<T>;
+};
+declare class LocalStorageBehavior<T = unknown> extends Behavior {
+    value: T;
+    /** Cross-tab sync rides on a nested withEventListener */
+    storageSync: EventListenerBehavior;
+    onCreate(key: string, initialValue: T): void;
+}
+/**
+ * An observable value persisted to localStorage under `key`, hydrated from
+ * storage at construction and kept in sync across tabs. Values must be
+ * JSON-serializable.
+ *
+ * @example theme = withLocalStorage('theme', 'dark'); // read/write this.theme.value
+ */
+declare const withLocalStorage: {
+    <T>(key: string, initialValue: T): LocalStorageBehavior<T>;
+    new <T>(key: string, initialValue: T): LocalStorageBehavior<T>;
+};
+interface ElementSizeRef {
+    readonly current: Element | null;
+}
+/**
+ * Observe one ref's border-box dimensions for the mounted lifetime of its
+ * host. Setup and teardown both live in onLayoutMount so React StrictMode's
+ * effect replay always reacquires the observer against the retained DOM node.
+ */
+declare class ElementSizeBehavior extends Behavior {
+    width: number | null;
+    height: number | null;
+    private target;
+    onCreate(target: ElementSizeRef): void;
+    measure(entry?: ResizeObserverEntry): void;
+    onLayoutMount(): (() => void) | undefined;
+}
+/**
+ * Reactive layout-space border-box width and height for an element ref.
+ * CSS transforms on the element or its ancestors do not affect the reported
+ * size, so responsive components behave consistently inside scaled containers.
+ * Values are null before layout mount, while no element is attached, and
+ * after cleanup.
+ *
+ * @example
+ * root = this.ref<HTMLDivElement>();
+ * size = withElementSize(this.root);
+ */
+declare const withElementSize: {
+    (target: ElementSizeRef): ElementSizeBehavior;
+    new (target: ElementSizeRef): ElementSizeBehavior;
+};
+declare class WindowSizeBehavior extends Behavior {
+    width: number;
+    height: number;
+    resize: EventListenerBehavior;
+    measure(): void;
+}
+/**
+ * Observable window inner width/height (0×0 during SSR).
+ *
+ * @example size = withWindowSize(); // this.size.width × this.size.height
+ */
+declare const withWindowSize: {
+    (): WindowSizeBehavior;
+    new (): WindowSizeBehavior;
+};
+declare class MediaQueryBehavior extends Behavior {
+    matches: boolean;
+    onCreate(query: MaybeGetter<string>): void;
+}
+/**
+ * Observable match state for a media query (false during SSR).
+ *
+ * @example isMobile = withMediaQuery('(max-width: 768px)'); // this.isMobile.matches
+ */
+declare const withMediaQuery: {
+    (query: MaybeGetter<string>): MediaQueryBehavior;
+    new (query: MaybeGetter<string>): MediaQueryBehavior;
+};
+declare class DebounceBehavior<T = unknown> extends Behavior {
+    value: T;
+    private _timer;
+    onCreate(source: MaybeGetter<T>, delay?: number): void;
+    onUnmount(): void;
+}
+/**
+ * A debounced mirror of a reactive source: updates settle after `delay` ms of quiet.
+ *
+ * @example debouncedQuery = withDebounce(() => this.query, 300);
+ */
+declare const withDebounce: {
+    <T>(source: MaybeGetter<T>, delay?: number): DebounceBehavior<T>;
+    new <T>(source: MaybeGetter<T>, delay?: number): DebounceBehavior<T>;
+};
+declare class ThrottleBehavior<T = unknown> extends Behavior {
+    value: T;
+    private _timer;
+    private _lastEmit;
+    onCreate(source: MaybeGetter<T>, delay?: number): void;
+    onUnmount(): void;
+}
+/**
+ * A throttled mirror of a reactive source: at most one update per `delay` ms, trailing edge included.
+ *
+ * @example scrollY = withThrottle(() => this.rawScrollY, 100);
+ */
+declare const withThrottle: {
+    <T>(source: MaybeGetter<T>, delay?: number): ThrottleBehavior<T>;
+    new <T>(source: MaybeGetter<T>, delay?: number): ThrottleBehavior<T>;
+};
+declare class DocumentTitleBehavior extends Behavior {
+    onCreate(title: MaybeGetter<string>): void;
+}
+/**
+ * Set document.title for the mounted lifetime; restores the previous title on unmount.
+ *
+ * @example title = withDocumentTitle(() => `Inbox (${this.unread})`);
+ */
+declare const withDocumentTitle: {
+    (title: MaybeGetter<string>): DocumentTitleBehavior;
+    new (title: MaybeGetter<string>): DocumentTitleBehavior;
+};
+declare class PageVisibilityBehavior extends Behavior {
+    visible: boolean;
+    visibilityListener: EventListenerBehavior;
+}
+/**
+ * Observable page visibility (true during SSR).
+ *
+ * @example page = withPageVisibility(); // pause work when !this.page.visible
+ */
+declare const withPageVisibility: {
+    (): PageVisibilityBehavior;
+    new (): PageVisibilityBehavior;
+};
+declare class AutosaveBehavior extends Behavior {
+    /** Posting rides on withAsync (out-of-order completions discarded) */
+    saver: AsyncBehavior<Response>;
+    /** Scheduling rides on withInterval (assigned in onCreate, still collected) */
+    timer: IntervalBehavior;
+    /** Current save endpoint — a one-way mirror of the url argument (this.sync) */
+    url: string;
+    private _data;
+    private _lastSaved;
+    onCreate(url: MaybeGetter<string>, data: () => unknown, interval?: MaybeGetter<number | null>): void;
+    /** Save now. Skipped when the payload hasn't changed since the last save. */
+    save(): void;
+    get saving(): boolean;
+    get error(): unknown;
+}
+/**
+ * Periodically POST a data snapshot as JSON while mounted, skipping saves
+ * when nothing changed. A getter interval reschedules on change; resolving
+ * to null pauses autosaving. Call save() for an immediate flush.
+ *
+ * @example autosave = withAutosave('/api/draft', () => this.doc, 5000);
+ */
+declare const withAutosave: {
+    (url: MaybeGetter<string>, data: () => unknown, interval?: MaybeGetter<number | null> | undefined): AutosaveBehavior;
+    new (url: MaybeGetter<string>, data: () => unknown, interval?: MaybeGetter<number | null> | undefined): AutosaveBehavior;
+};
+
+export { AsyncBehavior, AutosaveBehavior, DebounceBehavior, DocumentTitleBehavior, ElementSizeBehavior, type ElementSizeRef, EventListenerBehavior, FetchBehavior, IntervalBehavior, LocalStorageBehavior, MediaQueryBehavior, PageVisibilityBehavior, ThrottleBehavior, TimeoutBehavior, WindowSizeBehavior, withAsync, withAutosave, withDebounce, withDocumentTitle, withElementSize, withEventListener, withFetch, withInterval, withLocalStorage, withMediaQuery, withPageVisibility, withThrottle, withTimeout, withWindowSize };