zudoku 0.0.0-eb4182d → 0.0.0-eeace45

package/src/lib/components/navigation/utils.ts

@@ -1,10 +1,10 @@
-import { useLocation } from "react-router-dom";
+import { useLocation } from "react-router";
 import type {
   SidebarItem,
   SidebarItemCategory,
 } from "../../../config/validators/SidebarSchema.js";
 import { joinPath } from "../../util/joinPath.js";
-import { useTopNavigationItem, useZudoku } from "../context/ZudokuContext.js";
+import { useCurrentNavigation } from "../context/ZudokuContext.js";
 
 export type TraverseCallback<T> = (
   item: SidebarItem,
@@ -42,15 +42,12 @@ export const traverseSidebarItem = <T>(
 
 export const useCurrentItem = () => {
   const location = useLocation();
-  const topNavItem = useTopNavigationItem();
-  const { sidebars } = useZudoku();
-  const currentSidebar = topNavItem?.id ? sidebars[topNavItem.id] : [];
+  const nav = useCurrentNavigation();
+
+  const currentSidebar = nav.sidebar;
 
   return traverseSidebar(currentSidebar, (item) => {
-    if (
-      item.type === "doc" &&
-      joinPath(topNavItem?.id, item.id) === location.pathname
-    ) {
+    if (item.type === "doc" && joinPath(item.id) === location.pathname) {
       return item;
     }
   });
@@ -58,18 +55,17 @@ export const useCurrentItem = () => {
 
 export const useIsCategoryOpen = (category: SidebarItemCategory) => {
   const location = useLocation();
-  const topNavItem = useTopNavigationItem();
 
   return traverseSidebarItem(category, (item) => {
     if (item.type === "category" && item.link) {
-      const categoryLinkPath = joinPath(topNavItem?.id, item.link.id);
+      const categoryLinkPath = joinPath(item.link.id);
       if (categoryLinkPath === location.pathname) {
         return true;
       }
     }
 
     if (item.type === "doc") {
-      const docPath = joinPath(topNavItem?.id, item.id);
+      const docPath = joinPath(item.id);
       if (docPath === location.pathname) {
         return true;
       }
@@ -82,9 +78,8 @@ export const usePrevNext = (): {
   next?: { label: string; id: string };
 } => {
   const currentId = useLocation().pathname;
-  const { sidebars } = useZudoku();
-  const topNavItem = useTopNavigationItem();
-  const currentSidebar = topNavItem?.id ? sidebars[topNavItem.id] : [];
+  const nav = useCurrentNavigation();
+  const currentSidebar = nav.sidebar;
 
   let prev;
   let next;
@@ -94,9 +89,9 @@ export const usePrevNext = (): {
   traverseSidebar(currentSidebar, (item) => {
     const itemId =
       item.type === "doc"
-        ? joinPath(topNavItem?.id, item.id)
+        ? joinPath(item.id)
         : item.type === "category" && item.link
-          ? joinPath(topNavItem?.id, item.link.id)
+          ? joinPath(item.link.id)
           : undefined;
 
     if (!itemId) return;

package/src/lib/core/{DevPortalContext.ts → ZudokuContext.ts}

@@ -1,5 +1,5 @@
-import { QueryClient } from "@tanstack/react-query";
 import { ReactNode } from "react";
+import { TopNavigationItem } from "../../config/validators/common.js";
 import type { SidebarConfig } from "../../config/validators/SidebarSchema.js";
 import { type AuthenticationProvider } from "../authentication/authentication.js";
 import type { ComponentsContextType } from "../components/context/ComponentsContext.js";
@@ -7,11 +7,11 @@ import { Slotlets } from "../components/SlotletProvider.js";
 import { joinPath } from "../util/joinPath.js";
 import type { MdxComponentsType } from "../util/MdxComponents.js";
 import {
-  type DevPortalPlugin,
   isApiIdentityPlugin,
   isNavigationPlugin,
   type NavigationPlugin,
   needsInitialization,
+  type ZudokuPlugin,
 } from "./plugins.js";
 
 export interface ApiIdentity {
@@ -20,10 +20,7 @@ export interface ApiIdentity {
   id: string;
 }
 
-export const queryClient = new QueryClient();
-
 export type ApiKeyCache = "api-keys";
-export type DevPortalCacheKey = ApiKeyCache | string;
 
 type Metadata = Partial<{
   title: string;
@@ -51,7 +48,7 @@ type Page = Partial<{
   };
   banner?: {
     message: ReactNode;
-    color?: "note" | "tip" | "info" | "caution" | "danger";
+    color?: "note" | "tip" | "info" | "caution" | "danger" | (string & {});
     dismissible?: boolean;
   };
 }>;
@@ -60,9 +57,9 @@ export type ZudokuContextOptions = {
   metadata?: Metadata;
   page?: Page;
   authentication?: AuthenticationProvider;
-  topNavigation?: Array<{ id: string; label: string; default?: string }>;
+  topNavigation?: TopNavigationItem[];
   sidebars?: SidebarConfig;
-  plugins?: DevPortalPlugin[];
+  plugins?: ZudokuPlugin[];
   slotlets?: Slotlets;
   mdx?: {
     components?: MdxComponentsType;
@@ -70,9 +67,9 @@ export type ZudokuContextOptions = {
   overrides?: ComponentsContextType;
 };
 
-export class DevPortalContext {
+export class ZudokuContext {
   public plugins: NonNullable<ZudokuContextOptions["plugins"]>;
-  public sidebars: NonNullable<ZudokuContextOptions["sidebars"]>;
+  public sidebars: SidebarConfig;
   public topNavigation: NonNullable<ZudokuContextOptions["topNavigation"]>;
   public meta: ZudokuContextOptions["metadata"];
   public page: ZudokuContextOptions["page"];
@@ -97,10 +94,6 @@ export class DevPortalContext {
     );
   };
 
-  invalidateCache = async (key: DevPortalCacheKey[]) => {
-    await queryClient.invalidateQueries({ queryKey: key });
-  };
-
   getApiIdentities = async () => {
     const keys = await Promise.all(
       this.plugins

package/src/lib/core/plugins.ts

@@ -1,23 +1,26 @@
+import type { LucideIcon } from "lucide-react";
 import { type ReactElement } from "react";
-import { type RouteObject } from "react-router-dom";
+import { type RouteObject } from "react-router";
 import type { Sidebar } from "../../config/validators/SidebarSchema.js";
 import { MdxComponentsType } from "../util/MdxComponents.js";
-import { DevPortalContext, type ApiIdentity } from "./DevPortalContext.js";
+import { ZudokuContext, type ApiIdentity } from "./ZudokuContext.js";
 
-export type DevPortalPlugin =
+export type ZudokuPlugin =
   | CommonPlugin
   | ProfileMenuPlugin
   | NavigationPlugin
   | ApiIdentityPlugin
   | SearchProviderPlugin;
 
+export type { RouteObject };
+
 export interface NavigationPlugin {
   getRoutes: () => RouteObject[];
   getSidebar?: (path: string) => Promise<Sidebar>;
 }
 
 export interface ApiIdentityPlugin {
-  getIdentities: (context: DevPortalContext) => Promise<ApiIdentity[]>;
+  getIdentities: (context: ZudokuContext) => Promise<ApiIdentity[]>;
 }
 
 export interface SearchProviderPlugin {
@@ -28,52 +31,51 @@ export interface SearchProviderPlugin {
 }
 
 export interface ProfileMenuPlugin {
-  getProfileMenuItems: (context: DevPortalContext) => ProfileNavigationItem[];
+  getProfileMenuItems: (context: ZudokuContext) => ProfileNavigationItem[];
 }
 
 export type ProfileNavigationItem = {
   label: string;
   path?: string;
+  weight?: number;
+  category?: "top" | "middle" | "bottom";
   children?: ProfileNavigationItem[];
+  icon?: LucideIcon;
 };
 
 export interface CommonPlugin {
   initialize?: (
-    context: DevPortalContext,
+    context: ZudokuContext,
   ) => Promise<void | boolean> | void | boolean;
   getHead?: () => ReactElement | undefined;
   getMdxComponents?: () => MdxComponentsType;
 }
 
 export const isProfileMenuPlugin = (
-  obj: DevPortalPlugin,
+  obj: ZudokuPlugin,
 ): obj is ProfileMenuPlugin =>
   "getProfileMenuItems" in obj && typeof obj.getProfileMenuItems === "function";
 
 export const isNavigationPlugin = (
-  obj: DevPortalPlugin,
+  obj: ZudokuPlugin,
 ): obj is NavigationPlugin =>
   "getRoutes" in obj && typeof obj.getRoutes === "function";
 
 export const isSearchPlugin = (
-  obj: DevPortalPlugin,
+  obj: ZudokuPlugin,
 ): obj is SearchProviderPlugin =>
   "renderSearch" in obj && typeof obj.renderSearch === "function";
 
-export const needsInitialization = (
-  obj: DevPortalPlugin,
-): obj is CommonPlugin =>
+export const needsInitialization = (obj: ZudokuPlugin): obj is CommonPlugin =>
   "initialize" in obj && typeof obj.initialize === "function";
 
-export const hasHead = (obj: DevPortalPlugin): obj is CommonPlugin =>
+export const hasHead = (obj: ZudokuPlugin): obj is CommonPlugin =>
   "getHead" in obj && typeof obj.getHead === "function";
 
-export const isMdxProviderPlugin = (
-  obj: DevPortalPlugin,
-): obj is CommonPlugin =>
+export const isMdxProviderPlugin = (obj: ZudokuPlugin): obj is CommonPlugin =>
   "getMdxComponents" in obj && typeof obj.getMdxComponents === "function";
 
 export const isApiIdentityPlugin = (
-  obj: DevPortalPlugin,
+  obj: ZudokuPlugin,
 ): obj is ApiIdentityPlugin =>
   "getIdentities" in obj && typeof obj.getIdentities === "function";

package/src/lib/errors/ErrorAlert.tsx

@@ -1,16 +1,30 @@
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function ErrorAlert({ error }: { error: any }) {
-  const message = error?.message ?? "Something went wrong";
-  const stack = error?.stack;
+import { DeveloperHint } from "../components/DeveloperHint.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;
 
   return (
-    <div className="flex h-screen max-h-screen min-h-full items-center justify-center bg-primary-background px-4 py-16 lg:px-8">
+    <div className="flex h-screen max-h-[calc(100vh-var(--header-height))] min-h-full items-center justify-center bg-primary-background px-4 py-16 lg:px-8">
       <div className="mx-auto max-w-[85%] sm:max-w-[50%]">
         <h1 className="text-4xl font-bold tracking-tight text-h1-text sm:text-5xl">
-          Something went wrong
+          {title}
         </h1>
         <p className="mt-5 text-h1-text">{message}</p>
-        {stack ? (
+        {hint && <DeveloperHint className="mb-4">{hint}</DeveloperHint>}
+        {cause instanceof Error ? (
+          <pre className="mt-5 max-h-[400px] w-full overflow-scroll rounded-md border border-input-border bg-input-background p-3 text-property-name-text text-red-700">
+            {cause.stack}
+          </pre>
+        ) : stack ? (
           <pre className="mt-5 max-h-[400px] w-full overflow-scroll rounded-md border border-input-border bg-input-background p-3 text-property-name-text text-red-700">
             {stack}
           </pre>

package/src/lib/errors/RouterError.tsx

@@ -1,4 +1,4 @@
-import { isRouteErrorResponse, useRouteError } from "react-router-dom";
+import { isRouteErrorResponse, useRouteError } from "react-router";
 import { NotFoundPage } from "../components/NotFoundPage.js";
 import { ErrorAlert } from "./ErrorAlert.js";
 

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

@@ -58,9 +58,10 @@ export const createOperationSlug = (
   );
 };
 
-const cache = new LRUCache<string, Promise<OpenAPIDocument>>({
+const cache = new LRUCache<string, OpenAPIDocument>({
   ttl: 60 * 10 * 1000,
   ttlAutopurge: true,
+  fetchMethod: (_key, _oldValue, { context }) => validate(context as string),
 });
 
 const builder = new SchemaBuilder<{
@@ -205,7 +206,7 @@ const ExampleItem = builder
       name: t.exposeString("name"),
       summary: t.exposeString("summary", { nullable: true }),
       description: t.exposeString("description", { nullable: true }),
-      value: t.exposeString("value", { nullable: true }),
+      value: t.expose("value", { type: JSONScalar, nullable: true }),
       externalValue: t.exposeString("externalValue", { nullable: true }),
     }),
   });
@@ -347,10 +348,10 @@ const OperationItem = builder
               statusCode,
               description: response.description,
               content: Object.entries(response.content ?? {}).map(
-                ([mediaType, mediaTypeObject]) => ({
+                ([mediaType, { schema, examples }]) => ({
                   mediaType,
-                  schema: mediaTypeObject.schema,
-                  examples: Object.entries(mediaTypeObject.examples ?? {}).map(
+                  schema,
+                  examples: Object.entries(examples ?? {}).map(
                     ([name, value]) => ({ name, ...value }),
                   ),
                 }),
@@ -389,6 +390,10 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
       resolve: (root) => root.info.description,
       nullable: true,
     }),
+    summary: t.string({
+      resolve: (root) => root.info.summary,
+      nullable: true,
+    }),
     paths: t.field({
       type: [PathItem],
       resolve: (root) =>
@@ -429,16 +434,7 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
 
 const loadOpenAPISchema = async (input: NonNullable<unknown>) => {
   const hash = hashit(input);
-
-  if (cache.has(hash)) {
-    return cache.get(hash)!;
-  }
-
-  const schema = validate(input);
-
-  cache.set(hash, schema);
-
-  return schema;
+  return await cache.forceFetch(hash, { context: input });
 };
 
 const SchemaSource = builder.enumType("SchemaType", {
@@ -447,7 +443,6 @@ const SchemaSource = builder.enumType("SchemaType", {
 
 builder.queryType({
   fields: (t) => ({
-    // https://tan-cow-main-bce8a06.d2.zuplo.dev/openapi
     schema: t.field({
       type: Schema,
       args: {

package/src/lib/oas/parser/upgrade/index.ts

@@ -1,4 +1,5 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import { type RecordAny, traverse } from "../../../util/traverse.js";
 import type { OpenAPIDocument } from "../index.js";
 /**
  * Upgrade from OpenAPI 3.0.x to 3.1.0
@@ -6,30 +7,8 @@ import type { OpenAPIDocument } from "../index.js";
  * Taken from https://github.com/scalar/openapi-parser/blob/main/packages/openapi-parser/src/utils/upgradeFromThreeToThreeOne.ts
  * https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
  */
-export function traverse(
-  specification: Record<string, any>,
-  transform: (specification: Record<string, any>) => Record<string, any>,
-) {
-  const result: Record<string, any> = {};
 
-  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)
-          : item,
-      );
-    } else if (typeof value === "object" && value !== null) {
-      result[key] = traverse(value, transform);
-    } else {
-      result[key] = value;
-    }
-  }
-
-  return transform(result);
-}
-
-export const upgradeSchema = (schema: Record<string, any>): OpenAPIDocument => {
+export const upgradeSchema = (schema: RecordAny): OpenAPIDocument => {
   if (schema.openapi?.startsWith("3.0")) {
     schema.openapi = "3.1.0";
   }
@@ -75,7 +54,7 @@ export const upgradeSchema = (schema: Record<string, any>): OpenAPIDocument => {
   schema = traverse(schema, (sub) => {
     if (sub.type === "object" && sub.properties !== undefined) {
       for (const [, value] of Object.entries(sub.properties)) {
-        const v = (value ?? {}) as Record<string, any>;
+        const v = (value ?? {}) as RecordAny;
         if (v.type === "string" && v.format === "binary") {
           v.contentEncoding = "application/octet-stream";
           delete v.format;

package/src/lib/plugins/api-catalog/Catalog.tsx

@@ -0,0 +1,123 @@
+import slugify from "@sindresorhus/slugify";
+import { useSuspenseQuery } from "@tanstack/react-query";
+import { useSearchParams } from "react-router";
+import { Head, Link } from "zudoku/components";
+import { useAuthState } from "../../authentication/state.js";
+import { Markdown } from "../../components/Markdown.js";
+import { cn } from "../../util/cn.js";
+import type { ApiCatalogPluginOptions } from "./index.js";
+
+const getKey = (category: string, tag: string) => slugify(`${category}-${tag}`);
+
+export const Catalog = ({
+  items,
+  filterCatalogItems = (items) => items,
+  categories,
+  label = "API Library",
+}: Omit<ApiCatalogPluginOptions, "navigationId">) => {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const activeCategory = searchParams.get("category");
+  const auth = useAuthState();
+
+  const catalogItems = useSuspenseQuery({
+    queryFn: () => filterCatalogItems(items, { auth }),
+    queryKey: ["catalogItems", auth],
+  });
+
+  return (
+    <section className="pt-[--padding-content-top] pb-[--padding-content-bottom]">
+      <Head>
+        <title>{label}</title>
+      </Head>
+      <div className="grid grid-cols-12 gap-12">
+        <div className="flex flex-col gap-4 col-span-3 not-prose sticky top-48">
+          <div className="max-w-[--side-nav-width] flex flex-col gap-4 justify-between">
+            {categories?.map((category, idx) => (
+              <div key={category.label}>
+                <div className="flex justify-between mb-2.5">
+                  <span className="font-medium text-sm">{category.label}</span>
+                  {idx === 0 && activeCategory && (
+                    <button
+                      type="button"
+                      className="text-end text-sm text-foreground/60 hover:text-foreground"
+                      onClick={() => setSearchParams({})}
+                    >
+                      Clear
+                    </button>
+                  )}
+                </div>
+                <ul className="space-y-1 [&>li]:py-2">
+                  {category.tags
+                    .map((tag) => ({
+                      tag,
+                      count: items.filter((api) =>
+                        api.categories.find((c) => c.tags.includes(tag)),
+                      ).length,
+                    }))
+                    .map(({ tag, count }) => {
+                      const slug = getKey(category.label, tag);
+                      const isActive = slug === activeCategory;
+
+                      return (
+                        <li
+                          key={slug}
+                          className={cn(
+                            "flex rounded-lg justify-between text-sm cursor-pointer hover:text-primary transition px-[--padding-nav-item] -mx-[--padding-nav-item]",
+                            isActive && "bg-border/30 rounded",
+                          )}
+                          onClick={() => setSearchParams({ category: slug })}
+                        >
+                          <span>{tag}</span>
+                          <span
+                            className={cn(
+                              "flex items-center justify-center border rounded-md w-8 text-xs font-semibold",
+                              isActive &&
+                                "bg-primary border-primary text-primary-foreground",
+                            )}
+                          >
+                            {count}
+                          </span>
+                        </li>
+                      );
+                    })}
+                </ul>
+              </div>
+            ))}
+          </div>
+        </div>
+        <div className="col-span-9">
+          <h3 className="mt-0 text-2xl font-bold mb-4">{label}</h3>
+
+          <div className="grid grid-cols-2 gap-4">
+            {catalogItems.data
+              .filter(
+                (api) =>
+                  !activeCategory ||
+                  api.categories.find((c) =>
+                    c.tags.find((t) => getKey(c.label, t) === activeCategory),
+                  ),
+              )
+              .map((api) => (
+                <Link
+                  to={{
+                    pathname: `/${api.path}`,
+                    search: activeCategory ? `category=${activeCategory}` : "",
+                  }}
+                  className="no-underline hover:!text-foreground"
+                  key={api.path}
+                >
+                  <div className="border h-full rounded p-4 flex flex-col gap-2 cursor-pointer hover:bg-border/20 font-normal">
+                    <span className="font-semibold">{api.label}</span>
+                    <Markdown
+                      className="text-sm whitespace-pre-wrap mb-6 line-clamp-2"
+                      content={api.description}
+                    />
+                  </div>
+                </Link>
+              ))}
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+};

package/src/lib/plugins/api-catalog/index.tsx

@@ -0,0 +1,64 @@
+import type { AuthState } from "../../authentication/state.js";
+import type { ZudokuPlugin } from "../../core/plugins.js";
+import { Catalog } from "./Catalog.js";
+
+export type ApiCatalogItem = {
+  path: string;
+  label: string;
+  description: string;
+  categories: CatalogCategory[];
+};
+
+export type CatalogCategory = {
+  label: string;
+  tags: string[];
+};
+
+export type ApiCatalogPluginOptions = {
+  navigationId: string;
+  label: string;
+  categories?: CatalogCategory[];
+  items: ApiCatalogItem[];
+  filterCatalogItems?: filterCatalogItems;
+};
+
+export type CatalogContext<ProviderData = unknown> = {
+  auth: AuthState<ProviderData>;
+};
+
+export type filterCatalogItems<ProviderData = unknown> = (
+  items: ApiCatalogItem[],
+  { auth }: CatalogContext<ProviderData>,
+) => ApiCatalogItem[];
+
+export const apiCatalogPlugin = ({
+  navigationId,
+  items,
+  label,
+  categories,
+  filterCatalogItems,
+}: {
+  navigationId: string;
+  label: string;
+  categories?: CatalogCategory[];
+  items: ApiCatalogItem[];
+  filterCatalogItems?: filterCatalogItems;
+}): ZudokuPlugin => {
+  return {
+    getRoutes: () => {
+      return [
+        {
+          path: navigationId,
+          element: (
+            <Catalog
+              label={label}
+              items={items}
+              filterCatalogItems={filterCatalogItems}
+              categories={categories ?? []}
+            />
+          ),
+        },
+      ];
+    },
+  };
+};

package/src/lib/plugins/api-keys/CreateApiKey.tsx

@@ -1,7 +1,6 @@
 import { useMutation } from "@tanstack/react-query";
 import { useForm } from "react-hook-form";
-import { Link, useNavigate } from "react-router-dom";
-import { useZudoku } from "../../components/context/ZudokuContext.js";
+import { Link, useNavigate } from "react-router";
 import {
   Select,
   SelectContent,
@@ -9,7 +8,8 @@ import {
   SelectItem,
   SelectTrigger,
   SelectValue,
-} from "../../components/Select.js";
+} from "zudoku/ui/Select.js";
+import { useZudoku } from "../../components/context/ZudokuContext.js";
 import { Button } from "../../ui/Button.js";
 import { Input } from "../../ui/Input.js";
 import { ApiKeyService } from "./index.js";

package/src/lib/plugins/api-keys/ProtectedRoute.tsx

@@ -1,4 +1,4 @@
-import { Outlet } from "react-router-dom";
+import { Outlet } from "react-router";
 import { useAuth } from "../../authentication/hook.js";
 import { DeveloperHint } from "../../components/DeveloperHint.js";
 import { Button } from "../../ui/Button.js";

package/src/lib/plugins/api-keys/SettingsApiKeys.tsx

@@ -12,7 +12,7 @@ import {
   TrashIcon,
 } from "lucide-react";
 import { useState } from "react";
-import { Link } from "react-router-dom";
+import { Link } from "react-router";
 import { useZudoku } from "../../components/context/ZudokuContext.js";
 import { Slotlet } from "../../components/SlotletProvider.js";
 import { Button } from "../../ui/Button.js";