@etsoo/toolpad 1.0.0

package/src/persistence/useStorageState.tsx

@@ -0,0 +1,244 @@
+"use client";
+import * as React from "react";
+import { CODEC_STRING, Codec } from "./codec";
+
+// storage events only work across tabs, we'll use an event emitter to announce within the current tab
+const currentTabChangeListeners = new Map<string, Set<() => void>>();
+
+function onCurrentTabStorageChange(key: string, handler: () => void) {
+  let listeners = currentTabChangeListeners.get(key);
+
+  if (!listeners) {
+    listeners = new Set();
+    currentTabChangeListeners.set(key, listeners);
+  }
+
+  listeners.add(handler);
+}
+
+function offCurrentTabStorageChange(key: string, handler: () => void) {
+  const listeners = currentTabChangeListeners.get(key);
+  if (!listeners) {
+    return;
+  }
+
+  listeners.delete(handler);
+
+  if (listeners.size === 0) {
+    currentTabChangeListeners.delete(key);
+  }
+}
+
+function emitCurrentTabStorageChange(key: string) {
+  const listeners = currentTabChangeListeners.get(key);
+  if (listeners) {
+    listeners.forEach((listener) => listener());
+  }
+}
+
+if (typeof window !== "undefined") {
+  const origSetItem = window.localStorage.setItem;
+  window.localStorage.setItem = function setItem(key, value) {
+    const result = origSetItem.call(this, key, value);
+    emitCurrentTabStorageChange(key);
+    return result;
+  };
+}
+
+function subscribe(
+  area: Storage,
+  key: string | null,
+  callback: () => void
+): () => void {
+  if (!key) {
+    return () => {};
+  }
+  const storageHandler = (event: StorageEvent) => {
+    if (event.storageArea === area && event.key === key) {
+      callback();
+    }
+  };
+  window.addEventListener("storage", storageHandler);
+  onCurrentTabStorageChange(key, callback);
+  return () => {
+    window.removeEventListener("storage", storageHandler);
+    offCurrentTabStorageChange(key, callback);
+  };
+}
+
+function getSnapshot(area: Storage, key: string | null): string | null {
+  if (!key) {
+    return null;
+  }
+  try {
+    return area.getItem(key);
+  } catch {
+    // ignore
+    // See https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API#feature-detecting_localstorage
+    return null;
+  }
+}
+
+function setValue(area: Storage, key: string | null, value: string | null) {
+  if (!key) {
+    return;
+  }
+  try {
+    if (value === null) {
+      area.removeItem(key);
+    } else {
+      area.setItem(key, String(value));
+    }
+  } catch {
+    // ignore
+    // See https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API#feature-detecting_localstorage
+    return;
+  }
+  emitCurrentTabStorageChange(key);
+}
+
+export type StorageStateInitializer<T> = () => T | null;
+
+export type UseStorageStateHookResult<T> = [
+  T | null,
+  React.Dispatch<React.SetStateAction<T | null>>
+];
+
+const serverValue: UseStorageStateHookResult<any> = [null, () => {}];
+
+export function useStorageStateServer<
+  T = string
+>(): UseStorageStateHookResult<T> {
+  return serverValue;
+}
+
+export interface DefaultStorageStateoptions<T = string> {
+  codec?: Codec<T>;
+}
+export interface StorageStateOptions<T> extends DefaultStorageStateoptions<T> {
+  codec: Codec<T>;
+}
+
+function encode<V>(codec: Codec<V>, value: V | null): string | null {
+  return value === null ? null : codec.stringify(value);
+}
+
+function decode<V>(codec: Codec<V>, value: string | null): V | null {
+  return value === null ? null : codec.parse(value);
+}
+
+// Start with null for the hydration, and then switch to the actual value.
+const getKeyServerSnapshot = () => null;
+
+/**
+ * Sync state to local storage so that it persists through a page refresh. Usage is
+ * similar to useState except we pass in a storage key so that we can default
+ * to that value on page load instead of the specified initial value.
+ *
+ * Since the storage API isn't available in server-rendering environments, we
+ * return null during SSR and hydration.
+ */
+export function useStorageState(
+  area: Storage,
+  key: string | null,
+  initializer?: string | null | StorageStateInitializer<string>,
+  options?: DefaultStorageStateoptions
+): UseStorageStateHookResult<string>;
+export function useStorageState<T>(
+  area: Storage,
+  key: string | null,
+  initializer: T | null | StorageStateInitializer<T>,
+  options: StorageStateOptions<T>
+): UseStorageStateHookResult<T>;
+export function useStorageState<T = string>(
+  area: Storage,
+  key: string | null,
+  initializer: T | null | StorageStateInitializer<T> = null,
+  options?: DefaultStorageStateoptions | StorageStateOptions<T>
+): UseStorageStateHookResult<T> {
+  const codec = (options?.codec ?? CODEC_STRING) as Codec<T>;
+
+  const [initialValue] = React.useState(initializer);
+  const encodedInitialValue = React.useMemo(
+    () => encode(codec, initialValue),
+    [codec, initialValue]
+  );
+
+  const subscribeKey = React.useCallback(
+    (callback: () => void) => subscribe(area, key, callback),
+    [area, key]
+  );
+
+  const getKeySnapshot = React.useCallback<() => string | null>(
+    () => getSnapshot(area, key) ?? encodedInitialValue,
+    [area, encodedInitialValue, key]
+  );
+
+  const encodedStoredValue = React.useSyncExternalStore(
+    subscribeKey,
+    getKeySnapshot,
+    getKeyServerSnapshot
+  );
+
+  const storedValue = React.useMemo(
+    () => decode(codec, encodedStoredValue),
+    [codec, encodedStoredValue]
+  );
+
+  const setStoredValue = React.useCallback(
+    (value: React.SetStateAction<T | null>) => {
+      const valueToStore =
+        value instanceof Function ? value(storedValue) : value;
+      const encodedValueToStore = encode(codec, valueToStore);
+      setValue(area, key, encodedValueToStore);
+    },
+    [area, codec, storedValue, key]
+  );
+
+  const [nonStoredValue, setNonStoredValue] = React.useState(initialValue);
+
+  if (!key) {
+    return [nonStoredValue, setNonStoredValue];
+  }
+
+  return [storedValue, setStoredValue];
+}
+
+export interface UseStorageState {
+  /**
+   * Sync state to local or session storage so that it persists through a page refresh. Usage is
+   * similar to useState except we pass in a storage key that uniquely identifies the value.
+   * @param key The key to use for storing the value in local or session storage.
+   * @param initializer The initial value to use if the key is not present in storage.
+   * @param options Additional options for the storage state.
+   */
+  (
+    key: string | null,
+    initializer?: string | null | StorageStateInitializer<string>,
+    options?: DefaultStorageStateoptions
+  ): UseStorageStateHookResult<string>;
+  /**
+   * Sync state to local or session storage so that it persists through a page refresh. Usage is
+   * similar to useState except we pass in a storage key that uniquely identifies the value.
+   * @param key The key to use for storing the value in local or session storage.
+   * @param initializer The initial value to use if the key is not present in storage.
+   * @param options Additional options for the storage state.
+   */
+  <T>(
+    key: string | null,
+    initializer: T | null | StorageStateInitializer<T>,
+    options: StorageStateOptions<T>
+  ): UseStorageStateHookResult<T>;
+  /**
+   * Sync state to local or session storage so that it persists through a page refresh. Usage is
+   * similar to useState except we pass in a storage key that uniquely identifies the value.
+   * @param key The key to use for storing the value in local or session storage.
+   * @param initializer The initial value to use if the key is not present in storage.
+   * @param options Additional options for the storage state.
+   */
+  <T>(
+    key: string | null,
+    initializer?: T | null | StorageStateInitializer<T>,
+    options?: StorageStateOptions<T>
+  ): UseStorageStateHookResult<T>;
+}

