@react-md/core 1.0.0-next.20 → 1.0.0-next.21

package/src/error-boundary/ErrorBoundary.tsx

@@ -0,0 +1,103 @@
+"use client";
+
+import {
+  Component,
+  type ErrorInfo,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+
+import { Provider } from "./context.js";
+import { type ErrorBoundaryContext, type ErrorBoundaryState } from "./types.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface ErrorBoundaryProps {
+  onError?: (error: Error, errorInfo: ErrorInfo) => void;
+  fallback: ReactNode;
+  children: ReactNode;
+}
+
+/**
+ * **Client Component**
+ *
+ * This is a minimal fork of the `react-error-boundary` package from
+ * {@link https://github.com/bvaughn/react-error-boundary/tree/5.0.0}
+ * that only includes things I consider useful. Use the `react-error-boundary`
+ * if more complex behavior is required.
+ *
+ * @example Main Use Case
+ * ```tsx
+ * import { Button } from "@react-md/core/button/Button";
+ * import { ErrorBoundary } from "@react-md/core/error-boundary/ErrorBoundary";
+ * import { useErrorBoundary } from "@react-md/core/error-boundary/useErrorBoundary";
+ * import { Typography } from "@react-md/core/typography/Typography";
+ *
+ * function Example() {
+ *   return (
+ *     <ErrorBoundary
+ *       fallback={<SomeFallbackComponent />}
+ *     >
+ *       <SomeComponentThatMightError />
+ *     </ErrorBoundary>
+ *   );
+ * }
+ *
+ * "use client";
+ *
+ * function SomeFallbackComponent() {
+ *   const { error, errored, reset } = useErrorBoundary();
+ *
+ *   return (
+ *     <>
+ *       <Typography>Uh oh, something broke!</Typography>
+ *       <Button onClick={reset}>Try Again?</Button>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @since 6.0.0
+ */
+export class ErrorBoundary extends Component<
+  ErrorBoundaryProps,
+  ErrorBoundaryState
+> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+
+    this.state = { error: null, errored: false };
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { error, errored: true };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
+    this.props.onError?.(error, errorInfo);
+  }
+
+  reset = (): void => {
+    this.setState({ error: null, errored: false });
+  };
+
+  render(): ReactElement {
+    const { fallback } = this.props;
+    const { error, errored } = this.state;
+
+    let { children } = this.props;
+    if (errored) {
+      children = fallback;
+    }
+
+    return (
+      <Provider
+        // should always match
+        value={{ error, errored, reset: this.reset } as ErrorBoundaryContext}
+      >
+        {children}
+      </Provider>
+    );
+  }
+}

package/src/error-boundary/context.ts

@@ -0,0 +1,16 @@
+import { createContext } from "react";
+
+import { type ErrorBoundaryContext } from "./types.js";
+
+/**
+ * @internal
+ * @since 6.0.0
+ */
+export const context = createContext<ErrorBoundaryContext | null>(null);
+context.displayName = "ErrorBoundary";
+
+/**
+ * @internal
+ * @since 6.0.0
+ */
+export const { Provider } = context;

package/src/error-boundary/types.ts

@@ -0,0 +1,19 @@
+/**
+ * @since 6.0.0
+ */
+export type ErrorBoundaryState =
+  | {
+      errored: false;
+      error: null;
+    }
+  | {
+      errored: true;
+      error: Error;
+    };
+
+/**
+ * @since 6.0.0
+ */
+export type ErrorBoundaryContext = ErrorBoundaryState & {
+  reset: () => void;
+};

package/src/error-boundary/useErrorBoundary.ts

