ding-react-admin 1.0.0

package/src/index.ts

@@ -0,0 +1,182 @@
+export { AdminApp } from "./app/AdminApp";
+export { AdminLayout } from "./layouts/AdminLayout";
+export {
+  AuthProvider,
+  createSessionStorageAuthAdapter,
+  useAuth,
+  type AuthProviderProps,
+} from "./context/AuthProvider";
+export {
+  DataProvider,
+  useDataProvider,
+  type DataProviderProps,
+} from "./context/DataProvider";
+export {
+  PermissionsProvider,
+  createPermissionsChecker,
+  useCan,
+  usePermissions,
+  type PermissionsProviderProps,
+} from "./context/PermissionsProvider";
+export {
+  AppThemeProvider,
+  useThemeMode,
+} from "./context/AppThemeProvider";
+export type {
+  CreateResult,
+  DataProvider as DataProviderContract,
+  DeleteResult,
+  GetListParams,
+  GetListResult,
+  GetOneResult,
+  Identifier,
+  PaginationParams,
+  SortOrder,
+  SortSpec,
+  UpdateParams,
+  UpdateResult,
+  FormMutation,
+  FormValidationErrors,
+  ParseFormError,
+  ParseFormErrorContext,
+} from "./data/dataProviderTypes";
+export { combineResourceHandlers } from "./data/resourceHandlers";
+export {
+  parseDjangoDRFFormErrors,
+  parseDotNetFormErrors,
+  parseNodeFormErrors,
+  getErrorBody,
+  applyInlineFieldPaths,
+  asStringMessages,
+  finalizeFormErrors,
+} from "./data/parseFormErrorHelpers";
+export type {
+  DotNetFormErrorOptions,
+  NodeFormErrorOptions,
+} from "./data/parseFormErrorHelpers";
+export { createMemoryResourceHandlers } from "./data/createMemoryResourceHandlers";
+export { createRestResourceHandlers } from "./data/createRestResourceHandlers";
+export type { RestResourceHandlersConfig } from "./data/createRestResourceHandlers";
+export {
+  toDjangoRestOrdering,
+  toODataOrderBy,
+  toJsonApiSort,
+} from "./data/sortHelpers";
+export {
+  applyInMemoryListParams,
+  filterRows,
+  getById as getRowById,
+} from "./data/inMemoryList";
+export type {
+  CombineResourceHandlersOptions,
+  ResourceAction,
+  ResourceGuard,
+  ResourceHandlerEntry,
+  ResourceHandlerMap,
+  ResourceHandlers,
+} from "./data/resourceHandlers";
+export type { ResourcePermissions } from "./permissions/resourcePermissions";
+export { filterNavByPermission } from "./permissions/resourcePermissions";
+export type { MemoryResourceHandlersConfig } from "./data/createMemoryResourceHandlers";
+export type { PermissionsChecker } from "./context/PermissionsProvider";
+export { LoginPage } from "./pages/LoginPage";
+export { PlaceholderPage } from "./pages/PlaceholderPage";
+export { AuthPageLayout } from "./layouts/AuthPageLayout";
+export {
+  AuthAlternateLink,
+  DensitySwitch,
+  ThemeSwitch,
+  ThemeToolbar,
+} from "./components";
+export { Guard, GuestOnly, Protected, RequirePermission } from "./router/guards";
+export { createAdminRouter } from "./router/createAdminRouter";
+export {
+  deriveAuthPaths,
+  getRouteAccess,
+  partitionAdminRoutes,
+} from "./router/routeAccess";
+export type {
+  AdminAppProps,
+  AdminLayoutProps,
+  AdminRouteChild,
+  AppThemeProviderProps,
+  AuthAdapter,
+  LoginCredentials,
+  AuthRedirects,
+  CreateAdminRouterOptions,
+  AuthAlternateLinkProps,
+  AuthPageLayoutProps,
+  LoginPageProps,
+  NavItem,
+  RouteAccess,
+  ThemeDensity,
+  ThemeMode,
+} from "./types";
+export {
+  ResourceList,
+  FilterBar,
+  ResourceForm,
+  ResourceFormModal,
+  InlineFormSet,
+  FormTabs,
+  FormTab,
+  FormSteps,
+  FormStep,
+  saveInlineRows,
+  loadInlineRows,
+  TextField,
+  NumberField,
+  BooleanField,
+  DateField,
+  SelectField,
+  PasswordField,
+  ReferenceField,
+  ReferenceManyField,
+  TextColumn,
+  NumberColumn,
+  BooleanColumn,
+  DateColumn,
+  ReferenceColumn,
+  ReferenceManyColumn,
+  CustomColumn,
+  TextFilter,
+  NumberFilter,
+  BooleanFilter,
+  DateFilter,
+  SelectFilter,
+  ReferenceFilter,
+  ReferenceManyFilter,
+  useListQueryState,
+  useChoices,
+  getByPath,
+  pickBySources,
+  inlineArrayName,
+  useResourceListContext,
+  useRegisterFormSource,
+} from "./crud";
+export type {
+  ResourceFormProps,
+  ResourceFormInlineConfig,
+  ResourceFormModalProps,
+  InlineFormSetProps,
+  FormTabsProps,
+  FormTabProps,
+  FormStepsProps,
+  FormStepProps,
+  SaveInlineOptions,
+  InlineFormSetLayout,
+  ResourceListProps,
+  BaseSourceProps,
+  ChoiceOption,
+  ChoicesLoader,
+  ReferenceProps,
+  DisplayProps,
+  EditMode,
+  FieldRules,
+  ResourceListBuiltInActions,
+  ResourceListBulkAction,
+  ResourceListBulkActionHelpers,
+  ResourceListRowActionsHelpers,
+  ListQueryState,
+  ListQueryActions,
+} from "./crud";

