zudoku 0.0.0-ff3bc72 → 0.0.0-zuplo-api-keys.534c6f8

package/src/lib/util/invariant.ts

@@ -18,9 +18,21 @@ export default function invariant(
   throw new ZudokuError(provided ?? "Invariant failed");
 }
 
-class ZudokuError extends Error {
-  constructor(message: string) {
-    super(message);
+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 } = {},
+  ) {
+    super(message, { cause });
     this.name = "ZudokuError";
+    this.title = title;
+    this.developerHint = developerHint;
   }
 }

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/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,34 @@
+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;
+};

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;

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/useExposedProps.tsx

@@ -0,0 +1,27 @@
+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, params, searchParams, setSearchParams };
+};

package/src/lib/util/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,5 @@
+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;
+};

package/src/lib/util/useOnScreen.ts

@@ -0,0 +1,34 @@
+import { useEffect, useRef, useState } from "react";
+
+export const useOnScreen = <E extends Element = HTMLElement>({
+  rootMargin = "0px",
+  threshold,
+  root,
+}: {
+  rootMargin?: string;
+  threshold?: number;
+  root?: Element | null;
+} = {}) => {
+  const [isVisible, setIsVisible] = useState(false);
+  const ref = useRef<E | null>(null);
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (!entry) return;
+        setIsVisible(entry.isIntersecting);
+      },
+      { rootMargin, threshold, root },
+    );
+
+    const currentElement = ref.current;
+
+    if (!currentElement) return;
+
+    observer.observe(currentElement);
+
+    return () => observer.unobserve(currentElement);
+  }, [root, rootMargin, threshold]);
+
+  return [ref, isVisible] as const;
+};

package/src/lib/util/useScrollToAnchor.ts

@@ -1,59 +1,68 @@
-import { useEffect } from "react";
-import { useLocation } from "react-router-dom";
+import { useCallback, useEffect, useRef } from "react";
+import { useLocation } from "react-router";
 import { useViewportAnchor } from "../components/context/ViewportAnchorContext.js";
 import { DATA_ANCHOR_ATTR } from "../components/navigation/SidebarItem.js";
+import { scrollIntoViewIfNeeded } from "./scrollIntoViewIfNeeded.js";
 
