@lukoweb/apitogo 0.2.31 → 0.2.35

package/src/app/main.tsx

@@ -1,167 +1,175 @@
-import { Apitogo } from "@lukoweb/apitogo/components";
-import { Outlet } from "@lukoweb/apitogo/router";
-import type { RouteObject } from "react-router";
-import type { HighlighterCore } from "shiki";
-import { configuredApiKeysPlugin } from "virtual:zudoku-api-keys-plugin";
-import {
-  configuredApiCatalogPlugins,
-  configuredApiPlugins,
-} from "virtual:zudoku-api-plugins";
-import { configuredAuthProvider } from "virtual:zudoku-auth";
-import { configuredCustomPagesPlugin } from "virtual:zudoku-custom-pages-plugin";
-import { configuredDocsPlugin } from "virtual:zudoku-docs-plugin";
-import {
-  configuredModulesPlugins,
-  configuredModulesSlots,
-} from "virtual:zudoku-modules-plugin";
-import "virtual:zudoku-theme.css";
-import {
-  configuredHeaderNavigation,
-  configuredNavigation,
-  configuredNavigationRules,
-} from "virtual:zudoku-navigation";
-import { configuredSearchPlugin } from "virtual:zudoku-search-plugin";
-import type { ApitogoConfig } from "../config/config.js";
-import {
-  resolveModulesConfig,
-  getEffectiveRedirects,
-} from "../config/resolve-modules.js";
-import { BuildCheck } from "../lib/components/BuildCheck.js";
-import "./main.css";
-import { Meta } from "../lib/components/Meta.js";
-import "./polyfills.js";
-import { StatusPage } from "../lib/components/StatusPage.js";
-import { isNavigationPlugin } from "../lib/core/plugins.js";
-import { RouteGuard } from "../lib/core/RouteGuard.js";
-import type { ZudokuContextOptions } from "../lib/core/ZudokuContext.js";
-import { RouterError } from "../lib/errors/RouterError.js";
-import { ZuploEnv } from "./env.js";
-import { processRoutes } from "./processRoutes.js";
-import { createRedirectRoutes } from "./utils/createRedirectRoutes.js";
-
-export const shikiReady: Promise<HighlighterCore> =
-  import("../lib/shiki.js").then(async ({ highlighterPromise }) => {
-    const highlighter = await highlighterPromise;
-    const { registerShiki } = await import("virtual:zudoku-shiki-register");
-    await registerShiki(highlighter);
-    return highlighter;
-  });
-
-export const convertApitogoConfigToOptions = (
-  config: ApitogoConfig,
-): ZudokuContextOptions => {
-  const siteTitle =
-    config.metadata?.applicationName ?? config.site?.title ?? "API ToGo";
-
-  return {
-    basePath: config.basePath,
-    canonicalUrlOrigin: config.canonicalUrlOrigin,
-    aiAssistants: config.aiAssistants,
-    protectedRoutes: config.protectedRoutes,
-    site: {
-      ...config.site,
-      showPoweredBy: ZuploEnv.buildConfig?.entitlements.devPortalZuploBranding,
-      logo: config.site?.logo,
-    },
-    slots: { ...configuredModulesSlots, ...config.slots },
-    metadata: {
-      applicationName: siteTitle,
-      defaultTitle: siteTitle,
-      title: `%s - ${siteTitle}`,
-      ...config.metadata,
-    },
-    header: {
-      navigation: configuredHeaderNavigation,
-      placements: config.header?.placements,
-    },
-    navigation: configuredNavigation,
-    navigationRules: configuredNavigationRules,
-    mdx: config.mdx,
-    plugins: [
-      ...(configuredAuthProvider ? [configuredAuthProvider] : []),
-      ...(configuredDocsPlugin ? [configuredDocsPlugin] : []),
-      ...configuredApiPlugins,
-      ...(configuredSearchPlugin ? [configuredSearchPlugin] : []),
-      ...(configuredApiKeysPlugin ? [configuredApiKeysPlugin] : []),
-      ...(configuredCustomPagesPlugin ? [configuredCustomPagesPlugin] : []),
-      ...configuredModulesPlugins,
-      ...configuredApiCatalogPlugins,
-      ...(config.plugins ?? []),
-    ],
-    syntaxHighlighting: {
-      highlighterPromise: shikiReady,
-      themes: config.syntaxHighlighting?.themes,
-    },
-  };
-};
-
-/**
- * @deprecated Use {@link convertApitogoConfigToOptions} instead.
- */
-export const convertZudokuConfigToOptions = convertApitogoConfigToOptions;
-
-export const getRoutesByOptions = (
-  options: ZudokuContextOptions,
-  enableStatusPages = true,
-) => {
-  const allPlugins = [
-    ...(options.plugins ?? []),
-    ...(options.authentication ? [options.authentication] : []),
-  ];
-
-  const routes = allPlugins
-    .flatMap((plugin) => (isNavigationPlugin(plugin) ? plugin.getRoutes() : []))
-    .concat(
-      enableStatusPages
-        ? [400, 404, 500].map((statusCode) => ({
-            path: `/${statusCode}`,
-            element: <StatusPage statusCode={statusCode} />,
-          }))
-        : [],
-    )
-    .concat([{ path: "*", element: <StatusPage statusCode={404} /> }])
-    .map((route) => ({
-      ...route,
-      errorElement: <RouterError className="w-full m-0" />,
-    }));
-
-  // @TODO Detect conflicts in routes and log warning
-
-  return routes;
-};
-
-export const getRoutesByConfig = (config: ApitogoConfig): RouteObject[] => {
-  const resolvedModules = resolveModulesConfig(config);
-  const options = convertApitogoConfigToOptions(config);
-  const routes = getRoutesByOptions(
-    options,
-    import.meta.env.IS_ZUPLO || config.enableStatusPages,
-  );
-
-  return [
-    ...createRedirectRoutes(getEffectiveRedirects(config, resolvedModules)),
-    {
-      element: (
-        <Apitogo {...options} env={import.meta.env}>
-          <BuildCheck
-            buildId={import.meta.env.ZUPLO_BUILD_ID}
-            environmentType={import.meta.env.ZUPLO_ENVIRONMENT_TYPE}
-          />
-          <Outlet />
-        </Apitogo>
-      ),
-      hydrateFallbackElement: <div>Loading...</div>,
-      children: [
-        {
-          element: (
-            <Meta>
-              <RouteGuard />
-            </Meta>
-          ),
-          errorElement: <RouterError />,
-          children: processRoutes(routes),
-        },
-      ],
-    },
-  ];
-};
+import { Apitogo } from "@lukoweb/apitogo/components";
+import { Outlet } from "@lukoweb/apitogo/router";
+import type { RouteObject } from "react-router";
+import type { HighlighterCore } from "shiki";
+import { configuredApiKeysPlugin } from "virtual:zudoku-api-keys-plugin";
+import {
+  configuredApiCatalogPlugins,
+  configuredApiPlugins,
+} from "virtual:zudoku-api-plugins";
+import { configuredAuthProvider } from "virtual:zudoku-auth";
+import { configuredCustomPagesPlugin } from "virtual:zudoku-custom-pages-plugin";
+import { configuredDocsPlugin } from "virtual:zudoku-docs-plugin";
+import {
+  configuredModulesPlugins,
+  configuredModulesSlots,
+} from "virtual:zudoku-modules-plugin";
+import "virtual:zudoku-theme.css";
+import {
+  configuredHeaderNavigation,
+  configuredNavigation,
+  configuredNavigationRules,
+} from "virtual:zudoku-navigation";
+import { configuredSearchPlugin } from "virtual:zudoku-search-plugin";
+import type { ApitogoConfig } from "../config/config.js";
+import { getEffectiveRedirects } from "../config/effective-redirects.js";
+import type { ResolvedModulesConfig } from "../config/validators/ModulesSchema.js";
+import { BuildCheck } from "../lib/components/BuildCheck.js";
+import "./main.css";
+import { Meta } from "../lib/components/Meta.js";
+import "./polyfills.js";
+import { StatusPage } from "../lib/components/StatusPage.js";
+import { isNavigationPlugin } from "../lib/core/plugins.js";
+import { RouteGuard } from "../lib/core/RouteGuard.js";
+import type { ZudokuContextOptions } from "../lib/core/ZudokuContext.js";
+import { RouterError } from "../lib/errors/RouterError.js";
+import { ZuploEnv } from "./env.js";
+import { processRoutes } from "./processRoutes.js";
+import { createRedirectRoutes } from "./utils/createRedirectRoutes.js";
+
+export const shikiReady: Promise<HighlighterCore> =
+  import("../lib/shiki.js").then(async ({ highlighterPromise }) => {
+    const highlighter = await highlighterPromise;
+    const { registerShiki } = await import("virtual:zudoku-shiki-register");
+    await registerShiki(highlighter);
+    return highlighter;
+  });
+
+export const convertApitogoConfigToOptions = (
+  config: ApitogoConfig,
+): ZudokuContextOptions => {
+  const siteTitle =
+    config.metadata?.applicationName ?? config.site?.title ?? "API ToGo";
+
+  return {
+    basePath: config.basePath,
+    canonicalUrlOrigin: config.canonicalUrlOrigin,
+    aiAssistants: config.aiAssistants,
+    protectedRoutes: config.protectedRoutes,
+    site: {
+      ...config.site,
+      showPoweredBy: ZuploEnv.buildConfig?.entitlements.devPortalZuploBranding,
+      logo: config.site?.logo,
+    },
+    slots: { ...configuredModulesSlots, ...config.slots },
+    metadata: {
+      applicationName: siteTitle,
+      defaultTitle: siteTitle,
+      title: `%s - ${siteTitle}`,
+      ...config.metadata,
+    },
+    header: {
+      navigation: configuredHeaderNavigation,
+      placements: config.header?.placements,
+    },
+    navigation: configuredNavigation,
+    navigationRules: configuredNavigationRules,
+    mdx: config.mdx,
+    plugins: [
+      ...(configuredAuthProvider ? [configuredAuthProvider] : []),
+      ...(configuredDocsPlugin ? [configuredDocsPlugin] : []),
+      ...configuredApiPlugins,
+      ...(configuredSearchPlugin ? [configuredSearchPlugin] : []),
+      ...(configuredApiKeysPlugin ? [configuredApiKeysPlugin] : []),
+      ...(configuredCustomPagesPlugin ? [configuredCustomPagesPlugin] : []),
+      ...configuredModulesPlugins,
+      ...configuredApiCatalogPlugins,
+      ...(config.plugins ?? []),
+    ],
+    syntaxHighlighting: {
+      highlighterPromise: shikiReady,
+      themes: config.syntaxHighlighting?.themes,
+    },
+  };
+};
+
+/**
+ * @deprecated Use {@link convertApitogoConfigToOptions} instead.
+ */
+export const convertZudokuConfigToOptions = convertApitogoConfigToOptions;
+
+export const getRoutesByOptions = (
+  options: ZudokuContextOptions,
+  enableStatusPages = true,
+) => {
+  const allPlugins = [
+    ...(options.plugins ?? []),
+    ...(options.authentication ? [options.authentication] : []),
+  ];
+
+  const routes = allPlugins
+    .flatMap((plugin) => (isNavigationPlugin(plugin) ? plugin.getRoutes() : []))
+    .concat(
+      enableStatusPages
+        ? [400, 404, 500].map((statusCode) => ({
+            path: `/${statusCode}`,
+            element: <StatusPage statusCode={statusCode} />,
+          }))
+        : [],
+    )
+    .concat([{ path: "*", element: <StatusPage statusCode={404} /> }])
+    .map((route) => ({
+      ...route,
+      errorElement: <RouterError className="w-full m-0" />,
+    }));
+
+  // @TODO Detect conflicts in routes and log warning
+
+  return routes;
+};
+
+/**
+ * How the entry gets the resolved modules of a config. The server and the demo parse them from the config
+ * (`resolveModulesConfig`, which needs zod); the browser takes what the build already resolved, so the schema
+ * is not in the browser bundle.
+ */
+export type ModulesResolver = (config: ApitogoConfig) => ResolvedModulesConfig;
+
+export const getRoutesByConfig = (
+  config: ApitogoConfig,
+  resolveModules: ModulesResolver,
+): RouteObject[] => {
+  const resolvedModules = resolveModules(config);
+  const options = convertApitogoConfigToOptions(config);
+  const routes = getRoutesByOptions(
+    options,
+    import.meta.env.IS_ZUPLO || config.enableStatusPages,
+  );
+
+  return [
+    ...createRedirectRoutes(getEffectiveRedirects(config, resolvedModules)),
+    {
+      element: (
+        <Apitogo {...options} env={import.meta.env}>
+          <BuildCheck
+            buildId={import.meta.env.ZUPLO_BUILD_ID}
+            environmentType={import.meta.env.ZUPLO_ENVIRONMENT_TYPE}
+          />
+          <Outlet />
+        </Apitogo>
+      ),
+      hydrateFallbackElement: <div>Loading...</div>,
+      children: [
+        {
+          element: (
+            <Meta>
+              <RouteGuard />
+            </Meta>
+          ),
+          errorElement: <RouterError />,
+          children: processRoutes(routes),
+        },
+      ],
+    },
+  ];
+};

