zudoku 0.93.0 → 0.93.2

package/dist/declarations/app/env.d.ts

@@ -1,30 +1,6 @@
 export declare const ZuploEnv: {
     readonly isZuplo: boolean;
     readonly serverUrl: string | undefined;
-    buildConfig: {
-        entitlements: {
-            devPortalZuploBranding: boolean;
-            numberOfProjects: number;
-            numberOfUsers: number;
-            egressGbPerMonth: number;
-            requestsPerMonth: number;
-            numberOfApiKeys: number;
-            customDomains: number;
-            advancedAnalyticsEnabled: boolean;
-            devPortalAnalyticsEnabled: boolean;
-            premiumSupport: boolean;
-            emergencyPhoneSupport: boolean;
-            rbacEnabled: boolean;
-            onPremEnabled: boolean;
-            largeBuildRunners: boolean;
-        };
-        deploymentName: string;
-        environmentType?: string | undefined;
-        deploymentUrl?: string | undefined;
-        projectId?: string | undefined;
-        projectType?: string | undefined;
-        sourceType?: string | undefined;
-        accountName?: string | undefined;
-        projectName?: string | undefined;
-    } | undefined;
+    readonly deploymentName: string | undefined;
+    readonly devPortalZuploBranding: boolean | undefined;
 };

package/dist/declarations/app/wrapProtectedRoutes.d.ts

@@ -1,9 +1,8 @@
 import type { RouteObject } from "react-router";
 import type { ProtectedRoutesInput } from "../config/validators/ProtectedRoutesSchema.js";
