ding-react-admin 1.0.0

package/src/components/AuthAlternateLink.tsx

@@ -0,0 +1,23 @@
+import { Typography } from "antd";
+import { Link } from "react-router-dom";
+
+export type AuthAlternateLinkProps = {
+  prompt: string;
+  linkText: string;
+  to: string;
+};
+
+export function AuthAlternateLink({
+  prompt,
+  linkText,
+  to,
+}: AuthAlternateLinkProps) {
+  return (
+    <Typography.Paragraph
+      type="secondary"
+      style={{ textAlign: "center", marginBottom: 0 }}
+    >
+      {prompt} <Link to={to}>{linkText}</Link>
+    </Typography.Paragraph>
+  );
+}

package/src/components/DensitySwitch.tsx

@@ -0,0 +1,31 @@
+import { ColumnHeightOutlined, LayoutOutlined } from "@ant-design/icons";
+import { Segmented } from "antd";
+import type { SegmentedProps } from "antd";
+import { useThemeMode } from "../context/AppThemeProvider";
+import type { ThemeDensity } from "../types";
+
+const OPTIONS: SegmentedProps["options"] = [
+  {
+    label: "Comfortable",
+    value: "comfortable",
+    icon: <LayoutOutlined />,
+  },
+  {
+    label: "Compact",
+    value: "compact",
+    icon: <ColumnHeightOutlined />,
+  },
+];
+
+export function DensitySwitch() {
+  const { density, setDensity } = useThemeMode();
+
+  return (
+    <Segmented
+      size="small"
+      value={density}
+      options={OPTIONS}
+      onChange={(v) => setDensity(v as ThemeDensity)}
+    />
+  );
+}

package/src/components/ThemeSwitch.tsx

@@ -0,0 +1,28 @@
+import {
+  DesktopOutlined,
+  MoonOutlined,
+  SunOutlined,
+} from "@ant-design/icons";
+import { Segmented } from "antd";
+import type { SegmentedProps } from "antd";
+import type { ThemeMode } from "../types";
+import { useThemeMode } from "../context/AppThemeProvider";
+
+const OPTIONS: SegmentedProps["options"] = [
+  { label: "Light", value: "light", icon: <SunOutlined /> },
+  { label: "Dark", value: "dark", icon: <MoonOutlined /> },
+  { label: "Auto", value: "system", icon: <DesktopOutlined /> },
+];
+
+export function ThemeSwitch() {
+  const { mode, setMode } = useThemeMode();
+
+  return (
+    <Segmented
+      size="small"
+      value={mode}
+      options={OPTIONS}
+      onChange={(v) => setMode(v as ThemeMode)}
+    />
+  );
+}

package/src/components/ThemeToolbar.tsx

@@ -0,0 +1,34 @@
+import { SettingOutlined } from "@ant-design/icons";
+import { Button, Grid, Popover, Space, theme } from "antd";
+import { DensitySwitch } from "./DensitySwitch";
+import { ThemeSwitch } from "./ThemeSwitch";
+
+export function ThemeToolbar() {
+  const { token } = theme.useToken();
+  const screens = Grid.useBreakpoint();
+  const placement = screens.lg ? "bottomRight" : "bottom";
+
+  return (
+    <Popover
+      placement={placement}
+      trigger="click"
+      content={
+        <Space
+          orientation="vertical"
+          size="middle"
+          style={{ minWidth: 240, maxWidth: "min(92vw, 320px)" }}
+        >
+          <ThemeSwitch />
+          <DensitySwitch />
+        </Space>
+      }
+      styles={{ content: { padding: token.paddingSM } }}
+    >
+      <Button
+        type="default"
+        icon={<SettingOutlined />}
+        aria-label="Display and theme settings"
+      />
+    </Popover>
+  );
+}

package/src/components/index.ts

@@ -0,0 +1,4 @@
+export { AuthAlternateLink } from "./AuthAlternateLink";
+export { ThemeToolbar } from "./ThemeToolbar";
+export { ThemeSwitch } from "./ThemeSwitch";
+export { DensitySwitch } from "./DensitySwitch";

package/src/context/AppThemeProvider.tsx