@@ -0,0 +1,36 @@
+import { useContext } from "react";
+
+import { context } from "./context.js";
+import { type ErrorBoundaryContext } from "./types.js";
+
+/**
+ * @example Fallback Example
+ * ```tsx
+ * "use client";
+ *
+ * import { Button } from "@react-md/core/button/Button";
+ * import { useErrorBoundary } from "@react-md/core/error-boundary/useErrorBoundary";
+ * import { Typography } from "@react-md/core/typography/Typography";
+ *
+ * function SomeFallbackComponent() {
+ *   const { error, errored, reset } = useErrorBoundary();
+ *
+ *   return (
+ *     <>
+ *       <Typography>Uh oh, something broke!</Typography>
+ *       <Button onClick={reset}>Try Again?</Button>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @since 6.0.0
+ */
+export function useErrorBoundary(): ErrorBoundaryContext {
+  const value = useContext(context);
+  if (!value) {
+    throw new Error("ErrorBoundary has not been mounted");
+  }
+
+  return value;
+}

package/src/expansion-panel/ExpansionList.tsx

@@ -18,6 +18,7 @@ export interface ExpansionListProps extends HTMLAttributes<HTMLDivElement> {
  * This component is only used to implement the keyboard movement behavior for
  * the `ExpansionPanel` components.
  *
+ * @see {@link https://next.react-md.dev/components/expansion-panel | ExpansionPanel Demos}
  * @see {@link useExpansionList} for a custom implementation example if you do
  * not want to use a `<div>` for this wrapper component.
  * @since 6.0.0 Uses the new keyboard movement API and does not

package/src/expansion-panel/ExpansionPanel.tsx

@@ -168,6 +168,38 @@ export interface ExpansionPanelProps extends CardProps {
 /**
  * **Client Component**
  *
+ * An expansion panel enables content to be either collapsed (hidden) or
+ * expanded (visible) following the disclosure pattern.
+ *
+ * @example Simple Example
+ * ```tsx
+ * "use client";
+ *
+ * import { ExpansionList } from "@react-md/core/expansion-panel/ExpansionList";
+ * import { ExpansionPanel } from "@react-md/core/expansion-panel/ExpansionPanel";
+ * import { useExpansionPanels } from "@react-md/core/expansion-panel/useExpansionPanels";
+ * import { type ReactElement } from "react";
+ *
+ * export default function ExpansionPanelGroupExample(): ReactElement {
+ *   const { getPanelProps } = useExpansionPanels();
+ *
+ *   return (
+ *     <ExpansionList style={{ width: "100%" }}>
+ *       <ExpansionPanel {...getPanelProps(0)} headerChildren="Panel 1">
+ *         Panel 1 Contents
+ *       </ExpansionPanel>
+ *       <ExpansionPanel {...getPanelProps(1)} headerChildren="Panel 2">
+ *         Panel 2 Contents
+ *       </ExpansionPanel>
+ *       <ExpansionPanel {...getPanelProps(2)} headerChildren="Panel 3">
+ *         Panel 3 Contents
+ *       </ExpansionPanel>
+ *     </ExpansionList>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link https://next.react-md.dev/components/expansion-panel | ExpansionPanel Demos}
  * @see `useExpansionPanels` for examples.
  * @since 6.0.0 The content will be persistent and invisible using `display: none`
  * instead of unmounting and also animate the `margin-top` style.

package/src/expansion-panel/ExpansionPanelHeader.tsx

@@ -1,4 +1,3 @@
-import { cnb } from "cnbuilder";
 import {
   type ButtonHTMLAttributes,
   type MouseEventHandler,
@@ -12,6 +11,10 @@ import { getIcon } from "../icon/config.js";
 import { type PropsWithRef } from "../types.js";
 import { Typography, type TypographyProps } from "../typography/Typography.js";
 import { type TypographyType } from "../typography/typographyStyles.js";
+import {
+  expansionPanelButton,
+  expansionPanelHeading,
+} from "./expansionPanelStyles.js";
 
 /**
  * @since 6.0.0 Updated to include additional heading/Typography
@@ -88,13 +91,9 @@ export interface ExpansionPanelHeaderProps
  *
  * @example Custom Header
  * ```tsx
- * import type { ExpansionPanelProps } from "@react-md/core";
- * import {
- *   ExpansionPanel,
- *   ExpansionPanelHeader,
- * } from "@react-md/core";
- * import type { ReactElement } from "react";
- * const { useId } from "react";
+ * import { ExpansionPanel, type ExpansionPanelProps } from "@react-md/core/expansion-panel/ExpansionPanel";
+ * import { ExpansionPanelHeader } from "@react-md/core/expansion-panel/ExpansionPanelHeader";
+ * import { type ReactElement, useId } from "react";
  *
  * export type CustomExpansionPanelProps = ExpansionPanelProps & { id: string; };
  *
@@ -128,6 +127,7 @@ export interface ExpansionPanelHeaderProps
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/expansion-panel | ExpansionPanel Demos}
  * @since 6.0.0 Updated to be wrapped by the {@link Typography}
  * component and rendered as an `<h6>`.
  */
@@ -158,14 +158,14 @@ export const ExpansionPanelHeader = forwardRef<
       type={headingType}
       margin="none"
       {...headingProps}
-      className={cnb("rmd-expansion-panel__heading", headingProps?.className)}
+      className={expansionPanelHeading(headingProps)}
     >
       {beforeChildren}
       <ButtonUnstyled
         {...remaining}
         aria-expanded={expanded}
         id={id}
-        className={cnb("rmd-expansion-panel__button", className)}
+        className={expansionPanelButton({ className })}
       >
         {children}
         {icon && (

package/src/expansion-panel/expansionPanelStyles.ts

@@ -32,3 +32,36 @@ export function expansionPanel(
 
   return cnb(styles({ expanded, animate: !disableTransition }), className);
 }
+
+/**
+ * @since 6.0.0
+ */
+export interface ExpansionPanelHeadingClassNameOptions {
+  className?: string;
+}
+
+/**
+ * @since 6.0.0
+ */
+export function expansionPanelHeading(
+  options: ExpansionPanelHeadingClassNameOptions = {}
+): string {
+  const { className } = options;
+  return cnb(styles("heading"), className);
+}
+/**
+ * @since 6.0.0
+ */
+export interface ExpansionPanelButtonClassNameOptions {
+  className?: string;
+}
+
+/**
+ * @since 6.0.0
+ */
+export function expansionPanelButton(
+  options: ExpansionPanelButtonClassNameOptions = {}
+): string {
+  const { className } = options;
+  return cnb(styles("button"), className);
+}

package/src/expansion-panel/useExpansionList.ts

@@ -31,14 +31,12 @@ export type ExpansionListImplementation<E extends HTMLElement> =
 /**
  * @example Custom Implementation
  * ```tsx
- * import {
- *   ExpansionPanel,
- *   Form,
- *   KeyboardMovementProvider,
- *   useExpansionList,
- *   useExpansionPanels,
- * } from "@react-md/core";
- * import type { ReactElement } from "react";
+ * import { ExpansionPanel } from "@react-md/core/expansion-panel/ExpansionPanel";
+ * import { useExpansionList } from "@react-md/core/expansion-panel/useExpansionList";
+ * import { useExpansionPanels } from "@react-md/core/expansion-panel/useExpansionPanels";
+ * import { KeyboardMovementProvider } from "@react-md/core/movement/useKeyboardMovementProvider";
+ * import { Form } from "@react-md/core/form/Form";
+ * import { type ReactElement } from "react";
  *
  * import { BillingAddress } from "./BillingAddress";
  * import { BillingInformation } from "./BillingInformation";
@@ -66,6 +64,7 @@ export type ExpansionListImplementation<E extends HTMLElement> =
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/expansion-panel | ExpansionPanel Demos}
  * @since 6.0.0
  */
 export function useExpansionList<E extends HTMLElement>(

package/src/expansion-panel/useExpansionPanels.ts

@@ -125,11 +125,9 @@ export interface ExpansionPanelImplementation {
  *
  * @example Index Based Panels
  * ```tsx
- * import {
- *   ExpansionList,
- *   ExpansionPanel,
- *   useExpansionPanels,
- * } from "@react-md/core";
+ * import { ExpansionList } from "@react-md/core/expansion-panel/ExpansionList";
+ * import { ExpansionPanel } from "@react-md/core/expansion-panel/ExpansionPanel";
+ * import { useExpansionPanels } from "@react-md/core/expansion-panel/useExpansionPanels";
  * import { type ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -153,11 +151,9 @@ export interface ExpansionPanelImplementation {
  *
  * @example Custom Panel Ids and Expand All Panels by Default
  * ```tsx
- * import {
- *   ExpansionList,
- *   ExpansionPanel,
- *   useExpansionPanels,
- * } from "@react-md/core";
+ * import { ExpansionList } from "@react-md/core/expansion-panel/ExpansionList";
+ * import { ExpansionPanel } from "@react-md/core/expansion-panel/ExpansionPanel";
+ * import { useExpansionPanels } from "@react-md/core/expansion-panel/useExpansionPanels";
  * import { type ReactElement } from "react";
  *
  * import { BillingAddress } from "./BillingAddress";
@@ -191,6 +187,7 @@ export interface ExpansionPanelImplementation {
  * ```
  *
  *
+ * @see {@link https://next.react-md.dev/components/expansion-panel | ExpansionPanel Demos}
  * @since 6.0.0 The hook was renamed from `usePanels` to `useExpansionPanels`,
  * the API changed to return `getPanelProps` instead of a generated list of
  * panel props based on the provided `count`, and the hook no longer supports

package/src/files/FileInput.tsx

@@ -7,7 +7,7 @@ import {
   forwardRef,
 } from "react";
 
-import { type ButtonClassNameThemeOptions } from "../button/buttonStyles.js";
+import { type ButtonClassNameThemeOptions } from "../button/styles.js";
 import { getIcon } from "../icon/config.js";
 import { type ComponentWithRippleProps } from "../interaction/types.js";
 import { useElementInteraction } from "../interaction/useElementInteraction.js";
@@ -85,7 +85,8 @@ export interface FileInputProps
  *
  * @example Simple Example
  * ```tsx
- * import { FileInput, Form } from "@react-md/core";
+ * import { FileInput } from "@react-md/core/files/FileInput";
+ * import { Form } from "@react-md/core/form/Form";
  * import type { ReactElement } from "react";
  *
  * const extensions = [
@@ -124,6 +125,7 @@ export interface FileInputProps
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/file-input | FileInput Demos}
  * @since 6.0.0 Added additional support for `iconSize` and
  * `responsive`. Also removed the `disableIconSpacing` prop since it is no
  * longer required.

package/src/files/styles.ts

@@ -1,6 +1,6 @@
 import { cnb } from "cnbuilder";
 
-import { type ButtonClassNameOptions, button } from "../button/buttonStyles.js";
+import { type ButtonClassNameOptions, button } from "../button/styles.js";
 
 /** @since 6.0.0 */
 export type FileInputClassNameOptions = ButtonClassNameOptions;

package/src/files/useFileUpload.ts

@@ -205,6 +205,8 @@ const EMPTY_OBJECT = {} as const;
  * can also be used to upload the files as an `ArrayBuffer` and then uploaded to
  * a server.
  *
+ * @see {@link https://next.react-md.dev/components/file-input | FileInput Demos}
+ * @see {@link https://next.react-md.dev/hooks/use-file-input | useFileInput Demos}
  * @typeParam E - An optional HTMLElement type that is used for the
  * {@link FileUploadHandlers}.
  * @typeParam CustomError - An optional error type that gets returned from the

package/src/focus/useFocusContainer.ts

@@ -8,12 +8,8 @@ import {
   useRef,
 } from "react";
 
-import { TRANSITION_CONFIG } from "../transition/config.js";
-import {
-  type TransitionCallbacks,
-  type TransitionEnterHandler,
-  type TransitionExitHandler,
-} from "../transition/types.js";
+import { getTransitionCallbacks } from "../transition/getTransitionCallbacks.js";
+import { type TransitionCallbacks } from "../transition/types.js";
 import { useEnsuredRef } from "../useEnsuredRef.js";
 import {
   type FocusElementWithinType,
@@ -180,49 +176,39 @@ export function useFocusContainer<E extends HTMLElement>(
     prevFocus.current = document.activeElement;
   }, [activate]);
 
-  const handleMountFocus =
-    (callback: TransitionEnterHandler, skipped: boolean) =>
-    (appearing: boolean) => {
-      callback(appearing);
-      const instance = ref.current;
-      if (
-        instance &&
-        !skipped &&
-        !isFocusTypeDisabled("mount") &&
-        (!document.activeElement || !instance.contains(document.activeElement))
-      ) {
-        instance.focus();
-      }
-    };
-
-  const handleUnmountFocus =
-    (callback: TransitionExitHandler, skipped: boolean) => (): void => {
-      callback();
-      if (skipped || isFocusTypeDisabled("unmount")) {
-        return;
-      }
-
-      // For some reason, the `"Enter"` keydown event fires at a different timing
-      // than the Space  keydown event.
-      window.requestAnimationFrame(() => {
-        prevFocus.current?.focus();
-      });
-    };
-
   return {
     nodeRef: ref,
     transitionOptions: {
       nodeRef: refCallback,
-      onEntering: handleMountFocus(onEntering, false),
-      onEntered: handleMountFocus(
+      ...getTransitionCallbacks({
+        onEnterOnce: () => {
+          const instance = ref.current;
+          if (
+            instance &&
+            !isFocusTypeDisabled("mount") &&
+            (!document.activeElement ||
+              !instance.contains(document.activeElement))
+          ) {
+            instance.focus();
+          }
+        },
+        onEntering,
         onEntered,
-        !disableTransition && !TRANSITION_CONFIG.disabled
-      ),
-      onExiting: handleUnmountFocus(onExiting, false),
-      onExited: handleUnmountFocus(
+        onExitOnce: () => {
+          if (isFocusTypeDisabled("unmount")) {
+            return;
+          }
+
+          // For some reason, the `"Enter"` keydown event fires at a different timing
+          // than the Space  keydown event.
+          window.requestAnimationFrame(() => {
+            prevFocus.current?.focus();
+          });
+        },
+        onExiting,
         onExited,
-        !disableTransition && !TRANSITION_CONFIG.disabled
-      ),
+        disableTransition,
+      }),
     },
     eventHandlers: {
       onKeyDown(event) {

package/src/form/Checkbox.tsx

@@ -11,12 +11,14 @@ import { type CheckboxProps, InputToggle } from "./InputToggle.js";
  * @example Simple Example
  * ```tsx
  * import type { ReactElement } from "react";
- * import { Checkbox } from "@react-md/core";
+ * import { Checkbox } from "@react-md/core/form/Checkbox";
  *
  * function Example(): ReactElement {
  *   return <Checkbox label="Checkbox" value="a" />;
  * }
  * ```
+ *
+ * @see {@link https://next.react-md.dev/components/checkbox | Checkbox Demos}
  */
 export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(
   function Checkbox(props, ref) {

package/src/form/Fieldset.tsx

@@ -1,39 +1,6 @@
-import { cnb } from "cnbuilder";
 import { type FieldsetHTMLAttributes, forwardRef } from "react";
 
-import { bem } from "../utils/bem.js";
-
-const styles = bem("rmd-fieldset");
-
-/** @since 6.0.0 */
-export interface FieldsetClassNameOptions {
-  className?: string;
-
-  /**
-   * Set this to `true` to enable the default browser styles for a fieldset.
-   *
-   * @since 6.0.0 This was renamed from `unstyled`.
-   * @defaultValue `false`
-   */
-  browserStyles?: boolean;
-
-  /**
-   * @defaultValue `false`
-   */
-  fullWidth?: boolean;
-}
-
-/**
- * @since 6.0.0
- */
-export function fieldset(options: FieldsetClassNameOptions = {}): string {
-  const { className, fullWidth, browserStyles = false } = options;
-
-  return cnb(
-    styles({ unstyled: !browserStyles, "full-width": fullWidth }),
-    className
-  );
-}
+import { type FieldsetClassNameOptions, fieldset } from "./fieldsetStyles.js";
 
 /**
  * @since 6.0.0 Removed the `legend`, `legendStyle`,
@@ -47,7 +14,9 @@ export interface FieldsetProps
 /**
  * @example Simple Example
  * ```tsx
- * import { Form, Fieldset, Legend } from "@react-md/core";
+ * import { Form } from "@react-md/core/form/Form";
+ * import { Fieldset } from "@react-md/core/form/Fieldset";
+ * import { Legend } from "@react-md/core/form/Legend";
  *
  * function Example(): ReactElement {
  *   return (
@@ -60,6 +29,8 @@ export interface FieldsetProps
  *   );
  * }
  * ```
+ *
+ * @see {@link https://next.react-md.dev/components/fieldset | Fieldset Demos}
  */
 export const Fieldset = forwardRef<HTMLFieldSetElement, FieldsetProps>(
   function Fieldset(props, ref) {

package/src/form/Form.tsx

@@ -23,6 +23,8 @@ export interface FormProps extends FormHTMLAttributes<HTMLFormElement> {
  * This is probably one of the least useful components available as it doesn't
  * do much styling or logic. All this form component will do is add basic flex
  * behavior and prevent the default form submit behavior.
+ *
+ * @see {@link https://next.react-md.dev/components/form | Form Demos}
  */
 export const Form = forwardRef<HTMLFormElement, FormProps>(
   function Form(props, ref) {

package/src/form/FormMessage.tsx

@@ -17,6 +17,8 @@ import {
  *
  * This component can also be used to create form-level validation messages by
  * setting the `role` prop to `"alert"`.
+ *
+ * @see {@link https://next.react-md.dev/components/form-message | FormMessage Demos}
  */
 export const FormMessage = forwardRef<
   HTMLDivElement,

package/src/form/FormMessageContainer.tsx

@@ -22,6 +22,7 @@ export interface FormMessageContainerProps
  * Conditionally wraps the `children` in a `.rmd-form-message-container` wrapper
  * and renders the {@link FormMessage} component.
  *
+ * @see {@link https://next.react-md.dev/components/form-message | FormMessage Demos}
  * @since 2.5.0
  */
 export const FormMessageContainer = forwardRef<

package/src/form/FormMessageCounter.tsx

@@ -41,6 +41,8 @@ export interface FormMessageCounterProps
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/form-message | FormMessage Demos}
+ * @see {@link https://next.react-md.dev/components/text-field | TextField Demos}
  * @since 2.9.0
  */
 export function FormMessageCounter(

package/src/form/InputToggle.tsx

@@ -26,7 +26,7 @@ import {
 /**
  * @since 6.0.0
  */
-export interface InputToggleIconProps {
+export interface ConfigurableInputToggleIconProps {
   /**
    * @see {@link InputToggleSize}
    * @defaultValue `"normal"`
@@ -153,7 +153,7 @@ export interface BaseInputToggleProps
   extends Omit<InputHTMLAttributes<HTMLInputElement>, "size">,
     FormMessageContainerExtension,
     FormComponentStates,
-    InputToggleIconProps,
+    ConfigurableInputToggleIconProps,
     InputToggleLabelProps,
     ComponentWithRippleProps {
   /**
@@ -227,6 +227,8 @@ export type InputToggleProps = CheckboxInputToggleProps | RadioInputToggleProps;
 /**
  * **Client Component**
  *
+ * @see {@link https://next.react-md.dev/components/checkbox | Checkbox Demos}
+ * @see {@link https://next.react-md.dev/components/radio | Radio Demos}
  * @since 6.0.0 Now supports the `FormMessage` behavior and requires
  * different icons for each checked state.
  */