@ryupold/vode 1.8.11 → 1.9.0

package/src/state-context.ts

@@ -1,16 +1,10 @@
-import { AnimatedPatch, DeepPartial, Patchable, PatchableState, RenderPatch } from "./vode";
+import { DeepPartial, Patchable, PatchableState, RenderPatch } from "./vode";
 
 /**
  * State context for type-safe access and manipulation of nested state paths
  * while still be able to access the parent state. 
  */
-export interface StateContext<S extends Patchable<S>, SubState> extends SubContext<SubState> {
-    /** 
-     * parent state
-     * @see PatchableState<S>
-     */
-    get state(): S;
-}
+export interface StateContext<S extends Patchable<S>, SubState> extends SubContext<SubState> { }
 
 /**
  * State context for type-safe access and manipulation of nested sub-state values without knowledge of the parent state.
@@ -52,43 +46,56 @@ export type ProxySubContext<SubState> = SubContext<SubState> & {
     : SubContext<SubState[K]>
 };
 
+type ProxyState<SubState> = SubState & {
+    [K in keyof SubState]-?: NonNullable<SubState[K]> extends object | null
+    ? ProxyState<NonNullable<SubState[K]>>
+    : SubState[K]
+};
+
 /**
- * create a ProxyStateContext for type-safe dynamic access to nested state
- * 
- * @example
+ * Creates a `ProxyStateContext` for type-safe access and manipulation of nested state.
+ *
+ * There are two ways to reach a subcontext:
+ *
+ * **1. Property chaining** — traverse the proxy directly via property access:
  * ```typescript
- * const state = createState({
- *   user: {
- *    profile: {
- *     settings: { theme: 'dark', lang: 'en' }
- *   }
- * });
- * 
- * // Create a proxy context for the state
  * const ctx = context(state).user.profile.settings;
- * 
- * // Access nested state dynamically
- * const settings = ctx.get(); // { theme: 'dark', lang: 'en' }
- * 
- * // Update and trigger render
- * ctx.patch({ theme: 'light' });
- * 
- * // Update without render (silent mutation)
- * ctx.put({ lang: 'de' });
  * ```
- * 
- * @param state 
- * @returns 
+ *
+ * **2. Path producer function** — pass a callback that navigates 
+ * the state tree; needed if your intermediate path contains 'get', 'put' or 'patch' properties that would conflict with the context API:
+ * ```typescript
+ * const ctx = context(state, s => s.user.profile.settings);
+ * ```
+ *
+ * Both forms return a `ProxyStateContext` that supports the same operations:
+ * ```typescript
+ * ctx.get();                   // read current value
+ * ctx.patch({ theme: 'light' }); // update and trigger render
+ * ctx.put({ lang: 'de' });       // update without render (silent mutation)
+ * ```
+ *
+ * @param state - The root `PatchableState` to create a context for
+ * @param producePath - Optional path producer; receives a proxy of the state and should return the desired sub-node
+ * @returns A `ProxyStateContext` rooted at the given path, with further property-chain access available
  */
