zuplo 6.70.68 → 6.70.70

package/docs/dev-portal/zudoku/components/sidecar-box.mdx

@@ -0,0 +1,131 @@
+---
+title: Sidecar Box
+sidebar_icon: panel-right
+---
+
+import * as SidecarBox from "zudoku/ui/SidecarBox";
+import { SyntaxHighlight } from "zudoku/ui/SyntaxHighlight";
+import { Badge } from "zudoku/ui/Badge";
+
+A framed panel with an optional head, body, and footer. The OpenAPI plugin builds its sidecar with
+it (the request body, response, and example boxes), so reaching for it in custom plugin pages or MDX
+gives you content that matches that look.
+
+## Import
+
+```tsx
+import * as SidecarBox from "zudoku/ui/SidecarBox";
+import { SyntaxHighlight } from "zudoku/ui/SyntaxHighlight";
+```
+
+## Components
+
+- `SidecarBox.Root` - The outer framed container
+- `SidecarBox.Head` - Header row, typically a title or controls
+- `SidecarBox.Body` - Main content area with its own inner border
+- `SidecarBox.Footer` - Footer row for notes or actions
+
+`Head`, `Body`, and `Footer` are all optional. Use just `Root` and `Body` for a plain framed panel.
+
+## With a status badge
+
+The head is a plain flex row, so `justify-between` aligns a title on the left and a status badge (or
+any control) on the right, above an embedded code body.
+
+<SidecarBox.Root className="not-prose max-w-sm">
+  <SidecarBox.Head className="text-xs flex justify-between items-center">
+    <span className="font-medium">GET /users/{`{id}`}</span>
+    <Badge variant="muted">200</Badge>
+  </SidecarBox.Head>
+  <SidecarBox.Body className="p-0">
+    <SyntaxHighlight
+      embedded
+      language="bash"
+      className="rounded-none text-xs"
+      code={`curl https://api.example.com/users/usr_123 \\
+  -H "Authorization: Bearer $TOKEN"`}
+    />
+  </SidecarBox.Body>
+</SidecarBox.Root>
+
+```tsx
+<SidecarBox.Root>
+  <SidecarBox.Head className="text-xs flex justify-between items-center">
+    <span className="font-medium">GET /users/{id}</span>
+    <Badge variant="muted">200</Badge>
+  </SidecarBox.Head>
+  <SidecarBox.Body className="p-0">
+    <SyntaxHighlight embedded language="bash" className="rounded-none text-xs" code={curlExample} />
+  </SidecarBox.Body>
+</SidecarBox.Root>
+```
+
+## Anatomy
+
+All four parts together. The head and footer sit flush against the framed body in the middle.
+
+<SidecarBox.Root className="not-prose max-w-sm">
+  <SidecarBox.Head className="font-medium">Response</SidecarBox.Head>
+  <SidecarBox.Body className="p-3">A 200 response returns the user object.</SidecarBox.Body>
+  <SidecarBox.Footer className="text-muted-foreground text-xs">application/json</SidecarBox.Footer>
+</SidecarBox.Root>
+
+```tsx
+<SidecarBox.Root>
+  <SidecarBox.Head className="font-medium">Response</SidecarBox.Head>
+  <SidecarBox.Body className="p-3">A 200 response returns the user object.</SidecarBox.Body>
+  <SidecarBox.Footer className="text-muted-foreground text-xs">application/json</SidecarBox.Footer>
+</SidecarBox.Root>
+```
+
+## With a code block
+
+For code or JSON, drop the body padding with `className="p-0"` and let an embedded `SyntaxHighlight`
+own the spacing. This is the pattern the OpenAPI plugin uses for its example boxes.
+
+<SidecarBox.Root className="not-prose max-w-sm">
+  <SidecarBox.Head className="text-xs font-medium">Example response</SidecarBox.Head>
+  <SidecarBox.Body className="p-0">
+    <SyntaxHighlight
+      embedded
+      language="json"
+      className="rounded-none text-xs"
+      code={`{
+  "id": "usr_123",
+  "name": "Ada Lovelace",
+  "active": true
+}`}
+    />
+  </SidecarBox.Body>
+  <SidecarBox.Footer className="text-muted-foreground text-xs">200 OK</SidecarBox.Footer>
+</SidecarBox.Root>
+
+```tsx
+<SidecarBox.Root>
+  <SidecarBox.Head className="text-xs font-medium">Example response</SidecarBox.Head>
+  <SidecarBox.Body className="p-0">
+    <SyntaxHighlight
+      embedded
+      language="json"
+      className="rounded-none text-xs"
+      code={`{
+  "id": "usr_123",
+  "name": "Ada Lovelace",
+  "active": true
+}`}
+    />
+  </SidecarBox.Body>
+  <SidecarBox.Footer className="text-muted-foreground text-xs">200 OK</SidecarBox.Footer>
+</SidecarBox.Root>
+```
+
+## Props
+
+Each part accepts `children` and an optional `className` to extend or override its styling.
+
+| Component           | Description                                                        |
+| ------------------- | ------------------------------------------------------------------ |
+| `SidecarBox.Root`   | Outer frame. Sets the rounded border, background, and shadow.      |
+| `SidecarBox.Head`   | Top row. A flex container, so layout utilities apply directly.     |
+| `SidecarBox.Body`   | Content area with its own inner border. Use `p-0` for code blocks. |
+| `SidecarBox.Footer` | Bottom row for notes or actions.                                   |