package/src/react-router-dom/AppProvider.test.tsx

@@ -0,0 +1,17 @@
+import { describe, test, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { BrowserRouter } from "react-router-dom";
+import { AppProvider } from "./AppProvider";
+
+describe("React Router AppProvider", () => {
+  test("renders content correctly", async () => {
+    // placeholder test
+    render(
+      <BrowserRouter>
+        <AppProvider>Hello</AppProvider>
+      </BrowserRouter>
+    );
+
+    expect(screen.getByText("Hello")).toBeTruthy();
+  });
+});

package/src/react-router-dom/AppProvider.tsx

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

package/src/react-router-dom/index.tsx

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

package/src/shared/Link.tsx

@@ -0,0 +1,37 @@
+import * as React from "react";
+import { RouterContext } from "./context";
+
+/**
+ * @ignore - internal component.
+ */
+
+export interface LinkProps
+  extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  history?: "auto" | "push" | "replace";
+}
+
+export const Link = React.forwardRef(function Link(
+  props: LinkProps,
+  ref: React.ForwardedRef<HTMLAnchorElement>
+) {
+  const { children, href, onClick, history, ...rest } = props;
+  const routerContext = React.useContext(RouterContext);
+
+  const handleLinkClick = React.useMemo(() => {
+    if (!routerContext) {
+      return onClick;
+    }
+    return (event: React.MouseEvent<HTMLAnchorElement>) => {
+      event.preventDefault();
+      const url = new URL(event.currentTarget.href);
+      routerContext.navigate(url.pathname, { history });
+      onClick?.(event);
+    };
+  }, [routerContext, onClick, history]);
+
+  return (
+    <a ref={ref} href={href} {...rest} onClick={handleLinkClick}>
+      {children}
+    </a>
+  );
+});