-export function context<S extends PatchableState>(state: S): ProxyStateContext<S, S> {
-    return new ProxyStateContextImpl<S, S>(state, []) as unknown as ProxyStateContext<S, S>;
+
+export function context<S extends PatchableState, SS = S>(state: S): ProxyStateContext<S, SS>;
+export function context<S extends PatchableState, SS>(state: S, producePath: (ctx: ProxyState<S>) => ProxyState<SS>): ProxyStateContext<S, SS>;
+export function context<S extends PatchableState, SS = S>(state: S, producePath?: (ctx: ProxyState<S>) => ProxyState<SS>): ProxyStateContext<S, SS> {
+    if (producePath) {
+        const proxy = producePath(proxyState<S>(state, [] as string[]));
+        const keys = (proxy as any)["___KeYs___"] as string[];
+        return new ProxyStateContextImpl<S, SS>(state, keys) as unknown as ProxyStateContext<S, SS>;
+    }
+    return new ProxyStateContextImpl<S, S>(state, []) as unknown as ProxyStateContext<S, SS>;
 }
 
 class ProxyStateContextImpl<S extends PatchableState, SubState>
     implements StateContext<S, SubState> {
 
     constructor(
-        public readonly state: S,
+        private readonly state: S,
         private readonly keys: string[]
     ) {
         function putDeep(value: SubState | DeepPartial<SubState> | undefined | null, target: S | DeepPartial<S>) {
@@ -150,8 +157,6 @@ class ProxyStateContextImpl<S extends PatchableState, SubState>
 
         return new Proxy(this, {
             get: (target, prop, receiver) => {
-                if (prop === 'state')
-                    return state;
 
                 if (prop === 'get')
                     return get;
@@ -162,10 +167,12 @@ class ProxyStateContextImpl<S extends PatchableState, SubState>
                 if (prop === 'patch')
                     return patch;
 
-
                 // otherwise return a new ProxyStateContext for nested access
-                const newKeys = [...target.keys, String(prop)];
+            const newKeys = [...keys, String(prop)];
                 return new ProxyStateContextImpl<S, any>(target.state, newKeys);
+            },
+            set: (target: this, p: string | symbol, newValue: any, receiver: any) => {
+                throw new Error("ProxyStateContext is not meant to be directly mutated. Use put() or patch() methods on the StateContext instead");
             }
         });
     }
@@ -174,3 +181,23 @@ class ProxyStateContextImpl<S extends PatchableState, SubState>
     put(value: SubState | DeepPartial<SubState>): void { }
     patch(value: SubState | DeepPartial<SubState> | DeepPartial<SubState>[]): void { }
 }
+
+
+function proxyState<S extends PatchableState>(
+    state: S,
+    keys: string[]
+) {
+    return new Proxy(state, {
+        get: (target, prop, receiver) => {
+            if (prop === "___KeYs___") {
+                return keys;
+            }
+
+            const newKeys = [...keys, String(prop)];
+            return proxyState<S>(state, newKeys);
+        },
+        set: (target: any, p: string | symbol, newValue: any, receiver: any) => {
+            throw new Error("ProxyState is not meant to be directly mutated");
+        }
+    });
+}

package/src/vode.ts

@@ -228,10 +228,10 @@ export function app<S extends PatchableState = PatchableState>(
 
     function renderDom(isAnimated: boolean) {
         const sw = performance.now();
-        const vom = dom(_vode.state);
-        _vode.vode = render<S>(_vode.state, container.parentElement as Element, 0, 0, _vode.vode, vom)!;
+        _vode.vode = render<S>(_vode.state, container.parentElement as Element, 0, 0, _vode.vode, dom(_vode.state))!;
 
-        if ((<ContainerNode<S>>container).tagName.toUpperCase() !== (vom[0] as Tag).toUpperCase()) { //the tag name was changed during render -> update reference to vode-app-root 
+        if ((<ContainerNode<S>>container).tagName.toLowerCase() !== (<Vode<S>>_vode.vode)[0].toLowerCase()) {
+            //the tag name was changed during render -> update reference to vode-app-root 
             container = _vode.vode.node as Element;
             (<ContainerNode<S>>container)._vode = _vode
         }
@@ -299,6 +299,13 @@ export function app<S extends PatchableState = PatchableState>(
         hydrate<S>(container, true) as AttachedVode<S>,
         dom(<S>state)
     )!;
+
+    // if during initial render the tag of the root vode was changed (catch or different Tag)
+    if (container.tagName.toLowerCase() !== (<Vode<S>>_vode.vode)[0].toLowerCase()) {
+        container = _vode.vode.node as Element;
+        (container as ContainerNode<S>)._vode = _vode;
+    }
+
     const continueRendering = _vode.stats.syncRenderPatchCount !== patchCountBefore;
     _vode.isRendering = 0;
     _vode.stats.syncRenderCount++;

package/test/helper.ts

@@ -255,7 +255,7 @@ export class Expectation {
                                     } else {
                                         attributeValue = (e as HTMLElement).getAttribute(k);
                                     }
-                                    if (!attributeValue) {
+                                    if (attributeValue === null) {
                                         throw new ExpectationError(that, `expected at\n${path.join(" > ")}\n\nan element <${tag(cv)?.toUpperCase()}>\n\nwith attribute [${k}="${val}"]\n\nbut it was not found${failSuffix}`);
                                     }
                                     if (attributeValue !== val) {

package/test/tests-app.ts

@@ -120,8 +120,7 @@ export default {
 
         await state.patch([{ a: 10 }, { b: 20 }]);
 
-        await expect(state.a).toEqual(10);
-        await expect(state.b).toEqual(20);
+        await expect(state).toEqual({ a: 10, b: 20 });
     },
 
     "app(): multiple sequential patches both apply": async () => {
@@ -339,4 +338,45 @@ export default {
         const el = (container as any)._vode.vode.node;
         expect(el.onclick).toBeA("function");
     },
+
+    "app(): class as array renders correctly": async () => {
+        const root = document.createElement("div");
+        const container = document.createElement("div");
+        root.appendChild(container);
+
+        app(container, {}, () =>
+            [DIV, { class: ["foo", "bar", "baz"] }, "text"]
+        );
+
+        await expect(container).toMatch([DIV, { class: "foo bar baz" }, "text"]);
+    },
+
+    "app(): class as number becomes empty string": async () => {
+        const root = document.createElement("div");
+        const container = document.createElement("div");
+        root.appendChild(container);
+
+        app(container, {}, () =>
+            [DIV, { class: 123 as any }, "text"]
+        );
+
+        await expect(container).toMatch([DIV, { class: "" }, "text"]);
+    },
+
+    "app(): style object to string transition": async () => {
+        const root = document.createElement("div");
+        const container = document.createElement("div");
+        root.appendChild(container);
+        const state: any = { useObject: true };
+
+        app(container, state, (s: any) =>
+            [DIV, { style: s.useObject ? { color: "red" } : "color: blue" }, "text"]
+        );
+
+        await expect(container).toMatch([DIV, "text"]);
+
+        state.patch({ useObject: false });
+
+        await expect(container).toMatch([DIV, "text"]);
+    },
 };

package/test/tests-catch.ts

@@ -1,5 +1,5 @@
 import { expect } from "./helper";
-import { app, createState, DIV, ARTICLE, SECTION, P } from "../index";
+import { app, createState, DIV, ARTICLE, SECTION, P, MAIN } from "../index";
 
 function setup() {
     const root = document.createElement("div");
@@ -157,4 +157,64 @@ export default {
             ]
         );
     },
+
+    "catch: bubbles up to the root component if deeply nested vodes dont catch it earlier": async () => {
+        const root = document.createElement("div");
+        const container = document.createElement("div");
+        root.appendChild(container);
+
+        app(container, {}, () =>
+            [DIV,
+                {
+                    catch: (s: unknown, err: Error) => [DIV, `caught: ${err.message}`]
+                },
+
+                [MAIN,
+                    [SECTION,
+                        [ARTICLE, {
+                            onMount: () => {
+                                throw new Error("boom");
+                            }
+                        }],
+                    ],
+                ]
+            ]
+        );
+
+        await expect(container).toMatch(
+            [DIV, "caught: boom"],
+        );
+    },
+
+    "catch: if catching in root vode with different Tag -> container will be replaced": async () => {
+        const root = document.createElement("div");
+        const container = document.createElement("div");
+        root.appendChild(container);
+
+        await expect(root.firstChild === container).toEqual(true);
+
+        app(container, {}, () =>
+            [DIV,
+                {
+                    catch: (s: unknown, err: Error) => [P, `caught: ${err.message}`]
+                },
+
+                [MAIN,
+                    [SECTION,
+                        [ARTICLE, {
+                            onMount: () => {
+                                throw new Error("boom");
+                            }
+                        }],
+                    ],
+                ]
+            ]
+        );
+
+        await expect(root.firstChild === container).toEqual(false);
+
+        await expect(root.firstChild).toMatch(
+            [P, "caught: boom"],
+        );
+    },
 };

package/test/tests-examples.ts

@@ -91,7 +91,7 @@ export default {
                 [INPUT],
                 [BUTTON, "Add"],
                 [NAV,
-                    [BUTTON, "All"],
+                    [BUTTON, { class: 'active' }, "All"],
                     [BUTTON, "Active"],
                     [BUTTON, "Done"],
                 ],
@@ -115,7 +115,7 @@ export default {
                 [BUTTON, "Add"],
                 [NAV,
                     [BUTTON, "All"],
-                    [BUTTON, "Active"],
+                    [BUTTON, { class: 'active' }, "Active"],
                     [BUTTON, "Done"],
                 ],
                 [UL,
@@ -135,7 +135,7 @@ export default {
                 [NAV,
                     [BUTTON, "All"],
                     [BUTTON, "Active"],
-                    [BUTTON, "Done"],
+                    [BUTTON, { class: 'active' }, "Done"],
                 ],
                 [UL,
                     [LI, "[X] Walk dog"],

package/test/tests-mergeClass.ts

@@ -43,12 +43,14 @@ export default {
         await expect(mergeClass({ foo: true, bar: true }, { bar: false, baz: true })).toEqual({ foo: true, bar: false, baz: true });
     },
 
-    "mergeClass(): object and array": async () => {
-        await expect(mergeClass({ foo: true }, ["bar", "baz"])).toEqual({ foo: true, 0: "bar", 1: "baz" });
+    "mergeClass(): object and array (array items become class names with true)": async () => {
+        await expect(mergeClass({ foo: true }, ["bar", "baz"])).toEqual({ foo: true, bar: true, baz: true });
+        await expect(mergeClass({ active: true }, ["btn", "primary"])).toEqual({ active: true, btn: true, primary: true });
     },
 
-    "mergeClass(): array and object": async () => {
-        await expect(mergeClass(["foo", "bar"], { baz: true, qux: false })).toEqual({ 0: "foo", 1: "bar", baz: true, qux: false });
+    "mergeClass(): array and object (object keys become class names)": async () => {
+        await expect(mergeClass(["foo", "bar"], { baz: true, qux: false })).toEqual({ foo: true, bar: true, baz: true, qux: false });
+        await expect(mergeClass(["a", "b"], { c: true, d: false })).toEqual({ a: true, b: true, c: true, d: false });
     },
 
     "mergeClass(): falsy entries are skipped": async () => {
@@ -59,5 +61,10 @@ export default {
     "mergeClass(): multiple args (3+)": async () => {
         await expect(mergeClass("a", "b", "c")).toEqual("a b c");
         await expect(mergeClass("x", null, ["y", "z"], "w")).toEqual("y z x w");
+    },
+
+    "mergeClass(): incompatible types throw": async () => {
+        await expect(() => (mergeClass as any)(123 as any, "foo")).toFail();
+        await expect(() => (mergeClass as any)("foo", 456 as any)).toFail();
     }
 };

package/test/tests-mergeProps.ts

@@ -11,6 +11,11 @@ export default {
         await expect(mergeProps(p) === p).toEqual(true);
     },
 
+    "mergeProps(): single falsy arg returns undefined": async () => {
+        await expect(mergeProps(null)).toEqual(undefined);
+        await expect(mergeProps(undefined)).toEqual(undefined);
+    },
+
     "mergeProps(): two plain objects merged": async () => {
         await expect(mergeProps({ a: 1 }, { b: 2 })).toEqual({ a: 1, b: 2 });
     },

package/test/tests-patch-advanced.ts

@@ -11,8 +11,8 @@ function setup() {
 export default {
     "patch(): generator function yields multiple state updates": async () => {
         const container = setup();
-        const state: any = createState({ count: 0 });
-        app(container, state, (s: any) => [DIV, String(s.count)]);
+        const state = createState({ count: 0 });
+        app<typeof state>(container, state, (s) => [DIV, String(s.count)]);
 
         await expect(state.count).toEqual(0);
 
@@ -30,8 +30,8 @@ export default {
 
     "patch(): async generator yields over time": async () => {
         const container = setup();
-        const state: any = createState({ phase: "start", value: 0 });
-        app(container, state, (s: any) => [DIV, s.phase, String(s.value)]);
+        const state = createState({ phase: "start", value: 0 });
+        app<typeof state>(container, state, (s) => [DIV, s.phase, String(s.value)]);
 
         await expect(state.phase).toEqual("start");
 
@@ -53,38 +53,37 @@ export default {
 
     "patch(): Promise resolves and applies patch": async () => {
         const container = setup();
-        const state: any = createState({ msg: "before" });
-        app(container, state, (s: any) => [DIV, s.msg]);
-
-        state.patch(Promise.resolve({ msg: "after" }));
+        const state = createState({ msg: "before" });
+        app<typeof state>(container, state, (s) => [DIV, s.msg]);
 
-        await delay(10);
+        await state.patch(Promise.resolve({ msg: "after" }));
 
-        await expect(state.msg).toEqual("after");
+        await expect(state).toEqual({ msg: "after" });
         await expect(container).toMatch([DIV, "after"]);
     },
 
     "patch(): array with empty patches applies nothing": async () => {
         const container = setup();
-        const state: any = createState({ x: 1, y: 2 });
-        app(container, state, (s: any) => [DIV]);
+        const state = createState({ x: 1, y: 2 });
+        app(container, state, (s) => [DIV]);
+
+        await state.patch([{}, {}]);
 
-        state.patch([{}, {}]);
-        await expect(state.x).toEqual(1);
-        await expect(state.y).toEqual(2);
+        await delay(10);
+        await expect(state).toEqual({ x: 1, y: 2 });
     },
 
     "patch(): array with null/undefined items skips them": async () => {
         const container = setup();
-        const state: any = createState({ x: 0, y: 0 });
-        app(container, state, (s: any) => [DIV, String(s.x), String(s.y)]);
+        const state = createState({ x: 0, y: 0 });
+        app<typeof state>(container, state, (s) => [DIV, String(s.x), String(s.y)]);
 
         state.patch([null, { x: 10 }, undefined, { y: 20 }]);
 
-        await delay(10);
-
-        await expect(state.x).toEqual(10);
-        await expect(state.y).toEqual(20);
+        await expect(() => expect(state.x).toEqual(10))
+            .toSucceedAsync();
+        await expect(() => expect(state.y).toEqual(20))
+            .toSucceedAsync();
     },
 
     "patch(): returns Promise for generator functions, can be awaited": async () => {