zuplo 6.67.32 → 6.68.0

package/docs/dev-portal/zudoku/customization/colors-theme.mdx

@@ -0,0 +1,275 @@
+---
+sidebar_icon: paintbrush
+title: Colors & Theme
+description:
+  Customize your Dev Portal site's colors and theme with flexible options, including light/dark modes,
+  custom CSS, and shadcn registry integration.
+---
+
+Dev Portal provides flexible theming options allowing you to customize colors, import themes from
+[shadcn registries](https://ui.shadcn.com/docs/registry), and add custom CSS. You can create
+cohesive light and dark mode experiences that match your brand.
+
+:::tip
+
+Try out the interactive [Theme Playground](https://zudoku.dev/docs/theme-playground) to experiment with colors and see
+real-time previews of your theme changes.
+
+:::
+
+The theme system is built on [shadcn/ui theming](https://ui.shadcn.com/docs/theming) and
+[Tailwind v4](https://tailwindcss.com), giving us a great foundation to build upon:
+
+- **CSS variables** match `shadcn/ui` conventions
+- **Tailwind v4** CSS variable system for modern styling
+- **Theme editors** like [tweakcn](https://tweakcn.com/) work out of the box
+- **Shadcn registries** are supported
+
+## Custom Colors
+
+You can manually define colors for both light and dark modes, either by extending the
+[default theme](#default-theme) or creating a completely custom theme. Colors can be specified as
+hex values, RGB, HSL, OKLCH, etc. - basically anything that is supported by
+[Tailwind CSS](https://tailwindcss.com):
+
+```ts title=zudoku.config.ts
+const config = {
+  theme: {
+    light: {
+      background: "#ffffff",
+      foreground: "#020817",
+      card: "#ffffff",
+      cardForeground: "#020817",
+      popover: "#ffffff",
+      popoverForeground: "#020817",
+      primary: "#0284c7",
+      primaryForeground: "#ffffff",
+      secondary: "#f1f5f9",
+      secondaryForeground: "#020817",
+      muted: "#f1f5f9",
+      mutedForeground: "#64748b",
+      accent: "#f1f5f9",
+      accentForeground: "#020817",
+      destructive: "#ef4444",
+      destructiveForeground: "#ffffff",
+      border: "#e2e8f0",
+      input: "#e2e8f0",
+      ring: "#0284c7",
+      radius: "0.5rem",
+    },
+    dark: {
+      background: "#020817",
+      foreground: "#f8fafc",
+      card: "#020817",
+      cardForeground: "#f8fafc",
+      popover: "#020817",
+      popoverForeground: "#f8fafc",
+      primary: "#0ea5e9",
+      primaryForeground: "#f8fafc",
+      secondary: "#1e293b",
+      secondaryForeground: "#f8fafc",
+      muted: "#1e293b",
+      mutedForeground: "#94a3b8",
+      accent: "#1e293b",
+      accentForeground: "#f8fafc",
+      destructive: "#ef4444",
+      destructiveForeground: "#f8fafc",
+      border: "#1e293b",
+      input: "#1e293b",
+      ring: "#0ea5e9",
+      radius: "0.5rem",
+    },
+  },
+};
+```
+
+## Available Theme Variables
+
+| Variable                | Description                           |
+| ----------------------- | ------------------------------------- |
+| `background`            | Main background color                 |
+| `foreground`            | Main text color                       |
+| `card`                  | Card background color                 |
+| `cardForeground`        | Card text color                       |
+| `popover`               | Popover background color              |
+| `popoverForeground`     | Popover text color                    |
+| `primary`               | Primary action color                  |
+| `primaryForeground`     | Text color on primary backgrounds     |
+| `secondary`             | Secondary action color                |
+| `secondaryForeground`   | Text color on secondary backgrounds   |
+| `muted`                 | Muted/subtle background color         |
+| `mutedForeground`       | Text color for muted elements         |
+| `accent`                | Accent color for highlights           |
+| `accentForeground`      | Text color on accent backgrounds      |
+| `destructive`           | Color for destructive actions         |
+| `destructiveForeground` | Text color on destructive backgrounds |
+| `border`                | Border color                          |
+| `input`                 | Input field border color              |
+| `ring`                  | Focus ring color                      |
+| `radius`                | Border radius value                   |
+
+:::note
+
+While shadcn/ui defines additional theme variables, Dev Portal currently uses only these core variables.
+
+:::
+
+## shadcn Registry Integration
+
+The easiest way to customize your theme is by using a Shadcn registry theme. For example you can use
+the great [tweakcn](https://tweakcn.com/) visual theme editor.
+
+### Using tweakcn Themes
+
+<Stepper>
+
+1. Visit [tweakcn.com](https://tweakcn.com/) to select a preset or customize your theme visually
+
+   <Framed align="start">![](./tweakcn0.webp)</Framed>
+   <Framed align="start">![](./tweakcn1.webp)</Framed>
+
+1. Copy the registry URL from the "Copy" section
+
+   <Framed align="start">![](./tweakcn2.webp)</Framed>
+
+1. Add it to your configuration:
+   ```ts title=zudoku.config.ts
+   const config = {
+     theme: {
+       registryUrl: "https://tweakcn.com/r/themes/northern-lights.json",
+     },
+   };
+   ```
+1. The theme will then be automatically imported with all color variables, fonts, and styling
+   configured for you 🚀
+
+   <Framed align="start">![](./tweakcn3.webp)</Framed>
+
+</Stepper>
+
+You can still override specific values if needed:
+
+```ts title=zudoku.config.ts
+const config = {
+  theme: {
+    registryUrl: "https://tweakcn.com/api/registry/theme/xyz123",
+    // Override specific colors
+    light: {
+      primary: "#0066cc",
+    },
+    dark: {
+      primary: "#3399ff",
+    },
+  },
+};
+```
+
+Alternatively, you can copy the CSS code and paste it into your `customCss` configuration:
+
+```ts title=zudoku.config.ts
+const config = {
+  theme: {
+    customCss: `
+      /* Copied CSS code */
+    `,
+  },
+};
+```
+
+## Custom CSS
+
+For advanced styling, you can add custom CSS either as a string or structured object:
+
+:::note
+
+Changes to `customCss` require restarting the development server to take effect.
+
+:::
+
+### CSS String
+
+```ts title=zudoku.config.ts
+const config = {
+  theme: {
+    customCss: `
+      .custom {
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      }
+    `,
+  },
+};
+```
+
+### CSS Object
+
+```ts title=zudoku.config.ts
+const config = {
+  theme: {
+    customCss: {
+      ".custom": {
+        background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
+      },
+    },
+  },
+};
+```
+
+## Default Theme
+
+Dev Portal comes with a built-in default theme based on
+[shadcn/ui zinc base colors](https://ui.shadcn.com/docs/theming#zinc). If you want to start
+completely from scratch without any default styling, you can disable the default theme:
+
+```ts title=zudoku.config.ts
+const config = {
+  theme: {
+    noDefaultTheme: true,
+    // Your custom theme configuration
+  },
+};
+```
+
+When `noDefaultTheme` is set to `true`, no default colors or styling will be applied, giving you
+complete control over your theme. Changing this requires to restart the development server.
+
+## Complete Example
+
+Here's a comprehensive example combining multiple theming approaches:
+
+```ts title=zudoku.config.ts
+const config = {
+  theme: {
+    // Import base theme from registry
+    registryUrl: "https://tweakcn.com/api/registry/theme/modern-blue",
+
+    // Override specific colors
+    light: {
+      primary: "#0066cc",
+      accent: "#f0f9ff",
+    },
+    dark: {
+      primary: "#3399ff",
+      accent: "#0c1b2e",
+    },
+
+    // Custom fonts
+    fonts: {
+      sans: "Inter",
+      mono: "JetBrains Mono",
+    },
+
+    // Additional custom styling
+    customCss: {
+      ".hero-section": {
+        background: "var(--primary)",
+        color: "var(--primary-foreground)",
+        padding: "2rem",
+        "border-radius": "var(--radius)",
+      },
+    },
+  },
+};
+```
+
+This configuration imports a base theme, customizes colors for both light and dark modes, sets
+fonts, and adds custom component styling.

package/docs/dev-portal/zudoku/customization/fonts.md

@@ -0,0 +1,110 @@
+---
+sidebar_icon: baseline
+title: Font & Typography
+sidebar_label: Font & Typography
+description:
+  Learn how to customize fonts and typography in Dev Portal using predefined Google Fonts, custom font
+  URLs, or local fonts for sans, serif, and monospace text.
+---
+
+Dev Portal allows you to customize fonts for text (`sans`), serif content (`serif`), and code (`mono`).
+You can use predefined Google Fonts, external sources, or local fonts.
+
+## Predefined Google Fonts
+
+The easiest way to use fonts is with predefined Google Fonts. Simply specify the font name as a
+string:
+
+```ts title=zudoku.config.ts
+const config = {
+  theme: {
+    fonts: {
+      sans: "Inter",
+      serif: "Merriweather",
+      mono: "JetBrains Mono",
+    },
+  },
+};
+```
+
+### Available Google Fonts
+
+The following fonts are available as predefined options:
+
+**Sans Serif:** Inter, Roboto, Open Sans, Poppins, Montserrat, Outfit, Plus Jakarta Sans, DM Sans,
+IBM Plex Sans, Geist, Oxanium, Space Grotesk
+
+**Serif:** Architects Daughter, Merriweather, Playfair Display, Lora, Source Serif Pro, Libre
+Baskerville
+
+**Monospace:** JetBrains Mono, Fira Code, Source Code Pro, IBM Plex Mono, Roboto Mono, Space Mono,
+Geist Mono
+
+## Custom Font URLs
+
+For more control or to use fonts not in the predefined list, you can specify a custom font URL:
+
+```ts title=zudoku.config.ts
+const config = {
+  theme: {
+    fonts: {
+      sans: {
+        url: "https://fonts.googleapis.com/css2?family=Roboto:wght@400;700&display=swap",
+        fontFamily: "Roboto, sans-serif",
+      },
+      mono: {
+        url: "https://fonts.googleapis.com/css2?family=Roboto+Mono:wght@400;700&display=swap",
+        fontFamily: "Roboto Mono, monospace",
+      },
+    },
+  },
+};
+```
+
+## Local Fonts
+
+To use local fonts, add them to the `public` folder and create a `fonts.css` file:
+
+```css
+@font-face {
+  font-family: "CustomFont";
+  font-style: normal;
+  font-weight: 400;
+  src: url("/custom-font-400.woff2") format("woff2");
+}
+```
+
+Then reference the local CSS file:
+
+```ts title=zudoku.config.ts
+const config = {
+  theme: {
+    fonts: {
+      sans: {
+        url: "/fonts.css",
+        fontFamily: "CustomFont, sans-serif",
+      },
+    },
+  },
+};
+```
+
+## Mixed Configuration
+
+You can mix predefined fonts with custom fonts:
+
+```ts title=zudoku.config.ts
+const config = {
+  theme: {
+    fonts: {
+      sans: "Inter", // Predefined Google Font
+      serif: {
+        // Custom font
+        url: "/custom-serif.css",
+        fontFamily: "CustomSerif, serif",
+      },
+      mono: "Fira Code", // Predefined Google Font
+    },
+  },
+};
+```

package/docs/dev-portal/zudoku/extending/events.md

@@ -0,0 +1,124 @@
+---
+title: Events
+sidebar_icon: shuffle
+---
+
+Dev Portal provides an events system that allows plugins to react to various application events. This
+system enables you to build dynamic features that respond to user interactions and application state
+changes.
+
+## Available Events
+
+Currently, Dev Portal supports the following events:
+
+### location
+
+```typescript
+type LocationEvent = (e: { from?: Location; to: Location }) => void;
+```
+
+Emitted when the user navigates to a different route. Provides both the previous (`from`) and
+current (`to`)
+[Location objects](https://api.reactrouter.com/v7/interfaces/react_router.Location.html) from
+react-router.
+
+Note that the `from` location will be undefined on the initial page load.
+
+## Consuming Events in Plugins
+
+To consume events in your plugin, you can implement the events property in your plugin. This is
+useful for performing actions like sending analytics events or anything else that's not directly
+related to the UI.
+
+```typescript
+import { ZudokuPlugin, ZudokuEvents } from "zudoku";
+
+const navigationLoggerPlugin: ZudokuPlugin = {
+  events: {
+    location: ({ from, to }) => {
+      if (!from) {
+        console.log(`Initial navigation to: ${to.pathname}`);
+      } else {
+        console.log(`User navigated from: ${from.pathname} to: ${to.pathname}`);
+      }
+    },
+  },
+};
+```
+
+### Example in Dev Portal Config
+
+In your `zudoku.config.ts`, you can define the events like this:
+
+```typescript
+export default {
+  plugins: [
+    {
+      events: {
+        location: ({ from, to }) => {
+          if (!from) return;
+
+          // E.g. send an analytics event
+          sendAnalyticsEvent({
+            from: from.pathname,
+            to: to.pathname,
+          });
+        },
+      },
+    },
+  ],
+};
+```
+
+## Using Events in Components
+
+Dev Portal provides a convenient `useEvent` hook to subscribe to events in your React components. The
+hook can be used in three different ways:
+
+### 1. Getting the Latest Event Data
+
+If you just want to access the latest event data without a callback:
+
+```typescript
+import { useEvent } from "zudoku/hooks";
+
+function MyComponent() {
+  const locationEvent = useEvent("location");
+  return <div>Current path: {locationEvent?.to.pathname}</div>;
+}
+```
+
+### 2. Using Event Data in a Component
+
+If you want to transform the event data, return a value from the callback:
+
+```typescript
+import { useEvent } from "zudoku/hooks";
+
+function MyComponent() {
+  const pathname = useEvent("location", ({ to }) => to.pathname);
+  return <div>Current path: {pathname}</div>;
+}
+```
+
+### 3. Using a Callback for Side Effects
+
+If you just want to perform side effects when the event occurs:
+
+```typescript
+import { useEvent } from "zudoku/hooks";
+
+function MyComponent() {
+  useEvent("location", ({ from, to }) => {
+    if (from) {
+      console.log(`Navigation: ${from.pathname} → ${to.pathname}`);
+    }
+    // No return value needed for side effects
+  });
+
+  return <div>My Component</div>;
+}
+```
+
+The `useEvent` hook automatically handles subscription and cleanup in the React lifecycle, making it
+easy to work with events in your components.

package/docs/dev-portal/zudoku/guides/custom-pages.md

@@ -0,0 +1,106 @@
+---
+title: Custom pages
+sidebar_icon: layers-3
+---
+
+If you want to include pages in your documentation that have greater flexibility than MDX pages, it
+is possible to include custom pages of your own.
+
+These pages are typically built using standard React markup and can borrow from a set of prebuilt
+components that Dev Portal already has such as buttons, links and headers.
+
+Start by creating the page you want to add.
+
+## Setup a custom page
+
+Each custom page is a page component of its own and lives in a `src` directory at the root of your
+project. Let's create the `<MyCustomPage />` component as an example.
+
+From the root of your project run this command:
+
+```bash
+touch src/MyCustomPage.tsx
+```
+
+You can now open `/src/MyCustomPage.tsx` in the editor of your choice. It will be empty.
+
+Copy and paste this code to implement the page:
+
+```tsx
+import { Button, Head, Link } from "zudoku/components";
+
+export const MyCustomPage = () => {
+  return (
+    <section className="">
+      <Head>
+        <title>My Custom Page</title>
+      </Head>
+      <div>
+        <p>Welcome to MyCustomPage</p>
+      </div>
+    </section>
+  );
+};
+```
+
+## Configuration
+
+In the [Dev Portal Configuration](../configuration/overview.md) you will need to do the following:
+
+### Change Your Config Extension
+
+In order to embed `jsx`/`tsx` components into your Dev Portal config, you will need to change your file
+extension from `ts` to `tsx` (or `js` to `jsx` if not using TypeScript).
+
+```
+zudoku.config.ts -> zudoku.config.tsx
+```
+
+### Import Your Module
+
+Import the `<MyCustomPage />` component that you created.
+
+```typescript
+import { MyCustomPage } from "./src/MyCustomPage";
+```
+
+### Add a navigation entry
+
+Add a `custom-page` item to the `navigation` configuration. Each page you want to add to the site
+must be its own object.
+
+The `path` key can be set to whatever you like. This will appear as part of the URL in the address
+bar of the browser.
+
+The `element` key references the name of the custom page component that you want to load.
+
+```typescript
+{
+  // ...
+  navigation: [
+    {
+      type: "custom-page",
+      path: "/a-custom-page",
+      element: <MyCustomPage />,
+    },
+  ]
+  // ...
+}
+```
+
+This configuration will allow Dev Portal to load the contents of the `<MyCustomPage />` component when a
+user clicks on a link that points to `/a-custom-page`.
+
+## Troubleshooting
+
+### Updating Your `tsconfig.json`
+
+Your `include` property in `tsconfig.json` should automatically be updated to reflect the new custom
+pages, but in case it isn't, it should look like this:
+
+```json
+{
+  ...
+  "include": ["src", "zudoku.config.tsx", "src/MyCustomPage.tsx"]
+}
+```

package/docs/dev-portal/zudoku/guides/environment-variables.md

@@ -0,0 +1,99 @@
+---
+title: Environment Variables
+sidebar_icon: table
+---
+
+Dev Portal is built on top of Vite and uses [their approach](https://vite.dev/guide/env-and-mode) for
+managing environment variables.
+
+Dev Portal exposes environment variables under the `import.meta.env` object as strings automatically.
+
+To prevent accidentally leaking environment variables to the client, only variables prefixed with
+`ZUDOKU_PUBLIC_` are exposed to your Zudoku-processed code.
+
+:::warning{title="Security Notice"}
+
+Environment variables prefixed with `ZUDOKU_PUBLIC_` will be exposed to the client-side code and
+visible in the browser. Never use this prefix for sensitive information like API keys, passwords, or
+other secrets.
+
+:::
+
+## Local Env Files
+
+When developing locally, you can create a `.env` file in the root of your project and add
+environment-specific variables. See the
+[Vite documentation](https://vite.dev/guide/env-and-mode.html#env-files) for more information on
+supported files.
+
+Here is an example of a `.env.local` file:
+
+```sh
+ZUDOKU_PUBLIC_PAGE_TITLE=My Page Title
+```
+
+You can access this variable in your application like this:
+
+```ts
+const title = import.meta.env.ZUDOKU_PUBLIC_PAGE_TITLE;
+```
+
+## Configuration Files
+
+Environment variables can also be used in your configuration files. When referencing environment
+variables in your configuration files, you can use `process.env` directly.
+
+```ts
+import type { ZudokuConfig } from "zudoku";
+
+const config: ZudokuConfig = {
+  authentication: {
+    type: "auth0",
+    clientId: process.env.ZUDOKU_PUBLIC_AUTH_CLIENT_ID,
+    domain: process.env.ZUDOKU_PUBLIC_AUTH_DOMAIN,
+  },
+};
+```
+
+## React Components
+
+If you need to access environment variables inside a custom react component, you can access them via
+`import.meta.env`. Public environment variables are inlined during the build process.
+
+```tsx
+import React from "react";
+
+export const MyComponent = () => {
+  return <h1>{import.meta.env.ZUDOKU_PUBLIC_PAGE_TITLE}</h1>;
+};
+```
+
+## IntelliSense for TypeScript
+
+By default, Dev Portal provides type definitions for `import.meta.env` in `zudoku/client.d.ts`. While
+you can define more custom env variables in `.env.[mode]` files, you may want to get TypeScript
+IntelliSense for user-defined env variables that are prefixed with `ZUDOKU_PUBLIC_`.
+
+To achieve this, you can create a `zudoku-env.d.ts` in the src directory, then augment
+`ImportMetaEnv` like this:
+
+```typescript
+/// <reference types="zudoku/client" />
+
+interface ImportMetaEnv {
+  readonly ZUDOKU_PUBLIC_APP_TITLE: string;
+  // more env variables...
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+```
+
+:::warning{title="Imports will break type augmentation"}
+
+If the `ImportMetaEnv` augmentation does not work, make sure you do not have any import statements
+in `vite-env.d.ts`. A helpful explanation can be found on
+[this StackOverflow reply](https://stackoverflow.com/a/51114250).
+
+:::