package/src/layouts/AdminLayout.tsx

@@ -0,0 +1,381 @@
+import {
+  LogoutOutlined,
+  MenuOutlined,
+  UserOutlined,
+} from "@ant-design/icons";
+import {
+  Avatar,
+  Button,
+  Drawer,
+  Dropdown,
+  Grid,
+  Layout,
+  Menu,
+  theme,
+  Typography,
+} from "antd";
+import type { MenuProps } from "antd";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Outlet, useLocation, useNavigate } from "react-router-dom";
+import { ThemeToolbar } from "../components/ThemeToolbar";
+import { useAuth } from "../context/AuthProvider";
+import { usePermissions } from "../context/PermissionsProvider";
+import { useThemeMode } from "../context/AppThemeProvider";
+import { filterNavByPermission } from "../permissions/resourcePermissions";
+import type { AdminLayoutProps, NavItem } from "../types";
+
+const LIGHT_SIDEBAR_BG = "#001529";
+const DEFAULT_SIDER_KEY = "ding-react-admin-sider-collapsed";
+
+function readSiderCollapsed(key: string): boolean {
+  try {
+    return localStorage.getItem(key) === "1";
+  } catch {
+    return false;
+  }
+}
+
+function useIsMobileNav(): boolean {
+  const screens = Grid.useBreakpoint();
+  return screens.lg !== true;
+}
+
+/** Paths that correspond to actual routes (leaf menu rows only). */
+function collectLeafPaths(items: NavItem[]): Set<string> {
+  const set = new Set<string>();
+  function walk(nodes: NavItem[]) {
+    for (const n of nodes) {
+      if (n.children?.length) walk(n.children);
+      else set.add(n.path);
+    }
+  }
+  walk(items);
+  return set;
+}
+
+/** Submenu keys that must stay open for `pathname` to remain visible in the tree. */
+function ancestorKeysForActivePath(
+  items: NavItem[],
+  pathname: string,
+): string[] {
+  function dfs(nodes: NavItem[]): string[] | null {
+    for (const node of nodes) {
+      if (node.children?.length) {
+        const sub = dfs(node.children);
+        if (sub !== null) return [node.path, ...sub];
+      } else if (node.path === pathname) {
+        return [];
+      }
+    }
+    return null;
+  }
+  return dfs(items) ?? [];
+}
+
+function navItemsToAntdItems(
+  items: NavItem[],
+): NonNullable<MenuProps["items"]> {
+  return items.map((item) => {
+    const IconComp = item.Icon;
+    const icon = IconComp ? <IconComp /> : undefined;
+    if (item.children?.length) {
+      return {
+        key: item.path,
+        icon,
+        label: item.label,
+        children: navItemsToAntdItems(item.children),
+      };
+    }
+    return {
+      key: item.path,
+      icon,
+      label: item.label,
+    };
+  });
+}
+
+type NavMenuProps = {
+  menuItems: MenuProps["items"];
+  selectedKeys: string[];
+  inlineCollapsed: boolean;
+  openKeys?: string[];
+  onOpenChange?: (keys: string[]) => void;
+  onNavigate: (key: string) => void;
+};
+
+function NavMenu({
+  menuItems,
+  selectedKeys,
+  inlineCollapsed,
+  openKeys,
+  onOpenChange,
+  onNavigate,
+}: NavMenuProps) {
+  return (
+    <Menu
+      mode="inline"
+      theme="dark"
+      inlineCollapsed={inlineCollapsed}
+      selectedKeys={selectedKeys}
+      {...(!inlineCollapsed && openKeys !== undefined && onOpenChange
+        ? { openKeys, onOpenChange }
+        : {})}
+      items={menuItems}
+      onClick={({ key }) => onNavigate(key)}
+      style={{ background: "transparent", borderInlineEnd: "none" }}
+    />
+  );
+}
+
+export function AdminLayout({
+  navItems,
+  brand = "Admin",
+  collapsedBrand = "A",
+  mobileDrawerTitle,
+  headerExtras,
+  userMenuItems,
+  onUserMenuClick,
+  loginPath = "/login",
+  siderCollapsedStorageKey = DEFAULT_SIDER_KEY,
+}: AdminLayoutProps) {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const { resolved } = useThemeMode();
+  const isAppDark = resolved === "dark";
+  const { logout } = useAuth();
+  const can = usePermissions();
+  const [collapsed, setCollapsed] = useState(() =>
+    readSiderCollapsed(siderCollapsedStorageKey),
+  );
+  const [mobileNavOpen, setMobileNavOpen] = useState(false);
+  const isMobile = useIsMobileNav();
+  const { token } = theme.useToken();
+
+  const drawerTitle = mobileDrawerTitle ?? brand;
+
+  const handleLogout = () => {
+    logout();
+    navigate(loginPath, { replace: true });
+  };
+
+  const handleCollapse = useCallback(
+    (next: boolean) => {
+      setCollapsed(next);
+      try {
+        localStorage.setItem(siderCollapsedStorageKey, next ? "1" : "0");
+      } catch {
+        /* ignore */
+      }
+    },
+    [siderCollapsedStorageKey],
+  );
+
+  useEffect(() => {
+    if (!isMobile) setMobileNavOpen(false);
+  }, [isMobile]);
+
+  useEffect(() => {
+    setMobileNavOpen(false);
+  }, [location.pathname]);
+
+  const visibleNavItems = useMemo(
+    () => filterNavByPermission(navItems, can),
+    [navItems, can],
+  );
+
+  const leafPaths = useMemo(
+    () => collectLeafPaths(visibleNavItems),
+    [visibleNavItems],
+  );
+
+  const menuItems: MenuProps["items"] = useMemo(
+    () => navItemsToAntdItems(visibleNavItems),
+    [visibleNavItems],
+  );
+
+  const requiredOpenKeys = useMemo(
+    () => ancestorKeysForActivePath(visibleNavItems, location.pathname),
+    [visibleNavItems, location.pathname],
+  );
+
+  const [openKeys, setOpenKeys] = useState<string[]>(() =>
+    ancestorKeysForActivePath(visibleNavItems, location.pathname),
+  );
+
+  useEffect(() => {
+    setOpenKeys((prev) => [...new Set([...prev, ...requiredOpenKeys])]);
+  }, [requiredOpenKeys]);
+
+  const handleOpenChange = useCallback((keys: string[]) => {
+    setOpenKeys(keys);
+  }, []);
+
+  const defaultUserMenuItems: MenuProps["items"] = useMemo(
+    () => [
+      {
+        key: "logout",
+        icon: <LogoutOutlined />,
+        label: "Log out",
+        danger: true,
+      },
+    ],
+    [],
+  );
+
+  const resolvedUserItems = userMenuItems ?? defaultUserMenuItems;
+
+  const onDropdownMenuClick: MenuProps["onClick"] = (info) => {
+    if (onUserMenuClick) {
+      onUserMenuClick(info);
+      return;
+    }
+    if (info.key === "logout") handleLogout();
+  };
+
+  const siderBg = isAppDark ? token.colorBgContainer : LIGHT_SIDEBAR_BG;
+  const selectedKeys = [location.pathname];
+
+  const goNav = (key: string) => {
+    if (!leafPaths.has(key)) return;
+    navigate(key);
+    if (isMobile) setMobileNavOpen(false);
+  };
+
+  return (
+    <Layout
+      style={{
+        minHeight: "100vh",
+        width: "100%",
+        background: token.colorBgLayout,
+      }}
+    >
+      {!isMobile && (
+        <Layout.Sider
+          collapsible
+          collapsed={collapsed}
+          onCollapse={handleCollapse}
+          collapsedWidth={64}
+          style={{
+            background: siderBg,
+            borderInlineEnd: isAppDark
+              ? `1px solid ${token.colorSplit}`
+              : undefined,
+          }}
+        >
+          <div
+            style={{
+              height: 64,
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              fontWeight: 600,
+            }}
+          >
+            <Typography.Text
+              strong
+              style={{ color: token.colorTextLightSolid }}
+            >
+              {collapsed ? collapsedBrand : brand}
+            </Typography.Text>
+          </div>
+          <NavMenu
+            menuItems={menuItems}
+            selectedKeys={selectedKeys}
+            inlineCollapsed={collapsed}
+            openKeys={openKeys}
+            onOpenChange={handleOpenChange}
+            onNavigate={goNav}
+          />
+        </Layout.Sider>
+      )}
+      {isMobile && (
+        <Drawer
+          title={
+            <Typography.Text
+              strong
+              style={{ color: token.colorTextLightSolid }}
+            >
+              {drawerTitle}
+            </Typography.Text>
+          }
+          placement="left"
+          size={280}
+          onClose={() => setMobileNavOpen(false)}
+          open={mobileNavOpen}
+          styles={{
+            header: {
+              background: siderBg,
+              borderBottom: `1px solid ${token.colorSplit}`,
+            },
+            body: { padding: 0, background: siderBg },
+          }}
+          destroyOnHidden
+        >
+          <NavMenu
+            menuItems={menuItems}
+            selectedKeys={selectedKeys}
+            inlineCollapsed={false}
+            openKeys={openKeys}
+            onOpenChange={handleOpenChange}
+            onNavigate={goNav}
+          />
+        </Drawer>
+      )}
+      <Layout>
+        <Layout.Header
+          style={{
+            background: token.colorBgContainer,
+            paddingInline: token.paddingLG,
+            display: "flex",
+            alignItems: "center",
+            gap: token.marginSM,
+            lineHeight: "normal",
+          }}
+        >
+          {isMobile && (
+            <Button
+              type="text"
+              icon={<MenuOutlined />}
+              onClick={() => setMobileNavOpen(true)}
+              aria-label="Open navigation"
+            />
+          )}
+          <div style={{ flex: 1, minWidth: 0 }} />
+          {headerExtras}
+          <ThemeToolbar />
+          <Dropdown
+            menu={{
+              items: resolvedUserItems,
+              onClick: onDropdownMenuClick,
+            }}
+            trigger={["click"]}
+          >
+            <Button
+              type="text"
+              style={{
+                display: "inline-flex",
+                alignItems: "center",
+                gap: token.marginXS,
+                maxWidth: isMobile ? 44 : undefined,
+                paddingInline: isMobile ? token.paddingXS : undefined,
+              }}
+              aria-label="Account menu"
+            >
+              <Avatar size="small" icon={<UserOutlined />} />
+              {!isMobile && (
+                <Typography.Text type="secondary">User</Typography.Text>
+              )}
+            </Button>
+          </Dropdown>
+        </Layout.Header>
+        <Layout.Content
+          style={{
+            margin: isMobile ? token.marginSM : token.marginLG,
+          }}
+        >
+          <Outlet />
+        </Layout.Content>
+      </Layout>
+    </Layout>
+  );
+}