-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);
-};
-
-export const useScrollToAnchor = () => {
-  const location = useLocation();
+export const useScrollToHash = () => {
   const { setActiveAnchor } = useViewportAnchor();
 
-  useEffect(() => {
-    if (!location.hash) return;
+  const scrollToHash = useCallback(
+    (hash: string) => {
+      const cleanHash = hash.replace(/^#/, "");
 
-    const hash = decodeURIComponent(location.hash.split("/")[0].slice(1));
+      // Operation list items might have subdivisions that the sidebar doesn't show.
+      // The subdivisions are separated by a slash so we need to remove everything before the slash to get the sidebar correct item.
+      const linkHash = cleanHash.split("/").at(0)!;
+      const element = document.getElementById(decodeURIComponent(cleanHash));
 
-    const scrollToElement = () => {
-      const element = document.getElementById(hash);
-      const link = document.querySelector(`[${DATA_ANCHOR_ATTR}="${hash}"]`);
+      const link = document.querySelector(
+        `[${DATA_ANCHOR_ATTR}="${linkHash}"]`,
+      );
 
       if (element) {
         element.scrollIntoView();
         scrollIntoViewIfNeeded(link);
-        requestIdleCallback(() => setActiveAnchor(hash));
+        // Set the active anchor after the scroll has happened
+        // so the intersection observer doesn't trigger wrong items
+        requestIdleCallback(() => setActiveAnchor(linkHash));
         return true;
       }
 
+      // Scroll didn't happen
       return false;
-    };
+    },
+    [setActiveAnchor],
+  );
+
+  return scrollToHash;
+};
 
-    if (!scrollToElement()) {
-      const observer = new MutationObserver((_, obs) => {
-        if (!scrollToElement()) return;
-        obs.disconnect();
-      });
+export const useScrollToAnchor = () => {
+  const location = useLocation();
+  const scrollToHash = useScrollToHash();
+  const initialScrolled = useRef(false);
+
+  useEffect(() => {
+    if (!location.hash || !initialScrolled.current) return;
 
-      observer.observe(document.body, { childList: true, subtree: true });
+    scrollToHash(location.hash);
+  }, [location.hash, scrollToHash]);
 
-      return () => observer.disconnect();
+  useEffect(() => {
+    if (!location.hash) {
+      initialScrolled.current = true;
+      return;
     }
-  }, [location.hash, setActiveAnchor]);
+
+    const observer = new MutationObserver((_, obs) => {
+      if (!scrollToHash(location.hash)) return;
+      initialScrolled.current = true;
+      obs.disconnect();
+    });
+
+    observer.observe(document.body, { childList: true, subtree: true });
+
+    return () => observer.disconnect();
+  }, [location.hash, scrollToHash]);
 };

package/src/lib/util/useScrollToTop.ts

@@ -1,13 +1,18 @@
 import { useEffect, useRef } from "react";
-import { useLocation } from "react-router-dom";
+import { useLocation } from "react-router";
 
 export const useScrollToTop = () => {
   const location = useLocation();
   const previousPath = useRef(location.pathname);
 
   useEffect(() => {
-    if (previousPath.current === location.pathname) return;
-    window.scrollTo(0, 0);
+    const isNewPage = previousPath.current !== location.pathname;
+    const hasAnchor = location.hash !== "";
+
+    if (isNewPage && !hasAnchor) {
+      window.scrollTo(0, 0);
+    }
+
     previousPath.current = location.pathname;
-  }, [location.pathname]);
+  }, [location.pathname, location.hash]);
 };

package/src/shiki/langs/abap.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/abap";

package/src/shiki/langs/actionscript-3.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/actionscript-3";

package/src/shiki/langs/ada.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/ada";

package/src/shiki/langs/angular-expression.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/angular-expression";

package/src/shiki/langs/angular-html.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/angular-html";

package/src/shiki/langs/angular-inline-style.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/angular-inline-style";

package/src/shiki/langs/angular-inline-template.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/angular-inline-template";

package/src/shiki/langs/angular-let-declaration.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/angular-let-declaration";

package/src/shiki/langs/angular-template-blocks.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/angular-template-blocks";

package/src/shiki/langs/angular-template.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/angular-template";

package/src/shiki/langs/angular-ts.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/angular-ts";

package/src/shiki/langs/apache.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/apache";

package/src/shiki/langs/apex.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/apex";

package/src/shiki/langs/apl.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/apl";

package/src/shiki/langs/applescript.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/applescript";

package/src/shiki/langs/ara.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/ara";

package/src/shiki/langs/asciidoc.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/asciidoc";

package/src/shiki/langs/asm.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/asm";

package/src/shiki/langs/astro.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/astro";

package/src/shiki/langs/awk.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/awk";

package/src/shiki/langs/ballerina.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/ballerina";

package/src/shiki/langs/bat.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/bat";

package/src/shiki/langs/beancount.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/beancount";

package/src/shiki/langs/berry.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/berry";

package/src/shiki/langs/bibtex.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/bibtex";

package/src/shiki/langs/bicep.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/bicep";

package/src/shiki/langs/blade.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/blade";

package/src/shiki/langs/bsl.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/bsl";

package/src/shiki/langs/c.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/c";

package/src/shiki/langs/cadence.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/cadence";

package/src/shiki/langs/cairo.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/cairo";

package/src/shiki/langs/clarity.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/clarity";

package/src/shiki/langs/clojure.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/clojure";

package/src/shiki/langs/cmake.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/cmake";

package/src/shiki/langs/cobol.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/cobol";

package/src/shiki/langs/codeowners.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/codeowners";

package/src/shiki/langs/codeql.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/codeql";

package/src/shiki/langs/coffee.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/coffee";

package/src/shiki/langs/common-lisp.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/common-lisp";

package/src/shiki/langs/coq.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/coq";

package/src/shiki/langs/cpp-macro.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/cpp-macro";

package/src/shiki/langs/cpp.js

@@ -0,0 +1 @@
+export { default } from "@shikijs/langs/cpp";