@mehdad67/apitogo 0.1.24

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

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

@@ -0,0 +1,70 @@
+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/NavigationItem.js";
+import { scrollIntoViewIfNeeded } from "./scrollIntoViewIfNeeded.js";
+
+export const useScrollToHash = () => {
+  const { setActiveAnchor } = useViewportAnchor();
+
+  const scrollToHash = useCallback(
+    (hash: string) => {
+      const cleanHash = hash.replace(/^#/, "");
+
+      // Operation list items might have subdivisions that the navigation doesn't show.
+      // The subdivisions are separated by a slash so we need to remove everything before the slash to get the navigation correct item.
+      const linkHash = cleanHash.split("/").at(0);
+      if (!linkHash) return false;
+
+      const element = document.getElementById(decodeURIComponent(cleanHash));
+
+      const link = document.querySelector(
+        `[${DATA_ANCHOR_ATTR}="${linkHash}"]`,
+      );
+
+      if (element) {
+        element.scrollIntoView();
+        scrollIntoViewIfNeeded(link);
+        // 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;
+};
+
+export const useScrollToAnchor = () => {
+  const location = useLocation();
+  const scrollToHash = useScrollToHash();
+  const initialScrolled = useRef(false);
+
+  useEffect(() => {
+    if (!location.hash || !initialScrolled.current) return;
+
+    scrollToHash(location.hash);
+  }, [location.hash, scrollToHash]);
+
+  useEffect(() => {
+    if (!location.hash) {
+      initialScrolled.current = true;
+      return;
+    }
+
+    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

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

package/src/types.d.ts

@@ -0,0 +1,57 @@
+declare module "virtual:zudoku-docs-plugin" {
+  export const configuredDocsPlugin:
+    | import("./lib/core/plugins.ts").ApitogoPlugin
+    | undefined;
+  /**
+   * Map of markdown files and imports
+   */
+  export const configuredMarkdownFiles: Record<string, () => Promise<unknown>>;
+}
+
+declare module "virtual:zudoku-navigation" {
+  export const configuredHeaderNavigation: import("./config/validators/HeaderNavigationSchema.ts").HeaderNavigation;
+  export const configuredNavigation: import("./config/validators/NavigationSchema.ts").Navigation;
+  export const configuredNavigationRules: import("./config/validators/NavigationSchema.ts").ResolvedNavigationRule[];
+}
+
+declare module "virtual:zudoku-api-plugins" {
+  export const configuredApiPlugins: import("./lib/core/plugins.ts").ApitogoPlugin[];
+  export const configuredApiCatalogPlugins: import("./lib/core/plugins.ts").ApitogoPlugin[];
+}
+
+declare module "virtual:zudoku-search-plugin" {
+  export const configuredSearchPlugin:
+    | import("./lib/core/plugins.ts").ApitogoPlugin
+    | undefined;
+}
+
+declare module "virtual:zudoku-api-keys-plugin" {
+  export const configuredApiKeysPlugin:
+    | import("./lib/core/plugins.ts").ApitogoPlugin
+    | undefined;
+}
+
+declare module "virtual:zudoku-modules-plugin" {
+  export const configuredModulesPlugins: import("./lib/core/plugins.ts").ApitogoPlugin[];
+}
+
+declare module "virtual:zudoku-custom-pages-plugin" {
+  export const configuredCustomPagesPlugin:
+    | import("./lib/core/plugins.ts").ApitogoPlugin
+    | undefined;
+}
+
+declare module "virtual:zudoku-config" {
+  const config: import("./config/config.ts").ZudokuConfig;
+  export default config;
+}
+declare module "virtual:zudoku-auth" {
+  export const configuredAuthProvider:
+    | import("./lib/authentication/authentication.ts").AuthenticationPlugin
+    | undefined;
+}
+
+declare module "virtual:zudoku-shiki-register" {
+  import type { HighlighterCore } from "shiki/core";
+  export const registerShiki: (highlighter: HighlighterCore) => Promise<void>;
+}

package/src/vite/api/SchemaManager.ts

@@ -0,0 +1,371 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  $RefParser,
+  type JSONSchema,
+} from "@apidevtools/json-schema-ref-parser";
+import { upgrade, validate } from "@scalar/openapi-parser";
+import { deepEqual } from "fast-equals";
+import type { LoadedConfig } from "../../config/config.js";
+import type { Processor } from "../../config/validators/BuildSchema.js";
+import type { VersionConfig } from "../../config/validators/ZudokuConfig.js";
+import type { OpenAPIDocument } from "../../lib/oas/parser/index.js";
+import { ensureArray } from "../../lib/util/ensureArray.js";
+import { flattenAllOfProcessor } from "../../lib/util/flattenAllOfProcessor.js";
+import { joinUrl } from "../../lib/util/joinUrl.js";
+import { slugify } from "../../lib/util/slugify.js";
+import { generateCode } from "./schema-codegen.js";
+
+type ProcessedSchema = {
+  schema: OpenAPIDocument;
+  version: string;
+  path: string;
+  label?: string;
+  inputPath: string;
+  params: Record<string, string>;
+  importKey: string;
+  downloadUrl: string;
+  processedJsonPath: string;
+  processedTime: number;
+};
+const FALLBACK_VERSION = "default";
+
+type InputConfig = Partial<VersionConfig> & {
+  input: string;
+  params: Record<string, string>;
+};
+
+const parseInputString = (input: string) => {
+  const idx = input.indexOf("?");
+  if (idx === -1)
+    return { filePath: input, params: {} as Record<string, string> };
+  return {
+    filePath: input.slice(0, idx),
+    params: Object.fromEntries(new URLSearchParams(input.slice(idx))),
+  };
+};
+
+const canonicalParams = (params: Record<string, string>) =>
+  Object.entries(params)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([k, v]) => `${k}=${v}`)
+    .join("&");
+
+const paramsSuffix = (params: Record<string, string>) => {
+  const canonical = canonicalParams(params);
+  return canonical ? `-${slugify(canonical)}` : "";
+};
+
+const paramsPath = (params: Record<string, string>) => {
+  const canonical = canonicalParams(params);
+  return canonical ? slugify(canonical) : "";
+};
+
+const normalizeInputs = (
+  inputs:
+    | string
+    | InputConfig
+    | Array<
+        | string
+        | (Omit<InputConfig, "params"> & { params?: Record<string, string> })
+      >,
+): InputConfig[] =>
+  ensureArray(inputs).map((i) => {
+    const raw = typeof i === "string" ? { input: i } : i;
+    const { filePath, params } = parseInputString(raw.input);
+    return { ...raw, input: filePath, params: { ...params, ...raw.params } };
+  });
+
+export class SchemaManager {
+  private storeDir: string;
+  private processors: Processor[];
+  private processedSchemas: Record<string, ProcessedSchema[]> = {};
+  private referencedBy = new Map<string, Set<string>>();
+  public config: LoadedConfig;
+
+  constructor({
+    storeDir,
+    config,
+    processors,
+  }: {
+    storeDir: string;
+    config: LoadedConfig;
+    processors: Processor[];
+  }) {
+    this.storeDir = storeDir;
+    this.config = config;
+    this.processors = [
+      ({ schema }) => upgrade(schema).specification as OpenAPIDocument,
+      flattenAllOfProcessor,
+      ...processors,
+    ];
+  }
+
+  private getPathForFile = (input: string, params: Record<string, string>) => {
+    const filePath = path.resolve(this.config.__meta.rootDir, input);
+
+    const apis = ensureArray(this.config.apis ?? []);
+    for (const apiConfig of apis) {
+      if (!apiConfig || apiConfig.type !== "file" || !apiConfig.path) continue;
+
+      const match = normalizeInputs(apiConfig.input).some(
+        (i) =>
+          path.resolve(this.config.__meta.rootDir, i.input) === filePath &&
+          deepEqual(i.params, params),
+      );
+      if (match) return apiConfig.path;
+    }
+  };
+
+  public processSchema = async (input: InputConfig) => {
+    const filePath = path.resolve(this.config.__meta.rootDir, input.input);
+    const params = input.params;
+    const configuredPath = this.getPathForFile(input.input, params);
+    if (!configuredPath) {
+      // biome-ignore lint/suspicious/noConsole: Logging allowed here
+      console.warn(`No path found for file ${input.input}`);
+      return;
+    }
+
+    const parser = new $RefParser();
+    const schema = await parser.bundle(filePath, {
+      dereference: { preservedProperties: ["description", "summary"] },
+    });
+
+    this.referencedBy.set(filePath, new Set());
+
+    parser.$refs
+      .paths()
+      .filter((file) => file !== filePath)
+      .forEach((file) => {
+        if (!this.referencedBy.has(file)) {
+          this.referencedBy.set(file, new Set());
+        }
+        this.referencedBy.get(file)?.add(filePath);
+      });
+
+    const validatedSchema = await this.validateSchema(schema, filePath);
+    const processedSchema = await this.processors.reduce(
+      async (schema, processor) =>
+        processor({
+          schema: await schema,
+          file: filePath,
+          params,
+          dereference: (schema) =>
+            new $RefParser<OpenAPIDocument>().dereference(schema, {
+              dereference: {
+                preservedProperties: ["description", "summary"],
+                circular: "ignore",
+              },
+            }),
+        }),
+      Promise.resolve(validatedSchema),
+    );
+
+    const processedTime = Date.now();
+    const code = generateCode(processedSchema, filePath);
+
+    const prefixPath = slugify(configuredPath);
+    const processedFilePath = path.posix.join(
+      this.storeDir,
+      `${prefixPath}-${path.basename(filePath)}${paramsSuffix(params)}.js`,
+    );
+    const importKey = processedFilePath;
+
+    await fs.writeFile(processedFilePath, code);
+
+    const processedJsonPath = paramsSuffix(params)
+      ? processedFilePath.replace(/\.js$/, ".json")
+      : "";
+    if (processedJsonPath) {
+      await fs.writeFile(
+        processedJsonPath,
+        JSON.stringify(processedSchema, null, 2),
+      );
+    }
+
+    const schemas = this.processedSchemas[configuredPath];
+
+    if (!schemas) {
+      throw new Error(`No schemas found for navigation ID ${configuredPath}.`);
+    }
+
+    const index = schemas.findIndex(
+      (s) => s.inputPath === filePath && deepEqual(s.params, params),
+    );
+    const existingSchema = schemas[index];
+
+    const schemaVersion = processedSchema.info.version ?? FALLBACK_VERSION;
+    const versionPath =
+      existingSchema?.path && existingSchema.path.length > 0
+        ? existingSchema.path
+        : paramsPath(params) || schemaVersion;
+
+    const processed = {
+      schema: processedSchema,
+      version: schemaVersion,
+      path: versionPath,
+      label:
+        existingSchema?.label ??
+        (Object.keys(params).length > 0
+          ? Object.values(params).join(", ")
+          : undefined),
+      inputPath: filePath,
+      params,
+      importKey,
+      downloadUrl: this.createSchemaPath(
+        filePath,
+        versionPath,
+        configuredPath,
+        params,
+      ),
+      processedJsonPath,
+      processedTime,
+    } satisfies ProcessedSchema;
+
+    if (index > -1) {
+      schemas[index] = processed;
+    } else {
+      throw new Error(
+        `Schema with input path ${filePath} was not pre-initialized for ${configuredPath}.`,
+      );
+    }
+    return processed;
+  };
+
+  public getAllTrackedFiles = () => Array.from(this.referencedBy.keys());
+
+  public getFilesToReprocess = (changedFile: string): InputConfig[] => {
+    const resolvedPath = path.resolve(this.config.__meta.rootDir, changedFile);
+    const referencedBy = this.referencedBy.get(resolvedPath);
+
+    if (!referencedBy) return [];
+
+    const filesToProcess =
+      referencedBy.size === 0 ? [resolvedPath] : Array.from(referencedBy);
+
+    return filesToProcess.flatMap((fp) => {
+      const configs: InputConfig[] = [];
+      for (const schemas of Object.values(this.processedSchemas)) {
+        for (const s of schemas) {
+          if (s.inputPath === fp) {
+            configs.push({ input: fp, params: s.params });
+          }
+        }
+      }
+      return configs.length > 0 ? configs : [{ input: fp, params: {} }];
+    });
+  };
+
+  public processAllSchemas = async () => {
+    this.referencedBy.clear();
+    this.processedSchemas = {};
+
+    const apis = ensureArray(this.config.apis ?? []);
+    for (const apiConfig of apis) {
+      if (apiConfig.type !== "file" || !apiConfig.path) continue;
+
+      const inputs = normalizeInputs(apiConfig.input);
+      if (inputs.length === 0) throw new Error("No schema found");
+
+      this.processedSchemas[apiConfig.path] = inputs.map((input) => ({
+        schema: {} as OpenAPIDocument,
+        version: "",
+        path: input.path ?? "",
+        label: input.label,
+        inputPath: path.resolve(this.config.__meta.rootDir, input.input),
+        params: input.params,
+        importKey: "",
+        downloadUrl: "",
+        processedJsonPath: "",
+        processedTime: 0,
+      }));
+
+      const results = await Promise.allSettled(
+        inputs.map((input) => this.processSchema(input)),
+      );
+
+      const errors = results.flatMap((r) =>
+        r.status === "rejected" ? r.reason : [],
+      );
+
+      if (errors.length > 0) {
+        throw new Error(
+          `Failed to process schemas for ${apiConfig.path}: ${errors.join(", ")}`,
+        );
+      }
+    }
+  };
+
+  public getLatestSchema = (path: string) => this.processedSchemas[path]?.at(0);
+
+  public getSchemasForPath = (path: string) => this.processedSchemas[path];
+
+  public getSchemaImports = () =>
+    Object.values(this.processedSchemas)
+      .flat()
+      .filter((s) => s.importKey);
+
+  public getUrlToFilePathMap = () => {
+    const map = new Map<string, string>();
+
+    const apis = ensureArray(this.config.apis ?? []);
+    for (const apiConfig of apis) {
+      if (apiConfig.type !== "file" || !apiConfig.path) continue;
+
+      const downloadEnabled =
+        apiConfig.options?.schemaDownload?.enabled ??
+        this.config.defaults?.apis?.schemaDownload?.enabled ??
+        false;
+
+      if (!downloadEnabled) continue;
+
+      const schemas = this.processedSchemas[apiConfig.path];
+
+      if (!schemas || schemas.length === 0) continue;
+
+      for (const schema of schemas) {
+        map.set(
+          schema.downloadUrl,
+          schema.processedJsonPath || schema.inputPath,
+        );
+      }
+    }
+
+    return map;
+  };
+
+  private createSchemaPath = (
+    inputPath: string,
+    versionPath: string,
+    apiPath: string,
+    params: Record<string, string>,
+  ) => {
+    const suffix = paramsSuffix(params);
+    const extension = suffix ? ".json" : path.extname(inputPath);
+
+    return joinUrl(
+      this.config.basePath,
+      apiPath,
+      versionPath,
+      `schema${suffix}${extension}`,
+    );
+  };
+
+  private validateSchema = async (
+    schema: JSONSchema,
+    filePath: string,
+  ): Promise<OpenAPIDocument> => {
+    const validated = await validate(schema);
+    if (validated.errors?.length) {
+      // biome-ignore lint/suspicious/noConsole: Logging allowed here
+      console.warn(`Schema warnings in ${filePath}:`);
+      for (const error of validated.errors) {
+        // biome-ignore lint/suspicious/noConsole: Logging allowed here
+        console.warn(error);
+      }
+    }
+
+    return schema as OpenAPIDocument;
+  };
+}