package/src/app/standalone.tsx

@@ -1,60 +1,61 @@
-import { createRoot } from "react-dom/client";
-import { createBrowserRouter } from "react-router";
-import type { ZudokuConfig } from "../config/validators/ZudokuConfig.js";
-import { Bootstrap } from "../lib/components/Bootstrap.js";
-import { openApiPlugin } from "../lib/plugins/openapi/index.js";
-import "../lib/util/logInit.js";
-import "./main.css";
-import { getRoutesByConfig } from "./main.js";
-
-const root = document.querySelector("div[data-api-url]");
-if (!root) {
-  throw new Error("No div found with attribute data-api-url");
-}
-
-const apiUrl = root.getAttribute("data-api-url");
-
-if (!apiUrl) {
-  throw new Error("No api url found");
-}
-
-const title = document.getElementsByTagName("title")[0]?.innerText;
-const logoUrl = root.getAttribute("data-logo-url");
-
-// IMPORTANT: This component must not contain tailwind classes
-// This directory is not processed by the tailwind plugin
-
-const config = {
-  site: {
-    logo: logoUrl
-      ? {
-          src: {
-            light: logoUrl,
-            dark: logoUrl,
-          },
-        }
-      : undefined,
-    title,
-  },
-  navigation: [
-    {
-      type: "link",
-      label: "API Reference",
-      to: "/",
-    },
-  ],
-  plugins: [
-    // Using the plugin directly because there's no config file to load in the virtual plugins
-    openApiPlugin({
-      type: "url",
-      input: apiUrl,
-      path: "/",
-    }),
-  ],
-} satisfies ZudokuConfig;
-
-const routes = getRoutesByConfig(config);
-const router = createBrowserRouter(routes, {
-  basename: window.location.pathname,
-});
-createRoot(root).render(<Bootstrap router={router} />);
+import { createRoot } from "react-dom/client";
+import { createBrowserRouter } from "react-router";
+import { resolveModulesConfig } from "../config/resolve-modules.js";
+import type { ZudokuConfig } from "../config/validators/ZudokuConfig.js";
+import { Bootstrap } from "../lib/components/Bootstrap.js";
+import "../lib/util/logInit.js";
+import "./main.css";
+import { openApiPlugin } from "../lib/plugins/openapi/index.js";
+import { getRoutesByConfig } from "./main.js";
+
+const root = document.querySelector("div[data-api-url]");
+if (!root) {
+  throw new Error("No div found with attribute data-api-url");
+}
+
+const apiUrl = root.getAttribute("data-api-url");
+
+if (!apiUrl) {
+  throw new Error("No api url found");
+}
+
+const title = document.getElementsByTagName("title")[0]?.innerText;
+const logoUrl = root.getAttribute("data-logo-url");
+
+// IMPORTANT: This component must not contain tailwind classes
+// This directory is not processed by the tailwind plugin
+
+const config = {
+  site: {
+    logo: logoUrl
+      ? {
+          src: {
+            light: logoUrl,
+            dark: logoUrl,
+          },
+        }
+      : undefined,
+    title,
+  },
+  navigation: [
+    {
+      type: "link",
+      label: "API Reference",
+      to: "/",
+    },
+  ],
+  plugins: [
+    // Using the plugin directly because there's no config file to load in the virtual plugins
+    openApiPlugin({
+      type: "url",
+      input: apiUrl,
+      path: "/",
+    }),
+  ],
+} satisfies ZudokuConfig;
+
+const routes = getRoutesByConfig(config, resolveModulesConfig);
+const router = createBrowserRouter(routes, {
+  basename: window.location.pathname,
+});
+createRoot(root).render(<Bootstrap router={router} />);

