@lukoweb/apitogo 0.2.56 → 0.2.57

package/docs/configuration/navigation.mdx

@@ -1,415 +0,0 @@
----
-title: Navigation
-sidebar_icon: compass
-description:
-  Learn how to configure the navigation in APIToGo, including links, categories, documents, and
-  custom pages. Understand the structure of the navigation array and how to use icons, labels, and
-  paths.
----
-
-import { Book, Code, FileText } from "@lukoweb/apitogo/icons";
-
-APIToGo uses a single `navigation` array to control both the top navigation tabs and the sidebar.
-Items at the root of this array appear as tabs, and nested items build the sidebar tree. Navigation
-entries can be links, document references, categories or custom pages.
-
-## Basic configuration
-
-The navigation is defined using the `navigation` array in the APIToGo config file. Each item can be
-one of several types. At the simplest level you may only have links and categories.
-
-```tsx title="config"
-{
-  "navigation": [
-    {
-      "type": "category",
-      "label": "Documentation",
-      "icon": "book",
-      "items": [
-        {
-          "type": "doc",
-          "file": "documentation/introduction",
-          "label": "Introduction",
-          "icon": "file-text"
-        },
-        {
-          "type": "doc",
-          "file": "documentation/getting-started",
-          "path": "/docs/quick-start",
-          "label": "Quick Start"
-        }
-      ]
-    },
-    {
-      "type": "link",
-      "to": "/api",
-      "label": "API Reference",
-      "icon": "code",
-      "description": "Complete API documentation",
-      "badge": {
-        "label": "v2.0",
-        "color": "blue"
-      },
-      "display": "always"
-    }
-  ]
-}
-```
-
-## Generate navigation automatically
-
-In a config version 2 project, the portal builds the sidebar from the pages under
-`apitogo/portal/pages/`: the index page first, then the other pages by name, then one section per
-folder. There is no `navigation` key to maintain. Add a page with **`npx apitogo config`** (see
-**[Make config (CLI)](./make-config.mdx)**) or by creating the `.md`, `.mdx` or `.tsx` (React) file.
-
-## Navigation Items
-
-Navigation items can be of these types: `category`, `doc`, `link`, or `custom-page`.
-
-- `link`: A direct link to a page or external URL.
-- `category`: A group of links that can be expanded or collapsed.
-- `doc`: A reference to a document by it's file path: `file`.
-- `custom-pages`: A custom page that is made of a React component, see
-  [Custom Pages](../guides/custom-pages.md)
-
-### `type: link`
-
-`link` is the most basic item, it directly links to a path or URL. Use this for external resources
-or standalone pages.
-
-```json
-{
-  "type": "link",
-  "label": "Support",
-  "to": "/my/api" // or: https://example.com/my-external-link
-}
-```
-
-<details>
-<summary>**TypeScript type declaration**</summary>
-```ts
-type NavigationLink = {
-  type: "link";
-  to: string;
-  label: string;
-  icon?: string; // Lucide icon name
-  description?: string;
-  badge?: {
-    label: string;
-    color: "green" | "blue" | "yellow" | "red" | "purple" | "indigo" | "gray" | "outline";
-  };
-  display?:
-    | "auth"
-    | "anon"
-    | "always"
-    | "hide"
-    | ((params: { context: ApitogoContext; auth: UseAuthReturn }) => boolean);
-  target?: "_self" | "_blank";
-};
-```
-</details>
-
-### `type: category`
-
-The `category` type groups related items under a collapsible section. The `label` is the displayed
-text, and the `items` array contains `id`s of documents, links, or other categories.
-
-```json
-{
-  "type": "category",
-  "label": "Getting Started",
-  "collapsible": true, // optional
-  "collapsed": false, // optional
-  "items": [
-    {
-      "type": "link",
-      "label": "Support",
-      "to": "https://support.example.com"
-    }
-  ]
-}
-```
-
-<details>
-<summary>**TypeScript type declaration**</summary>
-
-```ts
-type NavigationCategory = {
-  type: "category";
-  icon?: string; // Lucide icon name
-  items: Array<NavigationDoc | NavigationLink | NavigationCategory | NavigationCustomPage>;
-  label: string;
-  collapsible?: boolean;
-  collapsed?: boolean;
-  link?: string | { type: "doc"; file: string; label?: string };
-  display?:
-    | "auth"
-    | "anon"
-    | "always"
-    | "hide"
-    | ((params: { context: ApitogoContext; auth: UseAuthReturn }) => boolean);
-};
-```
-
-</details>
-
-### `type: doc`
-
-Doc is used to reference markdown files. The `label` is the text that will be displayed, and the
-`file` is the file path associated with a markdown file.
-
-```json
-{
-  "type": "doc",
-  "label": "Overview",
-  "file": "docs/overview"
-}
-```
-
-<details>
-<summary>**TypeScript type declaration**</summary>
-
-```ts
-type NavigationDoc = {
-  type: "doc";
-  file: string;
-  path?: string;
-  icon?: string;
-  label?: string;
-  badge?: {
-    label: string;
-    color: "green" | "blue" | "yellow" | "red" | "purple" | "indigo" | "gray" | "outline";
-  };
-  display?:
-    | "auth"
-    | "anon"
-    | "always"
-    | "hide"
-    | ((params: { context: ApitogoContext; auth: UseAuthReturn }) => boolean);
-};
-```
-
-</details>
-
-#### Using shorthands
-
-Documents can be referenced as strings (using their file path), which is equivalent to
-`{ "type": "doc", "file": "path" }`:
-
-```json
-{
-  "navigation": [
-    {
-      "type": "category",
-      "label": "Documentation",
-      "icon": "book",
-      "items": [
-        "documentation/introduction",
-        "documentation/getting-started",
-        "documentation/installation"
-      ]
-    },
-    {
-      "type": "link",
-      "to": "/api",
-      "label": "API Reference",
-      "icon": "code"
-    }
-  ]
-}
-```
-
-This is much more concise when you don't need custom labels, icons, or other properties for
-individual documents.
-
-Learn more in the [Markdown documentation](/docs/markdown/overview)
-
-#### Custom paths
-
-The `path` property allows you to customize the URL path for a document. By default, APIToGo uses
-the file path to generate the URL, but you can override this behavior by specifying a custom path.
-
-### `type: custom-page`
-
-Custom pages allow you to create standalone pages that are not tied to a Markdown document. This is
-useful for creating landing pages, dashboards, or any other custom content.
-
-```tsx
-{
-  type: "custom-page",
-  path: "/a-custom-page",
-  element: <MyCustomPage />,
-  display: "always"
-}
-```
-
-<details>
-<summary>**TypeScript type declaration**</summary>
-
-```ts
-type NavigationCustomPage = {
-  type: "custom-page";
-  path: string;
-  label?: string;
-  element: any;
-  icon?: string; // Lucide icon name
-  badge?: {
-    label: string;
-    color: "green" | "blue" | "yellow" | "red" | "purple" | "indigo" | "gray" | "outline";
-    invert?: boolean;
-  };
-  display?:
-    | "auth"
-    | "anon"
-    | "always"
-    | "hide"
-    | ((params: { context: ApitogoContext; auth: UseAuthReturn }) => boolean);
-};
-```
-
-</details>
-
-## Display Control
-
-All navigation items support a `display` property that controls when the item should be visible:
-
-- `"always"` (default): Always visible
-- `"auth"`: Only visible when user is authenticated
-- `"anon"`: Only visible when user is not authenticated
-- `"hide"`: Never visible (useful for temporarily hiding items)
-- **callback function**: For custom logic, pass a function that receives `{ context, auth }` and
-  returns a boolean
-
-```json
-{
-  "type": "link",
-  "label": "Admin Panel",
-  "to": "/admin",
-  "display": "auth"
-}
-```
-
-### Custom Display Logic
-
-For more complex visibility rules, use a callback function:
-
-```tsx
-{
-  type: "link",
-  label: "Premium Features",
-  to: "/premium",
-  display: ({ auth }) => {
-    // Show only for users with premium role
-    return auth.user?.role === "premium";
-  }
-}
-```
-
-The callback receives:
-
-- `context`: The APIToGo runtime context (TypeScript type: `ApitogoContext`)
-- `auth`: The authentication state from `UseAuthReturn`, including `user`, `isAuthenticated`, etc.
-
-## Badges
-
-Navigation items can display badges with labels and colors. Badges support an optional `invert`
-property for styling:
-
-```json
-{
-  "type": "doc",
-  "file": "api/v2",
-  "badge": {
-    "label": "Beta",
-    "color": "yellow"
-  }
-}
-```
-
-## Icons
-
-Icons can be added to categories and documents by specifying an `icon` property. The value should be
-the name of a [Lucide icon](https://lucide.dev/icons) (e.g., `book` <Book size={16}
-style={{ display: 'inline' }} />, `code` <Code size={16} style={{ display: 'inline' }} />,
-`file-text` <FileText size={16} style={{ display: 'inline' }} />).
-
-```json
-{
-  "type": "category",
-  "label": "Getting Started",
-  "icon": "book"
-}
-```
-
-They can also be set on individual documents in their front matter:
-
-```md
----
-title: My Document
-sidebar_icon: book
----
-```
-
-## Title & Labels
-
-All navigation items can have a `label` property that determines the displayed text. For `doc`
-items, the `label` is optional; if omitted, APIToGo uses the document's `title` from its front
-matter or the first `#` header.
-
-To override the navigation label without changing the document's `title`, use the `sidebar_label`
-property in the front matter:
-
-```md
----
-title: My Long Title
-sidebar_label: Short Title
----
-```
-
-In this example, the document's title remains "My Long Title," but the sidebar displays "Short
-Title."
-
-## Navigation Rules
-
-Plugins generate sidebar navigation automatically (e.g. from OpenAPI tags). Navigation rules let you
-customize that generated sidebar by inserting, modifying, sorting, moving, or removing items. To
-change the top-level tabs themselves, use the `navigation` array directly.
-
-```tsx
-navigationRules: [
-  {
-    type: "sort",
-    match: "Shipments",
-    by: (a, b) => a.label.localeCompare(b.label),
-  },
-],
-```
-
-For a practical walkthrough with more examples, see the
-[Navigation Rules](/docs/guides/navigation-rules) guide.
-
-### Rule Types
-
-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                  |
-
-### Match Syntax
-
-The `match` property uses slash-separated segments to target items. The first segment identifies the
-top-level tab by label, and remaining segments navigate into the sidebar tree. Label matching is
-case-insensitive.
-
-```json
-match: "Users/Get User";      // by label
-match: "Users/0";             // first item
-match: "Users/-1";            // last item
-match: "Users/Advanced/0";   // mixed nesting
-```

