@etsoo/toolpad 1.0.0

package/src/PageContainer/PageContainer.tsx

@@ -0,0 +1,201 @@
+"use client";
+import * as React from "react";
+import PropTypes from "prop-types";
+import Breadcrumbs from "@mui/material/Breadcrumbs";
+import Container, { ContainerProps } from "@mui/material/Container";
+import Link from "@mui/material/Link";
+import Stack from "@mui/material/Stack";
+import Typography from "@mui/material/Typography";
+import useSlotProps from "@mui/utils/useSlotProps";
+import { styled } from "@mui/material";
+import { Link as ToolpadLink } from "../shared/Link";
+import {
+  PageContainerToolbar,
+  PageContainerToolbarProps
+} from "./PageContainerToolbar";
+import { getItemTitle } from "../shared/navigation";
+import { useActivePage } from "../useActivePage";
+import warnOnce from "../utils/warnOnce";
+
+const PageContentHeader = styled("div")(({ theme }) => ({
+  display: "flex",
+  flexDirection: "row",
+  justifyContent: "space-between",
+  gap: theme.spacing(2)
+}));
+
+export interface PageContainerSlotProps {
+  toolbar: PageContainerToolbarProps;
+}
+
+export interface PageContainerSlots {
+  /**
+   * The component that renders the actions toolbar.
+   * @default Snackbar
+   */
+  toolbar: React.ElementType;
+}
+
+export interface Breadcrumb {
+  /**
+   * The title of the breadcrumb segment.
+   */
+  title: string;
+  /**
+   * The path the breadcrumb links to.
+   */
+  path: string;
+}
+
+// TODO: Remove in the next major version
+/**
+ * @deprecated Use `Breadcrumb` instead.
+ */
+export type BreadCrumb = Breadcrumb;
+
+export interface PageContainerProps extends ContainerProps {
+  children?: React.ReactNode;
+  /**
+   * The title of the page. Leave blank to use the active page title.
+   */
+  title?: string;
+  /**
+   * The breadcrumbs of the page. Leave blank to use the active page breadcrumbs.
+   */
+  breadcrumbs?: Breadcrumb[];
+  // TODO: Remove in the next major version
+  /**
+   * @deprecated Use `breadcrumbs` instead.
+   */
+  breadCrumbs?: Breadcrumb[];
+  /**
+   * The components used for each slot inside.
+   */
+  slots?: PageContainerSlots;
+  /**
+   * The props used for each slot inside.
+   */
+  slotProps?: PageContainerSlotProps;
+}
+
+/**
+ * A container component to provide a title and breadcrumbs for your pages.
+ *
+ * Demos:
+ *
+ * - [Page Container](https://mui.com/toolpad/core/react-page-container/)
+ *
+ * API:
+ *
+ * - [PageContainer API](https://mui.com/toolpad/core/api/page-container)
+ */
+function PageContainer(props: PageContainerProps) {
+  const { children, slots, slotProps, breadcrumbs, breadCrumbs, ...rest } =
+    props;
+
+  if (process.env.NODE_ENV !== "production" && breadCrumbs) {
+    warnOnce(
+      "The PageContainer `breadCrumbs` prop is deprecated. Use `breadcrumbs` instead."
+    );
+  }
+
+  const activePage = useActivePage();
+
+  // TODO: Remove `props.breadCrumbs` in the next major version
+  const resolvedBreadcrumbs =
+    breadcrumbs ?? breadCrumbs ?? activePage?.breadcrumbs ?? [];
+  const title = props.title ?? activePage?.title ?? "";
+
+  const ToolbarComponent = props?.slots?.toolbar ?? PageContainerToolbar;
+  const toolbarSlotProps = useSlotProps({
+    elementType: ToolbarComponent,
+    ownerState: props,
+    externalSlotProps: props?.slotProps?.toolbar,
+    additionalProps: {}
+  });
+
+  return (
+    <Container {...rest}>
+      <Stack sx={{ my: 2 }} spacing={2}>
+        <Stack>
+          <Breadcrumbs aria-label="breadcrumb">
+            {resolvedBreadcrumbs
+              ? resolvedBreadcrumbs.map((item, index) => {
+                  return index < resolvedBreadcrumbs.length - 1 ? (
+                    <Link
+                      key={item.path}
+                      component={ToolpadLink}
+                      underline="hover"
+                      color="inherit"
+                      href={item.path}
+                    >
+                      {getItemTitle(item)}
+                    </Link>
+                  ) : (
+                    <Typography key={item.path} color="text.primary">
+                      {getItemTitle(item)}
+                    </Typography>
+                  );
+                })
+              : null}
+          </Breadcrumbs>
+
+          <PageContentHeader>
+            {title ? <Typography variant="h4">{title}</Typography> : null}
+            <ToolbarComponent {...toolbarSlotProps} />
+          </PageContentHeader>
+        </Stack>
+        <div>{children}</div>
+      </Stack>
+    </Container>
+  );
+}
+
+PageContainer.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 breadcrumbs of the page. Leave blank to use the active page breadcrumbs.
+   */
+  breadcrumbs: PropTypes.arrayOf(
+    PropTypes.shape({
+      path: PropTypes.string.isRequired,
+      title: PropTypes.string.isRequired
+    })
+  ),
+  /**
+   * @deprecated Use `breadcrumbs` instead.
+   */
+  breadCrumbs: PropTypes.arrayOf(
+    PropTypes.shape({
+      path: PropTypes.string.isRequired,
+      title: PropTypes.string.isRequired
+    })
+  ),
+  /**
+   * @ignore
+   */
+  children: PropTypes.node,
+  /**
+   * The props used for each slot inside.
+   */
+  slotProps: PropTypes.shape({
+    toolbar: PropTypes.shape({
+      children: PropTypes.node
+    }).isRequired
+  }),
+  /**
+   * The components used for each slot inside.
+   */
+  slots: PropTypes.shape({
+    toolbar: PropTypes.elementType
+  }),
+  /**
+   * The title of the page. Leave blank to use the active page title.
+   */
+  title: PropTypes.string
+} as any;
+
+export { PageContainer };