package/src/config/effective-redirects.ts

@@ -0,0 +1,31 @@
+import type { ResolvedModulesConfig } from "./validators/ModulesSchema.js";
+import type { ZudokuConfig } from "./validators/ZudokuConfig.js";
+
+/**
+ * The redirects of the config without the one that would shadow the landing page. Lives apart from
+ * `resolve-modules.ts` because the browser entry needs it and must not pull in the module schema (zod).
+ */
+export const getEffectiveRedirects = (
+  config: ZudokuConfig,
+  resolved: ResolvedModulesConfig,
+) => {
+  const redirects = config.redirects ?? [];
+
+  if (!resolved.landing.enabled) {
+    return redirects;
+  }
+
+  const landingPath = normalizePath(resolved.landing.path);
+
+  return redirects.filter(
+    (redirect) => normalizePath(redirect.from) !== landingPath,
+  );
+};
+
+const normalizePath = (path: string) => {
+  if (path === "/") {
+    return "/";
+  }
+
+  return path.replace(/\/+$/, "") || "/";
+};

package/src/config/header-navigation-guard.ts

@@ -0,0 +1,13 @@
+import type {
+  HeaderNavGroup,
+  HeaderNavItem,
+  HeaderNavLinkItem,
+} from "./validators/HeaderNavigationSchema.js";
+
+/**
+ * Lives apart from `HeaderNavigationSchema.ts` because the header components need it in the browser, and that file
+ * holds the schema (zod) and the list of every icon name.
+ */
+export const isHeaderNavGroup = (
+  item: HeaderNavItem | HeaderNavLinkItem | HeaderNavGroup,
+): item is HeaderNavGroup => "items" in item;