ding-react-admin 1.0.0

package/src/pages/PlaceholderPage.tsx

@@ -0,0 +1,9 @@
+import { Typography } from "antd";
+
+export function PlaceholderPage({ title }: { title: string }) {
+  return (
+    <Typography.Title level={3} style={{ marginTop: 0 }}>
+      {title}
+    </Typography.Title>
+  );
+}

package/src/permissions/resourcePermissions.ts

@@ -0,0 +1,47 @@
+import type { PermissionsChecker } from "../context/PermissionsProvider";
+
+/** Opaque permission strings per CRUD action (values come from your backend). */
+export type ResourcePermissions = {
+  /** List page, nav, route guard */
+  list?: string;
+  /** getOne — falls back to `list` when omitted */
+  read?: string;
+  /** New button, create modal, POST */
+  add?: string;
+  /** Edit / Quick edit, PATCH/PUT */
+  change?: string;
+  /** Row delete, bulk delete */
+  delete?: string;
+};
+
+export type ResourcePermissionSlot = keyof ResourcePermissions;
+
+/** When `permissions` is omitted, allow. When provided, missing slot → deny. */
+export function checkResourcePermission(
+  can: PermissionsChecker,
+  permissions: ResourcePermissions | undefined,
+  slot: ResourcePermissionSlot,
+): boolean {
+  if (!permissions) return true;
+  let perm = permissions[slot];
+  if (slot === "read" && !perm) perm = permissions.list;
+  if (!perm) return false;
+  return can(perm);
+}
+
+export function filterNavByPermission<T extends { permission?: string; children?: T[] }>(
+  items: T[],
+  can: PermissionsChecker,
+): T[] {
+  return items
+    .map((item) => {
+      if (item.children?.length) {
+        const children = filterNavByPermission(item.children, can);
+        if (children.length === 0) return null;
+        return { ...item, children };
+      }
+      if (item.permission && !can(item.permission)) return null;
+      return item;
+    })
+    .filter((item): item is T => item !== null);
+}

package/src/router/createAdminRouter.tsx

@@ -0,0 +1,64 @@
+import { Navigate, createBrowserRouter } from "react-router-dom";
+import { AdminLayout } from "../layouts/AdminLayout";
+import type { CreateAdminRouterOptions } from "../types";
+import { GuestOnly, Protected } from "./guards";
+import {
+  deriveAuthPaths,
+  partitionAdminRoutes,
+  toProtectedRouteObject,
+  toRouterSegment,
+} from "./routeAccess";
+
+export function createAdminRouter({
+  navItems,
+  children,
+  layoutProps,
+  redirects,
+}: CreateAdminRouterOptions) {
+  const { loginPath, homePath } = deriveAuthPaths(children, redirects);
+  const { guest, public: publicRoutes, protected: protectedRoutes } =
+    partitionAdminRoutes(children);
+
+  const routerRoutes = [];
+
+  for (const route of guest) {
+    if (!("path" in route) || !route.path) continue;
+    routerRoutes.push({
+      path: toRouterSegment(route.path),
+      element: (
+        <GuestOnly redirectTo={homePath}>{route.element}</GuestOnly>
+      ),
+    });
+  }
+
+  for (const route of publicRoutes) {
+    if (!("path" in route) || !route.path) continue;
+    routerRoutes.push({
+      path: toRouterSegment(route.path),
+      element: route.element,
+    });
+  }
+
+  if (protectedRoutes.length > 0) {
+    routerRoutes.push({
+      path: "/",
+      element: (
+        <Protected redirectTo={loginPath}>
+          <AdminLayout
+            navItems={navItems}
+            loginPath={loginPath}
+            {...layoutProps}
+          />
+        </Protected>
+      ),
+      children: protectedRoutes.map(toProtectedRouteObject),
+    });
+  }
+
+  routerRoutes.push({
+    path: "*",
+    element: <Navigate to={homePath} replace />,
+  });
+
+  return createBrowserRouter(routerRoutes);
+}

package/src/router/guards.tsx

@@ -0,0 +1,63 @@
+import type { ReactElement } from "react";
+import { Navigate } from "react-router-dom";
+import { useAuth } from "../context/AuthProvider";
+import { usePermissions } from "../context/PermissionsProvider";
+
+export function Guard({
+  when,
+  redirect,
+  children,
+}: {
+  when: boolean;
+  redirect: string;
+  children: ReactElement;
+}) {
+  return when ? children : <Navigate to={redirect} replace />;
+}
+
+export function Protected({
+  children,
+  redirectTo = "/login",
+}: {
+  children: ReactElement;
+  redirectTo?: string;
+}) {
+  const { isAuthenticated } = useAuth();
+  return (
+    <Guard when={isAuthenticated} redirect={redirectTo}>
+      {children}
+    </Guard>
+  );
+}
+
+export function GuestOnly({
+  children,
+  redirectTo = "/",
+}: {
+  children: ReactElement;
+  redirectTo?: string;
+}) {
+  const { isAuthenticated } = useAuth();
+  return (
+    <Guard when={!isAuthenticated} redirect={redirectTo}>
+      {children}
+    </Guard>
+  );
+}
+
+export function RequirePermission({
+  permission,
+  redirect,
+  children,
+}: {
+  permission: string;
+  redirect: string;
+  children: ReactElement;
+}) {
+  const can = usePermissions();
+  return (
+    <Guard when={can(permission)} redirect={redirect}>
+      {children}
+    </Guard>
+  );
+}