package/src/PageContainer/PageContainerToolbar.test.tsx

@@ -0,0 +1,11 @@
+import { describe, test } from "vitest";
+import { PageContainerToolbar } from "./PageContainerToolbar";
+import describeConformance from "../utils/describeConformance";
+
+describe("PageContainerToolbar", () => {
+  describeConformance(<PageContainerToolbar />, () => ({
+    skip: ["themeDefaultProps"]
+  }));
+
+  test("dummy test", () => {});
+});

package/src/PageContainer/PageContainerToolbar.tsx

@@ -0,0 +1,31 @@
+"use client";
+import * as React from "react";
+import { styled } from "@mui/material";
+
+const PageContainerToolbarRoot = styled("div")(({ theme }) => ({
+  display: "flex",
+  flexDirection: "row",
+  gap: theme.spacing(1),
+  // Ensure the toolbar is always on the right side, even after wrapping
+  marginLeft: "auto"
+}));
+
+export interface PageContainerToolbarProps {
+  children?: React.ReactNode;
+}
+
+/**
+ *
+ * Demos:
+ *
+ * - [Page Container](https://mui.com/toolpad/core/react-page-container/)
+ *
+ * API:
+ *
+ * - [PageContainerToolbar API](https://mui.com/toolpad/core/api/page-container-toolbar)
+ */
+function PageContainerToolbar(props: PageContainerToolbarProps) {
+  return <PageContainerToolbarRoot {...props} />;
+}
+
+export { PageContainerToolbar };

package/src/PageContainer/index.ts

@@ -0,0 +1,2 @@
+export * from "./PageContainer";
+export * from "./PageContainerToolbar";

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from "./AppProvider";
+
+export * from "./DashboardLayout";
+
+export * from "./Account";
+
+export * from "./PageContainer";
+
+export * from "./useActivePage";
+
+export * from "./useLocalStorageState";
+
+export * from "./useSessionStorageState";
+
+export * from "./persistence/codec";

package/src/nextjs/AppProvider.test.tsx

