@etsoo/toolpad 1.0.0

package/src/useActivePage/useActivePage.ts

@@ -0,0 +1,66 @@
+"use client";
+import * as React from "react";
+import { NavigationContext, RouterContext } from "../shared/context";
+import { getItemPath, getItemTitle, matchPath } from "../shared/navigation";
+import type { Breadcrumb } from "../PageContainer";
+
+export interface ActivePage {
+  title: string;
+  path: string;
+  /**
+   * @deprecated Use `breadcrumbs` instead.
+   */
+  breadCrumbs: Breadcrumb[];
+  breadcrumbs: Breadcrumb[];
+}
+
+export function useActivePage(): ActivePage | null {
+  const navigationContext = React.useContext(NavigationContext);
+  const routerContext = React.useContext(RouterContext);
+  const pathname = routerContext?.pathname ?? "/";
+  const activeItem = matchPath(navigationContext, pathname);
+
+  const rootItem = matchPath(navigationContext, "/");
+
+  return React.useMemo(() => {
+    if (!activeItem) {
+      return null;
+    }
+
+    const breadcrumbs: Breadcrumb[] = [];
+
+    if (rootItem) {
+      breadcrumbs.push({
+        title: getItemTitle(rootItem),
+        path: "/"
+      });
+    }
+
+    const segments = pathname.split("/").filter(Boolean);
+    let prefix = "";
+    for (const segment of segments) {
+      const path = `${prefix}/${segment}`;
+      prefix = path;
+      const item = matchPath(navigationContext, path);
+      if (!item) {
+        continue;
+      }
+      const itemPath = getItemPath(navigationContext, item);
+      const lastCrumb = breadcrumbs[breadcrumbs.length - 1];
+      if (lastCrumb?.path !== itemPath) {
+        breadcrumbs.push({
+          title: getItemTitle(item),
+          path: itemPath
+        });
+      }
+    }
+
+    return {
+      title: getItemTitle(activeItem),
+      path: getItemPath(navigationContext, activeItem),
+      breadcrumbs,
+      // TODO: Remove in the next major version
+      breadCrumbs: breadcrumbs
+    };
+  }, [activeItem, rootItem, pathname, navigationContext]);
+}

package/src/useLocalStorageState/index.ts

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

package/src/useLocalStorageState/useLocalStorageState.tsx

@@ -0,0 +1,23 @@
+"use client";
+import {
+  UseStorageState,
+  useStorageState,
+  useStorageStateServer
+} from "../persistence";
+
+/**
+ * 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.
+ */
+const useLocalStorageStateBrowser: UseStorageState = (
+  ...args: [any, any, any]
+) => useStorageState(window.localStorage, ...args);
+
+export const useLocalStorageState: UseStorageState =
+  typeof window === "undefined"
+    ? useStorageStateServer
+    : useLocalStorageStateBrowser;

package/src/useSessionStorageState/index.tsx

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

package/src/useSessionStorageState/useSessionStorageState.tsx

@@ -0,0 +1,23 @@
+"use client";
+import {
+  UseStorageState,
+  useStorageState,
+  useStorageStateServer
+} from "../persistence";
+
+/**
+ * Sync state to session 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.
+ */
+const useSessionStorageStateBrowser: UseStorageState = (
+  ...args: [any, any, any]
+) => useStorageState(window.sessionStorage, ...args);
+
+export const useSessionStorageState: UseStorageState =
+  typeof window === "undefined"
+    ? useStorageStateServer
+    : useSessionStorageStateBrowser;

package/src/utils/collections.ts

