@bndynet/vue-site 1.0.0 → 1.0.1

package/dist/router.d.ts

@@ -1,3 +1,4 @@
+import { RouterHistory } from 'vue-router';
 import { NavItem, ResolvedNavItem, StandalonePage } from './types';
 /**
  * Recursively drop nav items whose `visible()` predicate resolves to `false`. Sibling
@@ -6,4 +7,4 @@ import { NavItem, ResolvedNavItem, StandalonePage } from './types';
  */
 export declare function filterNavItems(items: NavItem[]): Promise<NavItem[]>;
 export declare function resolveNavItems(items: NavItem[], parentIndex?: number): ResolvedNavItem[];
-export declare function createSiteRouter(resolvedNav: ResolvedNavItem[], pages?: StandalonePage[]): Promise<import('vue-router').Router>;
+export declare function createSiteRouter(resolvedNav: ResolvedNavItem[], pages?: StandalonePage[], history?: RouterHistory): Promise<import('vue-router').Router>;

package/dist/types.d.ts

@@ -1,5 +1,44 @@
 import { App, Component } from 'vue';
 import { UserConfig as ViteUserConfig } from 'vite';
+import { RouteLocationNormalized } from 'vue-router';
+/**
+ * Per-page authorization requirement. Attached to a `NavItem` / `StandalonePage` via `auth`
+ * and stored on the route's `meta`. It is opaque metadata interpreted by
+ * `SiteConfig.auth.authorize` — use `true` for "any authenticated user", a role name or list of
+ * roles, or a custom predicate. The framework never inspects the rule itself; it forwards it to
+ * `authorize`.
+ */
+export type AuthRule = boolean | string | string[] | ((ctx: AuthContext) => boolean | Promise<boolean>);
+/**
+ * Context passed to `SiteConfig.auth.authorize`. `to` / `from` are present when the guard runs
+ * during navigation; they are absent during the one-time startup pass that filters the nav menu.
+ */
+export interface AuthContext {
+    /** The `auth` rule declared on the matched nav / standalone item. */
+    rule: AuthRule;
+    /** The resolved nav item being evaluated, when available. */
+    item?: ResolvedNavItem;
+    /** Target route (navigation-time only). */
+    to?: RouteLocationNormalized;
+    /** Previous route (navigation-time only). */
+    from?: RouteLocationNormalized;
+}
+/** Central authorization policy. Configure once in `site.config.ts`; pages opt in with `auth`. */
+export interface AuthConfig {
+    /**
+     * Decide whether the current user may access a route carrying `rule`. Return `true` to allow,
+     * `false` to deny, or a path string to redirect (e.g. your login page). Runs at navigation time
+     * on every guarded route, and once at startup (with only `rule` / `item`) to filter the nav menu
+     * — there, any result other than `true` hides the item.
+     */
+    authorize: (ctx: AuthContext) => boolean | string | Promise<boolean | string>;
+    /**
+     * Where to send users when `authorize` returns `false`. The denied target is appended as a
+     * `redirect` query param (e.g. `/login?redirect=/admin`). If omitted, denied navigations are
+     * simply cancelled.
+     */
+    loginPath?: string;
+}
 export interface NavItem {
     label: string;
     icon?: string;
@@ -26,6 +65,14 @@ export interface NavItem {
      * permission changes (e.g. login/logout) without recreating the app.
      */
     visible?: () => boolean | Promise<boolean>;
+    /**
+     * Per-page authorization rule, interpreted by `SiteConfig.auth.authorize`. Unlike `visible`
+     * (a build/startup-time existence switch), `auth` keeps the route registered and is enforced by
+     * a navigation guard on every navigation, so it reacts to login/logout and can redirect to a
+     * login page. It is also evaluated once at startup to hide unauthorized items from the menu.
+     * Requires `SiteConfig.auth` to be set; otherwise it is ignored.
+     */
+    auth?: AuthRule;
 }
 /**
  * A standalone, full-screen page registered outside the `nav` tree.
@@ -46,6 +93,11 @@ export interface StandalonePage {
      * Evaluated only at startup, so it does not react to later permission changes.
      */
     visible?: () => boolean | Promise<boolean>;
+    /**
+     * Per-page authorization rule, interpreted by `SiteConfig.auth.authorize` and enforced by a
+     * navigation guard. See `NavItem.auth`. Requires `SiteConfig.auth` to be set.
+     */
+    auth?: AuthRule;
 }
 /** CSS custom properties for one theme (`--color-bg`, etc.). */
 export type ThemePaletteVars = Record<string, string>;
@@ -87,6 +139,24 @@ export interface ThemeConfig {
         dark?: ThemePaletteVars;
     };
 }
+/** Router history configuration. */
+export interface RouterConfig {
+    /**
+     * History mode:
+     * - `'hash'` (default) — URLs use a `#` fragment (e.g. `/app/#/admin`). Works on any static host
+     *   with no server config; route paths are independent of the public base.
+     * - `'web'` — HTML5 history with clean URLs (e.g. `/app/admin`). Requires the host to serve
+     *   `index.html` for unknown paths (SPA fallback).
+     * @default 'hash'
+     */
+    mode?: 'hash' | 'web';
+    /**
+     * Base path for `'web'` mode (ignored for `'hash'`). Defaults to the app's public base
+     * (`import.meta.env.BASE_URL`, set by the CLI's `--base` / `env.vite.base`). Set this only to
+     * override that default (e.g. when calling `createSiteApp` from a custom entry).
+     */
+    base?: string;
+}
 export type SiteViteConfig = Partial<Omit<ViteUserConfig, 'root'>> & {
     /** Options passed to @vitejs/plugin-vue (the Vue plugin is added automatically) */
     vue?: Record<string, any>;
@@ -127,6 +197,14 @@ export interface SiteConfig {
      * still applies via root CSS variables.
      */
     pages?: StandalonePage[];
+    /**
+     * Central authorization policy. When set, any `NavItem` / `StandalonePage` carrying an `auth`
+     * rule is enforced by a navigation guard (redirecting to `auth.loginPath` on denial) and hidden
+     * from the nav menu at startup when not authorized. Omit to disable authorization entirely.
+     */
+    auth?: AuthConfig;
+    /** Router history configuration (hash vs HTML5). See `RouterConfig`. */
+    router?: RouterConfig;
     theme?: ThemeConfig;
     footer?: string;
     readme?: string;
@@ -137,6 +215,12 @@ export interface SiteConfig {
      * then site root). Injected by the `vue-site` CLI; omit when calling `createSiteApp` manually.
      */
     packageRepository?: string | null;
+    /**
+     * App public base path. Injected by the `vue-site` CLI from `import.meta.env.BASE_URL` (the
+     * resolved Vite `base`) and used as the default base for `'web'` history mode. Prefer setting
+     * `router.base` to override; omit when calling `createSiteApp` manually.
+     */
+    baseUrl?: string;
     /** Development / build environment configuration */
     env?: SiteEnvConfig;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bndynet/vue-site",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "A configurable Vue 3 site framework with sidebar navigation, markdown rendering, and theme switching.",
   "repository": {