@etsoo/toolpad 1.0.0

package/src/Account/AccountPreview.tsx

@@ -0,0 +1,189 @@
+import * as React from "react";
+import PropTypes from "prop-types";
+import Avatar, { AvatarProps } from "@mui/material/Avatar";
+import Typography from "@mui/material/Typography";
+import Tooltip from "@mui/material/Tooltip";
+import Stack from "@mui/material/Stack";
+import IconButton, { IconButtonProps } from "@mui/material/IconButton";
+import MoreVertIcon from "@mui/icons-material/MoreVert";
+import { SessionContext } from "../AppProvider";
+import { useLocaleText } from "../shared/locales/LocaleContext";
+
+export type AccountPreviewVariant = "condensed" | "expanded";
+
+export interface AccountPreviewSlots {
+  /**
+   * The component used for the Avatar
+   * @default Avatar
+   */
+  avatar?: React.ElementType;
+  /**
+   * The component used for the overflow icon button in the expanded variant
+   * @default IconButton
+   */
+  moreIconButton?: React.ElementType;
+  /**
+   * The component used for the avatar icon button in the condensed variant
+   * @default IconButton
+   */
+  avatarIconButton?: React.ElementType;
+}
+
+export interface AccountPreviewProps {
+  /**
+   * The components used for each slot inside.
+   */
+  slots?: AccountPreviewSlots;
+  /**
+   * The props used for each slot inside.
+   */
+  slotProps?: {
+    avatar?: AvatarProps;
+    moreIconButton?: IconButtonProps;
+    avatarIconButton?: IconButtonProps;
+  };
+  /**
+   * The type of account details to display.
+   * @property {'condensed'} condensed - Shows only the user's avatar.
+   * @property {'expanded'} expanded - Displays the user's avatar, name, and email if available.
+   * @default 'condensed'
+   */
+  variant?: AccountPreviewVariant;
+  /**
+   * The handler used when the preview is expanded
+   */
+  handleClick?: React.MouseEventHandler<HTMLElement>;
+  /**
+   * The state of the Account popover
+   * @default false
+   */
+  open?: boolean;
+}
+
+/**
+ * The AccountPreview component displays user account information.
+ *
+ * Demos:
+ *
+ * - [Account](https://mui.com/toolpad/core/react-account/)
+ *
+ * API:
+ *
+ * - [AccountPreview API](https://mui.com/toolpad/core/api/account-preview)
+ */
+function AccountPreview(props: AccountPreviewProps) {
+  const { slots, variant = "condensed", slotProps, open, handleClick } = props;
+  const session = React.useContext(SessionContext);
+  const localeText = useLocaleText();
+
+  if (!session || !session.user) {
+    return null;
+  }
+
+  const avatarContent = slots?.avatar ? (
+    <slots.avatar />
+  ) : (
+    <Avatar
+      src={session.user?.image || ""}
+      alt={session.user?.name || session.user?.email || ""}
+      sx={{
+        height: variant === "expanded" ? 48 : 32,
+        width: variant === "expanded" ? 48 : 32
+      }}
+      {...slotProps?.avatar}
+    />
+  );
+
+  if (variant === "expanded") {
+    return (
+      <Stack
+        direction="row"
+        justifyContent="flex-start"
+        spacing={2}
+        padding={2}
+      >
+        {avatarContent}
+        <Stack direction="column" justifyContent="space-evenly">
+          <Typography variant="body2" fontWeight="bolder" noWrap>
+            {session.user?.name}
+          </Typography>
+          <Typography variant="caption" noWrap>
+            {session.user?.email}
+          </Typography>
+        </Stack>
+        {handleClick &&
+          (slots?.moreIconButton ? (
+            <slots.moreIconButton />
+          ) : (
+            <IconButton
+              size="small"
+              onClick={handleClick}
+              {...slotProps?.moreIconButton}
+              sx={{ alignSelf: "flex-start", ...slotProps?.moreIconButton?.sx }}
+            >
+              <MoreVertIcon fontSize="small" />
+            </IconButton>
+          ))}
+      </Stack>
+    );
+  }
+
+  return (
+    <Tooltip title={session.user.name ?? "Account"}>
+      {slots?.avatarIconButton ? (
+        <slots.avatarIconButton />
+      ) : (
+        <IconButton
+          onClick={handleClick}
+          aria-label={localeText.iconButtonAriaLabel || "Current User"}
+          size="small"
+          aria-controls={open ? "account-menu" : undefined}
+          aria-haspopup="true"
+          aria-expanded={open ? "true" : undefined}
+          {...slotProps?.avatarIconButton}
+        >
+          {avatarContent}
+        </IconButton>
+      )}
+    </Tooltip>
+  );
+}
+
+AccountPreview.propTypes /* remove-proptypes */ = {
+  // ┌────────────────────────────── Warning ──────────────────────────────┐
+  // │ These PropTypes are generated from the TypeScript type definitions. │
+  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
+  // └─────────────────────────────────────────────────────────────────────┘
+  /**
+   * The handler used when the preview is expanded
+   */
+  handleClick: PropTypes.func,
+  /**
+   * The state of the Account popover
+   * @default false
+   */
+  open: PropTypes.bool,
+  /**
+   * The props used for each slot inside.
+   */
+  slotProps: PropTypes.shape({
+    avatar: PropTypes.object,
+    avatarIconButton: PropTypes.object,
+    moreIconButton: PropTypes.object
+  }),
+  /**
+   * The components used for each slot inside.
+   */
+  slots: PropTypes.shape({
+    avatar: PropTypes.elementType
+  }),
+  /**
+   * The type of account details to display.
+   * @property {'condensed'} condensed - Shows only the user's avatar.
+   * @property {'expanded'} expanded - Displays the user's avatar, name, and email if available.
+   * @default 'condensed'
+   */
+  variant: PropTypes.oneOf(["condensed", "expanded"])
+} as any;
+
+export { AccountPreview };