package/src/shared/branding.ts

@@ -0,0 +1,7 @@
+import * as React from "react";
+import { BrandingContext } from "./context";
+
+export function useApplicationTitle() {
+  const branding = React.useContext(BrandingContext);
+  return branding?.title ?? "Toolpad";
+}

package/src/shared/components.tsx

@@ -0,0 +1,46 @@
+import * as React from "react";
+import { CircularProgress, Typography, styled } from "@mui/material";
+import ErrorIcon from "@mui/icons-material/Error";
+
+const OverlayRoot = styled("div")(({ theme }) => ({
+  position: "absolute",
+  inset: "0 0 0 0",
+  display: "flex",
+  flexDirection: "column",
+  alignItems: "center",
+  justifyContent: "center",
+  padding: theme.spacing(2)
+}));
+
+export interface ErrorOverlayProps {
+  error?: unknown;
+}
+
+export function ErrorOverlay({ error }: ErrorOverlayProps) {
+  return (
+    <OverlayRoot>
+      <Typography
+        variant="h6"
+        sx={{
+          display: "flex",
+          flexDirection: "row",
+          gap: 1,
+          alignItems: "center"
+        }}
+      >
+        <ErrorIcon color="error" /> Error
+      </Typography>
+      <Typography textAlign="center">
+        {(error as any)?.message ?? "Unknown error"}
+      </Typography>
+    </OverlayRoot>
+  );
+}
+
+export function LoadingOverlay() {
+  return (
+    <OverlayRoot>
+      <CircularProgress />
+    </OverlayRoot>
+  );
+}

package/src/shared/context.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+import type { PaletteMode } from "@mui/material";
+import type { Branding, Navigation, Router } from "../AppProvider";
+
+export const BrandingContext = React.createContext<Branding | null>(null);
+
+export const NavigationContext = React.createContext<Navigation>([]);
+
+export const PaletteModeContext = React.createContext<{
+  paletteMode: PaletteMode;
+  setPaletteMode: (mode: PaletteMode) => void;
+  isDualTheme: boolean;
+}>({
+  paletteMode: "light",
+  setPaletteMode: () => {},
+  isDualTheme: false
+});
+
+export const RouterContext = React.createContext<Router | null>(null);
+
+export const WindowContext = React.createContext<Window | undefined>(undefined);

package/src/shared/locales/LocaleContext.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+import * as React from "react";
+import DEFAULT_LOCALE_TEXT from "./en";
+
+export type LocaleContextType = {
+  // Account
+  signInLabel?: string;
+  signOutLabel?: string;
+  // Account Preview
+  iconButtonAriaLabel?: string;
+};
+
+export const LocaleContext =
+  React.createContext<LocaleContextType>(DEFAULT_LOCALE_TEXT);
+
+export interface LocaleProviderProps {
+  localeText?: Partial<LocaleContextType>;
+  children: React.ReactNode;
+}
+
+/**
+ * @ignore - internal component.
+ */
+export function LocaleProvider({ localeText, children }: LocaleProviderProps) {
+  const mergedLocaleText = React.useMemo(
+    () => ({ ...DEFAULT_LOCALE_TEXT, ...localeText }),
+    [localeText]
+  );
+
+  return (
+    <LocaleContext.Provider value={mergedLocaleText}>
+      {children}
+    </LocaleContext.Provider>
+  );
+}
+
+/**
+ * @ignore - internal hook.
+ */
+
+export function useLocaleText() {
+  return React.useContext(LocaleContext);
+}

package/src/shared/locales/en.tsx

@@ -0,0 +1,9 @@
+const TOOLPAD_CORE_DEFAULT_LOCALE_TEXT = {
+  // Account
+  signInLabel: "Sign In",
+  signOutLabel: "Sign Out",
+  // Account Preview
+  iconButtonAriaLabel: "Current User"
+};
+
+export default TOOLPAD_CORE_DEFAULT_LOCALE_TEXT;

package/src/shared/navigation.tsx

