rask-ui 0.1.0 → 0.2.0

package/dist/component.d.ts

@@ -1,6 +1,23 @@
 import { type VNode } from "snabbdom";
 import { Observer } from "./observation";
 import { ChildNode } from "./render";
+/**
+ * Component function type. Components receive reactive props that should not be destructured.
+ *
+ * @warning **Do not destructure props!** Props are wrapped in a reactive proxy, and destructuring
+ * breaks reactivity. This is the same rule as Solid.js.
+ *
+ * @example
+ * // ❌ Bad - destructuring props loses reactivity
+ * function MyComponent({ count, name }) {
+ *   return () => <div>{count} {name}</div>; // Won't update!
+ * }
+ *
+ * // ✅ Good - access props directly in render
+ * function MyComponent(props) {
+ *   return () => <div>{props.count} {props.name}</div>; // Reactive!
+ * }
+ */
 export type Component<P> = ((props: P) => () => VNode) | (() => () => VNode);
 export type ComponentInstance = {
     parent: ComponentInstance | null;

package/dist/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,KAAK,EAAkB,MAAM,UAAU,CAAC;AAE7D,OAAO,EAAsB,QAAQ,EAAU,MAAM,eAAe,CAAC;AACrE,OAAO,EAAc,SAAS,EAAE,MAAM,UAAU,CAAC;AAGjD,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,KAAK,CAAC,GAAG,CAAC,MAAM,MAAM,KAAK,CAAC,CAAC;AAE7E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC;IAC1B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACrC,QAAQ,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;IAC5B,UAAU,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACnC,CAAC;AAIF,wBAAgB,mBAAmB,sBAElC;AAED,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,QAQrC;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,QAQvC;AAwGD,wBAAgB,eAAe,CAC7B,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,EACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,QAAQ,EAAE,SAAS,EAAE,GAAG,SAAS,4BAOlC"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,KAAK,EAAkB,MAAM,UAAU,CAAC;AAE7D,OAAO,EAAsB,QAAQ,EAAU,MAAM,eAAe,CAAC;AACrE,OAAO,EAAc,SAAS,EAAE,MAAM,UAAU,CAAC;AAGjD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,KAAK,CAAC,GAAG,CAAC,MAAM,MAAM,KAAK,CAAC,CAAC;AAE7E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC;IAC1B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACrC,QAAQ,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;IAC5B,UAAU,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;IAC9B,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACnC,CAAC;AAIF,wBAAgB,mBAAmB,sBAElC;AAED,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,QAQrC;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,QAQvC;AAuGD,wBAAgB,eAAe,CAC7B,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,EACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,QAAQ,EAAE,SAAS,EAAE,GAAG,SAAS,4BAWlC"}

package/dist/component.js