package/docs/dev-portal/zudoku/configuration/api-catalog.md

@@ -8,9 +8,9 @@ creates an overview of all your APIs and lets you organize them into categories
 
 ## Enable API Catalog
 
-The first step to enable the API Catalog, you need to add a `catalogs` object to your Dev Portal configuration file.
+To enable the API Catalog, add a `catalogs` object to your Dev Portal configuration file.
 
-```js title=zudoku.config.ts
+```ts title=zudoku.config.ts
 const config = {
   // ...
   catalogs: {
@@ -24,85 +24,105 @@ const config = {
 You can then add your APIs to the catalog by adding the `categories` property to your API
 configuration.
 
-```js title=zudoku.config.ts
+:::caution{title="Recommendation: nest API paths under the catalog path"}
+
+For a consistent user experience, APIs that appear in the catalog should have their `path` prefixed
+with the catalog path. For example, if your catalog is at `/catalog`, an API path should start with
+`/catalog/` (e.g., `/catalog/api-users`). APIs with paths outside the catalog path still appear in
+the catalog, but clicking them navigates the user outside the catalog section.
+
+:::
+
+```ts title=zudoku.config.ts
 const config = {
-  // ...
+  catalogs: {
+    path: "/catalog",
+    label: "API Catalog",
+  },
   apis: [
-    // ...
     {
       type: "file",
       input: "./operational.json",
-      path: "/api-operational",
+      path: "/catalog/api-operational", // Must be under /catalog/
       categories: [{ label: "General", tags: ["Operational"] }],
     },
     {
       type: "file",
       input: "./enduser.json",
-      path: "/api-enduser",
+      path: "/catalog/api-enduser", // Must be under /catalog/
       categories: [{ label: "General", tags: ["End-User"] }],
     },
     {
       type: "file",
       input: "./openapi.json",
-      path: "/api-auth",
+      path: "/catalog/api-auth", // Must be under /catalog/
       categories: [{ label: "Other", tags: ["Authentication"] }],
     },
-    // ...
   ],
-  // ...
 };
 ```
 
-## Advanced Configuration
-
-### Select APIs to show in the catalog
-
-You can select which APIs are shown in the catalog by using the `items` property. The `items`
-property is an array of navigation IDs of the APIs you want to show in the catalog.
+To add the catalog to your navigation, use a link item:
 
-```js title=zudoku.config.ts
+```ts title=zudoku.config.ts
 const config = {
-  // ...
-  catalogs: {
-    path: "/catalog",
-    label: "API Catalog",
-    // Only show the operational API in the catalog
-    items: ["api-operational"],
-  },
-  apis: [
-    // ...
+  navigation: [
     {
-      type: "file",
-      input: "./operational.json",
-      path: "/api-operational",
-      categories: [{ label: "General", tags: ["Operational"] }],
-    },
-    {
-      type: "file",
-      input: "./enduser.json",
-      path: "/api-enduser",
-      categories: [{ label: "General", tags: ["End-User"] }],
+      type: "link",
+      label: "API Catalog",
+      to: "/catalog",
+      icon: "square-library",
     },
   ],
-  // ...
+  // ... catalogs and apis config
 };
 ```
 
+## Advanced Configuration
+
 ### Filtering catalog items
 
 You can filter which APIs are shown in the catalog by using the `filterItems` property. The function
-receives the items and context as arguments.
+receives the items and the catalog context (including `auth`) as arguments. Each item has a
+`categories` array where each category has a `label` and `tags`.
 
-```js title=zudoku.config.ts
+```ts title=zudoku.config.ts
 const config = {
-  // ...
   catalogs: {
     path: "/catalog",
     label: "API Catalog",
     filterItems: (items, { auth }) => {
-      return items.filter((item) => item.tags.includes("public"));
+      return items.filter((item) =>
+        item.categories?.some((category) => category.tags?.includes("public")),
+      );
     },
   },
-  // ...
 };
 ```
+
+## Standalone APIs (without catalog)
+
+APIs that are **not** part of a catalog can use any path and will appear as standalone API reference
+pages. These APIs don't need `categories` and their paths don't need to be nested under a catalog.
+
+```ts title=zudoku.config.ts
+const config = {
+  apis: [
+    {
+      type: "file",
+      input: "./openapi.json",
+      path: "/api", // standalone, not under a catalog
+    },
+  ],
+  navigation: [
+    {
+      type: "link",
+      label: "API Reference",
+      to: "/api",
+    },
+  ],
+};
+```
+
+See the [API Reference](/dev-portal/zudoku/configuration/api-reference) page for full details on configuring
+individual APIs, including versioning and customization options.

package/docs/dev-portal/zudoku/configuration/api-reference.md

@@ -209,7 +209,7 @@ const config = {
       disableSecurity: true, // Disable security scheme display and playground auth (default)
       showVersionSelect: "if-available", // Control version selector visibility
       expandAllTags: true, // Control initial expanded state of tag categories
-      showInfoPage: true, // Show API information page as the index route
+      showInfoPage: true, // Always show the info page (unset = show only if a description is set)
       schemaDownload: {
         enabled: true, // Enable schema download button
         fileName: "schema", // Set name of the schema file when downloaded
@@ -234,8 +234,9 @@ Available options:
   - `"always"`: Always show version selector (disabled if only one version)
   - `"hide"`: Never show version selector
 - `expandAllTags`: Control initial expanded state of tag categories (default: `true`)
-- `showInfoPage`: Show the API information page as the index route (default: `true`). When disabled,
-  navigating to the API root redirects to the first tag instead
+- `showInfoPage`: Control the API information page shown as the index route. Set to `true` to always
+  show it, or `false` to always redirect the API root to the first tag. When unset, the page is
+  shown only if the API has a description, otherwise the API root redirects to the first tag
 - `schemaDownload`: Enable schema download functionality. When enabled, displays a button allowing
   users to download the OpenAPI schema, copy it to clipboard, or open in a new tab.
   - `enabled`: Enable or disable the schema download button
@@ -261,7 +262,7 @@ const config = {
       disableSecurity: true, // Disable security scheme display and playground auth (default)
       showVersionSelect: "if-available", // Control version selector visibility
       expandAllTags: false, // Control initial expanded state of tag categories
-      showInfoPage: true, // Show API information page as the index route
+      showInfoPage: true, // Always show the info page (unset = show only if a description is set)
       schemaDownload: {
         enabled: true, // Enable schema download button
         fileName: "schema", // Set name of the schema file when downloaded

package/docs/dev-portal/zudoku/configuration/navigation.mdx

@@ -93,6 +93,7 @@ type NavigationLink = {
   label: string;
   icon?: string; // Lucide icon name
   target?: "_self" | "_blank";
+  stack?: boolean; // open the destination as a stacked sub-nav
   badge?: {
     label: string;
     color: "green" | "blue" | "yellow" | "red" | "purple" | "indigo" | "gray" | "outline";
@@ -141,6 +142,7 @@ type NavigationCategory = {
   label: string;
   collapsible?: boolean;
   collapsed?: boolean;
+  stack?: boolean; // open the category's items as a stacked sub-nav
   link?: string | { type: "doc"; file: string; label?: string; path?: string };
   display?:
     | "auth"
@@ -460,6 +462,67 @@ type NavigationFilter = {
 
 </details>
 
+## Stacked navigation
+
+By default a category expands inline when clicked. Set `stack: true` and it opens as a full panel
+that slides in over the current menu, with a **Back** button to return. Use it for deep sections
+that would otherwise crowd the sidebar.
+
+`stack` works on categories and links. The panel content comes from the item itself:
+
+- A **category** with `stack: true` shows its own `items`.
+- A **link** with `stack: true` opens the navigation at its destination, such as the sidebar a
+  plugin generates at that path.
+
+```tsx title="Stack a category's items"
+{
+  type: "category",
+  label: "Shipping Guides",
+  stack: true,
+  items: ["guides/interstellar", "guides/intergalactic"],
+}
+```
+
+```tsx title="Stack a linked section (e.g. a GraphQL plugin)"
+{
+  type: "link",
+  label: "Developer API",
+  to: "/graphql/dev",
+  stack: true,
+}
+```
+
+The **Back** button points to the section the stacked item belongs to (for example "Back to Our
+APIs"), so the page still works when someone opens it directly from a search result or a shared
+link.
+
+:::note
+
+A stacked link drills into wherever its `to` points, so the destination should be a section with its
+own navigation, such as a plugin route or a category landing page. The slide animation respects the
+user's reduced-motion setting and falls back to an instant swap.
+
+:::
+
+### Stacking generated navigation
+
+Plugin-generated sidebars (e.g. OpenAPI) can be stacked too, with a
+[navigation rule](#navigation-rules). This is useful for large APIs: instead of one long scroll,
+make each tag drill into its own panel.
+
+```tsx title="Stack an OpenAPI tag"
+navigationRules: [
+  {
+    type: "modify",
+    match: "Shipments/Shipment/Shipment Management",
+    set: { stack: true },
+  },
+],
+```
+
+The `match` targets a generated category by label (here, the `Shipment Management` tag under the
+`Shipments` API). See [Navigation Rules](#navigation-rules) for the matching syntax.
+
 ## Display Control
 
 All navigation items support a `display` property that controls when the item should be visible:
@@ -671,13 +734,13 @@ For a practical walkthrough with more examples, see the
 
 Each rule has a `type` and a `match` property that targets a navigation item.
 
-| Type     | Description                                                               |
-| -------- | ------------------------------------------------------------------------- |
-| `insert` | Add items `before` or `after` a matched item                              |
-| `modify` | Change `label`, `icon`, `badge`, `collapsed`, `collapsible`, or `display` |
-| `remove` | Remove a matched item from the sidebar                                    |
-| `sort`   | Sort children of a matched category using a custom comparator             |
-| `move`   | Relocate a matched item `before` or `after` another item                  |
+| Type     | Description                                                                        |
+| -------- | ---------------------------------------------------------------------------------- |
+| `insert` | Add items `before` or `after` a matched item                                       |
+| `modify` | Change `label`, `icon`, `badge`, `collapsed`, `collapsible`, `display`, or `stack` |
+| `remove` | Remove a matched item from the sidebar                                             |
+| `sort`   | Sort children of a matched category using a custom comparator                      |
+| `move`   | Relocate a matched item `before` or `after` another item                           |
 
 ### Match Syntax