@@ -0,0 +1,128 @@
+import { ConfigProvider, theme as antdTheme } from "antd";
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+import type {
+  AppThemeProviderProps,
+  ThemeDensity,
+  ThemeMode,
+} from "../types";
+
+export type { ThemeDensity, ThemeMode };
+
+type ThemeContextValue = {
+  mode: ThemeMode;
+  setMode: (mode: ThemeMode) => void;
+  /** Resolved appearance for Ant Design (`system` → OS preference). */
+  resolved: "light" | "dark";
+  density: ThemeDensity;
+  setDensity: (density: ThemeDensity) => void;
+};
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+function readStoredMode(key: string): ThemeMode {
+  try {
+    const raw = localStorage.getItem(key);
+    if (raw === "light" || raw === "dark" || raw === "system") return raw;
+  } catch {
+    /* ignore */
+  }
+  return "system";
+}
+
+function getSystemDark(): boolean {
+  return window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+
+function readStoredDensity(key: string): ThemeDensity {
+  try {
+    const raw = localStorage.getItem(key);
+    if (raw === "comfortable" || raw === "compact") return raw;
+  } catch {
+    /* ignore */
+  }
+  return "comfortable";
+}
+
+const DEFAULT_MODE_KEY = "ding-react-admin-theme-mode";
+const DEFAULT_DENSITY_KEY = "ding-react-admin-theme-density";
+
+export function AppThemeProvider({
+  children,
+  modeStorageKey = DEFAULT_MODE_KEY,
+  densityStorageKey = DEFAULT_DENSITY_KEY,
+}: AppThemeProviderProps) {
+  const [mode, setModeState] = useState<ThemeMode>(() =>
+    readStoredMode(modeStorageKey),
+  );
+  const [density, setDensityState] = useState<ThemeDensity>(() =>
+    readStoredDensity(densityStorageKey),
+  );
+  const [systemDark, setSystemDark] = useState(getSystemDark);
+
+  useEffect(() => {
+    if (mode !== "system") return;
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    const onChange = () => setSystemDark(mq.matches);
+    onChange();
+    mq.addEventListener("change", onChange);
+    return () => mq.removeEventListener("change", onChange);
+  }, [mode]);
+
+  const setMode = (next: ThemeMode) => {
+    setModeState(next);
+    try {
+      localStorage.setItem(modeStorageKey, next);
+    } catch {
+      /* ignore */
+    }
+  };
+
+  const setDensity = (next: ThemeDensity) => {
+    setDensityState(next);
+    try {
+      localStorage.setItem(densityStorageKey, next);
+    } catch {
+      /* ignore */
+    }
+  };
+
+  const resolved: "light" | "dark" =
+    mode === "system" ? (systemDark ? "dark" : "light") : mode;
+
+  const configTheme = useMemo(() => {
+    const base =
+      resolved === "dark"
+        ? antdTheme.darkAlgorithm
+        : antdTheme.defaultAlgorithm;
+    return {
+      algorithm:
+        density === "compact"
+          ? [base, antdTheme.compactAlgorithm]
+          : base,
+    };
+  }, [resolved, density]);
+
+  const value = useMemo(
+    () => ({ mode, setMode, resolved, density, setDensity }),
+    [mode, resolved, density, setMode, setDensity],
+  );
+
+  return (
+    <ThemeContext.Provider value={value}>
+      <ConfigProvider theme={configTheme}>{children}</ConfigProvider>
+    </ThemeContext.Provider>
+  );
+}
+
+export function useThemeMode() {
+  const ctx = useContext(ThemeContext);
+  if (!ctx)
+    throw new Error("useThemeMode must be used within AppThemeProvider");
+  return ctx;
+}

package/src/context/AuthProvider.tsx

@@ -0,0 +1,77 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+import type { AuthAdapter, LoginCredentials } from "../types";
+
+type AuthContextValue = {
+  isAuthenticated: boolean;
+  login: (credentials: LoginCredentials) => Promise<void>;
+  logout: () => void;
+};
+
+const AuthContext = createContext<AuthContextValue | null>(null);
+
+export type AuthProviderProps = {
+  children: ReactNode;
+  /** How login, logout, and token reads are implemented (API, sessionStorage, etc.). */
+  adapter: AuthAdapter;
+};
+
+export function AuthProvider({ children, adapter }: AuthProviderProps) {
+  const [token, setToken] = useState<string | null>(() => adapter.getToken());
+
+  const login = useCallback(
+    async (credentials: LoginCredentials) => {
+      await adapter.login(credentials);
+      setToken(adapter.getToken());
+    },
+    [adapter],
+  );
+
+  const logout = useCallback(() => {
+    adapter.logout();
+    setToken(adapter.getToken());
+  }, [adapter]);
+
+  const value = useMemo<AuthContextValue>(
+    () => ({
+      isAuthenticated: Boolean(token),
+      login,
+      logout,
+    }),
+    [token, login, logout],
+  );
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
+
+export function useAuth() {
+  const ctx = useContext(AuthContext);
+  if (!ctx) throw new Error("useAuth must be used within AuthProvider");
+  return ctx;
+}
+
+const DEFAULT_SESSION_KEY = "ding-react-admin-auth";
+
+/** Store a non-empty token string in `sessionStorage` when “logged in”. */
+export function createSessionStorageAuthAdapter(
+  storageKey: string = DEFAULT_SESSION_KEY,
+): AuthAdapter {
+  return {
+    async login({ username, password }: LoginCredentials) {
+      if (!username.trim() || !password) throw new Error("Invalid credentials");
+      sessionStorage.setItem(storageKey, "1");
+    },
+    logout() {
+      sessionStorage.removeItem(storageKey);
+    },
+    getToken() {
+      return sessionStorage.getItem(storageKey);
+    },
+  };
+}

package/src/context/DataProvider.tsx

@@ -0,0 +1,30 @@
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type ReactNode,
+} from "react";
+import type { DataProvider as DataProviderContract } from "../data/dataProviderTypes";
+
+const DataContext = createContext<DataProviderContract | null>(null);
+
+export type DataProviderProps = {
+  children: ReactNode;
+  /** Your API client (REST adapter, in-memory mock, etc.). */
+  value: DataProviderContract;
+};
+
+export function DataProvider({ children, value }: DataProviderProps) {
+  const memo = useMemo(() => value, [value]);
+  return (
+    <DataContext.Provider value={memo}>{children}</DataContext.Provider>
+  );
+}
+
+export function useDataProvider() {
+  const ctx = useContext(DataContext);
+  if (!ctx) {
+    throw new Error("useDataProvider must be used within DataProvider");
+  }
+  return ctx;
+}

package/src/context/PermissionsProvider.tsx

@@ -0,0 +1,57 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  type ReactNode,
+} from "react";
+
+/**
+ * Check whether the current user has a permission string from your backend.
+ * Example: `can("users.create")` or `can("main.add_user")`.
+ */
+export type PermissionsChecker = (permission: string) => boolean;
+
+const PermissionsContext = createContext<PermissionsChecker | null>(null);
+
+export type PermissionsProviderProps = {
+  children: ReactNode;
+  /** Return true if the current user has this permission string. */
+  can: PermissionsChecker;
+};
+
+export function PermissionsProvider({
+  children,
+  can,
+}: PermissionsProviderProps) {
+  const memo = useMemo(() => can, [can]);
+  return (
+    <PermissionsContext.Provider value={memo}>
+      {children}
+    </PermissionsContext.Provider>
+  );
+}
+
+export function usePermissions(): PermissionsChecker {
+  const ctx = useContext(PermissionsContext);
+  if (!ctx) {
+    throw new Error(
+      "usePermissions must be used within PermissionsProvider",
+    );
+  }
+  return ctx;
+}
+
+/** Build a `can(permission)` checker from the user's permission strings (e.g. from login). */
+export function createPermissionsChecker(
+  getPermissions: () => string[] | undefined,
+): PermissionsChecker {
+  return (permission: string) =>
+    getPermissions()?.includes(permission) ?? false;
+}
+
+/** Convenience: `const allowed = useCan("users.create")();` */
+export function useCan(permission: string) {
+  const can = usePermissions();
+  return useCallback(() => can(permission), [can, permission]);
+}

