Feat/new docs

.claude/launch.json

@@ -7,6 +7,13 @@
 			"runtimeArgs": ["run", "--cwd", "client", "dev"],
 			"port": 5173,
 			"autoPort": true
+		},
+		{
+			"name": "docs-dev",
+			"runtimeExecutable": "bun",
+			"runtimeArgs": ["run", "--cwd", "docs", "dev"],
+			"port": 5174,
+			"autoPort": true
 		}
 	]
 }

Makefile

@@ -62,6 +62,9 @@ check: check/format check/lint check/typing check/cves check/security check/unus
 dev/client:
 	@ cd client && bun run dev
 
+dev/docs:
+	@ cd docs && bun run dev
+
 dev/example:
 	@ cd client && bun run build
 	@ PYTHONPATH=. uv run fastapi dev examples/main.py --host 0.0.0.0 --port $${PORT:-8000} --reload

docs/.gitignore

@@ -0,0 +1,25 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+config/.vitepress/cache

docs/config/.vitepress/config.mts

@@ -0,0 +1,62 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  srcDir: "../content",
+
+  title: "OpenAdmin",
+  description: "Admin panel for python",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Introduction', link: '/introduction/what-is-openadmin' },
+      { text: 'Components', link: '/components/' },
+      { text: 'Auth', link: '/auth/' },
+      { text: 'Cookbook', link: '/cookbook/implementing-auth' }
+    ],
+
+    sidebar: [
+      {
+        text: 'Introduction',
+        items: [
+          { text: 'What is OpenAdmin?', link: '/introduction/what-is-openadmin' },
+          { text: 'Getting Started', link: '/introduction/getting-started' }
+        ]
+      },
+      {
+        text: 'Components',
+        items: [
+          { text: 'Overview', link: '/components/' },
+          { text: 'Stat', link: '/components/stat' },
+          { text: 'Table', link: '/components/table' },
+          { text: 'Form', link: '/components/form' },
+          { text: 'Action', link: '/components/action' },
+          { text: 'Markdown', link: '/components/markdown' },
+          { text: 'Bar Chart', link: '/components/bar-chart' },
+          { text: 'Pie Chart', link: '/components/pie-chart' },
+          { text: 'Area Chart', link: '/components/area-chart' },
+          { text: 'Line Chart', link: '/components/line-chart' }
+        ]
+      },
+      {
+        text: 'Auth',
+        items: [
+          { text: 'Password Authentication', link: '/auth/' }
+        ]
+      },
+      {
+        text: 'Cookbook',
+        items: [
+          { text: 'Implementing Auth', link: '/cookbook/implementing-auth' },
+          { text: 'Implementing a Table', link: '/cookbook/implementing-table' },
+          { text: 'Implementing a Form with a Reference', link: '/cookbook/implementing-form-with-reference' }
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/openadmin-team/openadmin-py' }
+    ]
+  }
+})

docs/config/.vitepress/theme/index.ts

@@ -0,0 +1,17 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import './style.css'
+
+export default {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {
+      // https://vitepress.dev/guide/extending-default-theme#layout-slots
+    })
+  },
+  enhanceApp({ app, router, siteData }) {
+    // ...
+  }
+} satisfies Theme

docs/config/.vitepress/theme/style.css