@@ -0,0 +1,125 @@
+export function asArray<T>(maybeArray: T | T[]): T[] {
+  return Array.isArray(maybeArray) ? maybeArray : [maybeArray];
+}
+
+type PropertiesOf<P> = Extract<keyof P, string>;
+
+type Require<T, K extends keyof T> = T & { [P in K]-?: T[P] };
+
+type Ensure<U, K extends PropertyKey> = K extends keyof U
+  ? Require<U, K>
+  : U & Record<K, unknown>;
+
+/**
+ * Type aware version of Object.protoype.hasOwnProperty.
+ * See https://fettblog.eu/typescript-hasownproperty/
+ */
+export function hasOwnProperty<X extends {}, Y extends PropertyKey>(
+  obj: X,
+  prop: Y
+): obj is Ensure<X, Y> {
+  return obj.hasOwnProperty(prop);
+}
+
+/**
+ * Maps `obj` to a new object. The `mapper` function receives an entry array of key and value and
+ * is allowed to manipulate both. It can also return `null` to omit a property from the result.
+ */
+export function mapProperties<P, L extends PropertyKey, U>(
+  obj: P,
+  mapper: <K extends PropertiesOf<P>>(old: [K, P[K]]) => [L, U] | null
+): Record<L, U>;
+export function mapProperties<U, V>(
+  obj: Record<string, U>,
+  mapper: (old: [string, U]) => [string, V] | null
+): Record<string, V> {
+  return Object.fromEntries(
+    Object.entries(obj).flatMap((entry) => {
+      const mapped = mapper(entry);
+      return mapped ? [mapped] : [];
+    })
+  );
+}
+
+/**
+ * Maps an objects' property keys. The result is a new object with the mapped keys, but the same values.
+ */
+export function mapKeys<U>(
+  obj: Record<string, U>,
+  mapper: (old: string) => string
+): Record<string, U> {
+  return mapProperties(obj, ([key, value]) => [mapper(key), value]);
+}
+
+/**
+ * Maps an objects' property values. The result is a new object with the same keys, but mapped values.
+ */
+export function mapValues<P, V>(
+  obj: P,
+  mapper: (old: P[PropertiesOf<P>], key: PropertiesOf<P>) => V
+): Record<PropertiesOf<P>, V> {
+  return mapProperties(obj, ([key, value]) => [key, mapper(value, key)]);
+}
+/**
+ * Filters an objects' property values. Similar to `array.filter` but for objects. The result is a new
+ * object with all the properties removed for which `filter` returned `false`.
+ */
+export function filterValues<K extends PropertyKey, P, Q extends P>(
+  obj: Record<K, P>,
+  filter: (old: P) => old is Q
+): Record<K, Q>;
+export function filterValues<P>(
+  obj: P,
+  filter: (old: P[keyof P]) => boolean
+): Partial<P>;
+export function filterValues<U>(
+  obj: Record<string, U>,
+  filter: (old: U) => boolean
+): Record<string, U>;
+export function filterValues<U>(
+  obj: Record<string, U>,
+  filter: (old: U) => boolean
+): Record<string, U> {
+  return mapProperties(obj, ([key, value]) =>
+    filter(value) ? [key, value] : null
+  );
+}
+
+/**
+ * Filters an objects' property keys. Similar to `array.filter` but for objects. The result is a new
+ * object with all the properties removed for which `filter` returned `false`.
+ */
+export function filterKeys<P>(
+  obj: P,
+  filter: (old: keyof P) => boolean
+): Partial<P>;
+export function filterKeys<U>(
+  obj: Record<string, U>,
+  filter: (old: string) => boolean
+): Record<string, U>;
+export function filterKeys<U>(
+  obj: Record<string, U>,
+  filter: (old: string) => boolean
+): Record<string, U> {
+  return mapProperties(obj, ([key, value]) =>
+    filter(key) ? [key, value] : null
+  );
+}
+
+/**
+ * Compares the properties of two objects. Returns `true` if all properties are strictly equal, `false`
+ * otherwise.
+ * Pass a subset of properties to only compare those.
+ */
+export function equalProperties<P extends object>(
+  obj1: P,
+  obj2: P,
+  subset?: (keyof P)[]
+): boolean {
+  const keysToCheck = new Set(
+    subset ?? ([...Object.keys(obj1), ...Object.keys(obj2)] as (keyof P)[])
+  );
+  return Array.from(keysToCheck).every((key) =>
+    Object.is(obj1[key], obj2[key])
+  );
+}

package/src/utils/describeConformance.ts

@@ -0,0 +1,14 @@
+import * as React from "react";
+
+export interface ConformanceOptions {
+  refInstanceof?: unknown;
+  inheritComponent?: React.ElementType;
+  skip?: Array<"themeDefaultProps">;
+}
+
+export default function describeConformance(
+  minimalElement: React.ReactElement<unknown>,
+  getOptions: () => ConformanceOptions
+) {
+  getOptions();
+}

package/src/utils/events.ts

