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

package/src/menu/MenuItemGroup.tsx

@@ -28,13 +28,11 @@ export type MenuItemGroupProps = LabelRequiredForA11y<
  * @example Simple Example
  * ```tsx
  * import { ReactElement, useState } from "react";
- * import {
- *   DropdownMenu,
- *   MenuItemGroup,
- *   MenuItemRadio,
- *   MenuItemSeparator,
- *   MenuItemSwitch,
- * } from "@react-md/core";
+ * import { DropdownMenu } from "@react-md/core/menu/DropdownMenu";
+ * import { MenuItemGroup } from "@react-md/core/menu/MenuItemGroup";
+ * import { MenuItemRadio } from "@react-md/core/menu/MenuItemRadio";
+ * import { MenuItemSeparator } from "@react-md/core/menu/MenuItemSeparator";
+ * import { MenuItemSwitch } from "@react-md/core/menu/MenuItemSwitch";
  *
  * function Example(): ReactElement {
  *   const [value, setValue] = useState("value1");
@@ -78,6 +76,7 @@ export type MenuItemGroupProps = LabelRequiredForA11y<
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/menu | Menu Demos}
  * @since 5.0.0
  */
 export const MenuItemGroup = forwardRef<ListElement, MenuItemGroupProps>(

package/src/menu/MenuItemSeparator.tsx

@@ -18,6 +18,7 @@ export interface MenuItemSeparatorProps
  * will also automatically render itself vertically instead of horizontally if
  * the menu is rendering horizontally.
  *
+ * @see {@link https://next.react-md.dev/components/menu | Menu Demos}
  * @since 5.0.0 Renders as an `<li>` instead of a `<div>` or `<hr />`.
  */
 export const MenuItemSeparator = forwardRef<

package/src/menu/MenuWidget.tsx

@@ -1,44 +1,24 @@
 "use client";
 
-import { cnb } from "cnbuilder";
 import { type HTMLAttributes, forwardRef, useRef, useState } from "react";
 
 import { List } from "../list/List.js";
 import { type GetDefaultFocusedIndex } from "../movement/types.js";
 import { useKeyboardMovementProvider } from "../movement/useKeyboardMovementProvider.js";
 import { type NonNullMutableRef } from "../types.js";
-import { bem } from "../utils/bem.js";
 import { type MenuListConvenienceProps } from "./Menu.js";
 import { MenuWidgetKeyboardProvider } from "./MenuWidgetKeyboardProvider.js";
+import { menu } from "./styles.js";
 import {
   MenuBarProvider,
   useMenuBarContext,
   useMenuBarProvider,
 } from "./useMenuBarProvider.js";
 
-const styles = bem("rmd-menu");
 const noop = (): void => {
   // do nothing
 };
 
-/**
- * @since 6.0.0
- */
-export interface MenuClassNameOptions {
-  className?: string;
-  horizontal?: boolean;
-  elevated?: boolean;
-}
-
-/**
- * @since 6.0.0
- */
-export function menu(options: MenuClassNameOptions = {}): string {
-  const { className, horizontal, elevated } = options;
-
-  return cnb(styles({ horizontal, elevated }), className);
-}
-
 /**
  * @internal
  */

package/src/menu/styles.ts

@@ -0,0 +1,23 @@
+import { cnb } from "cnbuilder";
+
+import { bem } from "../utils/bem.js";
+
+const styles = bem("rmd-menu");
+
+/**
+ * @since 6.0.0
+ */
+export interface MenuClassNameOptions {
+  className?: string;
+  horizontal?: boolean;
+  elevated?: boolean;
+}
+
+/**
+ * @since 6.0.0
+ */
+export function menu(options: MenuClassNameOptions = {}): string {
+  const { className, horizontal, elevated } = options;
+
+  return cnb(styles({ horizontal, elevated }), className);
+}

package/src/menu/useContextMenu.ts

@@ -64,7 +64,9 @@ const noop = (): void => {
  * @example Simple Example
  * ```tsx
  * import type { ReactElement } from "react";