@@ -0,0 +1,131 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
+ * Colors
+ *
+ * Each colors have exact same color scale system with 3 levels of solid
+ * colors with different brightness, and 1 soft color.
+ *
+ * - `XXX-1`: The most solid color used mainly for colored text. It must
+ *   satisfy the contrast ratio against when used on top of `XXX-soft`.
+ *
+ * - `XXX-2`: The color used mainly for hover state of the button.
+ *
+ * - `XXX-3`: The color for solid background, such as bg color of the button.
+ *   It must satisfy the contrast ratio with pure white (#ffffff) text on
+ *   top of it.
+ *
+ * - `XXX-soft`: The color used for subtle background such as custom container
+ *   or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
+ *   on top of it.
+ *
+ *   The soft color must be semi transparent alpha channel. This is crucial
+ *   because it allows adding multiple "soft" colors on top of each other
+ *   to create an accent, such as when having inline code block inside
+ *   custom containers.
+ *
+ * - `default`: The color used purely for subtle indication without any
+ *   special meanings attached to it such as bg color for menu hover state.
+ *
+ * - `brand`: Used for primary brand colors, such as link text, button with
+ *   brand theme, etc.
+ *
+ * - `tip`: Used to indicate useful information. The default theme uses the
+ *   brand color for this by default.
+ *
+ * - `warning`: Used to indicate warning to the users. Used in custom
+ *   container, badges, etc.
+ *
+ * - `danger`: Used to show error, or dangerous message to the users. Used
+ *   in custom container, badges, etc.
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-c-default-1: var(--vp-c-gray-1);
+  --vp-c-default-2: var(--vp-c-gray-2);
+  --vp-c-default-3: var(--vp-c-gray-3);
+  --vp-c-default-soft: var(--vp-c-gray-soft);
+
+  --vp-c-brand-1: var(--vp-c-indigo-1);
+  --vp-c-brand-2: var(--vp-c-indigo-2);
+  --vp-c-brand-3: var(--vp-c-indigo-3);
+  --vp-c-brand-soft: var(--vp-c-indigo-soft);
+
+  --vp-c-tip-1: var(--vp-c-brand-1);
+  --vp-c-tip-2: var(--vp-c-brand-2);
+  --vp-c-tip-3: var(--vp-c-brand-3);
+  --vp-c-tip-soft: var(--vp-c-brand-soft);
+
+  --vp-c-warning-1: var(--vp-c-yellow-1);
+  --vp-c-warning-2: var(--vp-c-yellow-2);
+  --vp-c-warning-3: var(--vp-c-yellow-3);
+  --vp-c-warning-soft: var(--vp-c-yellow-soft);
+
+  --vp-c-danger-1: var(--vp-c-red-1);
+  --vp-c-danger-2: var(--vp-c-red-2);
+  --vp-c-danger-3: var(--vp-c-red-3);
+  --vp-c-danger-soft: var(--vp-c-red-soft);
+}
+
+/**
+ * Component: Button
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-text: var(--vp-c-white);
+  --vp-button-brand-bg: var(--vp-c-brand-3);
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-hover-text: var(--vp-c-white);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
+  --vp-button-brand-active-border: transparent;
+  --vp-button-brand-active-text: var(--vp-c-white);
+  --vp-button-brand-active-bg: var(--vp-c-brand-1);
+}
+
+/**
+ * Component: Home
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    #bd34fe 30%,
+    #41d1ff
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    #bd34fe 50%,
+    #47caff 50%
+  );
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(68px);
+  }
+}
+
+/**
+ * Component: Custom Block
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-custom-block-tip-border: transparent;
+  --vp-custom-block-tip-text: var(--vp-c-text-1);
+  --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
+  --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
+}
+

docs/content/auth/index.md

@@ -0,0 +1,96 @@
+# Authentication
+
+`AdminAuth` holds three hooks — login, authenticate, and logout — and `AdminPanel` wires them into the panel's routes for you.
+
+```python
+from openadmin.fastapi import AdminAuth
+
+auth = AdminAuth()
+```
+
+::: warning No protection by default
+An `AdminAuth()` instance's three hooks are no-op stubs until you override them: `login` and `logout` do nothing, and `authenticate` never raises — so it lets every request through. Passing `auth=None` to `AdminPanel` (the default) is equivalent: no `/auth/*` routes are even mounted, and `/api/*` is completely open. Either way, nothing is actually gated until you decorate all three hooks yourself.
+:::
+
+## The three hooks
+
+```python
+@auth.login()
+def login(req: Request, login_req: LoginReq) -> None: ...
+
+@auth.authenticate()
+def authenticate(req: Request) -> None: ...
+
+@auth.logout()
+def logout(req: Request) -> None: ...
+```
+
+Each decorator just stores the function you give it — it doesn't wrap or alter it, so the function can still be called or tested directly like any other. Each hook may be sync or async (`None | Awaitable[None]`).
+
+- **`login_func(req, login_req)`** — receives a `LoginReq` (`{username: str, password: str}`, a pydantic model). Raise an `HTTPException` to reject the credentials; return normally to accept them. This is where you'd typically write something into `req.session`.
+- **`authenticate_func(req)`** — runs as a dependency on **every** request under `/api/*`, i.e. every stat, table, form, action, chart, and markdown endpoint on every page. Raise an `HTTPException` (typically 401) to reject the request; return normally to allow it.
+- **`logout_func(req)`** — typically clears `req.session`. It runs behind `authenticate_func` itself, so a caller must already be authenticated to log out.
+
+## How `AdminPanel` wires them up
+
+Passing `auth=` to `AdminPanel(...)` does three things:
+
+1. Mounts `POST /auth/login`, calling your `login_func` and returning `204 No Content` on success.
+2. Mounts `POST /auth/logout`, calling your `logout_func`, itself gated behind `authenticate_func`.
+3. Adds `authenticate_func` as a router-level dependency on the entire `/api` router — so it runs before any component endpoint, panel-wide, with no per-page or per-component opt-in needed.
+
+The frontend's static assets (served at `/`) and the login endpoint itself are intentionally not gated, since a client needs to load the login screen and call `/auth/login` before it has anything to authenticate with.
+
+## Example
+
+```python
+# admin/auth.py
+from fastapi import HTTPException, Request, status
+
+from openadmin.fastapi import AdminAuth, LoginReq
+
+auth = AdminAuth()
+
+
+@auth.login()
+def login(req: Request, login_req: LoginReq) -> None:
+    if login_req.username == "admin" and login_req.password == "admin":
+        req.session.update({"token": "admin-token"})
+    else:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid username or password")
+
+
+@auth.authenticate()
+def authenticate(req: Request) -> None:
+    if req.session.get("token") != "admin-token":
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Unauthorized")
+
+
+@auth.logout()
+def logout(req: Request) -> None:
+    req.session.clear()
+```
+
+`req.session` comes from Starlette's `SessionMiddleware`, added on the *outer* application — not on `admin.app` — since middleware on the outer app also covers requests routed into the mounted sub-app:
+
+```python
+# main.py
+from fastapi import FastAPI
+from starlette.middleware.sessions import SessionMiddleware
+
+from openadmin.fastapi import AdminPanel
+
+from .admin.auth import auth
+
+app = FastAPI()
+app.add_middleware(SessionMiddleware, secret_key="change-me")
+
+admin = AdminPanel("My Admin", auth=auth)
+app.mount("/admin", admin.app)
+```
+
+::: danger
+Cookie-based sessions are only as secure as `secret_key`. Never hardcode it — load it from an environment variable or secret store — and compare credentials with a real user store and hashed passwords, not the plaintext check shown above.
+:::
+
+See [Implementing Auth](/cookbook/implementing-auth) for a full step-by-step recipe.