zudoku 0.0.0-f417aae → 0.0.0-f46233e4

package/src/lib/util/MdxComponents.tsx

@@ -1,23 +1,41 @@
-import { MDXProvider } from "@mdx-js/react";
-import type { ComponentProps } from "react";
-import { Link } from "react-router-dom";
+import type { MDXComponents } from "mdx/types.js";
+import { CodeBlock } from "zudoku/ui/CodeBlock.js";
+import { AnchorLink } from "../components/AnchorLink.js";
+import { Framed } from "../components/Framed.js";
 import { Heading } from "../components/Heading.js";
 import { InlineCode } from "../components/InlineCode.js";
-import { SyntaxHighlight } from "../components/SyntaxHighlight.js";
+import { Button } from "../ui/Button.js";
 import { Callout } from "../ui/Callout.js";
+import { Stepper } from "../ui/Stepper.js";
+import { SyntaxHighlight } from "../ui/SyntaxHighlight.js";
+import { cn } from "./cn.js";
 
-export type MdxComponentsType = ComponentProps<
-  typeof MDXProvider
->["components"];
+export type MdxComponentsType = Readonly<MDXComponents> | null | undefined;
 
 export const MdxComponents = {
-  // @ts-expect-error Node is not in types but still gets passed
   img: ({ node, ...props }) => {
     if (/\.(mp4|webm|mov|avi)$/.test(props.src ?? "")) {
-      return <video src={props.src} controls playsInline autoPlay loop />;
+      return (
+        // biome-ignore lint/a11y/useMediaCaption: No in control of the caption here
+        <video
+          src={props.src}
+          controls
+          playsInline
+          autoPlay
+          loop
+          className={cn("rounded-lg", props.className)}
+        />
+      );
     }
-    return <img {...props} className="rounded-md" />;
+    return (
+      <img
+        alt={props.alt}
+        {...props}
+        className={cn("rounded-lg", props.className)}
+      />
+    );
   },
+  Framed,
   h1: ({ children, id }) => (
     <Heading level={1} id={id}>
       {children}
@@ -48,40 +66,56 @@ export const MdxComponents = {
       {children}
     </Heading>
   ),
-  // @ts-expect-error Node is not in types but still gets passed
   a: ({ href, node, ...props }) =>
     href && !href.startsWith("http") ? (
-      <Link to={href} relative="path" {...props} />
+      <AnchorLink to={href} relative="path" {...props} />
     ) : (
       <a href={href} target="_blank" {...props} rel="noreferrer" />
     ),
+  Button,
   Callout,
+  Stepper,
+  SyntaxHighlight,
   tip: (props) => <Callout type="tip" {...props} />,
   info: (props) => <Callout type="info" {...props} />,
   note: (props) => <Callout type="note" {...props} />,
   caution: (props) => <Callout type="caution" {...props} />,
   warning: (props) => <Callout type="caution" {...props} />,
   danger: (props) => <Callout type="danger" {...props} />,
+  pre: (props) => (
+    <pre className={cn("not-prose my-4", props.className)} {...props} />
+  ),
+  code: ({
+    className,
+    node: _node,
+    children,
+    title,
+    inline,
+    showLineNumbers,
+    ...props
+  }) => {
+    const match = className?.match(/language?-(\w+)/);
 
-  pre: ({ children }) => <>{children}</>,
-  code: ({ className, children, ...props }) => {
-    // `inline` provided by the rehype plugin, as react-markdown removed support for that
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const inline = (props as any).inline;
-
-    if (inline === true || inline === "true") {
-      return <InlineCode className={className}>{children}</InlineCode>;
+    if (inline === "true" || inline === true) {
+      return (
+        <InlineCode className={cn(className, "inline")}>{children}</InlineCode>
+      );
     }
 
-    const match = className?.match(/language?-(\w+)/);
-
     return (
-      <SyntaxHighlight
+      <CodeBlock
         language={match?.[1]}
-        className="rounded-xl p-4 border dark:!bg-foreground/10 dark:border-transparent"
         showLanguageIndicator
-        code={String(children).trim()}
-      />
+        showLineNumbers={showLineNumbers}
+        title={title}
+      >
+        <code
+          className={cn(className, "overflow-x-auto scrollbar not-inline")}
+          {...props}
+        >
+          {children}
+        </code>
+      </CodeBlock>
     );
   },
 } satisfies MdxComponentsType;

package/src/lib/util/cn.ts

@@ -1,4 +1,4 @@
-import { clsx, type ClassValue } from "clsx";
+import { type ClassValue, clsx } from "clsx";
 import { twMerge } from "tailwind-merge";
 
 export function cn(...inputs: ClassValue[]) {

package/src/lib/util/createVariantComponent.tsx

@@ -1,12 +1,12 @@
 import { Slot } from "@radix-ui/react-slot";
-import { cva } from "class-variance-authority";
+import type { cva } from "class-variance-authority";
 import type { ClassValue } from "clsx";
+import type { HTMLElementType, JSX } from "react";
 import * as React from "react";
-import type { JSX } from "react/jsx-runtime";
 import { cn } from "./cn.js";
 
 const createVariantComponent = <
-  E extends keyof React.ReactHTML,
+  E extends HTMLElementType,
   C extends ReturnType<typeof cva>,
 >(
   tag: E,

package/src/lib/util/detectOS.ts

@@ -0,0 +1,9 @@
+export function detectOS() {
+  const userAgent = navigator.userAgent.toLowerCase();
+
+  if (userAgent.includes("win")) return "Windows";
+  if (userAgent.includes("mac")) return "macOS";
+  if (userAgent.includes("linux")) return "Linux";
+
+  return undefined;
+}

package/src/lib/util/ensureArray.ts

@@ -0,0 +1,3 @@
+export const ensureArray = <T extends NonNullable<unknown>>(
+  value: T | T[],
+): T[] => (Array.isArray(value) ? value : [value]);

package/src/lib/util/groupBy.ts

@@ -1,3 +1,4 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: Allow any type
 export const groupBy = <
   T extends Record<PropertyKey, any>,
   KeySelector extends (item: T) => PropertyKey,

package/src/lib/util/humanFileSize.test.ts

@@ -0,0 +1,24 @@
+import { humanFileSize } from "./humanFileSize.js";
+
+describe("humanFileSize", () => {
+  it("should handle zero bytes", () => {
+    expect(humanFileSize(0)).toBe("0 B");
+    expect(humanFileSize()).toBe("0 B");
+  });
+
+  it("should handle undefined bytes", () => {
+    expect(humanFileSize(undefined)).toBe("0 B");
+  });
+
+  it("should handle positive bytes", () => {
+    expect(humanFileSize(200)).toBe("200 B");
+    expect(humanFileSize(1000)).toBe("1.00 kB");
+    expect(humanFileSize(1000000)).toBe("1.00 MB");
+    expect(humanFileSize(1000000000)).toBe("1.00 GB");
+    expect(humanFileSize(1000000000000)).toBe("1.00 TB");
+    expect(humanFileSize(1000000000000000)).toBe("1.00 PB");
+    expect(humanFileSize(1000000000000000000)).toBe("1.00 EB");
+    expect(humanFileSize(1000000000000000000000)).toBe("1.00 ZB");
+    expect(humanFileSize(1000000000000000000000000)).toBe("1.00 YB");
+  });
+});

package/src/lib/util/humanFileSize.ts

@@ -0,0 +1,15 @@
+/**
+ * Converts a number of bytes to a human-readable file size string
+ * @param bytes - The number of bytes (defaults to 0)
+ * @returns A formatted string like "1.23 MB" or "456 B"
+ */
+export const humanFileSize = (bytes = 0) => {
+  if (bytes === 0) {
+    return "0 B";
+  }
+
+  const exponent = Math.floor(Math.log(bytes) / Math.log(1000.0));
+  const decimal = (bytes / 1000.0 ** exponent).toFixed(exponent ? 2 : 0);
+
+  return `${decimal} ${exponent ? `${"kMGTPEZY"[exponent - 1]}B` : "B"}`;
+};

package/src/lib/util/invariant.ts

@@ -1,4 +1,5 @@
 export default function invariant(
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
   condition: any,
   // Not providing an inline default argument for message as the result is smaller
   /**
@@ -18,17 +19,19 @@ export default function invariant(
   throw new ZudokuError(provided ?? "Invariant failed");
 }
 
+export type ZudokuErrorOptions = {
+  developerHint?: string;
+  title?: string;
+  cause?: Error;
+};
+
 export class ZudokuError extends Error {
   public developerHint: string | undefined;
   public title: string | undefined;
 
   constructor(
     message: string,
-    {
-      developerHint,
-      title,
-      cause,
-    }: { developerHint?: string; title?: string; cause?: Error } = {},
+    { developerHint, title, cause }: ZudokuErrorOptions = {},
   ) {
     super(message, { cause });
     this.name = "ZudokuError";

package/src/lib/util/joinPath.tsx

@@ -1,3 +1,6 @@
+/**
+ * @deprecated Use `joinUrl` instead.
+ */
 export const joinPath = (
   ...parts: Array<string | null | undefined | boolean>
 ) => {

package/src/lib/util/joinUrl.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "vitest";
+import { joinUrl } from "./joinUrl.js";
+
+describe("joinUrl", () => {
+  test("handles basic URL joining", () => {
+    expect(joinUrl("https://example.com", "path")).toBe(
+      "https://example.com/path",
+    );
+    expect(joinUrl("https://example.com/", "path")).toBe(
+      "https://example.com/path",
+    );
+    expect(joinUrl("https://example.com/", "/path")).toBe(
+      "https://example.com/path",
+    );
+  });
+
+  test("handles multiple path segments", () => {
+    expect(joinUrl("https://example.com", "api", "v1", "users")).toBe(
+      "https://example.com/api/v1/users",
+    );
+  });
+
+  // test("handles query parameters", () => {
+  //   expect(joinUrl("https://example.com", "path?query=1")).toBe(
+  //     "https://example.com/path?query=1",
+  //   );
+  //   expect(joinUrl("https://example.com?base=1", "path?query=1")).toBe(
+  //     "https://example.com/path?query=1",
+  //   );
+  // });
+
+  // test("handles repeated dots and question marks", () => {
+  //   expect(joinUrl("https://example.com", "path/../../../test")).toBe(
+  //     "https://example.com/path/../../../test",
+  //   );
+  //   expect(joinUrl("https://example.com", "test????a=1")).toBe(
+  //     "https://example.com/test????a=1",
+  //   );
+  // });
+
+  test("handles falsy values", () => {
+    expect(joinUrl("https://example.com", null, undefined, false, "path")).toBe(
+      "https://example.com/path",
+    );
+  });
+
+  test("handles numeric values", () => {
+    expect(joinUrl("https://example.com", "api", 123, "test")).toBe(
+      "https://example.com/api/123/test",
+    );
+  });
+
+  test("handles relative paths", () => {
+    expect(joinUrl("/api", "v1", "users")).toBe("/api/v1/users");
+    expect(joinUrl("api", "v1", "users")).toBe("/api/v1/users");
+  });
+
+  test("handles empty input", () => {
+    expect(joinUrl()).toBe("/");
+    expect(joinUrl("")).toBe("/");
+  });
+});

package/src/lib/util/joinUrl.ts

@@ -0,0 +1,57 @@
+// Mostly adapted from https://github.com/moxystudio/js-proper-url-join
+const defaultUrlRegExp = /^(\w+:\/\/[^/?]+)?([^?]*)(\?.*)?$/;
+
+const normalizeParts = (
+  parts: (string | number | null | undefined | false)[],
+): string[] =>
+  parts
+    .filter(
+      (part): part is string | number =>
+        part !== null &&
+        part !== undefined &&
+        part !== false &&
+        (typeof part === "string" || typeof part === "number"),
+    )
+    .map((part) => `${part}`)
+    .filter((part) => part);
+
+interface ParsedParts {
+  prefix: string;
+  pathname: string[];
+}
+
+const parseParts = (parts: string[]): ParsedParts => {
+  const partsStr = parts.join("/");
+  const [, prefix = "", pathname = ""] = partsStr.match(defaultUrlRegExp) ?? [];
+
+  return {
+    prefix,
+    pathname: pathname.split("/").filter((part) => part !== ""),
+  };
+};
+
+const buildUrl = (parsedParts: ParsedParts): string => {
+  const { prefix, pathname } = parsedParts;
+  let url = prefix;
+
+  if (pathname.length > 0) {
+    if (url) {
+      url += "/";
+    } else {
+      url = "/";
+    }
+    url += pathname.join("/");
+  } else if (!url) {
+    url = "/";
+  }
+
+  return url;
+};
+
+export const joinUrl = (
+  ...parts: Array<string | number | null | undefined | false>
+): string => {
+  const normalizedParts = normalizeParts(parts);
+  const parsedParts = parseParts(normalizedParts);
+  return buildUrl(parsedParts);
+};

package/src/lib/util/os.ts

@@ -0,0 +1,18 @@
+export function getOS(): "apple" | "linux" | "unix" | "windows" | undefined {
+  const notFound = -1;
+  const userAgent = navigator.userAgent.toLowerCase();
+  if (userAgent.indexOf("win") !== notFound) {
+    return "windows";
+  } else if (userAgent.indexOf("mac") !== notFound) {
+    return "apple";
+  } else if (userAgent.indexOf("linux") !== notFound) {
+    return "linux";
+  } else if (userAgent.indexOf("x11") !== notFound) {
+    return "unix";
+  }
+  return;
+}
+
+export function isAppleDevice(): boolean {
+  return getOS() === "apple";
+}

package/src/lib/util/pastellize.ts

@@ -1,14 +1,14 @@
 const c2n = (c: string) =>
   Math.abs(
-    isNaN(parseInt(c))
+    Number.isNaN(Number(c))
       ? c.toLowerCase().charCodeAt(0) - 96
-      : isNaN(parseInt(c))
+      : Number.isNaN(Number(c))
         ? 0
-        : parseInt(c),
+        : Number(c),
   );
 const s2n = (s: string) =>
   s.length > 1
-    ? parseInt(s.split("").reduce((a, c) => `${c2n(a) + c2n(c)}`))
+    ? Number(s.split("").reduce((a, c) => `${c2n(a) + c2n(c)}`))
     : c2n(s);
 
 export const pastellize = (

package/src/lib/util/scrollIntoViewIfNeeded.ts

@@ -0,0 +1,18 @@
+export const scrollIntoViewIfNeeded = (
+  element: Element | null,
+  options: ScrollIntoViewOptions = { block: "center" },
+) => {
+  if (!element) return;
+
+  const rect = element.getBoundingClientRect();
+  const isInView =
+    rect.top >= 0 &&
+    rect.left >= 0 &&
+    rect.bottom <=
+      (window.innerHeight || document.documentElement.clientHeight) &&
+    rect.right <= (window.innerWidth || document.documentElement.clientWidth);
+
+  if (isInView) return;
+
+  element.scrollIntoView(options);
+};

package/src/lib/util/traverse.ts

@@ -0,0 +1,70 @@
+import type { JsonValue, RecordAny } from "./types.js";
+
+export type { RecordAny };
+
+export const traverse = <T extends JsonValue = RecordAny>(
+  specification: RecordAny,
+  transform: (specification: RecordAny, path?: string[]) => T,
+  path: string[] = [],
+) => {
+  const transformed = transform(specification, path);
+  if (typeof transformed !== "object" || transformed === null) {
+    return transformed;
+  }
+
+  const result: RecordAny = Array.isArray(transformed) ? [] : {};
+
+  for (const [key, value] of Object.entries(transformed)) {
+    const currentPath = [...path, key];
+
+    if (Array.isArray(value)) {
+      result[key] = value.map((item, index) =>
+        typeof item === "object" && item != null
+          ? traverse(item, transform, [...currentPath, index.toString()])
+          : item,
+      );
+    } else if (typeof value === "object" && value != null) {
+      result[key] = traverse(value, transform, currentPath);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+};
+
+export const traverseAsync = async <T extends JsonValue = RecordAny>(
+  specification: RecordAny,
+  transform: (specification: RecordAny, path?: string[]) => T | Promise<T>,
+  path: string[] = [],
+) => {
+  const transformed = await transform(specification, path);
+  if (typeof transformed !== "object" || transformed === null) {
+    return transformed;
+  }
+
+  const result: RecordAny = Array.isArray(transformed) ? [] : {};
+
+  for (const [key, value] of Object.entries(transformed)) {
+    const currentPath = [...path, key];
+
+    if (Array.isArray(value)) {
+      result[key] = await Promise.all(
+        value.map(async (item, index) =>
+          typeof item === "object" && item != null
+            ? await traverseAsync(item, transform, [
+                ...currentPath,
+                index.toString(),
+              ])
+            : item,
+        ),
+      );
+    } else if (typeof value === "object" && value != null) {
+      result[key] = await traverseAsync(value, transform, currentPath);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+};

package/src/lib/util/types.ts

@@ -0,0 +1,7 @@
+// biome-ignore lint/suspicious/noExplicitAny: Allow any type
+export type RecordAny = Record<string, any>;
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonArray = JsonValue[];
+export type JsonObject = { [key: string]: JsonValue };
+export type JsonValue = JsonPrimitive | JsonArray | JsonObject;

package/src/lib/util/url.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { normalizeRedirectUrl } from "./url.js";
+
+describe("normalizeRedirectUrl", () => {
+  const mockOrigin = "https://example.com";
+
+  it("should return original URL if it doesn't start with origin", () => {
+    const result = normalizeRedirectUrl(
+      "https://other.com/path",
+      mockOrigin,
+      "/",
+    );
+    expect(result).toBe("https://other.com/path");
+  });
+
+  it("should remove origin when root is /", () => {
+    const result = normalizeRedirectUrl(
+      "https://example.com/some/path",
+      mockOrigin,
+      "/",
+    );
+    expect(result).toBe("/some/path");
+  });
+
+  it("should remove origin and root path when root is not /", () => {
+    const result = normalizeRedirectUrl(
+      "https://example.com/docs/some/path",
+      mockOrigin,
+      "/docs",
+    );
+    expect(result).toBe("/some/path");
+  });
+
+  it("should only remove origin when URL doesn't match root path", () => {
+    const result = normalizeRedirectUrl(
+      "https://example.com/other/path",
+      mockOrigin,
+      "/docs",
+    );
+    expect(result).toBe("/other/path");
+  });
+
+  it("should handle empty root path", () => {
+    const result = normalizeRedirectUrl(
+      "https://example.com/path",
+      mockOrigin,
+      "",
+    );
+    expect(result).toBe("/path");
+  });
+});

package/src/lib/util/url.ts

@@ -0,0 +1,18 @@
+/**
+ * Normalizes a redirect URL by removing the origin and optionally the root path
+ */
+export function normalizeRedirectUrl(
+  redirectTo: string,
+  origin: string,
+  basePath: string = "/",
+): string {
+  if (!redirectTo.startsWith(origin)) {
+    return redirectTo;
+  }
+
+  if (basePath !== "/" && redirectTo.startsWith(origin + basePath)) {
+    return redirectTo.slice(origin.length + basePath.length);
+  }
+
+  return redirectTo.slice(origin.length);
+}

package/src/lib/util/useCopyToClipboard.ts

@@ -0,0 +1,17 @@
+import { useCallback, useState } from "react";
+
+export const useCopyToClipboard = (timeout = 2000) => {
+  const [isCopied, setIsCopied] = useState(false);
+
+  const copyToClipboard = useCallback(
+    (text: string) => {
+      void navigator.clipboard.writeText(text);
+      setIsCopied(true);
+
+      setTimeout(() => setIsCopied(false), timeout);
+    },
+    [timeout],
+  );
+
+  return [isCopied, copyToClipboard] as const;
+};

package/src/lib/util/useExposedProps.tsx

@@ -1,10 +1,27 @@
-import { useLocation, useNavigate, useSearchParams } from "react-router-dom";
-import type { ExposedComponentProps } from "../components/SlotletProvider.js";
+import {
+  type Location,
+  type NavigateFunction,
+  type Params,
+  type SetURLSearchParams,
+  useLocation,
+  useNavigate,
+  useParams,
+  useSearchParams,
+} from "react-router";
+
+export type ExposedComponentProps = {
+  location: Location;
+  navigate: NavigateFunction;
+  searchParams: URLSearchParams;
+  setSearchParams: SetURLSearchParams;
+  params: Params;
+};
 
 export const useExposedProps = (): ExposedComponentProps => {
   const location = useLocation();
   const navigate = useNavigate();
   const [searchParams, setSearchParams] = useSearchParams();
+  const params = useParams();
 
-  return { location, navigate, searchParams, setSearchParams };
+  return { location, navigate, params, searchParams, setSearchParams };
 };

package/src/lib/util/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,6 @@
+import { useEffect, useLayoutEffect } from "react";
+
+const useIsomorphicLayoutEffect =
+  typeof window !== "undefined" ? useLayoutEffect : useEffect;
+
+export default useIsomorphicLayoutEffect;

package/src/lib/util/useLatest.ts

@@ -0,0 +1,18 @@
+import { useEffect, useRef } from "react";
+
+// This hook is useful when you need to store a reference to a variable that changes over time,
+// but you don't want to re-run any callbacks that depend on that variable every time it changes.
+// By using a reference to the latest value, you can ensure that any callbacks only run when necessary,
+// without any unnecessary re-renders.
+
+// Note: It's safe to put the return value of this hook in a dependency array, because it won't change!
+export const useLatest = <T>(current: T) => {
+  const valueRef = useRef(current);
+  valueRef.current = current;
+
+  useEffect(() => {
+    valueRef.current = current;
+  }, [current]);
+
+  return valueRef;
+};