@mehdad67/apitogo 0.1.24

package/src/lib/errors/ErrorAlert.tsx

@@ -0,0 +1,28 @@
+import { DeveloperHint } from "../components/DeveloperHint.js";
+import { Heading } from "../components/Heading.js";
+import { Typography } from "../components/Typography.js";
+import { ZudokuError } from "../util/invariant.js";
+
+export function ErrorAlert({ error }: { error: unknown }) {
+  const message =
+    error instanceof Error ? error.message : "Something went wrong";
+
+  const hint = error instanceof ZudokuError ? error.developerHint : undefined;
+  const title =
+    error instanceof ZudokuError ? error.title : "Something went wrong";
+  const stack = error instanceof Error ? error.stack : undefined;
+  const cause = error instanceof Error ? error.cause : undefined;
+
+  const stringError = cause instanceof Error ? String(cause.stack) : stack;
+
+  return (
+    <Typography className="grid grid-cols-1 max-w-none! pt-(--padding-content-top)">
+      <Heading level={1}>{title}</Heading>
+      Error: {message}
+      {hint && <DeveloperHint className="mb-4">{hint}</DeveloperHint>}
+      {stringError && (
+        <pre className="max-h-[400px] [&>pre]:p-4">{stringError}</pre>
+      )}
+    </Typography>
+  );
+}

package/src/lib/errors/ErrorMessage.tsx

@@ -0,0 +1,50 @@
+import {
+  Alert,
+  AlertDescription,
+  AlertTitle,
+} from "@lukoweb/apitogo/ui/Alert.js";
+import { Suspense, lazy } from "react";
+import { DeveloperHint } from "../components/DeveloperHint.js";
+import { ZudokuError } from "../util/invariant.js";
+
+const SyntaxHighlight = lazy(() =>
+  import("@lukoweb/apitogo/ui/SyntaxHighlight.js").then((m) => ({
+    default: m.SyntaxHighlight,
+  })),
+);
+
+export function ErrorMessage({ error }: { error: unknown }) {
+  const message =
+    error instanceof Error ? error.message : "Something went wrong";
+
+  const showDeveloperHints = process.env.NODE_ENV === "development";
+
+  const hint = error instanceof ZudokuError ? error.developerHint : undefined;
+  const title =
+    error instanceof ZudokuError ? error.title : "Something went wrong";
+  const stack = error instanceof Error ? error.stack : undefined;
+  const cause = error instanceof Error ? error.cause : undefined;
+
+  const stringError = cause instanceof Error ? String(cause.stack) : stack;
+
+  return (
+    <>
+      <Alert variant="destructive">
+        <AlertTitle>{title}</AlertTitle>
+        <AlertDescription>{message}</AlertDescription>
+      </Alert>
+      {showDeveloperHints && hint && (
+        <DeveloperHint className="mb-4">{hint}</DeveloperHint>
+      )}
+      {showDeveloperHints && stringError && (
+        <Suspense>
+          <SyntaxHighlight
+            className="max-h-[400px] [&>pre]:p-4"
+            language="js"
+            code={stringError}
+          />
+        </Suspense>
+      )}
+    </>
+  );
+}

package/src/lib/errors/RouterError.tsx

@@ -0,0 +1,18 @@
+import { isRouteErrorResponse, useRouteError } from "react-router";
+import { NotFoundPage } from "../components/NotFoundPage.js";
+import { cn } from "../util/cn.js";
+import { ErrorAlert } from "./ErrorAlert.js";
+
+export function RouterError({ className }: { className?: string }) {
+  const error = useRouteError();
+
+  if (isRouteErrorResponse(error) && error.status === 404) {
+    return <NotFoundPage />;
+  }
+
+  return (
+    <div className={cn("mx-4 max-w-2xl", className)} data-pagefind-ignore="all">
+      <ErrorAlert error={error} />
+    </div>
+  );
+}

package/src/lib/errors/ServerError.tsx

@@ -0,0 +1,5 @@
+import { ErrorAlert } from "./ErrorAlert.js";
+
+export function ServerError({ error }: { error: unknown }) {
+  return <ErrorAlert error={error} />;
+}

package/src/lib/errors/TopLevelError.tsx

@@ -0,0 +1,6 @@
+import type { FallbackProps } from "react-error-boundary";
+import { ErrorAlert } from "./ErrorAlert.js";
+
+export function TopLevelError({ error }: FallbackProps) {
+  return <ErrorAlert error={error} />;
+}

package/src/lib/hooks/index.ts