@@ -26,7 +26,6 @@ const hook = {
         vnode.data.componentInstance.onMounts.forEach((cb) => cb());
     },
     destroy(vnode) {
-        componentStack.shift();
         vnode.data.componentInstance.onCleanups.forEach((cb) => cb());
     },
     prepatch(oldVnode, thunk) {
@@ -69,7 +68,7 @@ const hook = {
             }, Array.isArray(renderResult) ? renderResult : [renderResult]);
         };
         const instance = {
-            parent: getCurrentComponent(),
+            parent: thunk.data.parentComponent || null,
             component,
             contexts: null,
             onMounts: [],
@@ -116,6 +115,9 @@ const hook = {
 export function createComponent(component, props, children) {
     const thunkNode = thunk("component", props.key, component, [props, children]);
     Object.assign(thunkNode.data.hook, hook);
+    // Capture the parent component at vnode creation time (during render)
+    // rather than at init time, to ensure correct parent relationships
+    thunkNode.data.parentComponent = getCurrentComponent();
     return thunkNode;
 }
 function copyToThunk(vnode, thunk) {

package/dist/createAsync.d.ts

@@ -11,6 +11,29 @@ type AsyncState<T> = {
     value: null;
     error: string;
 };
+/**
+ * Creates a reactive async state that tracks the lifecycle of a promise.
+ *
+ * @warning **Do not destructure the returned reactive object!** Destructuring breaks reactivity.
+ * Access properties directly in your render function instead.
+ *
+ * @example
+ * // ❌ Bad - destructuring loses reactivity
+ * function Component() {
+ *   const async = createAsync(fetchData());
+ *   const { isPending, value, error } = async; // Don't do this!
+ *   return () => <div>{isPending ? "Loading..." : value}</div>; // Won't update!
+ * }
+ *
+ * // ✅ Good - access properties directly
+ * function Component() {
+ *   const async = createAsync(fetchData());
+ *   return () => <div>{async.isPending ? "Loading..." : async.value}</div>;
+ * }
+ *
+ * @param promise - The promise to track
+ * @returns Reactive state with isPending, value, and error properties
+ */
 export declare function createAsync<T>(promise: Promise<T>): AsyncState<T>;
 export {};
 //# sourceMappingURL=createAsync.d.ts.map

package/dist/createAsync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createAsync.d.ts","sourceRoot":"","sources":["../src/createAsync.ts"],"names":[],"mappings":"AAEA,KAAK,UAAU,CAAC,CAAC,IACb;IACE,SAAS,EAAE,IAAI,CAAC;IAChB,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,IAAI,CAAC;CACb,GACD;IACE,SAAS,EAAE,KAAK,CAAC;IACjB,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,EAAE,IAAI,CAAC;CACb,GACD;IACE,SAAS,EAAE,KAAK,CAAC;IACjB,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,iBAwBjD"}
+{"version":3,"file":"createAsync.d.ts","sourceRoot":"","sources":["../src/createAsync.ts"],"names":[],"mappings":"AAEA,KAAK,UAAU,CAAC,CAAC,IACb;IACE,SAAS,EAAE,IAAI,CAAC;IAChB,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,IAAI,CAAC;CACb,GACD;IACE,SAAS,EAAE,KAAK,CAAC;IACjB,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,EAAE,IAAI,CAAC;CACb,GACD;IACE,SAAS,EAAE,KAAK,CAAC;IACjB,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,iBAwBjD"}

package/dist/createAsync.js

@@ -1,4 +1,27 @@
 import { createState } from "./createState";
+/**
+ * Creates a reactive async state that tracks the lifecycle of a promise.
+ *
+ * @warning **Do not destructure the returned reactive object!** Destructuring breaks reactivity.
+ * Access properties directly in your render function instead.
+ *
+ * @example
+ * // ❌ Bad - destructuring loses reactivity
+ * function Component() {
+ *   const async = createAsync(fetchData());
+ *   const { isPending, value, error } = async; // Don't do this!
+ *   return () => <div>{isPending ? "Loading..." : value}</div>; // Won't update!
+ * }
+ *
+ * // ✅ Good - access properties directly
+ * function Component() {
+ *   const async = createAsync(fetchData());
+ *   return () => <div>{async.isPending ? "Loading..." : async.value}</div>;
+ * }
+ *
+ * @param promise - The promise to track
+ * @returns Reactive state with isPending, value, and error properties
+ */
 export function createAsync(promise) {
     const state = createState({
         isPending: true,

package/dist/createAsync.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=createAsync.test.d.ts.map

package/dist/createAsync.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createAsync.test.d.ts","sourceRoot":"","sources":["../src/createAsync.test.ts"],"names":[],"mappings":""}

package/dist/createAsync.test.js

@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest';
+import { createAsync } from './createAsync';
+describe('createAsync', () => {
+    it('should start in pending state', () => {
+        const promise = new Promise(() => { });
+        const async = createAsync(promise);
+        expect(async.isPending).toBe(true);
+        expect(async.value).toBeNull();
+        expect(async.error).toBeNull();
+    });
+    it('should resolve to value state on success', async () => {
+        const promise = Promise.resolve('success');
+        const async = createAsync(promise);
+        expect(async.isPending).toBe(true);
+        await promise;
+        // Wait for state update
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(async.isPending).toBe(false);
+        expect(async.value).toBe('success');
+        expect(async.error).toBeNull();
+    });
+    it('should resolve to error state on rejection', async () => {
+        const promise = Promise.reject(new Error('failed'));
+        const async = createAsync(promise);
+        expect(async.isPending).toBe(true);
+        try {
+            await promise;
+        }
+        catch {
+            // Ignore
+        }
+        // Wait for state update
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(async.isPending).toBe(false);
+        expect(async.value).toBeNull();
+        expect(async.error).toContain('failed');
+    });
+    it('should handle numeric values', async () => {
+        const promise = Promise.resolve(42);
+        const async = createAsync(promise);
+        await promise;
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(async.value).toBe(42);
+    });
+    it('should handle object values', async () => {
+        const data = { id: 1, name: 'Test' };
+        const promise = Promise.resolve(data);
+        const async = createAsync(promise);
+        await promise;
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(async.value).toEqual(data);
+    });
+    it('should handle array values', async () => {
+        const data = [1, 2, 3, 4, 5];
+        const promise = Promise.resolve(data);
+        const async = createAsync(promise);
+        await promise;
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(async.value).toEqual(data);
+    });
+    it('should convert error to string', async () => {
+        const promise = Promise.reject('string error');
+        const async = createAsync(promise);
+        try {
+            await promise;
+        }
+        catch {
+            // Ignore
+        }
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(typeof async.error).toBe('string');
+        expect(async.error).toBe('string error');
+    });
+    it('should handle error objects', async () => {
+        const error = new Error('Something went wrong');
+        const promise = Promise.reject(error);
+        const async = createAsync(promise);
+        try {
+            await promise;
+        }
+        catch {
+            // Ignore
+        }
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(async.error).toContain('Something went wrong');
+    });
+    it('should create reactive state', async () => {
+        const promise = new Promise((resolve) => {
+            setTimeout(() => resolve('delayed'), 10);
+        });
+        const async = createAsync(promise);
+        expect(async.isPending).toBe(true);
+        await promise;
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        expect(async.isPending).toBe(false);
+        expect(async.value).toBe('delayed');
+    });
+    it('should handle immediate resolution', async () => {
+        const async = createAsync(Promise.resolve('immediate'));
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(async.isPending).toBe(false);
+        expect(async.value).toBe('immediate');
+    });
+    it('should handle immediate rejection', async () => {
+        const async = createAsync(Promise.reject('immediate error'));
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(async.isPending).toBe(false);
+        expect(async.error).toBe('immediate error');
+    });
+});

package/dist/createContext.d.ts

@@ -1,5 +1,29 @@
-export declare function createContext<T extends object>(): {
-    set(value: T): void;
+/**
+ * Creates a context object for providing and consuming values across component trees.
+ *
+ * @warning **Do not destructure context values returned by context.get()!** The returned
+ * value may be a reactive object, and destructuring breaks reactivity.
+ *
+ * @example
+ * // ❌ Bad - destructuring context value
+ * const ThemeContext = createContext<{ color: string }>();
+ *
+ * function Consumer() {
+ *   const theme = ThemeContext.get();
+ *   const { color } = theme; // Don't do this!
+ *   return () => <div style={{ color }}>Text</div>; // Won't update!
+ * }
+ *
+ * // ✅ Good - access properties directly
+ * function Consumer() {
+ *   const theme = ThemeContext.get();
+ *   return () => <div style={{ color: theme.color }}>Text</div>;
+ * }
+ *
+ * @returns Context object with inject() and get() methods
+ */
+export declare function createContext<T>(): {
+    inject(value: T): void;
     get(): T;
 };
 //# sourceMappingURL=createContext.d.ts.map

package/dist/createContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createContext.d.ts","sourceRoot":"","sources":["../src/createContext.ts"],"names":[],"mappings":"AAEA,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM;eAE/B,CAAC;WAaL,CAAC;EAmBX"}
+{"version":3,"file":"createContext.d.ts","sourceRoot":"","sources":["../src/createContext.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,CAAC;kBAEb,CAAC;WAaR,CAAC;EAoBX"}

package/dist/createContext.js

@@ -1,10 +1,35 @@
-import { getCurrentComponent } from "./component";
+import { getCurrentComponent, } from "./vdom/ComponentVNode";
+import { findComponentVNode } from "./vdom/utils";
+/**
+ * Creates a context object for providing and consuming values across component trees.
+ *
+ * @warning **Do not destructure context values returned by context.get()!** The returned
+ * value may be a reactive object, and destructuring breaks reactivity.
+ *
+ * @example
+ * // ❌ Bad - destructuring context value
+ * const ThemeContext = createContext<{ color: string }>();
+ *
+ * function Consumer() {
+ *   const theme = ThemeContext.get();
+ *   const { color } = theme; // Don't do this!
+ *   return () => <div style={{ color }}>Text</div>; // Won't update!
+ * }
+ *
+ * // ✅ Good - access properties directly
+ * function Consumer() {
+ *   const theme = ThemeContext.get();
+ *   return () => <div style={{ color: theme.color }}>Text</div>;
+ * }
+ *
+ * @returns Context object with inject() and get() methods
+ */
 export function createContext() {
     const context = {
-        set(value) {
+        inject(value) {
             const currentComponent = getCurrentComponent();
             if (!currentComponent) {
-                throw new Error("You can not set context out component setup");
+                throw new Error("You can not inject context outside component setup");
             }
             if (!currentComponent.contexts) {
                 currentComponent.contexts = new Map();
@@ -14,13 +39,14 @@ export function createContext() {
         get() {
             let currentComponent = getCurrentComponent();
             if (!currentComponent) {
-                throw new Error("You can not set context out component setup");
+                throw new Error("You can not get context outside component setup");
             }
             while (currentComponent) {
                 if (currentComponent.contexts?.has(context)) {
                     return currentComponent.contexts.get(context);
                 }
-                currentComponent = currentComponent.parent;
+                const componentNode = findComponentVNode(currentComponent.parent);
+                currentComponent = componentNode?.instance ?? null;
             }
             throw new Error("Could not find context in parent components");
         },

package/dist/createContext.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=createContext.test.d.ts.map

package/dist/createContext.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createContext.test.d.ts","sourceRoot":"","sources":["../src/createContext.test.tsx"],"names":[],"mappings":""}

package/dist/createContext.test.js

@@ -0,0 +1,136 @@
+import { jsx as _jsx, jsxs as _jsxs } from "./jsx-runtime";
+import { describe, it, expect } from "vitest";
+import { createContext } from "./createContext";
+import { render } from "./vdom";
+describe("createContext", () => {
+    it("should create a context object", () => {
+        const context = createContext();
+        expect(context).toHaveProperty("inject");
+        expect(context).toHaveProperty("get");
+    });
+    it("should allow setting and getting context values", () => {
+        const ThemeContext = createContext();
+        function Parent() {
+            ThemeContext.inject({ theme: "dark" });
+            return () => _jsx(Child, {});
+        }
+        function Child() {
+            const theme = ThemeContext.get();
+            return () => _jsx("div", { children: theme.theme });
+        }
+        const container = document.createElement("div");
+        document.body.appendChild(container);
+        const vnode = render(_jsx(Parent, {}), container);
+        expect(vnode.elm.textContent).toContain("dark");
+        document.body.removeChild(vnode.elm);
+    });
+    it("should traverse parent components to find context", () => {
+        const ThemeContext = createContext();
+        function GrandParent() {
+            ThemeContext.inject({ theme: "light" });
+            return () => _jsx(Parent, {});
+        }
+        function Parent() {
+            return () => _jsx(Child, {});
+        }
+        function Child() {
+            const theme = ThemeContext.get();
+            return () => _jsx("div", { children: theme.theme });
+        }
+        const container = document.createElement("div");
+        document.body.appendChild(container);
+        const vnode = render(_jsx(GrandParent, {}), container);
+        expect(vnode.elm.textContent).toContain("light");
+        document.body.removeChild(vnode.elm);
+    });
+    it("should throw error when context is not found", () => {
+        const ThemeContext = createContext();
+        function Child() {
+            expect(() => {
+                ThemeContext.get();
+            }).toThrow("Could not find context in parent components");
+            return () => _jsx("div", { children: "Child" });
+        }
+        const container = document.createElement("div");
+        document.body.appendChild(container);
+        const vnode = render(_jsx(Child, {}), container);
+        document.body.removeChild(vnode.elm);
+    });
+    it("should throw error when setting context outside component", () => {
+        const ThemeContext = createContext();
+        expect(() => {
+            ThemeContext.inject({ theme: "dark" });
+        }).toThrow("No current root");
+    });
+    it("should throw error when getting context outside component", () => {
+        const ThemeContext = createContext();
+        expect(() => {
+            ThemeContext.get();
+        }).toThrow("No current root");
+    });
+    it("should allow overriding context in nested components", () => {
+        const ThemeContext = createContext();
+        function GrandParent() {
+            ThemeContext.inject({ theme: "light" });
+            return () => (_jsxs("div", { children: [_jsx(Parent, {}), _jsx(ChildOfGrandParent, {})] }));
+        }
+        function Parent() {
+            ThemeContext.inject({ theme: "dark" });
+            return () => _jsx(ChildOfParent, {});
+        }
+        function ChildOfParent() {
+            const theme = ThemeContext.get();
+            return () => _jsx("div", { class: "child-of-parent", children: theme.theme });
+        }
+        function ChildOfGrandParent() {
+            const theme = ThemeContext.get();
+            return () => _jsx("div", { class: "child-of-grandparent", children: theme.theme });
+        }
+        const container = document.createElement("div");
+        document.body.appendChild(container);
+        const vnode = render(_jsx(GrandParent, {}), container);
+        const childOfParent = document.querySelector(".child-of-parent");
+        const childOfGrandParent = document.querySelector(".child-of-grandparent");
+        expect(childOfParent?.textContent).toBe("dark");
+        expect(childOfGrandParent?.textContent).toBe("light");
+        document.body.removeChild(vnode.elm);
+    });
+    it("should support multiple different contexts", () => {
+        const ThemeContext = createContext();
+        const UserContext = createContext();
+        function Parent() {
+            ThemeContext.inject({ theme: "dark" });
+            UserContext.inject({ name: "Alice" });
+            return () => _jsx(Child, {});
+        }
+        function Child() {
+            const theme = ThemeContext.get();
+            const user = UserContext.get();
+            return () => (_jsxs("div", { children: [theme.theme, " - ", user.name] }));
+        }
+        const container = document.createElement("div");
+        document.body.appendChild(container);
+        const vnode = render(_jsx(Parent, {}), container);
+        expect(vnode.elm.textContent).toContain("dark - Alice");
+        document.body.removeChild(vnode.elm);
+    });
+    it("should handle context values of different types", () => {
+        const NumberContext = createContext();
+        const ArrayContext = createContext();
+        function Parent() {
+            NumberContext.inject(42);
+            ArrayContext.inject(["a", "b", "c"]);
+            return () => _jsx(Child, {});
+        }
+        function Child() {
+            const num = NumberContext.get();
+            const arr = ArrayContext.get();
+            return () => (_jsxs("div", { children: [num, " - ", arr.join(",")] }));
+        }
+        const container = document.createElement("div");
+        document.body.appendChild(container);
+        const vnode = render(_jsx(Parent, {}), container);
+        expect(vnode.elm.textContent).toContain("42 - a,b,c");
+        document.body.removeChild(vnode.elm);
+    });
+});

package/dist/createMutation.d.ts

@@ -15,6 +15,29 @@ export type Mutation<T> = MutationState<T> & {
     mutate(): void;
     mutate(params: T): void;
 };
+/**
+ * Creates a reactive mutation that manages async mutations with loading and error states.
+ *
+ * @warning **Do not destructure the returned reactive object!** Destructuring breaks reactivity.
+ * Access properties directly in your render function instead.
+ *
+ * @example
+ * // ❌ Bad - destructuring loses reactivity
+ * function Component() {
+ *   const mutation = createMutation((params) => updateUser(params));
+ *   const { isPending, error } = mutation; // Don't do this!
+ *   return () => <button disabled={isPending}>Save</button>; // Won't update!
+ * }
+ *
+ * // ✅ Good - access properties directly
+ * function Component() {
+ *   const mutation = createMutation((params) => updateUser(params));
+ *   return () => <button disabled={mutation.isPending}>Save</button>;
+ * }
+ *
+ * @param mutator - Function that performs the mutation and returns a promise
+ * @returns Reactive mutation object with isPending, params, error properties and mutate method
+ */
 export declare function createMutation<T>(mutator: (params: T) => Promise<T>): Mutation<T>;
 export {};
 //# sourceMappingURL=createMutation.d.ts.map

package/dist/createMutation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createMutation.d.ts","sourceRoot":"","sources":["../src/createMutation.ts"],"names":[],"mappings":"AAEA,KAAK,aAAa,CAAC,CAAC,IAChB;IACE,SAAS,EAAE,IAAI,CAAC;IAChB,MAAM,EAAE,CAAC,CAAC;IACV,KAAK,EAAE,IAAI,CAAC;CACb,GACD;IACE,SAAS,EAAE,KAAK,CAAC;IACjB,MAAM,EAAE,IAAI,CAAC;IACb,KAAK,EAAE,IAAI,CAAC;CACb,GACD;IACE,SAAS,EAAE,KAAK,CAAC;IACjB,MAAM,EAAE,IAAI,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,GAAG;IAC3C,MAAM,IAAI,IAAI,CAAC;IACf,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;CACzB,CAAC;AAEF,wBAAgB,cAAc,CAAC,CAAC,EAC9B,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GACjC,QAAQ,CAAC,CAAC,CAAC,CA0Db"}
+{"version":3,"file":"createMutation.d.ts","sourceRoot":"","sources":["../src/createMutation.ts"],"names":[],"mappings":"AAEA,KAAK,aAAa,CAAC,CAAC,IAChB;IACE,SAAS,EAAE,IAAI,CAAC;IAChB,MAAM,EAAE,CAAC,CAAC;IACV,KAAK,EAAE,IAAI,CAAC;CACb,GACD;IACE,SAAS,EAAE,KAAK,CAAC;IACjB,MAAM,EAAE,IAAI,CAAC;IACb,KAAK,EAAE,IAAI,CAAC;CACb,GACD;IACE,SAAS,EAAE,KAAK,CAAC;IACjB,MAAM,EAAE,IAAI,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,GAAG;IAC3C,MAAM,IAAI,IAAI,CAAC;IACf,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GACjC,QAAQ,CAAC,CAAC,CAAC,CA0Db"}

package/dist/createMutation.js

@@ -1,4 +1,27 @@
 import { createState } from "./createState";
+/**
+ * Creates a reactive mutation that manages async mutations with loading and error states.
+ *
+ * @warning **Do not destructure the returned reactive object!** Destructuring breaks reactivity.
+ * Access properties directly in your render function instead.
+ *
+ * @example
+ * // ❌ Bad - destructuring loses reactivity
+ * function Component() {
+ *   const mutation = createMutation((params) => updateUser(params));
+ *   const { isPending, error } = mutation; // Don't do this!
+ *   return () => <button disabled={isPending}>Save</button>; // Won't update!
+ * }
+ *
+ * // ✅ Good - access properties directly
+ * function Component() {
+ *   const mutation = createMutation((params) => updateUser(params));
+ *   return () => <button disabled={mutation.isPending}>Save</button>;
+ * }
+ *
+ * @param mutator - Function that performs the mutation and returns a promise
+ * @returns Reactive mutation object with isPending, params, error properties and mutate method
+ */
 export function createMutation(mutator) {
     const state = createState({
         isPending: false,

package/dist/createMutation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=createMutation.test.d.ts.map

package/dist/createMutation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createMutation.test.d.ts","sourceRoot":"","sources":["../src/createMutation.test.ts"],"names":[],"mappings":""}