zudoku 0.0.0-eeace45 → 0.0.0-efc60ba6

package/src/lib/ui/Popover.tsx

@@ -17,7 +17,7 @@ const PopoverContent = React.forwardRef<
       align={align}
       sideOffset={sideOffset}
       className={cn(
-        "z-50 w-72 rounded-md border bg-popover p-4 text-popover-foreground shadow-md outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+        "z-50 w-72 rounded-md border bg-popover p-4 text-popover-foreground shadow-md outline-hidden data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
         className,
       )}
       {...props}

package/src/lib/ui/RadioGroup.tsx

@@ -26,7 +26,7 @@ const RadioGroupItem = React.forwardRef<
     <RadioGroupPrimitive.Item
       ref={ref}
       className={cn(
-        "aspect-square h-4 w-4 rounded-full border border-primary text-primary ring-offset-background focus:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+        "aspect-square h-4 w-4 rounded-full border border-primary text-primary ring-offset-background focus:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
         className,
       )}
       {...props}

package/src/lib/ui/Select.tsx

@@ -16,14 +16,14 @@ const SelectTrigger = React.forwardRef<
   <SelectPrimitive.Trigger
     ref={ref}
     className={cn(
-      "flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+      "flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus:outline-hidden focus:ring-1 focus:ring-ring focus:ring-offset-1 disabled:cursor-not-allowed disabled:opacity-50",
       className,
     )}
     {...props}
   >
     <span className="truncate">{children}</span>
     <SelectPrimitive.Icon asChild>
-      <ChevronDown className="flex-shrink-0 h-4 w-4 opacity-50" />
+      <ChevronDown className="shrink-0 h-4 w-4 opacity-50" />
     </SelectPrimitive.Icon>
   </SelectPrimitive.Trigger>
 ));
@@ -83,9 +83,9 @@ const SelectContent = React.forwardRef<
       <SelectScrollUpButton />
       <SelectPrimitive.Viewport
         className={cn(
-          "p-1",
           position === "popper" &&
             "h-[var(--radix-select-trigger-height)] w-full min-w-[var(--radix-select-trigger-width)]",
+          "divide-y",
         )}
       >
         {children}
@@ -115,7 +115,7 @@ const SelectItem = React.forwardRef<
   <SelectPrimitive.Item
     ref={ref}
     className={cn(
-      "relative flex w-full cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+      "relative flex w-full cursor-default select-none items-center py-1.5 pl-8 pr-2 text-sm outline-hidden focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
       className,
     )}
     {...props}

package/src/lib/ui/Slider.tsx

@@ -18,7 +18,7 @@ const Slider = React.forwardRef<
     <SliderPrimitive.Track className="relative h-2 w-full grow overflow-hidden rounded-full bg-secondary">
       <SliderPrimitive.Range className="absolute h-full bg-primary" />
     </SliderPrimitive.Track>
-    <SliderPrimitive.Thumb className="block h-5 w-5 rounded-full border-2 border-primary bg-background ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50" />
+    <SliderPrimitive.Thumb className="block h-5 w-5 rounded-full border-2 border-primary bg-background ring-offset-background transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50" />
   </SliderPrimitive.Root>
 ));
 Slider.displayName = SliderPrimitive.Root.displayName;

package/src/lib/ui/Stepper.tsx

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

package/src/lib/ui/Switch.tsx

@@ -9,7 +9,7 @@ const Switch = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <SwitchPrimitives.Root
     className={cn(
-      "peer inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input",
+      "peer inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input",
       className,
     )}
     {...props}

package/src/lib/ui/SyntaxHighlight.tsx

@@ -0,0 +1,35 @@
+import { memo } from "react";
+import { useZudoku } from "../components/context/ZudokuContext.js";
+import { highlight } from "../shiki.js";
+import invariant from "../util/invariant.js";
+import { CodeBlock, type CodeBlockProps } from "./CodeBlock.js";
+import { EmbeddedCodeBlock } from "./EmbeddedCodeBlock.js";
+
+type SyntaxHighlightProps = CodeBlockProps &
+  (
+    | { code: string; embedded?: boolean; children?: never }
+    | { code?: never; children: string; embedded?: boolean }
+  );
+
+export const SyntaxHighlight = memo(
+  ({ code, children, embedded, ...props }: SyntaxHighlightProps) => {
+    const { syntaxHighlighting } = useZudoku().options;
+
+    invariant(syntaxHighlighting?.highlighter, "Highlighter not found");
+
+    const highlightedCode = highlight(
+      syntaxHighlighting.highlighter,
+      code ?? children,
+      props.language,
+      syntaxHighlighting.themes,
+    );
+
+    return embedded ? (
+      <EmbeddedCodeBlock {...props}>{highlightedCode}</EmbeddedCodeBlock>
+    ) : (
+      <CodeBlock {...props}>{highlightedCode}</CodeBlock>
+    );
+  },
+);
+
+SyntaxHighlight.displayName = "SyntaxHighlight";

package/src/lib/ui/Tabs.tsx