-export declare const wrapProtectedRoutes: (routes: RouteObject[], protectedRoutes: ProtectedRoutesInput, isAuthenticated: boolean, basePath?: string) => RouteObject[];
-export declare const wrapProtectedRoutesForRender: (routes: RouteObject[], protectedRoutes: ProtectedRoutesInput, { isAuthenticated, bypassProtection, basePath, }: {
+export declare const wrapProtectedRoutes: (routes: RouteObject[], protectedRoutes: ProtectedRoutesInput, isAuthenticated: boolean) => RouteObject[];
+export declare const wrapProtectedRoutesForRender: (routes: RouteObject[], protectedRoutes: ProtectedRoutesInput, { isAuthenticated, bypassProtection, }: {
     isAuthenticated: boolean;
     bypassProtection?: boolean;
-    basePath?: string;
 }) => RouteObject[];
-export declare const warnInlineProtectedRoutes: (routes: RouteObject[], protectedRoutes: ProtectedRoutesInput, basePath?: string) => void;
+export declare const warnInlineProtectedRoutes: (routes: RouteObject[], protectedRoutes: ProtectedRoutesInput) => void;

package/dist/declarations/lib/components/Heading.d.ts

@@ -1,7 +1,7 @@
 import { type VariantProps } from "class-variance-authority";
 import type { HTMLAttributes, ReactNode } from "react";
 declare const heading: (props?: ({
-    level?: 1 | 2 | 3 | 4 | 5 | 6 | null | undefined;
+    level?: 1 | 2 | 3 | 4 | 6 | 5 | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export type HeadingProps = HTMLAttributes<HTMLHeadingElement> & VariantProps<typeof heading> & {
     children: ReactNode;

package/dist/declarations/lib/plugins/blog/BlogComponents.d.ts

@@ -0,0 +1,18 @@
+import { type BlogAuthor, type BlogPost, type BlogTag } from "./options.js";
+export declare const BlogFeedLink: ({ feedUrl }: {
+    feedUrl?: string;
+}) => import("react").JSX.Element | null;
+export declare const formatPostDate: (date: string) => string;
+export declare const PostMeta: ({ post, showReadingTime, className, }: {
+    post: BlogPost;
+    showReadingTime: boolean;
+    className?: string;
+}) => import("react").JSX.Element;
+export declare const PostAuthors: ({ authors, compact, }: {
+    authors: BlogAuthor[];
+    compact?: boolean;
+}) => import("react").JSX.Element | null;
+export declare const PostTags: ({ tags, blogPath, }: {
+    tags: BlogTag[];
+    blogPath: string;
+}) => import("react").JSX.Element | null;

package/dist/declarations/lib/plugins/blog/BlogListPage.d.ts

@@ -0,0 +1,8 @@
+import { type BlogPageOptions, type BlogPost, type BlogTag } from "./options.js";
+export declare const BlogListPage: ({ options, posts, page, pageCount, tag, }: {
+    options: BlogPageOptions;
+    posts: BlogPost[];
+    page?: number;
+    pageCount?: number;
+    tag?: BlogTag;
+}) => import("react").JSX.Element;

package/dist/declarations/lib/plugins/blog/BlogPostPage.d.ts

@@ -0,0 +1,9 @@
+import type { MDXImport } from "../markdown/index.js";
+import type { BlogPageOptions, BlogPost } from "./options.js";
+export declare const BlogPostPage: ({ options, post, newer, older, mdxComponent: MdxComponent, frontmatter, tableOfContents, __filepath, }: Omit<MDXImport, "default" | "excerpt"> & {
+    options: BlogPageOptions;
+    post: BlogPost;
+    newer?: BlogPost;
+    older?: BlogPost;
+    mdxComponent: MDXImport["default"];
+}) => import("react").JSX.Element;

package/dist/declarations/lib/plugins/blog/BlogTagsPage.d.ts

@@ -0,0 +1,5 @@
+import { type BlogPageOptions, type BlogPost } from "./options.js";
+export declare const BlogTagsPage: ({ options, posts, }: {
+    options: BlogPageOptions;
+    posts: BlogPost[];
+}) => import("react").JSX.Element;

package/dist/declarations/lib/plugins/blog/index.d.ts

@@ -0,0 +1,4 @@
+import type { ZudokuPlugin } from "../../core/plugins.js";
+import { type BlogPluginOptions } from "./options.js";
+export type { BlogAuthor, BlogPageOptions, BlogPluginOptions, BlogPost, BlogTag, } from "./options.js";
+export declare const blogPlugin: (options?: BlogPluginOptions) => ZudokuPlugin;

package/dist/declarations/lib/plugins/blog/options.d.ts

@@ -0,0 +1,61 @@
+import type { MDXImport } from "../markdown/index.js";
+export declare const BLOG_PLUGIN_NAME = "zudoku-blog";
+export type BlogAuthor = {
+    name: string;
+    title?: string;
+    url?: string;
+    imageUrl?: string;
+};
+export type BlogTag = {
+    label: string;
+    slug: string;
+};
+export type BlogPost = {
+    path: string;
+    title: string;
+    description?: string;
+    date: string;
+    authors: BlogAuthor[];
+    tags: BlogTag[];
+    readingTime: number;
+    image?: string;
+    draft?: boolean;
+};
+export type BlogPluginOptions = {
+    files?: string | string[];
+    path?: string;
+    title?: string;
+    description?: string;
+    postsPerPage?: number;
+    showReadingTime?: boolean;
+    authors?: Record<string, BlogAuthor>;
+    sidebar?: {
+        title?: string;
+        count?: number;
+    } | false;
+    feed?: boolean;
+};
+export type ResolvedBlogOptions = {
+    files: string[];
+    path: string;
+    title: string;
+    description?: string;
+    postsPerPage: number;
+    showReadingTime: boolean;
+    authors: Record<string, BlogAuthor>;
+    sidebar: {
+        title: string;
+        count: number;
+    } | false;
+    feed?: boolean;
+};
+export declare const resolveBlogOptions: (options?: BlogPluginOptions) => ResolvedBlogOptions;
+export type BlogManifest = {
+    tags: BlogTag[];
+    feedUrl?: string;
+    postImports: Record<string, () => Promise<MDXImport>>;
+    loadPosts: () => Promise<BlogPost[]>;
+};
+export type BlogPageOptions = Pick<ResolvedBlogOptions, "path" | "title" | "description" | "showReadingTime"> & Pick<BlogManifest, "feedUrl" | "tags">;
+export declare const getBlogPagePath: (blogPath: string, page: number) => string;
+export declare const getBlogTagPath: (blogPath: string, tag: Pick<BlogTag, "slug">) => string;

package/dist/declarations/lib/plugins/openapi/ParamInfos.d.ts

@@ -1,6 +1,7 @@
 import type { SchemaObject } from "../../oas/parser/index.js";
-export declare const ParamInfos: ({ schema, extraItems, className, }: {
+export declare const ParamInfos: ({ schema, nullable, extraItems, className, }: {
     schema?: SchemaObject;
+    nullable?: boolean;
     extraItems?: unknown[];
     className?: string;
 }) => import("react").JSX.Element;

package/dist/declarations/lib/plugins/openapi/components/EnumValues.d.ts

@@ -1,5 +1,6 @@
-export declare const EnumValues: ({ values, className, maxVisibleValues, }: {
+export declare const EnumValues: ({ values, className, descriptions, maxVisibleValues, }: {
     values: Array<string | number>;
+    descriptions?: Record<string, string>;
     className?: string;
     maxVisibleValues?: number;
 }) => import("react").JSX.Element | null;

package/dist/declarations/lib/plugins/openapi/schema/SchemaPropertyItem.d.ts

@@ -1,5 +1,5 @@
 import type { SchemaObject } from "../../../oas/parser/index.js";
-export declare const SchemaPropertyItem: ({ name, schema, group, defaultOpen, showCollapseButton, }: {
+export declare const SchemaPropertyItem: ({ name, schema: propertySchema, group, defaultOpen, showCollapseButton, }: {
     name: string;
     schema: SchemaObject;
     group: "required" | "optional" | "deprecated";

package/dist/declarations/lib/plugins/openapi/schema/SchemaView.d.ts

@@ -1,8 +1,8 @@
 import type { SchemaObject } from "../../../oas/parser/index.js";
-export declare const SchemaView: ({ schema, defaultOpen, cardHeader, embedded, hideRootRef, }: {
+export declare const SchemaView: ({ schema: rootSchema, defaultOpen, cardHeader, embedded, hideRootRef, }: {
     schema?: SchemaObject | null;
     defaultOpen?: boolean;
     cardHeader?: React.ReactNode;
     embedded?: boolean;
     hideRootRef?: boolean;
-}) => import("react").JSX.Element | undefined;
+}) => import("react").JSX.Element | null;

package/dist/declarations/lib/plugins/openapi/schema/utils.d.ts

@@ -1,10 +1,17 @@
 import type { ArraySchemaObject, SchemaObject } from "../../../oas/parser/index.js";
 export declare const isBasicType: (type: unknown) => type is "string" | "number" | "boolean" | "integer" | "null";
 export declare const isArrayType: (value: SchemaObject) => value is ArraySchemaObject;
+export declare const isBinarySchema: (schema?: SchemaObject) => boolean;
+export declare const withBinaryMediaType: (schema: SchemaObject | null | undefined, mediaType: string | undefined) => SchemaObject | undefined;
+export declare const unwrapNullableUnion: (schema: SchemaObject) => {
+    schema: SchemaObject;
+    nullable: boolean;
+};
 export declare const isComplexType: (value?: SchemaObject) => boolean | undefined;
 export declare const isCircularRef: (schema: unknown) => schema is string;
 export declare const isArrayCircularRef: (schema: SchemaObject) => schema is SchemaObject & {
     items: SchemaObject;
 };
+export declare const getEnumDescriptions: (schema?: SchemaObject) => Record<string, string> | undefined;
 export declare const getSchemaRefName: (schema?: SchemaObject | null) => string | undefined;
 export declare const extractCircularRefInfo: (ref?: string | SchemaObject) => string | undefined;

package/dist/declarations/lib/ui/Form.d.ts

@@ -18,7 +18,7 @@ declare const useFormField: () => {
 declare const FormItem: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
 declare const FormLabel: React.ForwardRefExoticComponent<Omit<LabelPrimitive.LabelProps & React.RefAttributes<HTMLLabelElement>, "ref"> & React.RefAttributes<HTMLLabelElement>>;
 declare const FormControl: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLElement> & {
-    children?: React.ReactNode;
+    children?: React.ReactNode | undefined;
 } & React.RefAttributes<HTMLElement>, "ref"> & React.RefAttributes<HTMLElement>>;
 declare const FormDescription: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
 declare const FormMessage: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;

package/dist/declarations/vite/zuplo.d.ts

@@ -0,0 +1,13 @@
+export type ZuploEnvironmentVariables = {
+    __ZUPLO_DEPLOYMENT_NAME?: string;
+    __ZUPLO_LOGGING_ID?: string;
+    __ZUPLO_REMOTE_LOG_TOKEN?: string;
+    __ZUPLO_AUTH_API_JWT?: string;
+    __ZUPLO_EXTERNAL_SERVICE_TOKEN?: string;
+    ZUPLO_ENVIRONMENT_TYPE?: "PRODUCTION" | "DEVELOPMENT" | "STAGING";
+    ZUPLO_PROJECT_ID?: string;
+    ZUPLO_API_KEY_SERVICE_BUCKET_NAME?: string;
+    ZUPLO_SERVICE_BUCKET_ID?: string;
+    __ZUPLO_CONFIG?: string;
+};
+export declare const getZuploSystemConfigurations: (string?: string) => ZuploEnvironmentVariables | undefined;

package/docs/configuration/api-catalog.md

@@ -6,6 +6,22 @@ sidebar_icon: book-open
 If you're dealing with multiple APIs and multiple OpenAPI files, the API Catalog comes in handy. It
 creates an overview of all your APIs and lets you organize them into categories and tags.
 
+## Categories and Tags
+
+Each entry in an API's `categories` array has two fields, `label` and `tags`, which serve different
+purposes:
+
+- **`label`** is the primary grouping. The catalog page renders one filter chip per unique label, so
+  this is what users click to narrow the list. An API can belong to multiple categories by adding
+  multiple entries to the array.
+- **`tags`** are secondary descriptors attached to that category. They do _not_ get their own filter
+  chip. Instead, they are matched against the search input and rendered as additional badges on the
+  API card (alongside the label). Use them for finer-grained keywords that should help users
+  discover an API without cluttering the top-level filters.
+
+For example, `{ label: "Payments", tags: ["billing", "subscriptions"] }` puts the API under the
+"Payments" filter chip and adds "billing" and "subscriptions" as searchable badges on its card.
+
 ## Enable API Catalog
 
 To enable the API Catalog, add a `catalogs` object to your Zudoku configuration file.

package/docs/configuration/blog.md

@@ -0,0 +1,214 @@
+---
+title: Blog
+navigation_icon: newspaper
+---
+
+Zudoku can publish a blog next to your documentation and API reference. Posts are Markdown or MDX
+files in a folder of your project: add a file and it shows up in the blog, with a paginated index,
+tag pages, a "Recent posts" sidebar and an RSS feed.
+
+:::caution{title="Beta"}
+
+The blog plugin is in beta. Its options, frontmatter fields and generated URLs may still change in a
+minor release. Feedback is welcome in [GitHub issues](https://github.com/zuplo/zudoku/issues).
+
+:::
+
+## Enable the blog
+
+Add the blog plugin to the `plugins` of your config. Every option has a default:
+
+```tsx title="zudoku.config.tsx"
+import { blogPlugin } from "zudoku/plugins/blog";
+
+export default {
+  plugins: [blogPlugin()],
+};
+```
+
+Then put your posts in the `blog` folder at the root of your project:
+
+```text title="File tree"
+blog/
+├── 2025-03-14-hello-world.md        → /blog/hello-world
+├── 2025-04-02-launch-week/
+│   ├── index.mdx                    → /blog/launch-week
+│   └── screenshot.png
+└── release-notes/
+    └── 2025-05-20-v2.md             → /blog/release-notes/v2
+```
+
+To link to the blog from the top navigation, add a link to your [navigation](./navigation.mdx):
+
+```tsx title="zudoku.config.tsx"
+export default {
+  navigation: [
+    // ...
+    { type: "link", to: "/blog", label: "Blog", icon: "newspaper" },
+  ],
+};
+```
+
+## Writing posts
+
+The file name sets the URL and the date of a post: a `YYYY-MM-DD-` prefix is the publish date and
+the rest is the slug. A post can also be a folder with an `index.md` or `index.mdx` file, which
+keeps its images next to it. Folders that aren't dated stay part of the URL.
+
+Some files are not posts:
+
+- Other Markdown files in a post's folder, such as partials imported by its `index.mdx` or a
+  `README.md`
+- Files and folders whose name starts with `_`, e.g. `_drafts/` or `_snippet.mdx`
+- Posts whose URL is taken by the blog's own pages: `<path>/tags`, `<path>/tags/*`, `<path>/page/*`
+  and `<path>/rss.xml`. These are skipped with a warning.
+
+Link to other posts by their file, e.g. `[Launch](./2025-04-02-launch-week/index.mdx)`, and the link
+points to the post's URL.
+
+Posts support everything [Markdown and MDX pages](../markdown/overview.md) do, including
+[admonitions](../markdown/admonitions.md), [code blocks](../markdown/code-blocks.md) and React
+components.
+
+```md title="blog/2025-03-14-hello-world.md"
+---
+title: Hello World
+description: The first post on our new developer blog.
+authors: [jane]
+tags: [Announcements, API]
+---
+
+This paragraph is the excerpt shown on the blog index page.
+
+## A section
+
+The post continues here.
+```
+
+### Frontmatter
+
+| Field         | Description                                                                                                                                                                                                        |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `title`       | Title of the post. Defaults to the first `# Heading`, which is then not repeated in the post body.                                                                                                                 |
+| `description` | Shown on the index page, in the feed and as the meta description. Defaults to the first paragraph.                                                                                                                 |
+| `date`        | Publish date, e.g. `2025-03-14` or `2025-03-14T09:00:00Z`. Defaults to the date in the file name, then the date of the commit that added the file (needs the full git history), then the file's modification time. |
+| `slug`        | Overrides the URL: `slug: launch` serves the post at `/blog/launch`.                                                                                                                                               |
+| `authors`     | Author keys from [`authors`](#authors), or inline objects such as `{ name: "Jane Doe", title: "Engineer" }`.                                                                                                       |
+| `tags`        | List of tags. Each tag gets a page listing its posts.                                                                                                                                                              |
+| `image`       | Image used as `og:image` when the post is shared. An absolute URL or a path in the `public` folder, e.g. `/cover.png`.                                                                                             |
+| `draft`       | When `true`, the post is only shown in development.                                                                                                                                                                |
+| `toc`         | Set to `false` to hide the table of contents.                                                                                                                                                                      |
+| `seo`         | `title` and `description` that override the browser title and meta description only.                                                                                                                               |
+
+Posts are sorted by date, newest first.
+
+## Plugin options
+
+```tsx title="zudoku.config.tsx"
+import { blogPlugin } from "zudoku/plugins/blog";
+
+export default {
+  plugins: [
+    blogPlugin({
+      files: "/blog/**/*.{md,mdx}",
+      path: "/blog",
+      title: "Blog",
+      description: "News and updates from the team.",
+      postsPerPage: 10,
+      showReadingTime: true,
+      authors: {
+        jane: {
+          name: "Jane Doe",
+          title: "Developer Advocate",
+          url: "https://example.com/jane",
+          imageUrl: "https://example.com/jane.png",
+        },
+      },
+      sidebar: { title: "Recent posts", count: 5 },
+      feed: true,
+    }),
+  ],
+};
+```
+
+### `files`
+
+**Type:** `string | string[]`  
+**Default:** `"/blog/**/*.{md,mdx}"`
+
+Glob patterns for the post files. Keep them outside of [`docs.files`](./docs.md#files) so a post
+isn't also published as a documentation page.
+
+### `path`
+
+**Type:** `string`  
+**Default:** `"/blog"`
+
+The route the blog is served under. The index is at `path`, further index pages at `path/page/2`,
+tags at `path/tags` and posts at `path/<slug>`.
+
+### `title` and `description`
+
+**Type:** `string`  
+**Default:** `"Blog"` and none
+
+Heading and introduction of the index page. Both are also used for the RSS feed.
+
+### `postsPerPage`
+
+**Type:** `number`  
+**Default:** `10`
+
+Number of posts on each page of the index.
+
+### `showReadingTime`
+
+**Type:** `boolean`  
+**Default:** `true`
+
+Shows an estimated reading time next to the date of each post.
+
+### `authors`
+
+**Type:** `Record<string, { name: string; title?: string; url?: string; imageUrl?: string }>`  
+**Default:** `{}`
+
+Authors that posts reference by key in their `authors` frontmatter, so their details are kept in one
+place. Authors without an `imageUrl` show their initial instead.
+
+### `sidebar`
+
+**Type:** `{ title?: string; count?: number } | false`  
+**Default:** `{ title: "Recent posts", count: 5 }`
+
+Lists the most recent posts in the sidebar of all blog pages. Set to `false` to hide it.
+
+### `feed`
+
+**Type:** `boolean`  
+**Default:** on when a site URL is configured
+
+Generates an RSS feed at `<path>/rss.xml` and links it from every blog page. Feeds need absolute
+links, so the site URL is taken from [`canonicalUrlOrigin`](./overview.md#canonicalurlorigin) or
+[`sitemap.siteUrl`](./overview.md#sitemap). Without either, no feed is generated.
+
+## Multiple blogs
+
+Add the plugin once per blog, each with its own `files` and `path`, for example a blog and a
+changelog:
+
+```tsx title="zudoku.config.tsx"
+import { blogPlugin } from "zudoku/plugins/blog";
+
+export default {
+  plugins: [
+    blogPlugin({ files: "/blog/**/*.{md,mdx}", path: "/blog" }),
+    blogPlugin({
+      files: "/changelog/**/*.{md,mdx}",
+      path: "/changelog",
+      title: "Changelog",
+      sidebar: false,
+    }),
+  ],
+};
+```