rask-ui 0.1.1 → 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;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"}
+{"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/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/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/createQuery.d.ts

@@ -14,6 +14,29 @@ type QueryState<T> = {
 export type Query<T> = QueryState<T> & {
     fetch(force?: boolean): void;
 };
+/**
+ * Creates a reactive query that manages data fetching 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 query = createQuery(() => fetchUsers());
+ *   const { isPending, data, error } = query; // Don't do this!
+ *   return () => <div>{isPending ? "Loading..." : data.length}</div>; // Won't update!
+ * }
+ *
+ * // ✅ Good - access properties directly
+ * function Component() {
+ *   const query = createQuery(() => fetchUsers());
+ *   return () => <div>{query.isPending ? "Loading..." : query.data.length}</div>;
+ * }
+ *
+ * @param fetcher - Function that returns a promise with the data to fetch
+ * @returns Reactive query object with isPending, data, error properties and fetch method
+ */
 export declare function createQuery<T>(fetcher: () => Promise<T>): Query<T>;
 export {};
 //# sourceMappingURL=createQuery.d.ts.map

package/dist/createQuery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createQuery.d.ts","sourceRoot":"","sources":["../src/createQuery.ts"],"names":[],"mappings":"AAEA,KAAK,UAAU,CAAC,CAAC,IACb;IACE,SAAS,EAAE,IAAI,CAAC;IAChB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACf,KAAK,EAAE,IAAI,CAAC;CACb,GACD;IACE,SAAS,EAAE,KAAK,CAAC;IACjB,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,EAAE,IAAI,CAAC;CACb,GACD;IACE,SAAS,EAAE,KAAK,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,GAAG;IACrC,KAAK,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9B,CAAC;AAEF,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CA+DlE"}
+{"version":3,"file":"createQuery.d.ts","sourceRoot":"","sources":["../src/createQuery.ts"],"names":[],"mappings":"AAEA,KAAK,UAAU,CAAC,CAAC,IACb;IACE,SAAS,EAAE,IAAI,CAAC;IAChB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACf,KAAK,EAAE,IAAI,CAAC;CACb,GACD;IACE,SAAS,EAAE,KAAK,CAAC;IACjB,IAAI,EAAE,CAAC,CAAC;IACR,KAAK,EAAE,IAAI,CAAC;CACb,GACD;IACE,SAAS,EAAE,KAAK,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,GAAG;IACrC,KAAK,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CA+DlE"}

package/dist/createQuery.js

@@ -1,4 +1,27 @@
 import { createState } from "./createState";
+/**
+ * Creates a reactive query that manages data fetching 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 query = createQuery(() => fetchUsers());
+ *   const { isPending, data, error } = query; // Don't do this!
+ *   return () => <div>{isPending ? "Loading..." : data.length}</div>; // Won't update!
+ * }
+ *
+ * // ✅ Good - access properties directly
+ * function Component() {
+ *   const query = createQuery(() => fetchUsers());
+ *   return () => <div>{query.isPending ? "Loading..." : query.data.length}</div>;
+ * }
+ *
+ * @param fetcher - Function that returns a promise with the data to fetch
+ * @returns Reactive query object with isPending, data, error properties and fetch method
+ */
 export function createQuery(fetcher) {
     const state = createState({
         isPending: true,

package/dist/createRef.test.d.ts

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

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

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

package/dist/createRef.test.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx, jsxs as _jsxs } from "./jsx-runtime";
+import { describe, it, expect } from "vitest";
+import { createRef } from "./createRef";
+import { render } from "./vdom";
+describe("createRef", () => {
+    it("should create a ref with null initial value", () => {
+        const ref = createRef();
+        expect(ref.current).toBeNull();
+    });
+    it("should be callable as a function", () => {
+        const ref = createRef();
+        expect(typeof ref).toBe("function");
+    });
+    it("should update current when called with a node", () => {
+        const ref = createRef();
+        const element = document.createElement("div");
+        ref(element);
+        expect(ref.current).toBe(element);
+    });
+    it("should update current when called with null", () => {
+        const ref = createRef();
+        const element = document.createElement("div");
+        ref(element);
+        expect(ref.current).toBe(element);
+        ref(null);
+        expect(ref.current).toBeNull();
+    });
+    it("should work with JSX ref attribute", async () => {
+        const ref = createRef();
+        function TestComponent() {
+            return () => _jsx("div", { ref: ref, children: "Hello" });
+        }
+        const container = document.createElement("div");
+        document.body.appendChild(container);
+        const vnode = render(_jsx(TestComponent, {}), container);
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(ref.current).not.toBeNull();
+        expect(ref.current?.tagName).toBe("DIV");
+        expect(ref.current?.textContent).toBe("Hello");
+        document.body.removeChild(vnode.elm);
+    });
+    it("should handle multiple ref updates", () => {
+        const ref = createRef();
+        const div = document.createElement("div");
+        const span = document.createElement("span");
+        ref(div);
+        expect(ref.current).toBe(div);
+        ref(span);
+        expect(ref.current).toBe(span);
+        ref(null);
+        expect(ref.current).toBeNull();
+    });
+    it("should work with different element types", async () => {
+        const inputRef = createRef();
+        const buttonRef = createRef();
+        function TestComponent() {
+            return () => (_jsxs("div", { children: [_jsx("input", { ref: inputRef, type: "text" }), _jsx("button", { ref: buttonRef, children: "Click" })] }));
+        }
+        const container = document.createElement("div");
+        document.body.appendChild(container);
+        const vnode = render(_jsx(TestComponent, {}), container);
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(inputRef.current?.tagName).toBe("INPUT");
+        expect(buttonRef.current?.tagName).toBe("BUTTON");
+        document.body.removeChild(vnode.elm);
+    });
+    it("should allow accessing DOM properties", async () => {
+        const ref = createRef();
+        function TestComponent() {
+            return () => _jsx("input", { ref: ref, type: "text", value: "test" });
+        }
+        const container = document.createElement("div");
+        document.body.appendChild(container);
+        const vnode = render(_jsx(TestComponent, {}), container);
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(ref.current?.value).toBe("test");
+        expect(ref.current?.type).toBe("text");
+        document.body.removeChild(vnode.elm);
+    });
+});

package/dist/createState.d.ts

@@ -1,2 +1,26 @@
+/**
+ * Creates a reactive state object that tracks property access and notifies observers on changes.
+ *
+ * @warning **Do not destructure the returned reactive object!** Destructuring breaks reactivity
+ * because it extracts plain values instead of maintaining proxy access. This is the same rule
+ * as Solid.js signals.
+ *
+ * @example
+ * // ❌ Bad - destructuring loses reactivity
+ * function Component(props) {
+ *   const state = createState({ count: 0, name: "foo" });
+ *   const { count, name } = state; // Don't do this!
+ *   return () => <div>{count} {name}</div>; // Won't update!
+ * }
+ *
+ * // ✅ Good - access properties directly in render
+ * function Component(props) {
+ *   const state = createState({ count: 0, name: "foo" });
+ *   return () => <div>{state.count} {state.name}</div>; // Reactive!
+ * }
+ *
+ * @param state - The initial state object to make reactive
+ * @returns A reactive proxy of the state object
+ */
 export declare function createState<T extends object>(state: T): T;
 //# sourceMappingURL=createState.d.ts.map

package/dist/createState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createState.d.ts","sourceRoot":"","sources":["../src/createState.ts"],"names":[],"mappings":"AAEA,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEzD"}
+{"version":3,"file":"createState.d.ts","sourceRoot":"","sources":["../src/createState.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEzD"}

package/dist/createState.js

@@ -1,4 +1,28 @@
 import { getCurrentObserver, Signal } from "./observation";
+/**
+ * Creates a reactive state object that tracks property access and notifies observers on changes.
+ *
+ * @warning **Do not destructure the returned reactive object!** Destructuring breaks reactivity
+ * because it extracts plain values instead of maintaining proxy access. This is the same rule
+ * as Solid.js signals.
+ *
+ * @example
+ * // ❌ Bad - destructuring loses reactivity
+ * function Component(props) {
+ *   const state = createState({ count: 0, name: "foo" });
+ *   const { count, name } = state; // Don't do this!
+ *   return () => <div>{count} {name}</div>; // Won't update!
+ * }
+ *
+ * // ✅ Good - access properties directly in render
+ * function Component(props) {
+ *   const state = createState({ count: 0, name: "foo" });
+ *   return () => <div>{state.count} {state.name}</div>; // Reactive!
+ * }
+ *
+ * @param state - The initial state object to make reactive
+ * @returns A reactive proxy of the state object
+ */
 export function createState(state) {
     return getProxy(state);
 }