@@ -0,0 +1,81 @@
+export type EventName = string | symbol;
+
+export type EventHandlers = Record<EventName, unknown>;
+
+export type EventHandler<
+  T extends EventHandlers,
+  K extends keyof T = keyof T
+> = (event: T[K]) => void;
+
+export type AllEventsHandler<
+  T extends EventHandlers,
+  K extends keyof T = keyof T
+> = (type: K, event: T[K]) => void;
+
+/**
+ * Lightweight event emitter
+ */
+export class Emitter<T extends EventHandlers = {}> {
+  private handlers = new Map<
+    keyof T,
+    Set<EventHandler<T> | AllEventsHandler<T>>
+  >();
+
+  /**
+   * Add a listener for an event
+   */
+  on(name: "*", handler: AllEventsHandler<T>): void;
+  on<K extends keyof T>(name: K, handler: EventHandler<T, K>): void;
+  on<K extends keyof T>(
+    name: K | "*",
+    handler: EventHandler<T, K> | AllEventsHandler<T>
+  ): void {
+    let eventHandlers = this.handlers.get(name);
+    if (!eventHandlers) {
+      eventHandlers = new Set();
+      this.handlers.set(name, eventHandlers);
+    }
+    eventHandlers.add(handler as EventHandler<T> | AllEventsHandler<T>);
+  }
+
+  /**
+   * Remove a listener from an event
+   */
+  off<K extends keyof T>(name: K, handler: EventHandler<T, K>) {
+    const eventHandlers = this.handlers.get(name);
+    if (eventHandlers) {
+      eventHandlers.delete(handler as EventHandler<T> | AllEventsHandler<T>);
+      if (eventHandlers.size <= 0) {
+        this.handlers.delete(name);
+      }
+    }
+  }
+
+  /**
+   * Subscribe to an event and return an unsubscribe function.
+   */
+  subscribe<K extends keyof T>(name: K, handler: EventHandler<T, K>) {
+    this.on(name, handler);
+    return () => {
+      this.off(name, handler);
+    };
+  }
+
+  /**
+   * Emit an event.
+   */
+  emit<K extends keyof T>(name: K, event: T[K]) {
+    const eventHandlers = this.handlers.get(name);
+    if (eventHandlers) {
+      for (const eventHandler of eventHandlers) {
+        (eventHandler as EventHandler<T, K>)(event);
+      }
+    }
+    const allHandlers = this.handlers.get("*");
+    if (allHandlers) {
+      for (const eventHandler of allHandlers) {
+        (eventHandler as AllEventsHandler<T>)(name, event);
+      }
+    }
+  }
+}

package/src/utils/hooks/index.ts

@@ -0,0 +1,2 @@
+export { default as useBoolean } from "./useBoolean";
+export { default as usePageTitle } from "./usePageTitle";

package/src/utils/hooks/useBoolean.ts

@@ -0,0 +1,12 @@
+import * as React from "react";
+
+/**
+ * A utility with shortcuts to manipulate boolean values.
+ */
+export default function useBoolean(initialValue: boolean) {
+  const [value, setValue] = React.useState(initialValue);
+  const toggle = React.useCallback(() => setValue((existing) => !existing), []);
+  const setTrue = React.useCallback(() => setValue(true), []);
+  const setFalse = React.useCallback(() => setValue(false), []);
+  return { value, setValue, toggle, setTrue, setFalse };
+}

package/src/utils/hooks/useDebounced.ts

@@ -0,0 +1,39 @@
+import * as React from "react";
+
+/**
+ * This hook allows you to debounce any fast changing value. The debounced value will only
+ * reflect the latest value when the useDebounce hook has not been called for the specified
+ * time period.
+ *
+ * Inspired by https://usehooks.com/useDebounce/
+ */
+export default function useDebounced<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = React.useState(() => value);
+  const timeoutIdRef = React.useRef<NodeJS.Timeout | null>(null);
+
+  React.useEffect(
+    () => () => {
+      if (timeoutIdRef.current) {
+        clearTimeout(timeoutIdRef.current);
+        timeoutIdRef.current = null;
+      }
+    },
+    []
+  );
+
+  React.useEffect(() => {
+    timeoutIdRef.current = setTimeout(
+      () => setDebouncedValue(() => value),
+      delay
+    );
+
+    return () => {
+      if (timeoutIdRef.current) {
+        clearTimeout(timeoutIdRef.current);
+        timeoutIdRef.current = null;
+      }
+    };
+  }, [value, delay]);
+
+  return debouncedValue;
+}