@@ -26,7 +26,7 @@ const TabsTrigger = React.forwardRef<
   <TabsPrimitive.Trigger
     ref={ref}
     className={cn(
-      "inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow",
+      "inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-sm font-medium ring-offset-background transition-all focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm",
       className,
     )}
     {...props}
@@ -41,7 +41,7 @@ const TabsContent = React.forwardRef<
   <TabsPrimitive.Content
     ref={ref}
     className={cn(
-      "mt-2 ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+      "mt-2 ring-offset-background focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
       className,
     )}
     {...props}

package/src/lib/ui/Textarea.tsx

@@ -9,7 +9,7 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
     return (
       <textarea
         className={cn(
-          "flex min-h-[80px] w-full rounded-md border border-input bg-background px-3 py-2 text-base ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+          "flex min-h-[80px] w-full rounded-md border border-input bg-background px-3 py-2 text-base ring-offset-background placeholder:text-muted-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
           className,
         )}
         ref={ref}

package/src/lib/ui/Toggle.tsx

@@ -5,7 +5,7 @@ import * as React from "react";
 import { cn } from "../util/cn.js";
 
 const toggleVariants = cva(
-  "inline-flex items-center justify-center rounded-md text-sm font-medium ring-offset-background transition-colors hover:bg-muted hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 gap-2",
+  "inline-flex items-center justify-center rounded-md text-sm font-medium ring-offset-background transition-colors hover:bg-muted hover:text-muted-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 gap-2",
   {
     variants: {
       variant: {

package/src/lib/ui/Tooltip.tsx

@@ -9,6 +9,15 @@ const Tooltip = TooltipPrimitive.Root;
 
 const TooltipTrigger = TooltipPrimitive.Trigger;
 
+const TooltipArrow = (
+  props: React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Arrow>,
+) => (
+  <TooltipPrimitive.Arrow
+    {...props}
+    className={cn(props.className, "fill-border")}
+  />
+);
+
 const TooltipContent = React.forwardRef<
   React.ElementRef<typeof TooltipPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>
@@ -25,4 +34,10 @@ const TooltipContent = React.forwardRef<
 ));
 TooltipContent.displayName = TooltipPrimitive.Content.displayName;
 
-export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger };
+export {
+  Tooltip,
+  TooltipArrow,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+};

package/src/lib/ui/util.tsx

@@ -0,0 +1,3 @@
+import { cn as cnUtil } from "../util/cn.js";
+
+export const cn = cnUtil;

package/src/lib/util/MdxComponents.tsx

@@ -1,19 +1,34 @@
-import { MDXComponents } from "mdx/types.js";
-import { Link } from "react-router";
+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 = Readonly<MDXComponents> | null | undefined;
 
 export const MdxComponents = {
   img: ({ node, ...props }) => {
     if (/\.(mp4|webm|mov|avi)$/.test(props.src ?? "")) {
-      return <video src={props.src} controls playsInline autoPlay loop />;
+      return (
+        <video
+          src={props.src}
+          controls
+          playsInline
+          autoPlay
+          loop
+          className={cn("rounded-lg", props.className)}
+        />
+      );
     }
-    return <img {...props} className="rounded-md" />;
+    return <img {...props} className={cn("rounded-lg", props.className)} />;
   },
+  Framed,
   h1: ({ children, id }) => (
     <Heading level={1} id={id}>
       {children}
@@ -46,36 +61,51 @@ export const MdxComponents = {
   ),
   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: ({ 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;
+  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+)/);
 
-    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, "not-inline")} {...props}>
+          {children}
+        </code>
+      </CodeBlock>
     );
   },
 } satisfies MdxComponentsType;

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/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,16 @@
+/**
+ * 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 / Math.pow(1000.0, exponent)).toFixed(
+    exponent ? 2 : 0,
+  );
+  return `${decimal} ${exponent ? `${"kMGTPEZY"[exponent - 1]}B` : "B"}`;
+};

package/src/lib/util/invariant.ts

@@ -18,17 +18,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/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

@@ -1,25 +1,34 @@
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type RecordAny = Record<string, any>;
+import type { JsonValue, RecordAny } from "./types.js";
 
-export const traverse = (
+export type { RecordAny };
+
+export const traverse = <T extends JsonValue = RecordAny>(
   specification: RecordAny,
-  transform: (specification: RecordAny) => RecordAny,
+  transform: (specification: RecordAny, path?: string[]) => T,
+  path: string[] = [],
 ) => {
-  const result: RecordAny = {};
+  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];
 
-  for (const [key, value] of Object.entries(specification)) {
     if (Array.isArray(value)) {
-      result[key] = value.map((item) =>
-        typeof item === "object" && item !== null
-          ? traverse(item, transform)
+      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);
+    } else if (typeof value === "object" && value != null) {
+      result[key] = traverse(value, transform, currentPath);
     } else {
       result[key] = value;
     }
   }
 
-  return transform(result);
+  return result;
 };

package/src/lib/util/types.ts

@@ -0,0 +1,7 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+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;