package/src/Account/SignInButton.tsx

@@ -0,0 +1,38 @@
+import * as React from "react";
+import Button, { ButtonProps } from "@mui/material/Button";
+import { AuthenticationContext } from "../AppProvider/AppProvider";
+import { useLocaleText } from "../shared/locales/LocaleContext";
+
+export /**
+ *
+ * Demos:
+ *
+ * - [Account](https://mui.com/toolpad/core/react-account/)
+ *
+ * API:
+ *
+ * - [SignInButton API](https://mui.com/toolpad/core/api/sign-in-button)
+ */ function SignInButton(props: ButtonProps) {
+  const authentication = React.useContext(AuthenticationContext);
+  const localeText = useLocaleText();
+
+  return (
+    <Button
+      disableElevation
+      variant="contained"
+      size="small"
+      onClick={authentication?.signIn}
+      sx={{
+        textTransform: "capitalize",
+        filter: "opacity(0.9)",
+        transition: "filter 0.2s ease-in",
+        "&:hover": {
+          filter: "opacity(1)"
+        }
+      }}
+      {...props}
+    >
+      {localeText?.signInLabel || "Sign In"}
+    </Button>
+  );
+}

package/src/Account/SignOutButton.tsx

@@ -0,0 +1,44 @@
+import * as React from "react";
+import Button, { ButtonProps } from "@mui/material/Button";
+import LogoutIcon from "@mui/icons-material/Logout";
+import { AuthenticationContext } from "../AppProvider/AppProvider";
+import { useLocaleText } from "../shared/locales/LocaleContext";
+
+export type SignOutButtonProps = ButtonProps;
+
+export /**
+ *
+ * Demos:
+ *
+ * - [Account](https://mui.com/toolpad/core/react-account/)
+ *
+ * API:
+ *
+ * - [SignOutButton API](https://mui.com/toolpad/core/api/sign-out-button)
+ */ function SignOutButton(props: SignOutButtonProps) {
+  const authentication = React.useContext(AuthenticationContext);
+  const localeText = useLocaleText();
+
+  return (
+    <Button
+      disabled={!authentication}
+      variant="outlined"
+      size="small"
+      disableElevation
+      onClick={authentication?.signOut}
+      sx={{
+        textTransform: "capitalize",
+        fontWeight: "normal",
+        filter: "opacity(0.9)",
+        transition: "filter 0.2s ease-in",
+        "&:hover": {
+          filter: "opacity(1)"
+        }
+      }}
+      startIcon={<LogoutIcon />}
+      {...props}
+    >
+      {localeText.signOutLabel}
+    </Button>
+  );
+}

package/src/Account/index.ts

@@ -0,0 +1,6 @@
+export * from "./Account";
+export * from "./AccountPreview";
+export * from "./AccountPopoverHeader";
+export * from "./AccountPopoverFooter";
+export * from "./SignOutButton";
+export * from "./SignInButton";