package/src/router/routeAccess.ts

@@ -0,0 +1,89 @@
+import type { RouteObject } from "react-router-dom";
+import type { AdminRouteChild, AuthRedirects, RouteAccess } from "../types";
+
+export function getRouteAccess(route: AdminRouteChild): RouteAccess {
+  return route.access ?? "protected";
+}
+
+export function partitionAdminRoutes(routes: AdminRouteChild[]) {
+  const guest: AdminRouteChild[] = [];
+  const publicRoutes: AdminRouteChild[] = [];
+  const protectedRoutes: AdminRouteChild[] = [];
+
+  for (const route of routes) {
+    const access = getRouteAccess(route);
+    if (access === "guest") guest.push(route);
+    else if (access === "public") publicRoutes.push(route);
+    else protectedRoutes.push(route);
+  }
+
+  return { guest, public: publicRoutes, protected: protectedRoutes };
+}
+
+/** React Router path segment for a top-level route (`/login` → `login`). */
+export function toRouterSegment(path: string): string {
+  return path.replace(/^\/+/, "");
+}
+
+export function toAbsolutePath(path: string): string {
+  return `/${toRouterSegment(path)}`;
+}
+
+/**
+ * Resolve redirect targets from declared routes and optional overrides.
+ * Throws when protected or guest routes exist but paths cannot be determined.
+ */
+export function deriveAuthPaths(
+  routes: AdminRouteChild[],
+  redirects?: AuthRedirects,
+): { loginPath: string; homePath: string } {
+  const { guest, protected: protectedRoutes } = partitionAdminRoutes(routes);
+  const firstGuest = guest.find((r) => "path" in r && r.path);
+  const indexProtected = protectedRoutes.find(
+    (r) => "index" in r && r.index,
+  );
+  const firstProtectedPath = protectedRoutes.find(
+    (r) => "path" in r && r.path,
+  );
+
+  let loginPath: string | undefined = redirects?.unauthenticated;
+  if (!loginPath && firstGuest && "path" in firstGuest && firstGuest.path) {
+    loginPath = toAbsolutePath(firstGuest.path);
+  }
+
+  let homePath: string | undefined = redirects?.afterLogin;
+  if (!homePath) {
+    if (indexProtected) homePath = "/";
+    else if (
+      firstProtectedPath &&
+      "path" in firstProtectedPath &&
+      firstProtectedPath.path
+    ) {
+      homePath = toAbsolutePath(firstProtectedPath.path);
+    }
+  }
+
+  if (protectedRoutes.length > 0 && !loginPath) {
+    throw new Error(
+      'createAdminRouter: protected routes require redirects.unauthenticated or a guest route (access: "guest").',
+    );
+  }
+
+  if (guest.length > 0 && !homePath) {
+    throw new Error(
+      'createAdminRouter: guest routes require redirects.afterLogin or a protected route (index or path).',
+    );
+  }
+
+  return {
+    loginPath: loginPath ?? "/",
+    homePath: homePath ?? "/",
+  };
+}
+
+export function toProtectedRouteObject(route: AdminRouteChild): RouteObject {
+  if ("index" in route && route.index) {
+    return { index: true, element: route.element };
+  }
+  return { path: route.path!, element: route.element };
+}

package/src/types.ts