- * import [ Menu, MenuItem, useContextMenu ] from "@react-md/core":
+ * import { Menu } from "@react-md/core/menu/Menu":
+ * import { MenuItem } from "@react-md/core/menu/MenuItem":
+ * import { useContextMenu } from "@react-md/core/menu/useContextMenu":
  *
  * function Example(): ReactElement {
  *   const { menuProps, onContextMenu } = useContextMenu();
@@ -83,6 +85,7 @@ const noop = (): void => {
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/menu#context-menu | Menu Demos}
  * @since 5.0.0
  * @since 6.0.0 No longer supports overriding most of the `Menu` props. The
  * props must be passed to the `Menu` component manually.

package/src/movement/useKeyboardMovementProvider.ts

@@ -77,7 +77,7 @@ const returnNegative1 = (): number => -1;
  * import {
  *   KeyboardMovementProvider,
  *   useKeyboardMovementProvider,
- * } from "@react-md/core";
+ * } from "@react-md/core/movement/useKeyboardMovementProvider";
  * import type { ReactElement, ReactNode } from "react";
  *
  * function Example({ children }: { children: ReactNode }): ReactElement {
@@ -101,7 +101,7 @@ const returnNegative1 = (): number => -1;
  *   KeyboardMovementProvider,
  *   useKeyboardMovementContext,
  *   useKeyboardMovementProvider,
- * } from "@react-md/core";
+ * } from "@react-md/core/movement/useKeyboardMovementProvider";
  * import type { ReactElement, ReactNode } from "react";
  * import { useId } from "react";
  *
@@ -147,7 +147,7 @@ const returnNegative1 = (): number => -1;
  *   KeyboardMovementProvider,
  *   useKeyboardMovementContext,
  *   useKeyboardMovementProvider,
- * } from "@react-md/core";
+ * } from "@react-md/core/movement/useKeyboardMovementProvider";
  * import type { ReactElement, ReactNode } from "react";
  * import { useId } from "react";
  *

package/src/navigation/CollapsibleNavGroup.tsx

@@ -50,6 +50,7 @@ export interface CollapsibleNavGroupProps
 /**
  * **Client Component**
  *
+ * @see {@link https://next.react-md.dev/components/navigation | Navigation Demos}
  * @since 6.0.0
  */
 export const CollapsibleNavGroup = forwardRef<

package/src/navigation/DefaultNavigationRenderer.tsx

@@ -27,6 +27,7 @@ export type DefaultNavigationRendererProps<
  * - `!!items` - `<CollapsibleNavGroup />`
  * - `<NavItemLink {...item} as={linkComponent} active={pathname === href} />`
  *