package/src/utils/hooks/useDebouncedHandler.ts

@@ -0,0 +1,71 @@
+import * as React from "react";
+
+interface Handler<P extends unknown[]> {
+  (...params: P): void;
+}
+
+interface DelayedInvocation<P extends unknown[]> {
+  startTime: number;
+  timeout: NodeJS.Timeout;
+  params: P;
+}
+
+function defer<P extends unknown[]>(
+  fn: React.MutableRefObject<Handler<P>>,
+  params: P,
+  delay: number
+) {
+  const timeout = setTimeout(() => {
+    fn.current(...params);
+  }, delay);
+
+  return { startTime: Date.now(), timeout, params };
+}
+
+/**
+ * Creates a debounced version of the handler that is passed. The invocation of [fn] is
+ * delayed for [delay] milliseconds from the last invocation of the debounced function.
+ *
+ * This implementation adds on the lodash implementation in that it handles updates to the
+ * delay value.
+ */
+export default function useDebouncedHandler<P extends unknown[]>(
+  fn: Handler<P>,
+  delay: number
+): Handler<P> {
+  const fnRef = React.useRef(fn);
+  React.useEffect(() => {
+    fnRef.current = fn;
+  }, [fn]);
+
+  const delayedInvocation = React.useRef<DelayedInvocation<P> | null>(null);
+
+  const clearCurrent = React.useCallback(() => {
+    if (delayedInvocation.current) {
+      clearTimeout(delayedInvocation.current.timeout);
+      delayedInvocation.current = null;
+    }
+  }, []);
+
+  React.useEffect(() => {
+    if (!delayedInvocation.current) {
+      return;
+    }
+
+    const { startTime, params } = delayedInvocation.current;
+
+    const elapsed = Date.now() - startTime;
+    const newDelay = Math.max(delay - elapsed, 0);
+
+    clearCurrent();
+    delayedInvocation.current = defer(fnRef, params, newDelay);
+  }, [delay, clearCurrent]);
+
+  return React.useCallback(
+    (...params: P) => {
+      clearCurrent();
+      delayedInvocation.current = defer(fnRef, params, delay);
+    },
+    [delay, clearCurrent]
+  );
+}

package/src/utils/hooks/useLatest.ts

@@ -0,0 +1,16 @@
+import * as React from "react";
+
+/**
+ * Returns the latest non-null, non-undefined value that has been passed to it.
+ */
+function useLatest<T>(value: T): T;
+function useLatest<T>(value: T | null | undefined): T | null | undefined;
+function useLatest<T>(value: T | null | undefined): T | null | undefined {
+  const [latest, setLatest] = React.useState<T | null | undefined>(value);
+  if (latest !== value && value !== null && value !== undefined) {
+    setLatest(value);
+  }
+  return value ?? latest;
+}
+
+export default useLatest;

package/src/utils/hooks/usePageTitle.ts

@@ -0,0 +1,14 @@
+import * as React from "react";
+
+/**
+ * Sets the current document title.
+ */
+export default function usePageTitle(title: string) {
+  React.useEffect(() => {
+    const original = document.title;
+    document.title = title;
+    return () => {
+      document.title = original;
+    };
+  }, [title]);
+}

package/src/utils/hooks/useSsr.ts

@@ -0,0 +1,24 @@
+import * as React from "react";
+
+function subscribe() {
+  return () => {};
+}
+
+function getSnapshot() {
+  return false;
+}
+
+function getServerSnapshot() {
+  return true;
+}
+
+/**
+ * Returns true when serverside rendering, or when hydrating.
+ */
+export default function useSsr() {
+  return React.useSyncExternalStore<boolean>(
+    subscribe,
+    getSnapshot,
+    getServerSnapshot
+  );
+}

package/src/utils/hooks/useStorageState.ts

