zudoku 0.32.5 → 0.33.0

package/src/lib/hooks/useEvent.test.tsx

@@ -0,0 +1,149 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { type PropsWithChildren } from "react";
+import { type Location } from "react-router";
+import { assertType, describe, expect, it, vi } from "vitest";
+import { ZudokuProvider } from "../components/context/ZudokuProvider.js";
+import { ZudokuContext, type ZudokuEvents } from "../core/ZudokuContext.js";
+import { useEvent } from "./useEvent.js";
+
+/**
+ * @vitest-environment happy-dom
+ */
+
+const createTestContext = () => {
+  const context = new ZudokuContext({});
+  const queryClient = new QueryClient();
+  const wrapper = ({ children }: PropsWithChildren) => (
+    <QueryClientProvider client={queryClient}>
+      <ZudokuProvider context={context}>{children}</ZudokuProvider>
+    </QueryClientProvider>
+  );
+
+  return { context, wrapper };
+};
+
+const locationData = {
+  pathname: "/test",
+  hash: "",
+  search: "",
+  key: "",
+  state: {},
+} satisfies Location;
+
+describe("useEvent", () => {
+  it("returns latest event data without callback", async () => {
+    const { context, wrapper } = createTestContext();
+    const { result } = renderHook(() => useEvent("location"), { wrapper });
+
+    await act(() => Promise.resolve());
+    await act(async () => {
+      context.emitEvent("location", { to: locationData });
+    });
+
+    expect(result.current).toEqual([{ to: locationData }]);
+  });
+
+  it("transforms event data with callback", async () => {
+    const { context, wrapper } = createTestContext();
+    const { result } = renderHook(
+      () => useEvent("location", ({ to }) => to.pathname),
+      { wrapper },
+    );
+
+    await act(() => Promise.resolve());
+    await act(async () => {
+      context.emitEvent("location", { to: locationData });
+    });
+
+    await waitFor(() => expect(result.current).toEqual("/test"));
+  });
+
+  it("handles side effects without return value", async () => {
+    const { context, wrapper } = createTestContext();
+    const sideEffect = vi.fn();
+
+    const { result } = renderHook(
+      () =>
+        useEvent("location", (event) => {
+          sideEffect(event);
+        }),
+      { wrapper },
+    );
+
+    await act(() => Promise.resolve());
+    await act(async () => {
+      context.emitEvent("location", { to: locationData });
+    });
+
+    expect(result.current).toBeUndefined();
+    expect(sideEffect).toHaveBeenCalledWith({ to: locationData });
+    expect(sideEffect).toHaveBeenCalledTimes(1);
+  });
+
+  it("removes event listener on cleanup", async () => {
+    const { context, wrapper } = createTestContext();
+    const sideEffect = vi.fn();
+
+    const { unmount } = renderHook(
+      () =>
+        useEvent("location", (event) => {
+          sideEffect(event);
+        }),
+      { wrapper },
+    );
+
+    await act(() => Promise.resolve());
+
+    // First event emission
+    await act(async () => {
+      context.emitEvent("location", { to: locationData });
+    });
+    expect(sideEffect).toHaveBeenCalledTimes(1);
+
+    // Unmount the hook
+    unmount();
+
+    // Second event emission after unmount
+    await act(async () => {
+      context.emitEvent("location", { to: locationData });
+    });
+
+    // The callback should not have been called again
+    expect(sideEffect).toHaveBeenCalledTimes(1);
+  });
+
+  describe("types", () => {
+    const { wrapper } = createTestContext();
+
+    it("infers event type when no callback is provided", () => {
+      const hook = renderHook(() => useEvent("location"), { wrapper });
+      assertType<Parameters<ZudokuEvents["location"]> | undefined>(
+        hook.result.current,
+      );
+    });
+
+    it("infers string type from pathname callback", () => {
+      const hook = renderHook(
+        () => useEvent("location", ({ to }) => to.pathname),
+        { wrapper },
+      );
+      assertType<string>(hook.result.current);
+    });
+
+    it("infers object type from object callback", () => {
+      const hook = renderHook(
+        () => useEvent("location", ({ to }) => ({ query: to.search })),
+        { wrapper },
+      );
+      assertType<{ query: string }>(hook.result.current);
+    });
+
+    it("infers void type from empty callback", () => {
+      const hook = renderHook(() => useEvent("location", () => {}), {
+        wrapper,
+      });
+      assertType<void>(hook.result.current);
+    });
+  });
+});