@@ -0,0 +1,135 @@
+import type { MenuProps } from "antd";
+import type { ReactElement, ReactNode } from "react";
+
+export type ThemeMode = "light" | "dark" | "system";
+
+export type ThemeDensity = "comfortable" | "compact";
+
+/**
+ * Sidebar / app-hub navigation row. Maps to Ant Design `Menu` items.
+ *
+ * - **`children`** — nested submenu; parent rows should use a `path` that you **do not** navigate to as a leaf (for example `/catalog`), unless you define that route.
+ * - **`label`** — string or any React node (badges, extra markup).
+ * - **`Icon`** — optional; omit on group-only rows if you prefer text-only labels.
+ */
+export type NavItem = {
+  /** Menu item key and `navigate()` target for leaf items (pathname). Parents use this as submenu key. */
+  path: string;
+  label: ReactNode;
+  Icon?: React.ComponentType;
+  /** Hide this item when the user lacks this permission string. */
+  permission?: string;
+  children?: NavItem[];
+};
+
+/** Credentials passed from login forms to `AuthAdapter.login` and `useAuth().login`. */
+export type LoginCredentials = {
+  username: string;
+  password: string;
+  [key: string]: unknown;
+};
+
+/** Pluggable login/logout/token backend (e.g. sessionStorage, your REST API). */
+export type AuthAdapter = {
+  login: (credentials: LoginCredentials) => Promise<void>;
+  logout: () => void;
+  /** Synchronous read of session (e.g. token). Used after mount and after login/logout. */
+  getToken: () => string | null;
+};
+
+/** How a route participates in auth when using `AdminApp` / `createAdminRouter`. */
+export type RouteAccess =
+  /** Inside `AdminLayout`; requires a session. Default. */
+  | "protected"
+  /** Top-level; no session required (signup, forgot-password, etc.). */
+  | "public"
+  /** Top-level; only for guests (`GuestOnly`). Use for login. */
+  | "guest";
+
+export type AuthRedirects = {
+  /** Where unauthenticated users are sent. Required with protected routes unless a guest route is declared. */
+  unauthenticated?: string;
+  /** After login and when visiting guest routes while authenticated. Required with guest routes unless a protected route is declared. */
+  afterLogin?: string;
+};
+
+export type AppThemeProviderProps = {
+  children: ReactNode;
+  /** localStorage key for theme mode. Default `ding-react-admin-theme-mode`. */
+  modeStorageKey?: string;
+  /** localStorage key for density. Default `ding-react-admin-theme-density`. */
+  densityStorageKey?: string;
+};
+
+export type AdminLayoutProps = {
+  navItems: NavItem[];
+  /** Shown in sider header when expanded; drawer title on mobile. */
+  brand?: ReactNode;
+  /** Shown in sider header when collapsed. */
+  collapsedBrand?: ReactNode;
+  /** Optional drawer title override (defaults to `brand`). */
+  mobileDrawerTitle?: ReactNode;
+  headerExtras?: ReactNode;
+  /** Full menu items for the account dropdown. If omitted, a default “Log out” item is used. */
+  userMenuItems?: MenuProps["items"];
+  onUserMenuClick?: MenuProps["onClick"];
+  /** Where to send the user after logout. Default `/login`. */
+  loginPath?: string;
+  /** localStorage key for sider collapsed state. Default `ding-react-admin-sider-collapsed`. */
+  siderCollapsedStorageKey?: string;
+};
+
+export type { AuthPageLayoutProps } from "./layouts/AuthPageLayout";
+export type { AuthAlternateLinkProps } from "./components/AuthAlternateLink";
+
+export type LoginPageProps = {
+  title?: ReactNode;
+  description?: ReactNode;
+  /** @deprecated Use `brand` — shown above the card, not in the card header. */
+  logo?: ReactNode;
+  /** Brand mark centered above the card. */
+  brand?: ReactNode;
+  /** Extra form items rendered before the submit button. */
+  extraFields?: ReactNode;
+  showThemeToolbar?: boolean;
+  /** Navigate here after successful login. Default `/`. */
+  afterLoginPath?: string;
+  /** Row below the card linking to registration (or another auth flow). */
+  alternateAuth?: {
+    prompt?: string;
+    linkText: string;
+    to: string;
+  };
+  /** Custom footer below the card; overrides `alternateAuth` when set. */
+  footer?: ReactNode;
+};
+
+type AdminRouteChildBase = {
+  element: ReactElement;
+  /** Default `protected`. See [docs/routing.md](../docs/routing.md). */
+  access?: RouteAccess;
+};
+
+/** Route list for `AdminApp` / `createAdminRouter`. */
+export type AdminRouteChild =
+  | (AdminRouteChildBase & { index: true; path?: undefined })
+  | (AdminRouteChildBase & { path: string; index?: undefined });
+
+export type CreateAdminRouterOptions = {
+  navItems: NavItem[];
+  /** App routes; split by `access` into guest, public, and protected segments. */
+  children: AdminRouteChild[];
+  layoutProps?: Partial<AdminLayoutProps>;
+  redirects?: AuthRedirects;
+};
+
+export type AdminAppProps = {
+  navItems: NavItem[];
+  routes: AdminRouteChild[];
+  /** Override login / post-login redirect paths when they cannot be inferred from routes. */
+  authRedirects?: AuthRedirects;
+  layoutProps?: Partial<AdminLayoutProps>;
+  theme?: Partial<
+    Pick<AppThemeProviderProps, "modeStorageKey" | "densityStorageKey">
+  >;
+};

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />