@getforma/core 1.0.10 → 1.2.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 /// <reference path="./jsx.d.ts" />
-import { S as SignalGetter } from './signal-C9v4akyJ.cjs';
-export { a as SignalOptions, b as SignalSetter, c as createSignal } from './signal-C9v4akyJ.cjs';
-export { R as Resource, a as ResourceOptions, c as createResource } from './resource-DeEzxUz6.cjs';
+import { S as SignalGetter } from './signal-CRBJYQ6B.cjs';
+export { a as SignalOptions, b as SignalSetter, c as createSignal } from './signal-CRBJYQ6B.cjs';
+export { R as Resource, a as ResourceOptions, c as createResource } from './resource-D6HfVgiA.cjs';
 export { getBatchDepth, isComputed, isEffect, isEffectScope, isSignal, trigger } from 'alien-signals';
 
 declare function createEffect(fn: () => void | (() => void)): () => void;
@@ -125,21 +125,6 @@ declare function batch(fn: () => void): void;
  */
 declare function untrack<T>(fn: () => T): T;
 
-/**
- * Forma Reactive - Root
- *
- * Explicit reactive ownership scope. All effects created inside a root
- * are automatically disposed when the root is torn down.
- *
- * Uses alien-signals' `effectScope` under the hood for native graph-level
- * effect tracking, with a userland disposer list for non-effect cleanup
- * (e.g., event listeners, DOM references, timers).
- *
- * Roots created inside another root are automatically owned by the parent
- * (Solid-style). When the parent is disposed, all child roots are disposed
- * too. Use {@link createUnownedRoot} for roots that must outlive their
- * lexical parent (e.g., mount points, test harnesses).
- */
 /**
  * Create a reactive root scope.
  *
@@ -312,22 +297,23 @@ type Dispatch<A> = (action: A) => void;
  */
 declare function createReducer<S, A>(reducer: (state: S, action: A) => S, initialState: S): [state: SignalGetter<S>, dispatch: Dispatch<A>];
 
-/** Callback signature for the global {@link onError} handler. */
+/** Callback signature for a global {@link onError} handler. */
 type ErrorHandler = (error: unknown, info?: {
     source?: string;
 }) => void;
 /**
- * Install a global error handler for FormaJS reactive errors.
- * Called when effects, computeds, or event handlers throw.
+ * Install a global error handler for FormaJS reactive errors. Called when
+ * effects, computeds, or event handlers throw. Multiple handlers may be
+ * registered; returns an unsubscribe function that removes only this handler.
  *
  * ```ts
- * onError((err, info) => {
- *   console.error(`[${info?.source}]`, err);
- *   Sentry.captureException(err);
+ * const off = onError((err, info) => {
+ *   Sentry.captureException(err, { tags: { source: info?.source } });
  * });
+ * // later: off();
  * ```
  */
-declare function onError(handler: ErrorHandler): void;
+declare function onError(handler: ErrorHandler): () => void;
 
 /**
  * Forma DOM - Element
@@ -957,6 +943,8 @@ interface HistoryControls<T> {
     cursor: () => number;
     /** Clear all history, keeping only the current value. */
     clear: () => void;
+    /** Stop tracking the source signal and release the history stack. */
+    destroy: () => void;
 }
 /**
  * Create undo/redo history tracking for a signal.
@@ -971,6 +959,13 @@ interface HistoryControls<T> {
  * h.redo();            // count() === 2
  * h.canUndo();         // true (reactive)
  * ```
+ *
+ * **Limitation:** the source must be a signal whose getter returns a stable
+ * value (a primitive or a stable object reference). A `createStore` slice whose
+ * getter returns a *fresh proxy on every read* is not supported: the undo/redo
+ * echo guard compares by identity, so a new proxy each read makes every
+ * undo/redo look like an external change and clears the redo history. Track
+ * store state with `setState`/direct mutation, not `createHistory`.
  */
 declare function createHistory<T>(source: [get: () => T, set: (v: T) => void], options?: {
     maxLength?: number;
@@ -983,6 +978,8 @@ declare function createHistory<T>(source: [get: () => T, set: (v: T) => void], o
  * Reads stored value on creation; writes on every signal change.
  * Zero dependencies -- native browser APIs only.
  */
+/** The phase in which a persist operation failed, passed to {@link PersistOptions.onError}. */
+type PersistErrorPhase = 'hydrate' | 'serialize' | 'write' | 'migrate';
 /** Options for {@link persist} — storage backend, serialization, and validation. */
 interface PersistOptions<T> {
     /** Storage backend. Defaults to localStorage. */
@@ -993,6 +990,14 @@ interface PersistOptions<T> {
     deserialize?: (s: string) => T;
     /** Optional validator — return true if the deserialized value is valid. Rejects corrupt/tampered data. */
     validate?: (v: unknown) => v is T;
+    /** Current schema version. When set, values are stored in a versioned envelope. */
+    version?: number;
+    /** Migrate stored data whose version is older than {@link version}. Runs before validate. */
+    migrate?: (oldValue: unknown, oldVersion: number) => T;
+    /** Re-hydrate when another tab writes this key. Defaults to true for localStorage. */
+    syncTabs?: boolean;
+    /** Report hydrate/serialize/write/migrate failures instead of swallowing them. */
+    onError?: (err: unknown, phase: PersistErrorPhase) => void;
 }
 /**
  * Persist a signal's value to storage.
@@ -1007,7 +1012,7 @@ interface PersistOptions<T> {
  * setTheme('dark'); // auto-saved to localStorage under key 'app:theme'
  * ```
  */
-declare function persist<T>(source: [get: () => T, set: (v: T) => void], key: string, options?: PersistOptions<T>): void;
+declare function persist<T>(source: [get: () => T, set: (v: T) => void], key: string, options?: PersistOptions<T>): () => void;
 
 /**
  * A typed publish/subscribe event bus.
@@ -1170,4 +1175,4 @@ declare function onIntersect(el: HTMLElement, handler: (entry: IntersectionObser
  */
 declare function onMutation(el: HTMLElement, handler: (mutations: MutationRecord[]) => void, options?: MutationObserverInit): () => void;
 
-export { $, $$, type CleanupFn, type ComponentDef, type Context, type CreateListOptions, type Dispatch, type ErrorHandler, type EventBus, Fragment, type HistoryControls, type IslandHydrateFn, type KeyOptions, type ListTransitionHooks, type PersistOptions, type ReconcileResult, type Ref, type SetupFn, SignalGetter, type StoreSetter, type SwitchCase, activateIslands, addClass, batch, children, cleanup, closest, createBus, createComputed, createContext, createEffect, createErrorBoundary, createHistory, createList, createMemo, createPortal, createReducer, createRef, createRoot, createShow, createStore, createSuspense, createSwitch, createText, createUnownedRoot, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, fragment, h, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, removeClass, setAttr, setHTMLUnsafe, setStyle, setText, siblings, template, templateMany, toggleClass, trackDisposer, unprovide, untrack };
+export { $, $$, type CleanupFn, type ComponentDef, type Context, type CreateListOptions, type Dispatch, type ErrorHandler, type EventBus, Fragment, type HistoryControls, type IslandHydrateFn, type KeyOptions, type ListTransitionHooks, type PersistErrorPhase, type PersistOptions, type ReconcileResult, type Ref, type SetupFn, SignalGetter, type StoreSetter, type SwitchCase, activateIslands, addClass, batch, children, cleanup, closest, createBus, createComputed, createContext, createEffect, createErrorBoundary, createHistory, createList, createMemo, createPortal, createReducer, createRef, createRoot, createShow, createStore, createSuspense, createSwitch, createText, createUnownedRoot, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, fragment, h, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, removeClass, setAttr, setHTMLUnsafe, setStyle, setText, siblings, template, templateMany, toggleClass, trackDisposer, unprovide, untrack };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /// <reference path="./jsx.d.ts" />
-import { S as SignalGetter } from './signal-C9v4akyJ.js';
-export { a as SignalOptions, b as SignalSetter, c as createSignal } from './signal-C9v4akyJ.js';
-export { R as Resource, a as ResourceOptions, c as createResource } from './resource-BHsgURy0.js';
+import { S as SignalGetter } from './signal-CRBJYQ6B.js';
+export { a as SignalOptions, b as SignalSetter, c as createSignal } from './signal-CRBJYQ6B.js';
+export { R as Resource, a as ResourceOptions, c as createResource } from './resource-ljs2X5NM.js';
 export { getBatchDepth, isComputed, isEffect, isEffectScope, isSignal, trigger } from 'alien-signals';
 
 declare function createEffect(fn: () => void | (() => void)): () => void;
@@ -125,21 +125,6 @@ declare function batch(fn: () => void): void;
  */
 declare function untrack<T>(fn: () => T): T;
 
-/**
- * Forma Reactive - Root
- *
- * Explicit reactive ownership scope. All effects created inside a root
- * are automatically disposed when the root is torn down.
- *
- * Uses alien-signals' `effectScope` under the hood for native graph-level
- * effect tracking, with a userland disposer list for non-effect cleanup
- * (e.g., event listeners, DOM references, timers).
- *
- * Roots created inside another root are automatically owned by the parent
- * (Solid-style). When the parent is disposed, all child roots are disposed
- * too. Use {@link createUnownedRoot} for roots that must outlive their
- * lexical parent (e.g., mount points, test harnesses).
- */
 /**
  * Create a reactive root scope.
  *
@@ -312,22 +297,23 @@ type Dispatch<A> = (action: A) => void;
  */
 declare function createReducer<S, A>(reducer: (state: S, action: A) => S, initialState: S): [state: SignalGetter<S>, dispatch: Dispatch<A>];
 
-/** Callback signature for the global {@link onError} handler. */
+/** Callback signature for a global {@link onError} handler. */
 type ErrorHandler = (error: unknown, info?: {
     source?: string;
 }) => void;
 /**
- * Install a global error handler for FormaJS reactive errors.
- * Called when effects, computeds, or event handlers throw.
+ * Install a global error handler for FormaJS reactive errors. Called when
+ * effects, computeds, or event handlers throw. Multiple handlers may be
+ * registered; returns an unsubscribe function that removes only this handler.
  *
  * ```ts
- * onError((err, info) => {
- *   console.error(`[${info?.source}]`, err);
- *   Sentry.captureException(err);
+ * const off = onError((err, info) => {
+ *   Sentry.captureException(err, { tags: { source: info?.source } });
  * });
+ * // later: off();
  * ```
  */
-declare function onError(handler: ErrorHandler): void;
+declare function onError(handler: ErrorHandler): () => void;
 
 /**
  * Forma DOM - Element
@@ -957,6 +943,8 @@ interface HistoryControls<T> {
     cursor: () => number;
     /** Clear all history, keeping only the current value. */
     clear: () => void;
+    /** Stop tracking the source signal and release the history stack. */
+    destroy: () => void;
 }
 /**
  * Create undo/redo history tracking for a signal.
@@ -971,6 +959,13 @@ interface HistoryControls<T> {
  * h.redo();            // count() === 2
  * h.canUndo();         // true (reactive)
  * ```
+ *
+ * **Limitation:** the source must be a signal whose getter returns a stable
+ * value (a primitive or a stable object reference). A `createStore` slice whose
+ * getter returns a *fresh proxy on every read* is not supported: the undo/redo
+ * echo guard compares by identity, so a new proxy each read makes every
+ * undo/redo look like an external change and clears the redo history. Track
+ * store state with `setState`/direct mutation, not `createHistory`.
  */
 declare function createHistory<T>(source: [get: () => T, set: (v: T) => void], options?: {
     maxLength?: number;
@@ -983,6 +978,8 @@ declare function createHistory<T>(source: [get: () => T, set: (v: T) => void], o
  * Reads stored value on creation; writes on every signal change.
  * Zero dependencies -- native browser APIs only.
  */
+/** The phase in which a persist operation failed, passed to {@link PersistOptions.onError}. */
+type PersistErrorPhase = 'hydrate' | 'serialize' | 'write' | 'migrate';
 /** Options for {@link persist} — storage backend, serialization, and validation. */
 interface PersistOptions<T> {
     /** Storage backend. Defaults to localStorage. */
@@ -993,6 +990,14 @@ interface PersistOptions<T> {
     deserialize?: (s: string) => T;
     /** Optional validator — return true if the deserialized value is valid. Rejects corrupt/tampered data. */
     validate?: (v: unknown) => v is T;
+    /** Current schema version. When set, values are stored in a versioned envelope. */
+    version?: number;
+    /** Migrate stored data whose version is older than {@link version}. Runs before validate. */
+    migrate?: (oldValue: unknown, oldVersion: number) => T;
+    /** Re-hydrate when another tab writes this key. Defaults to true for localStorage. */
+    syncTabs?: boolean;
+    /** Report hydrate/serialize/write/migrate failures instead of swallowing them. */
+    onError?: (err: unknown, phase: PersistErrorPhase) => void;
 }
 /**
  * Persist a signal's value to storage.
@@ -1007,7 +1012,7 @@ interface PersistOptions<T> {
  * setTheme('dark'); // auto-saved to localStorage under key 'app:theme'
  * ```
  */
-declare function persist<T>(source: [get: () => T, set: (v: T) => void], key: string, options?: PersistOptions<T>): void;
+declare function persist<T>(source: [get: () => T, set: (v: T) => void], key: string, options?: PersistOptions<T>): () => void;
 
 /**
  * A typed publish/subscribe event bus.
@@ -1170,4 +1175,4 @@ declare function onIntersect(el: HTMLElement, handler: (entry: IntersectionObser
  */
 declare function onMutation(el: HTMLElement, handler: (mutations: MutationRecord[]) => void, options?: MutationObserverInit): () => void;
 
-export { $, $$, type CleanupFn, type ComponentDef, type Context, type CreateListOptions, type Dispatch, type ErrorHandler, type EventBus, Fragment, type HistoryControls, type IslandHydrateFn, type KeyOptions, type ListTransitionHooks, type PersistOptions, type ReconcileResult, type Ref, type SetupFn, SignalGetter, type StoreSetter, type SwitchCase, activateIslands, addClass, batch, children, cleanup, closest, createBus, createComputed, createContext, createEffect, createErrorBoundary, createHistory, createList, createMemo, createPortal, createReducer, createRef, createRoot, createShow, createStore, createSuspense, createSwitch, createText, createUnownedRoot, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, fragment, h, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, removeClass, setAttr, setHTMLUnsafe, setStyle, setText, siblings, template, templateMany, toggleClass, trackDisposer, unprovide, untrack };
+export { $, $$, type CleanupFn, type ComponentDef, type Context, type CreateListOptions, type Dispatch, type ErrorHandler, type EventBus, Fragment, type HistoryControls, type IslandHydrateFn, type KeyOptions, type ListTransitionHooks, type PersistErrorPhase, type PersistOptions, type ReconcileResult, type Ref, type SetupFn, SignalGetter, type StoreSetter, type SwitchCase, activateIslands, addClass, batch, children, cleanup, closest, createBus, createComputed, createContext, createEffect, createErrorBoundary, createHistory, createList, createMemo, createPortal, createReducer, createRef, createRoot, createShow, createStore, createSuspense, createSwitch, createText, createUnownedRoot, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, fragment, h, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, removeClass, setAttr, setHTMLUnsafe, setStyle, setText, siblings, template, templateMany, toggleClass, trackDisposer, unprovide, untrack };