package/src/crud/FilterBar.tsx

@@ -0,0 +1,36 @@
+import { Space, Typography } from "antd";
+import type { ReactNode } from "react";
+import { useFilterContext } from "./context/FilterContext";
+
+function FilterBarUI() {
+  const ctx = useFilterContext();
+  if (!ctx || ctx.filters.length === 0) return null;
+
+  return (
+    <Space wrap size="middle" style={{ marginBottom: 16 }}>
+      {ctx.filters.map((f) => (
+        <Space key={f.key} orientation="vertical" size={2}>
+          {f.label ? (
+            <Typography.Text type="secondary" style={{ fontSize: 12 }}>
+              {f.label}
+            </Typography.Text>
+          ) : null}
+          {f.render({
+            value: ctx.values[f.source],
+            onChange: (v) => ctx.setFilterValue(f.source, v),
+          })}
+        </Space>
+      ))}
+    </Space>
+  );
+}
+
+/** Wrap filter field components; renders filter controls above the table. */
+export function FilterBar({ children }: { children: ReactNode }) {
+  return (
+    <>
+      {children}
+      <FilterBarUI />
+    </>
+  );
+}

package/src/crud/FormSteps.tsx

@@ -0,0 +1,135 @@
+import { Button, Space, Steps, type StepsProps } from "antd";
+import {
+  Children,
+  isValidElement,
+  useCallback,
+  useMemo,
+  useState,
+  type CSSProperties,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { useFormContext, useFormState } from "react-hook-form";
+import { FormSectionSourcesProvider } from "./context/FormSectionContext";
+import {
+  sectionHasError,
+  useActivateFirstErrorSection,
+  useSectionSourceRefs,
+} from "./utils/formSectionErrors";
+
+export type FormStepProps = {
+  title: ReactNode;
+  description?: ReactNode;
+  children: ReactNode;
+};
+
+export function FormStep(_props: FormStepProps) {
+  return null;
+}
+
+function isFormStep(child: ReactNode): child is ReactElement<FormStepProps> {
+  return isValidElement(child) && child.type === FormStep;
+}
+
+export type FormStepsProps = {
+  children: ReactNode;
+  initialStep?: number;
+  /** Show Previous / Next controls below the active step. Default true. */
+  showNavigation?: boolean;
+  /** Allow clicking step headers to change the active step. Default false. */
+  allowStepSelect?: boolean;
+  stepsStyle?: CSSProperties;
+  navigationStyle?: CSSProperties;
+} & Partial<Pick<StepsProps, "size" | "direction" | "type" | "status">>;
+
+export function FormSteps({
+  children,
+  initialStep = 0,
+  showNavigation = true,
+  allowStepSelect = false,
+  stepsStyle,
+  navigationStyle,
+  size,
+  direction,
+  type,
+  status,
+}: FormStepsProps) {
+  const steps = useMemo(
+    () => Children.toArray(children).filter(isFormStep),
+    [children],
+  );
+  const sectionRefs = useSectionSourceRefs(steps.length);
+  const [current, setCurrent] = useState(initialStep);
+  const lastIndex = steps.length - 1;
+
+  useActivateFirstErrorSection(sectionRefs, setCurrent);
+
+  const { control, getFieldState } = useFormContext();
+  const formState = useFormState({ control });
+
+  const stepItems = useMemo(
+    () =>
+      steps.map((step, index) => {
+        const hasError = sectionHasError(
+          sectionRefs[index].current,
+          getFieldState,
+          formState,
+        );
+
+        return {
+          title: step.props.title,
+          description: step.props.description,
+          status: hasError ? ("error" as const) : undefined,
+        };
+      }),
+    [formState, getFieldState, sectionRefs, steps],
+  );
+
+  const handleStepSelect = useCallback(
+    (next: number) => {
+      setCurrent(next);
+    },
+    [],
+  );
+
+  return (
+    <>
+      <Steps
+        current={current}
+        items={stepItems}
+        style={{ marginBottom: 24, ...stepsStyle }}
+        onChange={allowStepSelect ? handleStepSelect : undefined}
+        size={size}
+        direction={direction}
+        type={type}
+        status={status}
+      />
+
+      {steps.map((step, index) => (
+        <div
+          key={(step.key as string | undefined) ?? String(index)}
+          style={{ display: current === index ? undefined : "none" }}
+        >
+          <FormSectionSourcesProvider sourcesRef={sectionRefs[index]}>
+            {step.props.children}
+          </FormSectionSourcesProvider>
+        </div>
+      ))}
+
+      {showNavigation && steps.length > 1 ? (
+        <Space style={{ marginTop: 16, ...navigationStyle }}>
+          <Button disabled={current === 0} onClick={() => setCurrent((s) => s - 1)}>
+            Previous
+          </Button>
+          <Button
+            type="primary"
+            disabled={current === lastIndex}
+            onClick={() => setCurrent((s) => s + 1)}
+          >
+            Next
+          </Button>
+        </Space>
+      ) : null}
+    </>
+  );
+}