package/src/lib/hooks/useEvent.ts

@@ -0,0 +1,41 @@
+import { useEffect, useState } from "react";
+import { useZudoku } from "../components/context/ZudokuContext.js";
+import type { ZudokuEvents } from "../core/ZudokuContext.js";
+
+type EventParameters<Event extends keyof ZudokuEvents> = Parameters<
+  ZudokuEvents[Event]
+>;
+
+/**
+ * Hook to subscribe to Zudoku events with automatic cleanup
+ * @param event The event to subscribe to
+ * @param callback Optional callback to be called when the event is emitted
+ * @returns The latest event data if no callback is provided, or the callback's return value if it returns something
+ */
+export function useEvent<E extends keyof ZudokuEvents>(
+  event: E,
+): EventParameters<E>;
+export function useEvent<E extends keyof ZudokuEvents, R>(
+  event: E,
+  callback: (...args: EventParameters<E>) => R,
+): R;
+export function useEvent<E extends keyof ZudokuEvents, R>(
+  event: E,
+  callback?: (...args: EventParameters<E>) => R,
+) {
+  const zudoku = useZudoku();
+  const [latestData, setLatestData] = useState<R | EventParameters<E>>();
+
+  useEffect(() => {
+    return zudoku.addEventListener(event, ((...args: EventParameters<E>) => {
+      if (callback) {
+        const result = callback(...args);
+        setLatestData(result);
+      } else {
+        setLatestData(args);
+      }
+    }) as ZudokuEvents[E]);
+  }, [zudoku, event, callback]);
+
+  return latestData;
+}

package/src/lib/ui/Stepper.css

@@ -0,0 +1,43 @@
+@tailwind components;
+
+@layer components {
+  .stepper {
+    /* @apply mb-6; */
+  }
+
+  .stepper > ol {
+    --bullet-size: 1.75rem;
+    --line-spacing: 0.25rem;
+    @apply flex flex-col list-none p-0 m-0;
+    counter-reset: step-counter;
+  }
+
+  .stepper > ol > li {
+    @apply relative ps-12 pb-6 my-0;
+    counter-increment: step-counter;
+  }
+
+  .stepper > ol > li:last-child {
+    @apply pb-0;
+  }
+
+  /* Bullet with number */
+  .stepper > ol > li::before {
+    @apply absolute left-0 flex items-center justify-center size-[--bullet-size];
+    @apply bg-muted/80 border border-border text-muted-foreground text-[calc(var(--bullet-size)/2)] font-semibold rounded-full;
+    content: counter(step-counter);
+  }
+
+  /* Vertical line */
+  .stepper > ol > li::after {
+    @apply absolute content-[''] w-[2px] bg-border -translate-x-1/2;
+    left: calc(var(--bullet-size) / 2);
+    top: calc(var(--bullet-size) + var(--line-spacing));
+    height: calc(100% - var(--bullet-size) - (2 * var(--line-spacing)));
+  }
+
+  .stepper > ol > li > :first-child {
+    @apply mt-0 pt-0;
+    transform: translateY(calc((var(--bullet-size) - 1lh) / 2));
+  }
+}

package/src/lib/ui/Stepper.tsx

@@ -0,0 +1,8 @@
+import type { PropsWithChildren } from "react";
+import "./Stepper.css";
+
+const Stepper = ({ children }: PropsWithChildren) => {
+  return <div className="stepper">{children}</div>;
+};
+
+export { Stepper };

package/src/lib/util/MdxComponents.tsx

@@ -1,8 +1,9 @@
-import { MDXComponents } from "mdx/types.js";
+import { type MDXComponents } from "mdx/types.js";
 import { Link } from "react-router";
 import { Heading } from "../components/Heading.js";
 import { InlineCode } from "../components/InlineCode.js";
 import { Callout } from "../ui/Callout.js";
+import { Stepper } from "../ui/Stepper.js";
 import { SyntaxHighlight } from "../ui/SyntaxHighlight.js";
 
 export type MdxComponentsType = Readonly<MDXComponents> | null | undefined;
@@ -51,6 +52,8 @@ export const MdxComponents = {
       <a href={href} target="_blank" {...props} rel="noreferrer" />
     ),
   Callout,
+  Stepper,
+  SyntaxHighlight,
   tip: (props) => <Callout type="tip" {...props} />,
   info: (props) => <Callout type="info" {...props} />,
   note: (props) => <Callout type="note" {...props} />,