@@ -0,0 +1,48 @@
+import * as React from "react";
+import { describe, test, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { AppProvider } from "./AppProvider";
+import { Router } from "../AppProvider";
+
+vi.mock("next/navigation", () => {
+  const searchParams = new URLSearchParams();
+  const push = () => {};
+  const replace = () => {};
+  const router = { push, replace };
+  return {
+    usePathname: () => "/",
+    useSearchParams: () => searchParams,
+    useRouter: () => router
+  };
+});
+
+vi.mock("next/router", () => ({ useRouter: () => null }));
+
+vi.mock("next/compat/router", () => ({ useRouter: () => null }));
+
+interface RouterTestProps {
+  children: React.ReactNode;
+}
+
+function RouterTest({ children }: RouterTestProps) {
+  const [pathname, setPathname] = React.useState("/page");
+
+  const router = React.useMemo<Router>(() => {
+    return {
+      pathname,
+      searchParams: new URLSearchParams(),
+      navigate: (path) => setPathname(String(path))
+    };
+  }, [pathname]);
+
+  return <AppProvider router={router}>{children}</AppProvider>;
+}
+
+describe("Nextjs AppProvider", () => {
+  test("renders content correctly", async () => {
+    // placeholder test
+    render(<RouterTest>Hello</RouterTest>);
+
+    expect(screen.getByText("Hello")).toBeTruthy();
+  });
+});

package/src/nextjs/AppProvider.tsx

@@ -0,0 +1,18 @@
+"use client";
+import { useRouter } from "next/compat/router";
+import { AppProviderNextApp } from "./AppProviderNextApp";
+import { AppProviderNextPages } from "./AppProviderNextPages";
+import type { AppProviderProps } from "../AppProvider";
+
+/**
+ * @ignore - internal component.
+ */
+function AppProvider(props: AppProviderProps) {
+  const router = useRouter();
+  const AppProviderComponent = router
+    ? AppProviderNextPages
+    : AppProviderNextApp;
+  return <AppProviderComponent {...props} />;
+}
+
+export { AppProvider };

package/src/nextjs/AppProviderNextApp.tsx

@@ -0,0 +1,37 @@
+import * as React from "react";
+import { usePathname, useSearchParams, useRouter } from "next/navigation";
+import type { AppProviderProps, Navigate, Router } from "../AppProvider";
+import { AppProvider } from "../AppProvider/AppProviderComponent";
+
+/**
+ * @ignore - internal component.
+ */
+export function AppProviderNextApp(props: AppProviderProps) {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const { push, replace } = useRouter();
+
+  const navigate = React.useCallback<Navigate>(
+    (url, { history = "auto" } = {}) => {
+      if (history === "auto" || history === "push") {
+        return push(String(url));
+      }
+      if (history === "replace") {
+        return replace(String(url));
+      }
+      throw new Error(`Invalid history option: ${history}`);
+    },
+    [push, replace]
+  );
+
+  const routerImpl = React.useMemo<Router>(
+    () => ({
+      pathname,
+      searchParams,
+      navigate
+    }),
+    [pathname, navigate, searchParams]
+  );
+
+  return <AppProvider router={routerImpl} {...props} />;
+}

package/src/nextjs/AppProviderNextPages.tsx

@@ -0,0 +1,52 @@
+import * as React from "react";
+import { useRouter } from "next/router";
+import type { AppProviderProps, Navigate, Router } from "../AppProvider";
+import { asArray } from "../utils/collections";
+import { AppProvider } from "../AppProvider/AppProviderComponent";
+
+/**
+ * @ignore - internal component.
+ */
+export function AppProviderNextPages(props: AppProviderProps) {
+  const { push, replace, asPath, query } = useRouter();
+
+  const search = React.useMemo(() => {
+    const params = new URLSearchParams();
+    Object.entries(query ?? {}).forEach(([key, value]) => {
+      asArray(value ?? []).forEach((v) => {
+        params.append(key, v);
+      });
+    });
+    return params.toString();
+  }, [query]);
+
+  // Stable search params object
+  const searchParams = React.useMemo(
+    () => new URLSearchParams(search),
+    [search]
+  );
+
+  const navigate = React.useCallback<Navigate>(
+    (url, { history = "auto" } = {}) => {
+      if (history === "auto" || history === "push") {
+        return push(String(url));
+      }
+      if (history === "replace") {
+        return replace(String(url));
+      }
+      throw new Error(`Invalid history option: ${history}`);
+    },
+    [push, replace]
+  );
+
+  const routerImpl = React.useMemo<Router>(
+    () => ({
+      pathname: asPath,
+      searchParams,
+      navigate
+    }),
+    [asPath, navigate, searchParams]
+  );
+
+  return <AppProvider router={routerImpl} {...props} />;
+}

package/src/nextjs/index.tsx

@@ -0,0 +1 @@
+export * from "./AppProvider";

package/src/persistence/codec.tsx

@@ -0,0 +1,81 @@
+/**
+ * A codec that can encode and decode values of type V to and from strings.
+ * @typeParam V The type of values that can be encoded and decoded.
+ */
+export interface Codec<V> {
+  /**
+   * Decodes a string value into a value of type V.
+   * @param value The value to decode.
+   * @returns The decoded value.
+   */
+  parse: (value: string) => V;
+  /**
+   * Encodes a value of type V into a string.
+   * @param value The value to encode.
+   * @returns The encoded value.
+   */
+  stringify: (value: V) => string;
+}
+
+/**
+ * A codec that can encode and decode Date objects to and from strings.
+ */
+export const CODEC_DATE: Codec<Date> = {
+  parse: (value) => new Date(value),
+  stringify: (value) => value.toISOString()
+};
+
+/**
+ * A codec that can encode and decode Date objects to and from strings, but only the date part.
+ */
+export const CODEC_DATE_ONLY: Codec<Date> = {
+  parse: (value) => new Date(value),
+  stringify: (value) => value.toISOString().split("T")[0]
+};
+
+/**
+ * A codec that can encode and decode numbers to and from strings.
+ */
+export const CODEC_NUMBER: Codec<number> = {
+  parse: (value) => Number(value),
+  stringify: (value) => String(value)
+};
+
+/**
+ * A codec that can encode and decode boolean values to and from strings.
+ */
+export const CODE_BOOLEAN: Codec<boolean> = {
+  parse: (value) => value === "true",
+  stringify: (value) => String(value)
+};
+
+/**
+ * A codec that can encode and decode JSON values to and from strings.
+ */
+export const CODEC_JSON: Codec<unknown> = {
+  parse: (value) => {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return null;
+    }
+  },
+  stringify: (value) => JSON.stringify(value)
+};
+
+/**
+ * A codec that can encode and decode JSON values to and from strings.
+ * If the JSON value is invalid, parsing will fail.
+ */
+export const CODEC_JSON_STRICT: Codec<unknown> = {
+  parse: (value) => JSON.parse(value),
+  stringify: (value) => JSON.stringify(value)
+};
+
+/**
+ * A codec that can encode and decode strings to and from strings.
+ */
+export const CODEC_STRING: Codec<string> = {
+  parse: (value) => value,
+  stringify: (value) => value
+};