package/src/layouts/AuthPageLayout.tsx

@@ -0,0 +1,81 @@
+import { Flex, theme } from "antd";
+import type { ReactNode } from "react";
+import { ThemeToolbar } from "../components/ThemeToolbar";
+
+export type AuthPageLayoutProps = {
+  children: ReactNode;
+  /** Brand mark centered above the card. */
+  brand?: ReactNode;
+  /** Row below the card (e.g. link to register or login). */
+  footer?: ReactNode;
+  showThemeToolbar?: boolean;
+};
+
+export function AuthPageLayout({
+  children,
+  brand,
+  footer,
+  showThemeToolbar = true,
+}: AuthPageLayoutProps) {
+  const { token } = theme.useToken();
+
+  return (
+    <Flex
+      vertical
+      align="stretch"
+      style={{
+        height: "100dvh",
+        maxHeight: "100dvh",
+        width: "100%",
+        overflow: "hidden",
+        background: token.colorBgLayout,
+      }}
+    >
+      {showThemeToolbar ? (
+        <Flex
+          justify="flex-end"
+          style={{
+            flexShrink: 0,
+            width: "100%",
+            padding: 16,
+            background: token.colorBgLayout,
+          }}
+        >
+          <ThemeToolbar />
+        </Flex>
+      ) : null}
+      {brand ? (
+        <div
+          style={{
+            flexShrink: 0,
+            textAlign: "center",
+            padding: "0 24px 16px",
+          }}
+        >
+          {brand}
+        </div>
+      ) : null}
+      <Flex
+        flex={1}
+        vertical
+        align="center"
+        justify="flex-start"
+        style={{
+          width: "100%",
+          minHeight: 0,
+          padding: "0 24px 24px",
+          overflow: "auto",
+          overflowX: "hidden",
+          background: token.colorBgLayout,
+        }}
+      >
+        {children}
+        {footer ? (
+          <div style={{ marginTop: 16, width: "100%", maxWidth: 520 }}>
+            {footer}
+          </div>
+        ) : null}
+      </Flex>
+    </Flex>
+  );
+}