package/src/AppProvider/AppProvider.test.tsx

@@ -0,0 +1,25 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import * as React from "react";
+import { describe, test, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { createTheme } from "@mui/material/styles";
+import { AppProvider } from "./AppProviderComponent";
+
+describe("AppProvider", () => {
+  test("renders content correctly", async () => {
+    render(<AppProvider>Hello world</AppProvider>);
+
+    expect(screen.getByText("Hello world")).toBeTruthy();
+  });
+
+  test("renders content correctly when using legacy theme", async () => {
+    const legacyTheme = createTheme();
+
+    render(<AppProvider theme={legacyTheme}>Hello world</AppProvider>);
+
+    expect(screen.getByText("Hello world")).toBeTruthy();
+  });
+});

package/src/AppProvider/AppProvider.tsx

@@ -0,0 +1,116 @@
+"use client";
+import * as React from "react";
+import { Theme } from "@mui/material/styles";
+
+export interface NavigateOptions {
+  history?: "auto" | "push" | "replace";
+}
+
+export interface Navigate {
+  (url: string | URL, options?: NavigateOptions): void;
+}
+
+/**
+ * Abstract router used by Toolpad components.
+ */
+export interface Router {
+  pathname: string;
+  searchParams: URLSearchParams;
+  navigate: Navigate;
+}
+
+export interface Branding {
+  title?: string;
+  logo?: React.ReactNode;
+}
+
+export interface NavigationPageItem {
+  kind?: "page";
+  segment?: string;
+  title?: string;
+  icon?: React.ReactNode;
+  pattern?: string;
+  action?: React.ReactNode;
+  children?: Navigation;
+}
+
+export interface NavigationSubheaderItem {
+  kind: "header";
+  title: string;
+}
+
+export interface NavigationDividerItem {
+  kind: "divider";
+}
+
+export type NavigationItem =
+  | NavigationPageItem
+  | NavigationSubheaderItem
+  | NavigationDividerItem;
+
+export type Navigation = NavigationItem[];
+
+export interface Session {
+  user?: {
+    id?: string | null;
+    name?: string | null;
+    image?: string | null;
+    email?: string | null;
+  };
+}
+
+export interface Authentication {
+  signIn: () => void;
+  signOut: () => void;
+}
+
+export const AuthenticationContext = React.createContext<Authentication | null>(
+  null
+);
+
+export const SessionContext = React.createContext<Session | null>(null);
+
+export type AppTheme = Theme | { light: Theme; dark: Theme };
+
+export interface AppProviderProps {
+  /**
+   * The content of the app provider.
+   */
+  children: React.ReactNode;
+  /**
+   * [Theme or themes](https://mui.com/toolpad/core/react-app-provider/#theming) to be used by the app in light/dark mode. A [CSS variables theme](https://mui.com/material-ui/customization/css-theme-variables/overview/) is recommended.
+   * @default createTheme()
+   */
+  theme?: AppTheme;
+  /**
+   * Branding options for the app.
+   * @default null
+   */
+  branding?: Branding | null;
+  /**
+   * Navigation definition for the app.
+   * @default []
+   */
+  navigation?: Navigation;
+  /**
+   * Router implementation used inside Toolpad components.
+   * @default null
+   */
+  router?: Router;
+  /**
+   * Session info about the current user.
+   * @default null
+   */
+  session?: Session | null;
+  /**
+   * Authentication methods.
+   * @default null
+   */
+  authentication?: Authentication | null;
+  /**
+   * The window where the application is rendered.
+   * This is needed when rendering the app inside an iframe, for example.
+   * @default window
+   */
+  window?: Window;
+}

package/src/AppProvider/AppProviderComponent.tsx

@@ -0,0 +1,162 @@
+"use client";
+import PropTypes from "prop-types";
+import {
+  BrandingContext,
+  NavigationContext,
+  RouterContext,
+  WindowContext
+} from "../shared/context";
+import { AppThemeProvider } from "./AppThemeProvider";
+import { createTheme as createMuiTheme, Theme } from "@mui/material/styles";
+import {
+  AppProviderProps,
+  AuthenticationContext,
+  SessionContext
+} from "./AppProvider";
+
+function createTheme(): Theme {
+  return createMuiTheme({
+    cssVariables: {
+      colorSchemeSelector: "data-toolpad-color-scheme"
+    },
+    colorSchemes: { dark: true }
+  });
+}
+
+/**
+ *
+ * Demos:
+ *
+ * - [App Provider](https://mui.com/toolpad/core/react-app-provider/)
+ * - [Dashboard Layout](https://mui.com/toolpad/core/react-dashboard-layout/)
+ *
+ * API:
+ *
+ * - [AppProvider API](https://mui.com/toolpad/core/api/app-provider)
+ */
+function AppProvider(props: AppProviderProps) {
+  const {
+    children,
+    theme = createTheme(),
+    branding = null,
+    navigation = [],
+    router = null,
+    authentication = null,
+    session = null,
+    window: appWindow
+  } = props;
+
+  return (
+    <WindowContext.Provider value={appWindow}>
+      <AuthenticationContext.Provider value={authentication}>
+        <SessionContext.Provider value={session}>
+          <RouterContext.Provider value={router}>
+            <AppThemeProvider theme={theme} window={appWindow}>
+              <BrandingContext.Provider value={branding}>
+                <NavigationContext.Provider value={navigation}>
+                  {children}
+                </NavigationContext.Provider>
+              </BrandingContext.Provider>
+            </AppThemeProvider>
+          </RouterContext.Provider>
+        </SessionContext.Provider>
+      </AuthenticationContext.Provider>
+    </WindowContext.Provider>
+  );
+}
+
+AppProvider.propTypes /* remove-proptypes */ = {
+  // ┌────────────────────────────── Warning ──────────────────────────────┐
+  // │ These PropTypes are generated from the TypeScript type definitions. │
+  // │ To update them, edit the TypeScript types and run `pnpm proptypes`. │
+  // └─────────────────────────────────────────────────────────────────────┘
+  /**
+   * Authentication methods.
+   * @default null
+   */
+  authentication: PropTypes.shape({
+    signIn: PropTypes.func.isRequired,
+    signOut: PropTypes.func.isRequired
+  }),
+  /**
+   * Branding options for the app.
+   * @default null
+   */
+  branding: PropTypes.shape({
+    logo: PropTypes.node,
+    title: PropTypes.string
+  }),
+  /**
+   * The content of the app provider.
+   */
+  children: PropTypes.node,
+  /**
+   * Navigation definition for the app.
+   * @default []
+   */
+  navigation: PropTypes.arrayOf(
+    PropTypes.oneOfType([
+      PropTypes.shape({
+        action: PropTypes.node,
+        children: PropTypes.arrayOf(
+          PropTypes.oneOfType([
+            PropTypes.object,
+            PropTypes.shape({
+              kind: PropTypes.oneOf(["header"]).isRequired,
+              title: PropTypes.string.isRequired
+            }),
+            PropTypes.shape({
+              kind: PropTypes.oneOf(["divider"]).isRequired
+            })
+          ]).isRequired
+        ),
+        icon: PropTypes.node,
+        kind: PropTypes.oneOf(["page"]),
+        pattern: PropTypes.string,
+        segment: PropTypes.string,
+        title: PropTypes.string
+      }),
+      PropTypes.shape({
+        kind: PropTypes.oneOf(["header"]).isRequired,
+        title: PropTypes.string.isRequired
+      }),
+      PropTypes.shape({
+        kind: PropTypes.oneOf(["divider"]).isRequired
+      })
+    ]).isRequired
+  ),
+  /**
+   * Router implementation used inside Toolpad components.
+   * @default null
+   */
+  router: PropTypes.shape({
+    navigate: PropTypes.func.isRequired,
+    pathname: PropTypes.string.isRequired,
+    searchParams: PropTypes.instanceOf(URLSearchParams).isRequired
+  }),
+  /**
+   * Session info about the current user.
+   * @default null
+   */
+  session: PropTypes.shape({
+    user: PropTypes.shape({
+      email: PropTypes.string,
+      id: PropTypes.string,
+      image: PropTypes.string,
+      name: PropTypes.string
+    })
+  }),
+  /**
+   * [Theme or themes](https://mui.com/toolpad/core/react-app-provider/#theming) to be used by the app in light/dark mode. A [CSS variables theme](https://mui.com/material-ui/customization/css-theme-variables/overview/) is recommended.
+   * @default createTheme()
+   */
+  theme: PropTypes.object,
+  /**
+   * The window where the application is rendered.
+   * This is needed when rendering the app inside an iframe, for example.
+   * @default window
+   */
+  window: PropTypes.object
+} as any;
+
+export { AppProvider };