package/src/persistence/index.ts

@@ -0,0 +1 @@
+export * from "./useStorageState";

package/src/persistence/useStorageState.test.tsx

@@ -0,0 +1,101 @@
+import { describe, test, expect, beforeEach } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import { useStorageState } from "./useStorageState";
+
+describe("useStorageState", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+  });
+
+  test("can do basic local storage with initial value", async () => {
+    const { result, rerender } = renderHook(() =>
+      useStorageState(window.localStorage, "foo", "bar")
+    );
+
+    expect(result.current[0]).toBe("bar");
+
+    act(() => {
+      result.current[1]("baz");
+    });
+
+    rerender();
+
+    expect(result.current[0]).toBe("baz");
+  });
+
+  test("can do basic local storage without initial value", async () => {
+    const { result, rerender } = renderHook(() =>
+      useStorageState(window.localStorage, "foo")
+    );
+
+    expect(result.current[0]).toBe(null);
+
+    act(() => {
+      result.current[1]("baz");
+    });
+
+    rerender();
+
+    expect(result.current[0]).toBe("baz");
+  });
+
+  test("can clear storage value, and reset to intiial value", async () => {
+    const { result, rerender } = renderHook(() =>
+      useStorageState(window.localStorage, "foo", "bar")
+    );
+
+    act(() => {
+      result.current[1]("baz");
+    });
+
+    rerender();
+
+    expect(result.current[0]).toBe("baz");
+
+    act(() => {
+      result.current[1](null);
+    });
+
+    rerender();
+
+    expect(result.current[0]).toBe("bar");
+  });
+
+  test("can clear storage value", async () => {
+    const { result, rerender } = renderHook(() =>
+      useStorageState(window.localStorage, "foo")
+    );
+
+    act(() => {
+      result.current[1]("baz");
+    });
+
+    rerender();
+
+    expect(result.current[0]).toBe("baz");
+
+    act(() => {
+      result.current[1](null);
+    });
+
+    rerender();
+
+    expect(result.current[0]).toBe(null);
+  });
+
+  test("can handle complex types", async () => {
+    const { result, rerender } = renderHook(() =>
+      useStorageState(window.localStorage, "foo", { a: 1 }, { codec: JSON })
+    );
+
+    expect(result.current[0]).toEqual({ a: 1 });
+
+    act(() => {
+      result.current[1]({ b: 2 });
+    });
+
+    rerender();
+
+    expect(result.current[0]).toEqual({ b: 2 });
+  });
+});