package/docs/configuration/protected-routes.md

@@ -1,150 +0,0 @@
----
-title: Protected Routes
-sidebar_icon: squares-subtract
-description:
-  Learn how to protect specific routes in your documentation using authentication, including simple
-  array patterns, advanced authorization with reason codes, and custom callback functions.
----
-
-You can protect specific routes in your documentation by adding the `protectedRoutes` property to
-your [APIToGo configuration](./overview.md). This requires [authentication](./authentication.md) to
-be configured. The property supports two formats: a simple array of path patterns, or an advanced
-object format with custom authorization logic.
-
-:::note{title="Client-side protection only"}
-
-`protectedRoutes` are client-side only. Do not rely on `protectedRoutes` to hide sensitive
-information.
-
-We are working on an additional offering that secures this data server-side.
-
-:::
-
-## Array Format
-
-The simplest way to protect routes is to provide an array of path patterns. Users must be
-authenticated to access these routes.
-
-```typescript title="config"
-{
-  // ...
-  protectedRoutes: [
-    "/admin/*",     // Protect all routes under /admin
-    "/settings",    // Protect the settings page
-    "/api/*",       // Protect all API-related routes
-    "/private/:id"  // Protect dynamic routes with parameters
-  ],
-  // ...
-}
-```
-
-When a user tries to access a protected route, a login dialog will appear prompting them to sign in
-or register. After logging in, they are automatically redirected back to the route they were trying
-to access.
-
-## Object Format
-
-For more complex authorization logic, you can provide a record mapping route patterns to custom
-callback functions:
-
-```typescript title="config"
-{
-  // ...
-  protectedRoutes: {
-    // Only allow authenticated users with admin role
-    "/admin/*": ({ auth }) =>
-      auth.isAuthenticated && auth.user?.role === "admin",
-
-    // Check if user has enterprise access
-    "/api/enterprise/*": ({ auth }) =>
-      auth.isAuthenticated && auth.user?.subscription === "enterprise",
-
-    // Allow access to beta features based on user attributes
-    "/beta/*": ({ auth }) =>
-      auth.isAuthenticated && auth.user?.betaAccess === true,
-  },
-  // ...
-}
-```
-
-### Callback Parameters
-
-The callback function receives an object with:
-
-- `auth` - The current authentication state, including `isAuthenticated`, `isPending`, `profile`,
-  and more
-- `context` - The APIToGo context providing access to configuration and utilities
-- `reasonCode` - An object containing the reason code constants `UNAUTHORIZED` and `FORBIDDEN` (see
-  [Reason Codes](#reason-codes))
-
-### Return Values
-
-The callback can return a `boolean` or a reason code string:
-
-| Return value              | Behavior                                          |
-| ------------------------- | ------------------------------------------------- |
-| `true`                    | Allow access to the route                         |
-| `false`                   | Treated as `UNAUTHORIZED` - prompts login         |
-| `reasonCode.UNAUTHORIZED` | Show a login dialog prompting the user to sign in |
-| `reasonCode.FORBIDDEN`    | Show a 403 "Access Denied" page                   |
-
-## Reason Codes
-
-Reason codes allow you to distinguish between users who need to sign in and users who are signed in
-but lack permission. This is useful for building role-based or attribute-based access control.
-
-- **`UNAUTHORIZED`** - The user is not authenticated. A login dialog is shown, and navigation to the
-  route is blocked until the user signs in.
-- **`FORBIDDEN`** - The user is authenticated but does not have permission. A 403 "Access Denied"
-  page is displayed instead of the route content.
-
-```typescript title="config"
-{
-  // ...
-  protectedRoutes: {
-    // Members-only page: unauthenticated users see a login prompt
-    "/only-members": ({ auth, reasonCode }) =>
-      auth.isAuthenticated ? true : reasonCode.UNAUTHORIZED,
-
-    // VIP page: unauthenticated users see a login prompt,
-    // authenticated users without permission see "Access Denied"
-    "/vip-lounge": ({ auth, reasonCode }) =>
-      !auth.isAuthenticated
-        ? reasonCode.UNAUTHORIZED
-        : auth.profile?.email?.endsWith("@example.com")
-          ? true
-          : reasonCode.FORBIDDEN,
-  },
-  // ...
-}
-```
-
-## Navigation Blocking
-
-When a user navigates to a route that returns `false` or `UNAUTHORIZED`, navigation is intercepted
-before the page changes. The user stays on the current page while a login dialog is displayed. If
-the user cancels, they remain on the current page. If they log in successfully, navigation
-automatically proceeds to the protected route.
-
-Routes that return `FORBIDDEN` do not block navigation — the user navigates to the route and sees
-the "Access Denied" page.
-
-## Path Patterns
-
-The path patterns follow the same syntax as [React Router](https://reactrouter.com):
-
-- `:param` matches a URL segment up to the next `/`, `?`, or `#`
-- `*` matches zero or more characters up to the next `/`, `?`, or `#`
-- `/*` matches all characters after the pattern
-
-For example:
-
-- `/users/:id` matches `/users/123` or `/users/abc`
-- `/docs/*` matches `/docs/getting-started` or `/docs/api/reference`
-- `/settings` matches only the exact path `/settings`
-
-## Next Steps
-
-- Learn about [authentication providers](./authentication.md#authentication-providers) supported by
-  APIToGo
-- Configure [user data](./authentication.md#user-data) display