+ * @see {@link https://next.react-md.dev/components/navigation | Navigation Demos}
  * @since 6.0.0
  */
 export function DefaultNavigationRenderer<

package/src/navigation/NavGroup.tsx

@@ -15,6 +15,7 @@ export interface NavGroupProps extends ListProps {
  * A simple wrapper around the {@link Link} component that ads the
  * `--rmd-tree-depth: depth` custom property to allow for incremented padding.
  *
+ * @see {@link https://next.react-md.dev/components/navigation | Navigation Demos}
  * @since 6.0.0
  */
 export const NavGroup = forwardRef<HTMLUListElement, NavGroupProps>(

package/src/navigation/NavItem.tsx

@@ -14,6 +14,7 @@ export interface NavItemProps extends LiHTMLAttributes<HTMLLIElement> {
  * and should not be used on its own. See the `CollapsibleNavGroup` and
  * `NavItemLink` instead.
  *
+ * @see {@link https://next.react-md.dev/components/navigation | Navigation Demos}
  * @since 6.0.0
  */
 export const NavItem = forwardRef<HTMLLIElement, NavItemProps>(

package/src/navigation/NavItemButton.tsx

@@ -35,6 +35,7 @@ export interface NavItemButtonProps
 /**
  * **Client Component**
  *
+ * @see {@link https://next.react-md.dev/components/navigation | Navigation Demos}
  * @since 6.0.0
  */
 export const NavItemButton = forwardRef<HTMLButtonElement, NavItemButtonProps>(

package/src/navigation/NavItemLink.tsx

@@ -64,6 +64,7 @@ export interface NavItemLinkProps
 /**
  * **Client Component**
  *
+ * @see {@link https://next.react-md.dev/components/navigation | Navigation Demos}
  * @since 6.0.0
  */
 export const NavItemLink = forwardRef<HTMLAnchorElement, NavItemLinkProps>(

package/src/navigation/NavSubheader.tsx

@@ -15,6 +15,7 @@ export type NavSubheaderProps = ListSubheaderProps;
  * A simple wrapper around the {@link ListSubheader} that updates the padding
  * based on the current navigation item depth to match the other items.
  *
+ * @see {@link https://next.react-md.dev/components/navigation | Navigation Demos}
  * @since 6.0.0
  */
 export const NavSubheader = forwardRef<HTMLLIElement, NavSubheaderProps>(

package/src/navigation/Navigation.tsx

@@ -65,6 +65,50 @@ export interface NavigationProps<
 /**
  * **Client Component**
  *
+ * The `Navigation` component can be used to create a list of links to
+ * different pages within the app and generally used within a `Sheet` or
+ * `LayoutNav`.
+ *
+ * @example Simple Example
+ * ```tsx
+ * "use client";
+ *
+ * import { Navigation } from "@react-md/core/navigation/Navigation";
+ * import { type NavigationItem } from "@react-md/core/navigation/types";
+ * import { useNavigationExpansion } from "@react-md/core/navigation/useNavigationExpansion";
+ * import { usePathname } from "next/navigation.js";
+ * import { type ReactElement } from "react";
+ *
+ * import { LinkUnstyled } from "@/components/LinkUnstyled.jsx";
+ *
+ * const items: readonly NavigationItem[] = [
+ *   {
+ *     type: "route",
+ *     href: "/",
+ *     children: "Home",
+ *   },
+ *   {
+ *     type: "route",
+ *     href: "/page-1",
+ *     children: "Page 1",
+ *   },
+ * ];
+ *
+ * export function MainNavigation(): ReactElement {
+ *   const pathname = usePathname();
+ *   const { data } = useNavigationExpansion({
+ *     pathname,
+ *     linkComponent: LinkUnstyled,
+ *   });
+ *   return (
+ *     <nav aria-label="Navigation">
+ *       <Navigation data={data} items={items} />
+ *     </nav>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link https://next.react-md.dev/components/navigation | Navigation Demos}
  * @since 6.0.0
  */
 export function Navigation<

package/src/navigation/getTableOfContentsHeadings.ts

@@ -0,0 +1,70 @@
+import {
+  type TableOfContentsHeadingItem,
+  type TableOfContentsHeadings,
+  type TableOfContentsHeadingsOptions,
+} from "./types.js";
+
+/**
+ * @internal
+ * @since 6.0.0
+ */
+export interface GetTableOfContentsHeadingsOptions
+  extends Required<TableOfContentsHeadingsOptions> {
+  ssr: boolean;
+}
+
+/**
+ * This is used by the `useTableOfContentsHeadings` hook to find
+ * the active heading element which is why it is marked as
+ * internal.
+ *
+ * This will always return an empty list if `ssr` is `true` or
+ * `typeof window === "undefined"`.
+ *
+ * @internal
+ * @since 6.0.0
+ */
+export function getTableOfContentsHeadings(
+  options: GetTableOfContentsHeadingsOptions
+): TableOfContentsHeadings {
+  const { ssr, selector, getDepth, getHeadingText } = options;
+
+  if (ssr || typeof window === "undefined") {
+    return [];
+  }
+
+  const root = {
+    id: "",
+    depth: 0,
+    items: [],
+    children: "",
+  } satisfies TableOfContentsHeadingItem;
+  let previous: TableOfContentsHeadingItem = root;
+  const parents: TableOfContentsHeadingItem[] = [];
+  const headings = document.querySelectorAll(selector);
+  headings.forEach((heading) => {
+    const depth = getDepth(heading);
+    const item: TableOfContentsHeadingItem = {
+      id: heading.id,
+      depth,
+      items: [],
+      children: getHeadingText(heading),
+    };
+    if (depth > previous.depth) {
+      if (!previous.items) {
+        previous.items = [];
+      }
+
+      parents.push(previous);
+    } else if (depth < previous.depth) {
+      while (parents[parents.length - 1].depth >= depth) {
+        parents.pop();
+      }
+    }
+    const i = parents.length - 1;
+    parents[i].items = [...(parents[i].items ?? []), item];
+    previous = item;
+  });
+
+  return root.items;
+}

package/src/navigation/navItemStyles.ts

@@ -1,6 +1,6 @@
 import { cnb } from "cnbuilder";
 
-import { button } from "../button/buttonStyles.js";
+import { button } from "../button/styles.js";
 import { cssUtils } from "../cssUtils.js";
 import { bem } from "../utils/bem.js";
 

package/src/navigation/types.ts

@@ -215,3 +215,60 @@ export interface NavItemContentProps {
     keyof TooltippedElementEventHandlers<HTMLAnchorElement>
   >;
 }
+
+/**
+ * @since 6.0.0
+ */
+export interface HeadingReference {
+  id: string;
+}
+
+/**
+ * @since 6.0.0
+ */
+export interface HeadingReferenceWithChildren extends HeadingReference {
+  items?: readonly HeadingReferenceWithChildren[];
+}
+
+/** @since 6.0.0 */
+export interface TableOfContentsHeadingsOptions {
+  /**
+   * This should be a `document.querySelectorAll` query that returns elements
+   * to display in a table of contents component that have a valid id.
+   *
+   * @see {@link DEFAULT_HEADING_SELECTOR}
+   * @defaultValue `main :where(:not(nav *)):where(h1[id],h2[id],h3[id],h4[id],h5[id],h6[id])`
+   */
+  selector?: string;
+
+  /**
+   * @see {@link DEFAULT_GET_HEADING_DEPTH}
+   * @defaultValue `(element) => parseInt(element.tagName.substring(1))`
+   */
+  getDepth?: (element: Element) => number;
+
+  /**
+   * This is used to get the text to display in a table of contents from each
+   * heading element.
+   *
+   * @see {@link DEFAULT_GET_HEADING_TEXT}
+   * @defaultValue `(element) => element.textContent || ""`
+   */
+  getHeadingText?: (element: Element) => string;
+}
+
+/** @since 6.0.0 */
+export interface TableOfContentsHeading extends HeadingReference {
+  depth: number;
+  children: string;
+}
+
+/** @since 6.0.0 */
+export interface TableOfContentsHeadingItem
+  extends TableOfContentsHeading,
+    HeadingReferenceWithChildren {
+  items?: TableOfContentsHeadingItem[];
+}
+
+/** @since 6.0.0 */
+export type TableOfContentsHeadings = readonly TableOfContentsHeadingItem[];

package/src/navigation/useActiveHeadingId.ts

@@ -9,20 +9,7 @@ import {
   useIntersectionObserver,
 } from "../useIntersectionObserver.js";
 import { parseCssLengthUnit } from "../utils/parseCssLengthUnit.js";
-
-/**
- * @since 6.0.0
- */
-export interface HeadingReference {
-  id: string;
-}
-
-/**
- * @since 6.0.0
- */
-export interface HeadingReferenceWithChildren extends HeadingReference {
-  items?: readonly HeadingReferenceWithChildren[];
-}
+import { type HeadingReferenceWithChildren } from "./types.js";
 
 /**
  * @defaultValue `[0.0, 1.0]`
@@ -62,7 +49,7 @@ export const DEFAULT_ACTIVE_HEADING_GET_ROOT_MARGIN = (): string => {
  */
 function getHeadingElements(
   items: readonly HeadingReferenceWithChildren[]
-): HTMLElement[] {
+): readonly HTMLElement[] {
   const headings: HTMLElement[] = [];
   items.forEach((item) => {
     const heading = document.getElementById(item.id);
@@ -127,6 +114,7 @@ export interface ActiveHeadingIdOptions {
  * This is heavily inspired by:
  * @see https://github.com/mdn/yari/blob/231d6aab8f1c8efe159d268c261446c5b7ae12d9/client/src/document/hooks.ts#L171
  *
+ * @see {@link https://next.react-md.dev/hooks/use-active-heading-id | useActiveHeadingId Demos}
  * @since 6.0.0
  */
 export function useActiveHeadingId(options: ActiveHeadingIdOptions): string {

package/src/navigation/useNavigationExpansion.ts

@@ -116,6 +116,8 @@ export interface NavigationExpansionImplementation extends NavigationExpansion {
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/getting-started/layout | Layout Demos}
+ * @see {@link https://next.react-md.dev/components/navigation | Navigation Demos}
  * @since 6.0.0
  */
 export function useNavigationExpansion(

package/src/navigation/useTableOfContentsHeadings.ts

@@ -1,12 +1,13 @@
 "use client";
 
-import { useMemo } from "react";
+import { useEffect, useState } from "react";
 
-import { useSsr } from "../SsrProvider.jsx";
+import { useSsr } from "../SsrProvider.js";
+import { getTableOfContentsHeadings } from "./getTableOfContentsHeadings.js";
 import {
-  type HeadingReference,
-  type HeadingReferenceWithChildren,
-} from "./useActiveHeadingId.js";
+  type TableOfContentsHeadings,
+  type TableOfContentsHeadingsOptions,
+} from "./types.js";
 
 /**
  * This will find all headings that have an `id` that are not part of a `<nav>`
@@ -34,49 +35,6 @@ export const DEFAULT_GET_HEADING_DEPTH = (element: Element): number => {
 export const DEFAULT_GET_HEADING_TEXT = (element: Element): string =>
   element.textContent || "";
 
-/** @since 6.0.0 */
-export interface TableOfContentsHeadingsOptions {
-  /**
-   * This should be a `document.querySelectorAll` query that returns elements
-   * to display in a table of contents component that have a valid id.
-   *
-   * @see {@link DEFAULT_HEADING_SELECTOR}
-   * @defaultValue `main :where(:not(nav *)):where(h1[id],h2[id],h3[id],h4[id],h5[id],h6[id])`
-   */
-  selector?: string;
-
-  /**
-   * @see {@link DEFAULT_GET_HEADING_DEPTH}
-   * @defaultValue `(element) => parseInt(element.tagName.substring(1))`
-   */
-  getDepth?: (element: Element) => number;
-
-  /**
-   * This is used to get the text to display in a table of contents from each
-   * heading element.
-   *
-   * @see {@link DEFAULT_GET_HEADING_TEXT}
-   * @defaultValue `(element) => element.textContent || ""`
-   */
-  getHeadingText?: (element: Element) => string;
-}
-
-/** @since 6.0.0 */
-export interface TableOfContentsHeading extends HeadingReference {
-  depth: number;
-  children: string;
-}
-
-/** @since 6.0.0 */
-export interface TableOfContentsHeadingItem
-  extends TableOfContentsHeading,
-    HeadingReferenceWithChildren {
-  items?: TableOfContentsHeadingItem[];
-}
-
-/** @since 6.0.0 */
-export type TableOfContentsHeadings = TableOfContentsHeadingItem[];
-
 /**
  * The `useTableOfContentsHeadings` should normally be used with the
  * `useActiveHeadingId` hook to generate a table of contents for the current
@@ -95,56 +53,31 @@ export type TableOfContentsHeadings = TableOfContentsHeadingItem[];
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/hooks/use-table-of-contents-headings | useTableOfContentsHeadings Demos}
  * @since 6.0.0
  */
 export function useTableOfContentsHeadings(
   options: TableOfContentsHeadingsOptions = {}
-): readonly HeadingReferenceWithChildren[] {
+): TableOfContentsHeadings {
   const {
     selector = DEFAULT_HEADING_SELECTOR,
     getDepth = DEFAULT_GET_HEADING_DEPTH,
     getHeadingText = DEFAULT_GET_HEADING_TEXT,
   } = options;
   const ssr = useSsr();
-
-  return useMemo(() => {
-    if (ssr || typeof window === "undefined") {
-      return [];
-    }
-
-    const root = {
-      id: "",
-      depth: 0,
-      items: [],
-      children: "",
-    } satisfies TableOfContentsHeadingItem;
-    let previous: TableOfContentsHeadingItem = root;
-    const parents: TableOfContentsHeadingItem[] = [];
-    const headings = document.querySelectorAll(selector);
-    headings.forEach((heading) => {
-      const depth = getDepth(heading);
-      const item: TableOfContentsHeadingItem = {
-        id: heading.id,
-        depth,
-        items: [],
-        children: getHeadingText(heading),
-      };
-      if (depth > previous.depth) {
-        if (!previous.items) {
-          previous.items = [];
-        }
-
-        parents.push(previous);
-      } else if (depth < previous.depth) {
-        while (parents[parents.length - 1].depth >= depth) {
-          parents.pop();
-        }
-      }
-      const i = parents.length - 1;
-      parents[i].items = [...(parents[i].items ?? []), item];
-      previous = item;
-    });
-
-    return root.items;
+  const [headings, setHeadings] = useState(() =>
+    getTableOfContentsHeadings({
+      ssr,
+      selector,
+      getDepth,
+      getHeadingText,
+    })
+  );
+  useEffect(() => {
+    setHeadings(
+      getTableOfContentsHeadings({ ssr, selector, getDepth, getHeadingText })
+    );
   }, [getDepth, getHeadingText, selector, ssr]);
+
+  return headings;
 }

package/src/overlay/Overlay.tsx

@@ -14,7 +14,14 @@ import {
   DEFAULT_OVERLAY_CLASSNAMES,
   DEFAULT_OVERLAY_TIMEOUT,
   overlay,
-} from "./overlayStyles.js";
+} from "./styles.js";
+
+declare module "react" {
+  interface CSSProperties {
+    "--rmd-overlay-background-color"?: string;
+    "--rmd-overlay-z-index"?: number;
+  }
+}
 
 /**
  * @since 6.0.0 Added `align` and `justify` props.
@@ -73,7 +80,9 @@ export interface OverlayProps
  *
  * @example Simple Example
  * ```tsx
- * import { Button, Overlay, useToggle } from "@react-md/core";
+ * import { Button } from "@react-md/core/button/Button";
+ * import { Overlay } from "@react-md/core/overlay/Overlay";
+ * import { useToggle } from "@react-md/core/useToggle";
  * import type { ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -88,6 +97,7 @@ export interface OverlayProps
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/overlay | Overlay Demos}
  * @since 6.0.0 Removed the `onRequestClose` prop in favor of using
  * the `onClick` prop instead.
  */

package/src/overlay/{overlayStyles.ts → styles.ts}

@@ -11,13 +11,6 @@ import {
 } from "../transition/types.js";
 import { bem } from "../utils/bem.js";
 
-declare module "react" {
-  interface CSSProperties {
-    "--rmd-overlay-background-color"?: string;
-    "--rmd-overlay-z-index"?: number;
-  }
-}
-
 const styles = bem("rmd-overlay");
 
 /** @since 6.0.0 */
@@ -34,6 +27,7 @@ export interface OverlayClassNameOptions {
 
   /** @defaultValue `false` */
   absolute?: boolean;
+
   /** @defaultValue `"center"` */
   align?: BoxAlignItems;
 

package/src/portal/Portal.tsx

@@ -37,6 +37,7 @@ export interface PortalProps {
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/portal | Portal Demos}
  * @see {@link PortalContainerProvider}
  * @see {@link usePortalContainer}
  */

package/src/portal/PortalContainerProvider.tsx

@@ -62,6 +62,7 @@ export interface PortalContainerProviderProps {
  * `<div id="rmd-portal-container"></div>` will be added as the last child to
  * the `document.body` and be used as the container element.
  *
+ * @see {@link https://next.react-md.dev/components/portal | Portal Demos}
  * @see {@link Portal}
  * @since 6.0.0
  */