@@ -0,0 +1,13 @@
+export { useMDXComponents } from "@mdx-js/react";
+export { useTheme } from "next-themes";
+export {
+  useAuth,
+  useRefreshUserProfile,
+  useVerifiedEmail,
+} from "../authentication/hook.js";
+export { CACHE_KEYS, useCache } from "../components/cache.js";
+export { useApitogo } from "../components/context/ZudokuContext.js";
+/** @deprecated Use {@link useApitogo} instead. */
+export { useZudoku } from "../components/context/ZudokuContext.js";
+export { useExposedProps } from "../util/useExposedProps.js";
+export { useEvent } from "./useEvent.js";

package/src/lib/hooks/useEvent.ts

@@ -0,0 +1,41 @@
+import { useEffect, useState } from "react";
+import { useApitogo } from "../components/context/ZudokuContext.js";
+import type { ApitogoEvents } from "../core/ZudokuContext.js";
+
+type EventParameters<Event extends keyof ApitogoEvents> = Parameters<
+  ApitogoEvents[Event]
+>;
+
+/**
+ * Hook to subscribe to APIToGo application 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 ApitogoEvents>(
+  event: E,
+): EventParameters<E>;
+export function useEvent<E extends keyof ApitogoEvents, R>(
+  event: E,
+  callback: (...args: EventParameters<E>) => R,
+): R;
+export function useEvent<E extends keyof ApitogoEvents, R>(
+  event: E,
+  callback?: (...args: EventParameters<E>) => R,
+) {
+  const apitogo = useApitogo();
+  const [latestData, setLatestData] = useState<R | EventParameters<E>>();
+
+  useEffect(() => {
+    return apitogo.addEventListener(event, ((...args: EventParameters<E>) => {
+      if (callback) {
+        const result = callback(...args);
+        setLatestData(result);
+      } else {
+        setLatestData(args);
+      }
+    }) as ApitogoEvents[E]);
+  }, [apitogo, event, callback]);
+
+  return latestData;
+}

package/src/lib/hooks/useHighlighter.ts

@@ -0,0 +1,15 @@
+import { use } from "react";
+import type { HighlighterCore } from "shiki";
+import { useZudoku } from "../components/context/ZudokuContext.js";
+
+export const useHighlighter = (): HighlighterCore => {
+  const { syntaxHighlighting } = useZudoku().options;
+
+  if (!syntaxHighlighting) {
+    throw new Error(
+      "Syntax highlighting not configured. Provide highlighterPromise in syntaxHighlighting options.",
+    );
+  }
+
+  return use(syntaxHighlighting.highlighterPromise);
+};

package/src/lib/hooks/useHotkey.ts

@@ -0,0 +1,70 @@
+import { useEffect, useRef } from "react";
+import { isAppleDevice } from "../util/os.js";
+
+const keymap = {
+  other: {
+    alt: "Alt",
+    meta: "Ctrl",
+    ctrl: "Ctrl",
+    shift: "⇧",
+    option: "Alt",
+  },
+  apple: {
+    alt: "⌥",
+    meta: "⌘",
+    ctrl: "Ctrl",
+    shift: "⇧",
+    option: "⌥",
+  },
+};
+
+export const useHotkey = (hotkey: string, callback: () => void) => {
+  const hotkeySanitized = hotkey.toLowerCase().split("+");
+  const meta = hotkeySanitized.includes("meta");
+  const shift = hotkeySanitized.includes("shift");
+  const alt =
+    hotkeySanitized.includes("option") || hotkeySanitized.includes("alt");
+  const ctrl = hotkeySanitized.includes("ctrl");
+
+  const key = hotkey.split("+").pop();
+
+  const callbackRef = useRef(callback);
+
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  useEffect(() => {
+    const handler = (event: KeyboardEvent) => {
+      if (
+        (event.code === `Key${key?.toUpperCase()}` ||
+          event.code.toLowerCase() === key?.toLowerCase()) &&
+        event.metaKey === meta &&
+        event.shiftKey === shift &&
+        event.altKey === alt &&
+        event.ctrlKey === ctrl
+      ) {
+        event.preventDefault();
+        callbackRef.current();
+      }
+    };
+
+    window.addEventListener("keydown", handler);
+    return () => {
+      window.removeEventListener("keydown", handler);
+    };
+  }, [key, meta, shift, alt, ctrl]);
+
+  return {
+    trigger: () => callbackRef.current(),
+    label: hotkeySanitized.map((key: string) =>
+      key === "meta" ||
+      key === "ctrl" ||
+      key === "alt" ||
+      key === "shift" ||
+      key === "option"
+        ? keymap[isAppleDevice() ? "apple" : "other"][key]
+        : key,
+    ),
+  };
+};

package/src/lib/icons.ts

@@ -0,0 +1,2 @@
+export * from "lucide-react";
+export * from "./MissingIcon.js";

package/src/lib/navigation/applyRules.ts

@@ -0,0 +1,127 @@
+import type {
+  NavigationItem,
+  ResolvedNavigationRule,
+  SortableNavigationItem,
+} from "../../config/validators/NavigationSchema.js";
+import { findByPath } from "./pathMatcher.js";
+
+export const SORTABLE_TYPES = ["doc", "link", "category", "section"] as const;
+export type SortableType = (typeof SORTABLE_TYPES)[number];
+
+const isSortable = (item: NavigationItem): item is SortableNavigationItem =>
+  SORTABLE_TYPES.some((t) => t === item.type);
+
+export type ApplyRulesResult = {
+  result: NavigationItem[];
+  warnings: string[];
+};
+
+const cloneNavigation = (items: NavigationItem[]): NavigationItem[] =>
+  items.map((item) =>
+    item.type === "category"
+      ? { ...item, items: cloneNavigation(item.items) }
+      : { ...item },
+  );
+
+// Strips the top-nav prefix from a rule path if it matches the current label.
+const normalizeRulePath = (rulePath: string, topNavLabel?: string) => {
+  if (!topNavLabel) return rulePath;
+
+  const segments = rulePath.split("/").filter(Boolean);
+  const first = segments[0];
+  if (!first) return rulePath;
+
+  // Number segments can't match a top-nav label
+  if (!Number.isNaN(Number(first))) {
+    return segments.length > 1 ? undefined : rulePath;
+  }
+
+  if (first.toLowerCase() === topNavLabel.toLowerCase()) {
+    const rest = segments.slice(1).join("/");
+    return rest || "/";
+  }
+
+  // Multi-segment path where first segment doesn't match → different context
+  if (segments.length > 1) return undefined;
+
+  // Single segment: apply to sidebar as-is
+  return rulePath;
+};
+
+export const applyRules = (
+  navigation: NavigationItem[],
+  rules: ResolvedNavigationRule[],
+  topNavLabel?: string,
+): ApplyRulesResult => {
+  const result = cloneNavigation(navigation);
+  const warnings: string[] = [];
+
+  for (const rule of rules) {
+    const normalizedPath = normalizeRulePath(rule.match, topNavLabel);
+    if (normalizedPath === undefined) continue;
+
+    const match = findByPath(result, normalizedPath);
+    if (!match) {
+      warnings.push(`Rule target "${rule.match}" not found`);
+      continue;
+    }
+
+    if (match.isRoot) {
+      if (rule.type === "sort") {
+        result.sort((a, b) =>
+          isSortable(a) && isSortable(b) ? rule.by(a, b) : 0,
+        );
+      } else {
+        warnings.push(`Rule type "${rule.type}" cannot target the root level`);
+      }
+      continue;
+    }
+
+    switch (rule.type) {
+      case "remove":
+        match.parentItems.splice(match.index, 1);
+        break;
+      case "modify":
+        match.parentItems[match.index] = { ...match.item, ...rule.set };
+        break;
+      case "insert": {
+        const offset = rule.position === "after" ? 1 : 0;
+        match.parentItems.splice(match.index + offset, 0, ...rule.items);
+        break;
+      }
+      case "sort": {
+        const sortableItems =
+          match.item.type === "category" ? match.item.items : undefined;
+
+        if (sortableItems) {
+          sortableItems.sort((a, b) =>
+            isSortable(a) && isSortable(b) ? rule.by(a, b) : 0,
+          );
+        } else {
+          warnings.push(`Sort target "${rule.match}" is not a category`);
+        }
+        break;
+      }
+      case "move": {
+        const toPath = normalizeRulePath(rule.to, topNavLabel);
+        if (toPath === undefined) break;
+
+        const [item] = match.parentItems.splice(match.index, 1);
+        if (!item) break;
+
+        const target = findByPath(result, toPath);
+        if (!target || target.isRoot) {
+          warnings.push(`Move target "${rule.to}" not found`);
+          match.parentItems.splice(match.index, 0, item);
+          break;
+        }
+
+        const offset = rule.position === "after" ? 1 : 0;
+        target.parentItems.splice(target.index + offset, 0, item);
+        break;
+      }
+    }
+  }
+
+  return { result, warnings };
+};

package/src/lib/navigation/pathMatcher.ts

@@ -0,0 +1,81 @@
+import type { NavigationItem } from "../../config/validators/NavigationSchema.js";
+
+type PathSegment =
+  | { type: "label"; value: string }
+  | { type: "index"; value: number };
+
+export type PathMatchResult =
+  | undefined
+  | {
+      item: NavigationItem;
+      parentItems: NavigationItem[];
+      index: number;
+      isRoot?: false;
+    }
+  | { parentItems: NavigationItem[]; isRoot: true };
+
+const parseSegment = (segment: string): PathSegment => {
+  if (/^-?\d+$/.test(segment)) return { type: "index", value: Number(segment) };
+  return { type: "label", value: segment };
+};
+
+const splitPathSegments = (path: string): string[] =>
+  path.split("/").filter(Boolean);
+
+const matchesSegment = (
+  segment: PathSegment,
+  item: NavigationItem,
+  index: number,
+  length: number,
+): boolean => {
+  switch (segment.type) {
+    case "index": {
+      const normalized =
+        segment.value < 0 ? length + segment.value : segment.value;
+      return normalized === index;
+    }
+    case "label":
+      return item.label?.toLowerCase() === segment.value.toLowerCase();
+  }
+};
+
+export const findByPath = (
+  navigation: NavigationItem[],
+  pathString: string,
+): PathMatchResult => {
+  if (!pathString) return undefined;
+
+  // Special case: "/" matches the root level for sorting/manipulation
+  if (pathString === "/") {
+    return { parentItems: navigation, isRoot: true };
+  }
+
+  const segments = splitPathSegments(pathString).map(parseSegment);
+  if (segments.length === 0) return undefined;
+
+  let currentItems = navigation;
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (!segment) return undefined;
+
+    const foundIndex = currentItems.findIndex((item, idx) =>
+      matchesSegment(segment, item, idx, currentItems.length),
+    );
+
+    if (foundIndex === -1) return undefined;
+    const item = currentItems[foundIndex];
+    if (!item) return undefined;
+
+    if (i === segments.length - 1) {
+      return {
+        item,
+        parentItems: currentItems,
+        index: foundIndex,
+      };
+    }
+
+    if (item.type !== "category") return undefined;
+    currentItems = item.items;
+  }
+};

package/src/lib/oas/graphql/circular.ts

@@ -0,0 +1,69 @@
+import { GraphQLJSON } from "graphql-type-json";
+import { GraphQLScalarType } from "graphql/index.js";
+import { CIRCULAR_REF, SCHEMA_REF_PREFIX } from "./constants.js";
+
+const OPENAPI_PROPS = new Set([
+  "properties",
+  "items",
+  "additionalProperties",
+  "allOf",
+  "anyOf",
+  "oneOf",
+]);
+
+export const handleCircularRefs = (
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
+  obj: any,
+  currentPath = new WeakSet(),
+  refs = new WeakMap(),
+  path: string[] = [],
+  currentRefPaths = new Set<string>(),
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
+): any => {
+  if (obj === null || typeof obj !== "object") return obj;
+
+  const refPath = obj.__$ref;
+  const isCircular =
+    currentPath.has(obj) ||
+    (typeof refPath === "string" && currentRefPaths.has(refPath));
+
+  if (isCircular) {
+    if (typeof refPath === "string") return SCHEMA_REF_PREFIX + refPath;
+    const circularProp = path.find((p) => !OPENAPI_PROPS.has(p)) || path[0];
+    return [CIRCULAR_REF, circularProp].filter(Boolean).join(":");
+  }
+
+  if (refs.has(obj)) return refs.get(obj);
+
+  currentPath.add(obj);
+  if (typeof refPath === "string") currentRefPaths.add(refPath);
+
+  const recurse = (value: unknown, key: string) =>
+    handleCircularRefs(
+      value,
+      currentPath,
+      refs,
+      [...path, key],
+      currentRefPaths,
+    );
+
+  const result = Array.isArray(obj)
+    ? obj.map((item, i) => recurse(item, i.toString()))
+    : Object.fromEntries(
+        Object.entries(obj).map(([k, v]) => [k, recurse(v, k)]),
+      );
+
+  refs.set(obj, result);
+  currentPath.delete(obj);
+  if (typeof refPath === "string") currentRefPaths.delete(refPath);
+
+  return result;
+};
+
+export const GraphQLJSONSchema = new GraphQLScalarType({
+  ...GraphQLJSON,
+  name: "JSONSchema",
+  description: "OpenAPI schema scalar type that handles circular references",
+  serialize: (value: unknown) =>
+    GraphQLJSON.serialize(handleCircularRefs(value)),
+});

package/src/lib/oas/graphql/constants.ts

@@ -0,0 +1,2 @@
+export const CIRCULAR_REF = "$[Circular Reference]";
+export const SCHEMA_REF_PREFIX = "$ref:";