@bndynet/vue-site 1.0.0 → 1.0.2

package/README.md

@@ -6,6 +6,8 @@ Configurable Vue 3 site framework: one package, `site.config.ts`, and Markdown p
 
 - Config-driven nav (Lucide icon names)
 - Permission-gated nav via a `visible` predicate (sync or async; hides item and skips its route)
+- Per-page authorization via `auth` + a central `authorize` policy (navigation guard + login redirect)
+- Hash or HTML5 (`web`) router history, configurable in `site.config.ts`
 - Markdown (`?raw`) or Vue pages
 - highlight.js, light/dark theme + localStorage
 - Project `README.md` as Home
@@ -74,6 +76,9 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 | `footer` | Footer text |
 | `readme` | Raw Home content if no `README.md` |
 | `links` | Header links: Lucide `icon` + `link`, optional `title` |
+| `pages` | `StandalonePage[]` — full-screen routes outside the `nav` tree (no top bar/sidebar/footer) |
+| `auth` | Central authorization policy (`AuthConfig`) — see [Per-page authorization](#per-page-authorization-auth) |
+| `router` | History mode (`RouterConfig`) — `hash` (default) or HTML5 `web`; see [Router history](#router-history-router) |
 | `packageRepository` | Usually set by CLI from `package.json`; omit when using `createSiteApp` alone |
 | `env` | Dev/build options — see below |
 | `bootstrap` | Optional path from site root (e.g. `./bootstrap.ts`) — module loaded once before the Vue app |
@@ -90,6 +95,7 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 | `children` | Nested group |
 | `link` | Render as a hyperlink (internal route path or external URL) instead of a page route |
 | `visible` | `() => boolean \| Promise<boolean>`, awaited once at startup. Return `false` to hide the item from the nav and skip its route (not reachable by direct URL). A hidden parent hides its subtree; a group with no remaining children is pruned. Not reactive to later changes. |
+| `auth` | Authorization rule (`AuthRule`) interpreted by `auth.authorize`. Keeps the route registered and enforces it via a navigation guard (so direct URLs redirect to login). Requires `SiteConfig.auth`. See [Per-page authorization](#per-page-authorization-auth). |
 
 ### `ThemeConfig`
 
@@ -100,6 +106,90 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 | `palettes` | — | Partial overrides for built-in light/dark only |
 | `extraThemes` | — | Extra themes: `id`, `label`, `icon`, optional `basedOn`, `palette`; import `builtinThemePalettes` for full defaults |
 
+## Per-page authorization (`auth`)
+
+Gate individual pages on the current user. Add an `auth` rule to any `NavItem` or `StandalonePage`, and a single `auth.authorize` policy in `SiteConfig` to decide access.
+
+```typescript
+import { defineConfig } from '@bndynet/vue-site'
+
+export default defineConfig({
+  title: 'My Site',
+  auth: {
+    loginPath: '/login',
+    authorize: ({ rule }) => {
+      const user = getCurrentUser() // your own auth state
+      if (!user) return '/login' // not signed in -> redirect (string)
+      if (rule === true) return true // `auth: true` -> any signed-in user
+      if (typeof rule === 'string') return user.roles.includes(rule)
+      if (Array.isArray(rule)) return rule.some((r) => user.roles.includes(r))
+      return true
+    },
+  },
+  nav: [
+    { label: 'Home', icon: 'home', page: () => import('../README.md?raw') },
+    { label: 'Dashboard', icon: 'gauge', auth: true, page: () => import('./pages/Dash.vue') },
+    { label: 'Admin', icon: 'shield', auth: ['admin'], page: () => import('./pages/Admin.vue') },
+  ],
+  pages: [
+    { path: '/login', page: () => import('./pages/Login.vue') }, // no `auth` -> always reachable
+  ],
+})
+```
+
+### How it works
+
+- `authorize` runs **on every navigation** (a Vue Router `beforeEach` guard). It receives `{ rule, item, to, from }` and returns `true` (allow), `false` (deny), or a path `string` (redirect, e.g. to a login page).
+- On `false`, the user is sent to `auth.loginPath` with the requested path as a `redirect` query (`/login?redirect=/admin`); if `loginPath` is unset, the navigation is cancelled.
+- `authorize` also runs **once at startup** (with only `rule` / `item`) to hide unauthorized items from the nav menu. Like `visible`, this menu filtering is not reactive — it reflects the state at app creation, so update it by recreating the app (e.g. a full reload after login).
+- Guarded routes stay **registered**, so visiting a protected URL directly triggers the guard (and your login redirect) rather than silently 404-ing.
+- The login page itself must **not** carry an `auth` rule (and `loginPath` is always allowed by the guard) to avoid redirect loops.
+
+### `AuthConfig`
+
+| Property | Description |
+|----------|-------------|
+| `authorize` | `(ctx: AuthContext) => boolean \| string \| Promise<boolean \| string>`. `true` allows, `false` denies, a `string` redirects. |
+| `loginPath` | Where to send denied users (with `?redirect=`). Optional; without it, denials cancel navigation. |
+
+`AuthRule` is `boolean \| string \| string[] \| ((ctx: AuthContext) => boolean \| Promise<boolean>)`. The framework never inspects the rule; it forwards it to `authorize`, so its meaning is entirely up to you.
+
+### `visible` vs `auth`
+
+| | `visible` | `auth` |
+|--|-----------|--------|
+| Decides | Whether the item/route **exists** | Whether the **current user** may enter |
+| When | Build/startup (once) | Navigation (every time) + startup for menu filtering |
+| Route registered | No (unreachable by URL) | Yes (guarded; can redirect to login) |
+| Reacts to login/logout | No | Guard yes; menu filtering no |
+| Best for | Env / feature-flag / static trimming | Login state, roles, login redirects |
+
+Use `visible` for static existence trimming and `auth` for user-based access. They can be combined on the same item.
+
+## Router history (`router`)
+
+By default routes use **hash** history (`#/path`), which works on any static host with no server configuration and is independent of the public base. To get clean URLs, switch to HTML5 history:
+
+```typescript
+export default defineConfig({
+  title: 'My Site',
+  router: { mode: 'web' }, // /app/admin instead of /app/#/admin
+  nav: [/* ... */],
+})
+```
+
+### `RouterConfig`
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `mode` | `hash` | `hash` (`#/path`, no server config) or `web` (HTML5 clean URLs) |
+| `base` | `import.meta.env.BASE_URL` | Base path for `web` mode. The CLI sets this from `--base` / `env.vite.base` automatically; override only when calling `createSiteApp` from a custom entry. |
+
+Notes:
+
+- **`web` mode requires SPA fallback**: configure your host to serve `index.html` for unknown paths, otherwise deep links / refreshes 404. Hash mode needs nothing.
+- **Subpath deploys**: with the CLI, `--base=/app/` is picked up automatically as the history base in `web` mode. In [library mode](#library-mode), pass `router: { mode: 'web', base: import.meta.env.BASE_URL }` from your own entry.
+
 ## `env` (`SiteEnvConfig`)
 
 | Property | Description |
@@ -152,7 +242,7 @@ app.mount('#app')
 
 Use a top-level `await` in your entry (or an async IIFE): `createSiteApp` is async and **awaits** `configureApp` when it returns a `Promise`. If you set optional `bootstrap` in config, that module loads before the app is created; if you omit `bootstrap`, that step is skipped.
 
-Exports: `createSiteApp`, `defineConfig`, `useTheme`, `useSiteConfig`, `themeRefKey`. Types: `SiteConfig`, `SiteEnvConfig`, `SiteViteConfig`, `SiteExternalLink`, `NavItem`, `ThemeConfig`, `ThemeOption`, `ThemePaletteVars`, `ResolvedNavItem`.
+Exports: `createSiteApp`, `defineConfig`, `useTheme`, `useSiteConfig`, `themeRefKey`. Types: `SiteConfig`, `SiteEnvConfig`, `SiteViteConfig`, `SiteExternalLink`, `NavItem`, `StandalonePage`, `AuthRule`, `AuthContext`, `AuthConfig`, `RouterConfig`, `ThemeConfig`, `ThemeOption`, `ThemePaletteVars`, `ResolvedNavItem`.
 
 ### Theme in Vue pages (`useTheme`)
 

package/bin/vue-site.mjs

@@ -205,6 +205,7 @@ function buildBootstrapScript({ siteConfig, siteConfigSpecifier }) {
     `    ...siteConfig,`,
     `    ...(hasThemeQuery ? { theme: { ...(siteConfig.theme || {}), default: resolvedTheme } } : {}),`,
     `    packageRepository: repositoryUrl,`,
+    `    baseUrl: import.meta.env.BASE_URL,`,
     `  })`,
     `  app.mount('#app')`,
     `})()`,

package/dist/auth.d.ts

@@ -0,0 +1,22 @@
+import { Router } from 'vue-router';
+import { AuthConfig, ResolvedNavItem } from './types';
+/** Query param carrying the originally requested path when redirecting to the login page. */
+export declare const AUTH_REDIRECT_QUERY = "redirect";
+/**
+ * Startup-once pass that drops nav items the current user is not authorized to see, so they do not
+ * appear in the rendered menu. Mirrors the pruning of `filterNavItems`: a hidden parent removes its
+ * subtree, and a group left with no children and no own `page` / `link` is pruned. Routes are not
+ * affected (they are still registered by `createSiteRouter`); only the menu list is filtered. An
+ * item is shown only when `authorize` returns exactly `true`.
+ */
+export declare function pruneNavByAuth(items: ResolvedNavItem[], auth: AuthConfig): Promise<ResolvedNavItem[]>;
+/**
+ * Install a global `beforeEach` guard that enforces a route's `meta.auth` rule at navigation time.
+ *
+ * - Routes without an `auth` rule (or with `false`) are always allowed.
+ * - The configured `loginPath` is always allowed (so the login page itself is reachable; prevents loops).
+ * - Otherwise `authorize` is called: `true` allows, a string redirects (to that path; allowed as-is
+ *   when it equals the current path to avoid loops), and `false` redirects to `loginPath` with a
+ *   `redirect` query of the requested path (or cancels the navigation when no `loginPath` is set).
+ */
+export declare function applyAuthGuard(router: Router, auth: AuthConfig): void;

package/dist/index.d.ts

@@ -4,5 +4,5 @@ export { useTheme, themeRefKey } from './composables/useTheme';
 export { useSiteConfig } from './composables/useSiteConfig';
 export { builtinThemePalettes } from './theme/presets';
 export { ElMessage, ElMessageBox, ElNotification, } from 'element-plus';
-export type { SiteConfig, SiteEnvConfig, SiteViteConfig, SiteExternalLink, NavItem, StandalonePage, ThemeConfig, ThemeOption, ThemePaletteVars, ResolvedNavItem, } from './types';
+export type { SiteConfig, SiteEnvConfig, SiteViteConfig, SiteExternalLink, NavItem, StandalonePage, AuthRule, AuthContext, AuthConfig, RouterConfig, ThemeConfig, ThemeOption, ThemePaletteVars, ResolvedNavItem, } from './types';
 export declare function defineConfig(config: SiteConfig): SiteConfig;