@@ -0,0 +1,130 @@
+import * as React from "react";
+import { Emitter } from "../events";
+
+// storage events only work across windows, we'll use an event emitter to announce within the window
+const emitter = new Emitter<Record<string, null>>();
+
+function subscribe(area: Storage, key: string, cb: () => void): () => void {
+  const storageHandler = (event: StorageEvent) => {
+    if (event.storageArea === area && event.key === key) {
+      cb();
+    }
+  };
+  window.addEventListener("storage", storageHandler);
+  emitter.on(key, cb);
+  return () => {
+    window.removeEventListener("storage", storageHandler);
+    emitter.off(key, cb);
+  };
+}
+
+function getSnapshot(area: Storage, key: string): string | null {
+  return area.getItem(key);
+}
+
+function setValue(area: Storage, key: string, value: string | null) {
+  if (typeof window !== "undefined") {
+    if (value === null) {
+      area.removeItem(key);
+    } else {
+      area.setItem(key, String(value));
+    }
+    emitter.emit(key, null);
+  }
+}
+
+type Initializer<T> = () => T;
+
+type UseStorageStateHookResult<T> = [
+  T,
+  React.Dispatch<React.SetStateAction<T>>
+];
+
+function useStorageStateServer(
+  kind: "session" | "local",
+  key: string,
+  initializer: string | Initializer<string>
+): UseStorageStateHookResult<string>;
+function useStorageStateServer(
+  kind: "session" | "local",
+  key: string,
+  initializer?: string | null | Initializer<string | null>
+): UseStorageStateHookResult<string | null>;
+function useStorageStateServer(
+  kind: "session" | "local",
+  key: string,
+  initializer: string | null | Initializer<string | null> = null
+):
+  | UseStorageStateHookResult<string | null>
+  | UseStorageStateHookResult<string> {
+  const [initialValue] = React.useState(initializer);
+  return [initialValue, () => {}];
+}
+
+/**
+ * Sync state to local/session 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 initialValue during SSR and hydration.
+ *
+ * Things this hook does different from existing solutions:
+ * - SSR-capable: it shows initial value during SSR and hydration, but immediately
+ *   initializes when clientside mounted.
+ * - Sync state across tabs: When another tab changes the value in the storage area, the
+ *   current tab follows suit.
+ */
+function useStorageStateBrowser(
+  kind: "session" | "local",
+  key: string,
+  initializer: string | Initializer<string>
+): UseStorageStateHookResult<string>;
+function useStorageStateBrowser(
+  kind: "session" | "local",
+  key: string,
+  initializer?: string | null | Initializer<string | null>
+): UseStorageStateHookResult<string | null>;
+function useStorageStateBrowser(
+  kind: "session" | "local",
+  key: string,
+  initializer: string | null | Initializer<string | null> = null
+):
+  | UseStorageStateHookResult<string | null>
+  | UseStorageStateHookResult<string> {
+  const [initialValue] = React.useState(initializer);
+  const area = kind === "session" ? window.sessionStorage : window.localStorage;
+  const subscribeKey = React.useCallback(
+    (cb: () => void) => subscribe(area, key, cb),
+    [area, key]
+  );
+  const getKeySnapshot = React.useCallback(
+    () => getSnapshot(area, key) ?? initialValue,
+    [area, initialValue, key]
+  );
+  const getKeyServerSnapshot = React.useCallback(
+    () => initialValue,
+    [initialValue]
+  );
+
+  const storedValue = React.useSyncExternalStore(
+    subscribeKey,
+    getKeySnapshot,
+    getKeyServerSnapshot
+  );
+
+  const setStoredValue = React.useCallback(
+    (value: React.SetStateAction<string | null>) => {
+      const valueToStore =
+        value instanceof Function ? value(storedValue) : value;
+      setValue(area, key, valueToStore);
+    },
+    [area, key, storedValue]
+  );
+
+  return [storedValue, setStoredValue];
+}
+
+export default typeof window === "undefined"
+  ? useStorageStateServer
+  : useStorageStateBrowser;

package/src/utils/warnOnce.ts

@@ -0,0 +1,12 @@
+const history = new Set<string>();
+
+/**
+ * Warns only once for a specific message.
+ * @param msg The message to warn.
+ */
+export default function warnOnce(msg: string) {
+  if (!history.has(msg)) {
+    history.add(msg);
+    console.warn(msg);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    /* Visit https://aka.ms/tsconfig.json to read more about this file */
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Node10",
+    "isolatedModules": true,
+    "outDir": "build",
+    "noEmit": false,
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+    "forceConsistentCasingInFileNames": true,
+    "lib": ["dom", "dom.iterable", "esnext"]
+  },
+  "include": ["src", "vitest.setup.ts"]
+}