@getforma/core 1.1.0 → 1.3.0

package/dist/index.d.cts

@@ -334,6 +334,19 @@ declare function onError(handler: ErrorHandler): () => void;
 declare const Fragment: (props: {
     children?: unknown;
 }) => DocumentFragment;
+/**
+ * Run `build()` with the SVG namespace active so nested `h()` calls create
+ * SVG-namespaced elements — including dual-use tags like `<a>` that `h()` would
+ * otherwise create as HTML. `h()` resolves tags by this explicit context (there
+ * is no automatic parent-walk); a `foreignObject` creates the SVG element but
+ * does not auto-switch its descendants back to HTML (author those with plain
+ * `h()` outside `svg()`). MathML is not supported.
+ *
+ * ```ts
+ * const icon = svg(() => h('svg', { viewBox: '0 0 10 10' }, h('a', { href: '#' })));
+ * ```
+ */
+declare function svg<T extends Node>(build: () => T): T;
 /**
  * Remove all event listeners previously attached via `h()` on the given element.
  *
@@ -943,6 +956,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.
@@ -957,6 +972,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;
@@ -969,6 +991,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. */
@@ -979,6 +1003,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.
@@ -993,7 +1025,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.
@@ -1156,4 +1188,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, svg, template, templateMany, toggleClass, trackDisposer, unprovide, untrack };

package/dist/index.d.ts

@@ -334,6 +334,19 @@ declare function onError(handler: ErrorHandler): () => void;
 declare const Fragment: (props: {
     children?: unknown;
 }) => DocumentFragment;
+/**
+ * Run `build()` with the SVG namespace active so nested `h()` calls create
+ * SVG-namespaced elements — including dual-use tags like `<a>` that `h()` would
+ * otherwise create as HTML. `h()` resolves tags by this explicit context (there
+ * is no automatic parent-walk); a `foreignObject` creates the SVG element but
+ * does not auto-switch its descendants back to HTML (author those with plain
+ * `h()` outside `svg()`). MathML is not supported.
+ *
+ * ```ts
+ * const icon = svg(() => h('svg', { viewBox: '0 0 10 10' }, h('a', { href: '#' })));
+ * ```
+ */
+declare function svg<T extends Node>(build: () => T): T;
 /**
  * Remove all event listeners previously attached via `h()` on the given element.
  *
@@ -943,6 +956,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.
@@ -957,6 +972,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;
@@ -969,6 +991,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. */
@@ -979,6 +1003,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.
@@ -993,7 +1025,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.
@@ -1156,4 +1188,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, svg, template, templateMany, toggleClass, trackDisposer, unprovide, untrack };