@alextheman/components 6.9.1 → 6.10.1

package/dist/index.d.cts

@@ -3,14 +3,14 @@ import { CollapseProps } from "@mui/material/Collapse";
 import { PaletteMode, SxProps, Theme } from "@mui/material/styles";
 import * as _$react from "react";
 import { CSSProperties, ComponentProps, ComponentPropsWithRef, ComponentPropsWithoutRef, ComponentType, Dispatch, ElementType, JSX, MouseEvent, MouseEventHandler, ReactNode, Ref, SetStateAction } from "react";
-import Button$1, { ButtonOwnProps, ButtonProps } from "@mui/material/Button";
 import { LinkProps } from "@mui/material/Link";
 import { CreateEnumType, OptionalOnCondition } from "@alextheman/utility";
-import { MenuItemOwnProps } from "@mui/material/MenuItem";
+import Button$1, { ButtonOwnProps, ButtonProps } from "@mui/material/Button";
 import { AlertColor } from "@mui/material/Alert";
 import { LiveProvider } from "react-live";
 import { CommonProps, OverridableComponent } from "@mui/material/OverridableComponent";
 import { SwitchProps } from "@mui/material/Switch";
+import { MenuItemOwnProps } from "@mui/material/MenuItem";
 import { SvgIconTypeMap } from "@mui/material/SvgIcon";
 import { ListItemButtonProps } from "@mui/material/ListItemButton";
 import { TypographyProps } from "@mui/material/Typography";
@@ -66,31 +66,6 @@ declare function CollapsableItem({
   useDefaultStyling
 }: CollapsableItemProps): _$react_jsx_runtime0.JSX.Element;
 //#endregion