package/src/pages/LoginPage.tsx

@@ -0,0 +1,80 @@
+import { Button, Card, Form, Input, Typography } from "antd";
+import { useNavigate } from "react-router-dom";
+import { AuthAlternateLink } from "../components/AuthAlternateLink";
+import { useAuth } from "../context/AuthProvider";
+import { AuthPageLayout } from "../layouts/AuthPageLayout";
+import type { LoginPageProps } from "../types";
+
+export function LoginPage({
+  title = "Sign in",
+  description = "Use any username and password to continue.",
+  logo,
+  brand,
+  extraFields,
+  showThemeToolbar = true,
+  afterLoginPath = "/",
+  alternateAuth,
+  footer,
+}: LoginPageProps) {
+  const { login } = useAuth();
+  const navigate = useNavigate();
+  const brandNode = brand ?? logo;
+
+  const resolvedFooter =
+    footer ??
+    (alternateAuth ? (
+      <AuthAlternateLink
+        prompt={alternateAuth.prompt ?? "Don't have an account?"}
+        linkText={alternateAuth.linkText}
+        to={alternateAuth.to}
+      />
+    ) : null);
+
+  return (
+    <AuthPageLayout
+      brand={brandNode}
+      footer={resolvedFooter}
+      showThemeToolbar={showThemeToolbar}
+    >
+      <Card style={{ width: "100%", maxWidth: 360 }} title={title}>
+        {description ? (
+          <Typography.Paragraph type="secondary" style={{ marginTop: 0 }}>
+            {description}
+          </Typography.Paragraph>
+        ) : null}
+        <Form
+          layout="vertical"
+          onFinish={async (values: Record<string, unknown>) => {
+            await login({
+              username: String(values.username ?? ""),
+              password: String(values.password ?? ""),
+              ...values,
+            });
+            navigate(afterLoginPath, { replace: true });
+          }}
+        >
+          <Form.Item
+            name="username"
+            label="Username"
+            rules={[{ required: true, message: "Required" }]}
+          >
+            <Input autoComplete="username" />
+          </Form.Item>
+          <Form.Item
+            name="password"
+            label="Password"
+            rules={[{ required: true, message: "Required" }]}
+          >
+            <Input.Password autoComplete="current-password" />
+          </Form.Item>
+          {extraFields}
+          <Form.Item style={{ marginBottom: 0 }}>
+            <Button type="primary" htmlType="submit" block>
+              Log in
+            </Button>
+          </Form.Item>
+        </Form>
+      </Card>
+    </AuthPageLayout>
+  );
+}