@@ -0,0 +1,197 @@
+import { pathToRegexp } from "path-to-regexp";
+import invariant from "invariant";
+import type {
+  Navigation,
+  NavigationItem,
+  NavigationPageItem,
+  NavigationSubheaderItem
+} from "../AppProvider";
+
+export const getItemKind = (item: NavigationItem) => item.kind ?? "page";
+
+export const isPageItem = (item: NavigationItem): item is NavigationPageItem =>
+  getItemKind(item) === "page";
+
+export const getItemTitle = (
+  item: NavigationPageItem | NavigationSubheaderItem
+) => {
+  return isPageItem(item) ? item.title ?? item.segment ?? "" : item.title;
+};
+
+export function getPageItemFullPath(
+  basePath: string,
+  navigationItem: NavigationPageItem
+) {
+  return `${basePath}${basePath && !navigationItem.segment ? "" : "/"}${
+    navigationItem.segment ?? ""
+  }`;
+}
+
+export function isPageItemSelected(
+  navigationItem: NavigationPageItem,
+  basePath: string,
+  pathname: string
+) {
+  return navigationItem.pattern
+    ? pathToRegexp(`${basePath}/${navigationItem.pattern}`).test(pathname)
+    : getPageItemFullPath(basePath, navigationItem) === pathname;
+}
+
+export function hasSelectedNavigationChildren(
+  navigationItem: NavigationItem,
+  basePath: string,
+  pathname: string
+): boolean {
+  if (isPageItem(navigationItem) && navigationItem.children) {
+    const navigationItemFullPath = getPageItemFullPath(
+      basePath,
+      navigationItem
+    );
+
+    return navigationItem.children.some((nestedNavigationItem) => {
+      if (!isPageItem(nestedNavigationItem)) {
+        return false;
+      }
+
+      if (nestedNavigationItem.children) {
+        return hasSelectedNavigationChildren(
+          nestedNavigationItem,
+          navigationItemFullPath,
+          pathname
+        );
+      }
+
+      return isPageItemSelected(
+        nestedNavigationItem,
+        navigationItemFullPath,
+        pathname
+      );
+    });
+  }
+
+  return false;
+}
+
+/**
+ * Builds a map of navigation page items to their respective paths. This map is used to quickly
+ * lookup the path of a navigation item. It will be cached for the lifetime of the navigation.
+ */
+function buildItemToPathMap(
+  navigation: Navigation
+): Map<NavigationPageItem, string> {
+  const map = new Map<NavigationPageItem, string>();
+
+  const visit = (item: NavigationItem, base: string) => {
+    if (isPageItem(item)) {
+      const path = `${base}${item.segment ? `/${item.segment}` : ""}` || "/";
+      map.set(item, path);
+      if (item.children) {
+        for (const child of item.children) {
+          visit(child, path);
+        }
+      }
+    }
+  };
+
+  for (const item of navigation) {
+    visit(item, "");
+  }
+
+  return map;
+}
+
+const itemToPathMapCache = new WeakMap<
+  Navigation,
+  Map<NavigationPageItem, string>
+>();
+
+/**
+ * Gets the cached map of navigation page items to their respective paths.
+ */
+function getItemToPathMap(navigation: Navigation) {
+  let map = itemToPathMapCache.get(navigation);
+  if (!map) {
+    map = buildItemToPathMap(navigation);
+    itemToPathMapCache.set(navigation, map);
+  }
+  return map;
+}
+
+/**
+ * Build a lookup map of paths to navigation items. This map is used to match paths against
+ * to find the active page.
+ */
+function buildItemLookup(navigation: Navigation) {
+  const map = new Map<string | RegExp, NavigationPageItem>();
+  const visit = (item: NavigationItem) => {
+    if (isPageItem(item)) {
+      const path = getItemPath(navigation, item);
+      if (map.has(path)) {
+        console.warn(`Duplicate path in navigation: ${path}`);
+      }
+      map.set(path, item);
+      if (item.pattern) {
+        const basePath = item.segment
+          ? path.slice(0, -item.segment.length)
+          : path;
+        map.set(pathToRegexp(basePath + item.pattern), item);
+      }
+      if (item.children) {
+        for (const child of item.children) {
+          visit(child);
+        }
+      }
+    }
+  };
+  for (const item of navigation) {
+    visit(item);
+  }
+  return map;
+}
+const itemLookupMapCache = new WeakMap<
+  Navigation,
+  Map<string | RegExp, NavigationPageItem>
+>();
+function getItemLookup(navigation: Navigation) {
+  let map = itemLookupMapCache.get(navigation);
+  if (!map) {
+    map = buildItemLookup(navigation);
+    itemLookupMapCache.set(navigation, map);
+  }
+  return map;
+}
+
+/**
+ * Matches a path against the navigation to find the active page. i.e. the page that should be
+ * marked as selected in the navigation.
+ */
+export function matchPath(
+  navigation: Navigation,
+  path: string
+): NavigationPageItem | null {
+  const lookup = getItemLookup(navigation);
+
+  for (const [key, item] of lookup.entries()) {
+    if (typeof key === "string" && key === path) {
+      return item;
+    }
+    if (key instanceof RegExp && key.test(path)) {
+      return item;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Gets the path for a specific navigation page item.
+ */
+export function getItemPath(
+  navigation: Navigation,
+  item: NavigationPageItem
+): string {
+  const map = getItemToPathMap(navigation);
+  const path = map.get(item);
+  invariant(path, `Item not found in navigation: ${item.title}`);
+  return path;
+}

package/src/useActivePage/index.ts

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