-//#region src/components/DropdownMenu.d.ts
-interface DropdownMenuProps {
-  children: ReactNode | ((closeMenu: () => void) => ReactNode);
-  buttonChildren?: ReactNode;
-  button?: ElementType;
-  buttonProps?: Omit<ButtonOwnProps, "onClick" | "endIcon">;
-  isOpenIcon?: ReactNode;
-  isClosedIcon?: ReactNode;
-  onOpen?: () => void;
-  onClose?: () => void;
-}
-/**
- * @deprecated This component does not support the new context-based pattern and individual DropdownMenuItem components. Please use DropdownMenu2 instead.
- */
-declare function DropdownMenu({
-  children,
-  button: Button,
-  buttonChildren,
-  buttonProps: incomingButtonProps,
-  isOpenIcon,
-  isClosedIcon,
-  onOpen,
-  onClose
-}: DropdownMenuProps): _$react_jsx_runtime0.JSX.Element;
-//#endregion
 //#region src/components/ExternalLink.d.ts
 interface ExternalLinkProps extends Omit<LinkProps, "to" | "target" | "rel"> {
   /** The URL of the place you want to navigate to. */
@@ -198,79 +173,10 @@ declare function InternalLink({
 }: InternalLinkProps): _$react_jsx_runtime0.JSX.Element;
 //#endregion
 //#region src/types/ContextHookOptions.d.ts
-interface ContextHookOptions<S extends boolean = true> {
-  strict?: S;
-}
-//#endregion
-//#region src/providers/DropdownMenu2/DropdownMenu2.d.ts
-interface DropdownMenuContextValue {
-  closeMenu: () => void;
-  isDropdownOpen: boolean;
-}
-declare function useDropdownMenu<Strict extends boolean = true>({
-  strict
-}?: ContextHookOptions<Strict>): OptionalOnCondition<Strict, DropdownMenuContextValue>;
-interface DropdownMenu2Props {
-  children: ReactNode;
-  button?: ElementType;
-  buttonProps?: Omit<ButtonOwnProps, "endIcon"> & {
-    onClick?: (event: MouseEvent<HTMLElement>) => void;
-  };
-  openIcon?: ReactNode;
-  closedIcon?: ReactNode;
-}
-declare function DropdownMenu2({
-  children,
-  button: Button,
-  buttonProps,
-  openIcon,
-  closedIcon
-}: DropdownMenu2Props): _$react_jsx_runtime0.JSX.Element;
-//#endregion
-//#region src/providers/DropdownMenu2/DropdownMenuExternalLink.d.ts
-interface DropdownMenuExternalLinkProps extends MenuItemOwnProps {
-  ref?: Ref<HTMLAnchorElement>;
-  href: ComponentProps<typeof ExternalLink>["href"];
-  onClick?: MouseEventHandler<HTMLAnchorElement>;
-  children: ReactNode;
-}
-declare function DropdownMenuExternalLink({
-  ref,
-  href,
-  children,
-  onClick,
-  ...menuItemProps
-}: DropdownMenuExternalLinkProps): _$react_jsx_runtime0.JSX.Element;
-//#endregion
-//#region src/providers/DropdownMenu2/DropdownMenuInternalLink.d.ts
-interface DropdownMenuInternalLinkProps extends MenuItemOwnProps {
-  ref?: Ref<HTMLAnchorElement>;
-  to: ComponentProps<typeof InternalLink>["to"];
-  onClick?: MouseEventHandler<HTMLAnchorElement>;
-  children: ReactNode;
+interface ContextHookOptions<Strict extends boolean = true> {
+  /** Error if the context is missing if this is set to true. */
+  strict?: Strict;
 }
-declare function DropdownMenuInternalLink({
-  to,
-  ref,
-  children,
-  onClick,
-  ...menuItemProps
-}: DropdownMenuInternalLinkProps): _$react_jsx_runtime0.JSX.Element;
-//#endregion
-//#region src/providers/DropdownMenu2/DropdownMenuItem.d.ts
-type DropdownMenuItemProps<RootComponent extends ElementType = typeof Button$1> = {
-  component?: RootComponent;
-  children?: ReactNode;
-  ref?: ComponentPropsWithRef<RootComponent>["ref"];
-  onClick?: ComponentProps<RootComponent>["onClick"];
-} & Omit<ComponentPropsWithoutRef<RootComponent>, "children" | "ref"> & MenuItemOwnProps;
-declare function DropdownMenuItem<RootComponent extends ElementType>({
-  component,
-  children,
-  ref,
-  onClick,
-  ...menuItemProps
-}: DropdownMenuItemProps<RootComponent>): _$react_jsx_runtime0.JSX.Element;
 //#endregion
 //#region src/providers/LoaderProvider/LoaderProvider.d.ts
 interface LoaderProviderBaseProps<DataType> {
@@ -372,13 +278,17 @@ interface ModeContextValue {
   toggleMode: () => void;
   mode: PaletteMode;
 }
+/** Access the mode context directly. */
 declare function useMode<Strict extends boolean = true>({
   strict
 }?: ContextHookOptions<Strict>): OptionalOnCondition<Strict, ModeContextValue>;
 interface ModeProviderProps {
+  /** The children that will have access to the current mode. */
   children: ReactNode;
+  /** The initial mode. */
   mode?: PaletteMode;
 }
+/** Provides information about the current theme mode to its children components. */
 declare function ModeProvider({
   children,
   mode: modeProp
@@ -401,6 +311,7 @@ interface ScreenSizeContextValue {
   /** The current window height. */
   windowHeight: number;
 }
+/** Access the screen size context directly. */
 declare function useScreenSize<Strict extends boolean = true>({
   strict
 }?: ContextHookOptions<Strict>): OptionalOnCondition<Strict, ScreenSizeContextValue>;
@@ -413,15 +324,20 @@ declare function ScreenSizeProvider({
 //#endregion
 //#region src/providers/SnackbarProvider.d.ts
 interface SnackbarProviderProps {
+  /** The children that will have access to the snackbar context. */
   children: ReactNode;
+  /** The amount of seconds to wait before hiding the snackbar. */
   autoHideDuration?: number;
 }
 interface SnackbarContextValue {
+  /** A function that adds the snackbar to the page. */
   addSnackbar: (message: string, severity?: AlertColor, duration?: number) => void;
 }
+/** Access the snackbar context directly. */
 declare function useSnackbar<Strict extends boolean = true>({
   strict
 }?: ContextHookOptions<Strict>): OptionalOnCondition<Strict, SnackbarContextValue>;
+/** Controls the display of the snackbars on the page. */
 declare function SnackbarProvider({
   children,
   autoHideDuration
@@ -452,35 +368,53 @@ declare function ModeToggle(): _$react_jsx_runtime0.JSX.Element;
 //#endregion
 //#region src/components/NavigationBottom.d.ts
 interface NavItemBottom {
+  /** The value associated with the nav item. */
   value: string;
+  /** The label to display on the nav item. */
   label: string;
+  /** An icon to display alongside the nav item. */
   icon?: JSX.Element;
+  /** Where in your app the nav item should navigate to. */
   to: string;
 }
 interface NavigationBottomProps {
+  /** Children to display above the nav bar. */
   children: ReactNode;
+  /** An array of nav items to show. */
   navItems: Array<NavItemBottom>;
 }
+/** Renders a navigation bar at the bottom of the screen. Especially helpful for common navigation options in a mobile app. */
 declare function NavigationBottom({
   children,
   navItems
 }: NavigationBottomProps): _$react_jsx_runtime0.JSX.Element;
 //#endregion
 //#region src/components/NavigationDrawer.d.ts
+interface NavMenuItemOptions {
+  /** The label to display on the nav item option. */
+  label: string;
+  /** Where in your app the nav item option should navigate to. */
+  to: string;
+  /** An icon to display alongside the nav item option. */
+  icon?: ReactNode;
+}
 interface NavMenuItem {
+  /** The category to display all the nav item options under. */
   category: string;
-  options: Array<{
-    label: string;
-    to: string;
-    icon?: ReactNode;
-  }>;
+  /** An array of nav options to display under the chosen category. */
+  options: Array<NavMenuItemOptions>;
 }
 interface NavigationDrawerProps {
+  /** The title to display at the top of the wrapper. */
   title: string;
+  /** An array of nav items to show. */
   navItems: Array<NavMenuItem>;
+  /** Any extra elements to add to the header. */
   headerElements?: ReactNode;
+  /** Children to display within the wrapper. */
   children: ReactNode;
 }
+/** Renders a collapsable drawer to help with navigation. Best used as the main means of navigation on desktop apps. */
 declare function NavigationDrawer({
   title,
   navItems,
@@ -509,8 +443,10 @@ declare function Page({
 //#endregion
 //#region src/components/ReactPlayground.d.ts
 interface ReactPlaygroundProps extends ComponentProps<typeof LiveProvider> {
+  /** Extra styling to apply to the preview. Must be compatible with the Material UI `sx` prop. */
   previewStyles?: SxProps<Theme>;
 }
+/** Renders a playground to help demonstrate your React code in an interactive setting. */
 declare function ReactPlayground({
   code,
   previewStyles,
@@ -519,17 +455,26 @@ declare function ReactPlayground({
 //#endregion
 //#region src/components/SkeletonRow.d.ts
 interface SkeletonRowProps {
+  /** The number of columns the SkeletonRow should display. */
   columns: number;
 }
+/** Renders the skeleton of a table row. Often helpful to represent the loading state of the data in your table. */
 declare function SkeletonRow({
   columns
 }: SkeletonRowProps): _$react_jsx_runtime0.JSX.Element;
 //#endregion
 //#region src/components/SubmitButton.d.ts
 interface SubmitButtonProps extends Omit<ButtonProps, "type"> {
+  /** An option to disable the button on submit if the form is not dirty. */
   disableClean?: boolean;
+  /** The label for the button. */
   label: string;
 }
+/**
+ * A Submit Button for use with `react-hook-form`.
+ *
+ * Note that this is planned to eventually be deprecated and replaced with a newer version of `SubmitButton` that is instead compatible with `@tanstack/react-form`.
+ */
 declare function SubmitButton({
   disableClean,
   label,
@@ -538,15 +483,20 @@ declare function SubmitButton({
 //#endregion
 //#region src/components/SwitchWithIcons.d.ts
 interface SwitchWithIconsProps extends Omit<SwitchProps, "icon" | "checkedIcon"> {
+  /** The icon to show when the switch is in a checked state. */
   checkedIcon: ComponentType<{
     style?: CSSProperties;
   }>;
+  /** Additional styling to apply to the icon that shows when checked. */
   checkedIconStyles?: CommonProps["style"];
+  /** The icon to show when the switch is in an unchecked state. */
   uncheckedIcon: ComponentType<{
     style?: CSSProperties;
   }>;
+  /** Additional styling to apply to the icon that shows when unchecked. */
   uncheckedIconStyles?: CommonProps["style"];
 }
+/** Renders a switch with your provided icons. */
 declare function SwitchWithIcons({
   checkedIcon: CheckedIcon,
   checkedIconStyles,
@@ -555,10 +505,146 @@ declare function SwitchWithIcons({
   ...switchProps
 }: SwitchWithIconsProps): _$react_jsx_runtime0.JSX.Element;
 //#endregion
+//#region src/deprecated/DropdownMenu.d.ts
+interface DropdownMenuProps {
+  children: ReactNode | ((closeMenu: () => void) => ReactNode);
+  buttonChildren?: ReactNode;
+  button?: ElementType;
+  buttonProps?: Omit<ButtonOwnProps, "onClick" | "endIcon">;
+  isOpenIcon?: ReactNode;
+  isClosedIcon?: ReactNode;
+  onOpen?: () => void;
+  onClose?: () => void;
+}
+/**
+ * @deprecated This component does not support the new context-based pattern and individual DropdownMenuItem components. Please use DropdownMenu2 instead.
+ */
+declare function DropdownMenu({
+  children,
+  button: Button,
+  buttonChildren,
+  buttonProps: incomingButtonProps,
+  isOpenIcon,
+  isClosedIcon,
+  onOpen,
+  onClose
+}: DropdownMenuProps): _$react_jsx_runtime0.JSX.Element;
+//#endregion
 //#region src/deprecated/DarkModeToggle.d.ts
 /** @deprecated This component has been renamed to `ModeToggle`. */
 declare const DarkModeToggle: typeof ModeToggle;
 //#endregion
+//#region src/v7/components/DropdownMenu/DropdownMenu.d.ts
+interface DropdownMenuContextValue {
+  /** A function responsible for closing the dropdown menu. */
+  closeMenu: () => void;
+  /** Represents whether or not the dropdown is open. */
+  isDropdownOpen: boolean;
+}
+/**
+  Access the DropdownMenu context directly.
+ */
+declare function useDropdownMenu$1<Strict extends boolean = true>({
+  strict
+}?: ContextHookOptions<Strict>): OptionalOnCondition<Strict, DropdownMenuContextValue>;
+interface DropdownMenuProps$1 {
+  /** The children to render inside of the dropdown. */
+  children: ReactNode;
+  /** The button component to be used as the dropdown toggle (defaults to a Material UI Button) */
+  button?: ElementType;
+  /** Props to pass to the Button. */
+  buttonProps?: Omit<ButtonOwnProps, "endIcon"> & {
+    onClick?: (event: MouseEvent<HTMLElement>) => void;
+  };
+  /** The icon to display on the button when it is open. */
+  openIcon?: ReactNode;
+  /** The icon to display on the button when it is closed. */
+  closedIcon?: ReactNode;
+}
+/** Renders a dropdown menu consisting of `DropdownMenuItem` components imported from this package. */
+declare function DropdownMenu$1({
+  children,
+  button: Button,
+  buttonProps,
+  openIcon,
+  closedIcon
+}: DropdownMenuProps$1): _$react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/v7/components/DropdownMenu/DropdownMenuItem.d.ts
+type DropdownMenuItemProps$1<RootComponent extends ElementType = typeof Button$1> = {
+  /**
+   * An optional component to provide to override the current component.
+   *
+   * Note that the provided component must:
+   * - accept a `to` prop.
+   * - correctly handle the forwarded `ref`.
+   * - render a valid anchor element (or equivalent) for proper accessibility.
+   */
+  component?: RootComponent; /** The children to be rendered within the menu item. */
+  children?: ReactNode; /** The ref to forward to allow it to be used with polymorphic components */
+  ref?: ComponentPropsWithRef<RootComponent>["ref"]; /** A function to execute after clicking the item. */
+  onClick?: ComponentProps<RootComponent>["onClick"];
+} & Omit<ComponentPropsWithoutRef<RootComponent>, "children" | "ref"> & MenuItemOwnProps;
+/** Represents a menu item to be used inside the `DropdownMenu`. It must be used as children of the `DropdownMenu` component. */
+declare function DropdownMenuItem$1<RootComponent extends ElementType>({
+  component,
+  children,
+  ref,
+  onClick,
+  ...menuItemProps
+}: DropdownMenuItemProps$1<RootComponent>): _$react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/deprecated/DropdownMenu2/DropdownMenu2.d.ts
+declare const useDropdownMenu: typeof useDropdownMenu$1;
+/**
+ * @deprecated Please use `DropdownMenuProps` from `@alextheman/components/v7` instead.
+ *
+ * This will be replaced in the root entrypoint in a future release.
+ */
+type DropdownMenu2Props = DropdownMenuProps$1;
+/**
+ * @deprecated Please use `DropdownMenu` from `@alextheman/components/v7` instead.
+ *
+ * This will be replaced in the root entrypoint in a future release.
+ */
+declare const DropdownMenu2: typeof DropdownMenu$1;
+//#endregion
+//#region src/deprecated/DropdownMenu2/DropdownMenuItem.d.ts
+type DropdownMenuItemProps<RootComponent extends ElementType> = DropdownMenuItemProps$1<RootComponent>;
+declare const DropdownMenuItem: typeof DropdownMenuItem$1;
+//#endregion
+//#region src/deprecated/DropdownMenuExternalLink.d.ts
+interface DropdownMenuExternalLinkProps extends MenuItemOwnProps {
+  ref?: Ref<HTMLAnchorElement>;
+  href: ComponentProps<typeof ExternalLink>["href"];
+  onClick?: MouseEventHandler<HTMLAnchorElement>;
+  children: ReactNode;
+}
+/** @deprecated Please use `<DropdownMenuItem component={ExternalLink} />` instead. */
+declare function DropdownMenuExternalLink({
+  ref,
+  href,
+  children,
+  onClick,
+  ...menuItemProps
+}: DropdownMenuExternalLinkProps): _$react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/deprecated/DropdownMenuInternalLink.d.ts
+interface DropdownMenuInternalLinkProps extends MenuItemOwnProps {
+  ref?: Ref<HTMLAnchorElement>;
+  to: ComponentProps<typeof InternalLink>["to"];
+  onClick?: MouseEventHandler<HTMLAnchorElement>;
+  children: ReactNode;
+}
+/** @deprecated Please use `<DropdownMenuItem component={InternalLink} />` instead. */
+declare function DropdownMenuInternalLink({
+  to,
+  ref,
+  children,
+  onClick,
+  ...menuItemProps
+}: DropdownMenuInternalLinkProps): _$react_jsx_runtime0.JSX.Element;
+//#endregion
 //#region src/deprecated/IconWithPopover.d.ts
 interface IconWithPopoverProps {
   icon?: (OverridableComponent<SvgIconTypeMap<unknown, "svg">> & {
@@ -612,7 +698,16 @@ declare function PopoverText({
 }: PopoverTextProps): _$react_jsx_runtime0.JSX.Element;
 //#endregion
 //#region src/hooks/useHash.d.ts
-declare function useHash<S extends string>(initialHash: S | undefined): [S, Dispatch<SetStateAction<S>>];
+/**
+ * Stores changes to the window hash as React state.
+ *
+ * @template StateType - The type of the hash state.
+ *
+ * @param initialHash - The initial value of the hash.
+ *
+ * @returns A tuple containing the hash state, and a updater function to set the hash state.
+ */
+declare function useHash<StateType extends string>(initialHash: StateType | undefined): [StateType, Dispatch<SetStateAction<StateType>>];
 //#endregion
-export { Artwork, CollapsableItem, type CollapsableItemProps, ContextHookOptions, DarkModeToggle, DropdownMenu, DropdownMenu2, type DropdownMenu2Props, DropdownMenuExternalLink, type DropdownMenuExternalLinkProps, DropdownMenuInternalLink, type DropdownMenuInternalLinkProps, DropdownMenuItem, type DropdownMenuItemProps, type DropdownMenuProps, ExternalLink, type ExternalLinkProps, FileInput, FileInputList, type FileInputListProps, type FileInputProps, FileType, IconWithPopover, type IconWithPopoverProps, InternalLink, type InternalLinkProps, ListItemInternalLink, Loader, LoaderData, type LoaderDataProps, LoaderError, type LoaderErrorBaseProps, type LoaderErrorProps, type LoaderErrorPropsWithNullable, type LoaderErrorPropsWithUndefinedOrNull, type LoaderProps, LoaderProvider, type LoaderProviderBaseProps, type LoaderProviderProps, type LoaderProviderPropsWithError, type LoaderProviderPropsWithNoError, ModeProvider, type ModeProviderProps, ModeToggle, type NavItemBottom, type NavMenuItem, NavigationBottom, type NavigationBottomProps, NavigationDrawer, type NavigationDrawerProps, Page, PopoverText, type PopoverTextProps, ReactPlayground, type ReactPlaygroundProps, type ScreenSizeContextValue, type ScreenSizeProps, ScreenSizeProvider, SkeletonRow, type SkeletonRowProps, SnackbarProvider, type SnackbarProviderProps, SubmitButton, type SubmitButtonProps, SwitchWithIcons, type SwitchWithIconsProps, useDropdownMenu, useHash, useMode, useScreenSize, useSnackbar };
+export { Artwork, CollapsableItem, type CollapsableItemProps, ContextHookOptions, DarkModeToggle, DropdownMenu, DropdownMenu2, type DropdownMenu2Props, DropdownMenuExternalLink, DropdownMenuInternalLink, DropdownMenuItem, type DropdownMenuItemProps, type DropdownMenuProps, ExternalLink, type ExternalLinkProps, FileInput, FileInputList, type FileInputListProps, type FileInputProps, FileType, IconWithPopover, type IconWithPopoverProps, InternalLink, type InternalLinkProps, ListItemInternalLink, Loader, LoaderData, type LoaderDataProps, LoaderError, type LoaderErrorBaseProps, type LoaderErrorProps, type LoaderErrorPropsWithNullable, type LoaderErrorPropsWithUndefinedOrNull, type LoaderProps, LoaderProvider, type LoaderProviderBaseProps, type LoaderProviderProps, type LoaderProviderPropsWithError, type LoaderProviderPropsWithNoError, ModeProvider, type ModeProviderProps, ModeToggle, type NavItemBottom, type NavMenuItem, NavigationBottom, type NavigationBottomProps, NavigationDrawer, type NavigationDrawerProps, Page, PopoverText, type PopoverTextProps, ReactPlayground, type ReactPlaygroundProps, type ScreenSizeContextValue, type ScreenSizeProps, ScreenSizeProvider, SkeletonRow, type SkeletonRowProps, SnackbarProvider, type SnackbarProviderProps, SubmitButton, type SubmitButtonProps, SwitchWithIcons, type SwitchWithIconsProps, useDropdownMenu, useHash, useMode, useScreenSize, useSnackbar };
 //# sourceMappingURL=index.d.cts.map