@react-md/core 1.0.0-next.15 → 1.0.0-next.17

package/src/navigation/types.ts

@@ -47,13 +47,15 @@ export interface NavigationItemSubheader extends ListSubheaderProps {
  * @example Route Group Output
  * ```tsx
  * const nextParents = [item, ...parents];
+ * const id = getNavigationGroupId(item, nextParents);
  * return (
  *   <CollapsibleNavGroup
- *     depth={nextParents.length})
- *     defaultCollapsed={() =>
- *       !data.pathname.includes(getHrefFromParents(nextParents))
- *     }
+ *     depth={nextParents.length}
+ *     collapsed={!data?.expandedItems.has(id)}
  *     buttonChildren={item.children}
+ *     toggleCollapsed={() => {
+ *       data?.toggleExpandedItem(id);
+ *     }}
  *   >
  *     {children}
  *   </CollapsibleNavGroup>
@@ -66,6 +68,43 @@ export interface NavigationItemSubheader extends ListSubheaderProps {
  */
 export interface NavigationItemGroup {
   type: "group";
+
+  /**
+   * An optional unique id to identify the group used for handling the expanded
+   * state when the `href` can't be used.
+   */
+  id?: string;
+
+  /**
+   * An optional href to prefix all child routes with and can be used instead of
+   * the {@link id} for handling the expanded state.
+   *
+   * @example
+   * ```ts
+   * {
+   *   type: "group",
+   *   href: "/some-path",
+   *   children: "Some Name",
+   *   items: [
+   *     {
+   *       type: "route",
+   *       href: "/page-1",
+   *       children: "Page 1",
+   *     },
+   *     {
+   *       type: "route",
+   *       href: "/page-2",
+   *       children: "Page 2",
+   *     },
+   *   ],
+   * }
+   * ```
+   *
+   * Would result in:
+   *
+   * - Page 1 - `/some-path/page-1`
+   * - Page 2 - `/some-path/page-2`
+   */
   href?: string;
   children: ReactNode;
   items: readonly NavigationItem[];
@@ -95,16 +134,27 @@ export type NavigationItem =
 /**
  * @since 6.0.0
  */
-export type NavigationLinkComponent =
-  | "a"
-  | ForwardRefExoticComponent<
-      AnchorHTMLAttributes<HTMLAnchorElement> & { href: string }
-    >;
+export type CustomNavigationLinkComponent = ForwardRefExoticComponent<
+  AnchorHTMLAttributes<HTMLAnchorElement> & { href: string }
+>;
+
+/**
+ * @since 6.0.0
+ */
+export type NavigationLinkComponent = "a" | CustomNavigationLinkComponent;
+
+/**
+ * @since 6.0.0
+ */
+export interface NavigationExpansion {
+  expandedItems: ReadonlySet<string>;
+  toggleExpandedItem: (id: string) => void;
+}
 
 /**
  * @since 6.0.0
  */
-export interface NavigationRenderData {
+export interface NavigationRenderData extends NavigationExpansion {
   /**
    * This is used to set the `active` state on a `NavItemLink`
    */

package/src/navigation/useActiveHeadingId.ts

@@ -112,7 +112,7 @@ export interface ActiveHeadingIdOptions {
   threshold?: IntersectionObserverThreshold;
 
   /** @see {@link DEFAULT_ACTIVE_HEADING_GET_ROOT_MARGIN} */
-  getRootMargin?(): IntersectionObserverRootMargin;
+  getRootMargin?: () => IntersectionObserverRootMargin;
 
   /** @defaultValue `headings[0]?.id ?? ""` */
   defaultActiveId?: UseStateInitializer<string>;

package/src/navigation/useNavigationExpansion.ts

@@ -0,0 +1,170 @@
+"use client";
+import { useEffect, useMemo, useRef } from "react";
+import { type UseStateInitializer, type UseStateSetter } from "../types.js";
+import { useReadonlySet } from "../useReadonlySet.js";
+import {
+  type NavigationExpansion,
+  type NavigationLinkComponent,
+  type NavigationRenderData,
+} from "./types.js";
+import { getPartsFromPathname } from "./utils.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface NavigationExpansionOptions {
+  pathname: string;
+  linkComponent: NavigationLinkComponent;
+
+  /**
+   * An optional list or set of items that should be expanded before the user
+   * interacts with the navigation items.
+   *
+   * The default implementation works well with the `DefaultNavigationRenderer`
+   * by allowing all "folders" (or groups) of items to be expanded by the
+   * `pathname`.
+   *
+   * ```ts
+   * const navItems: readonly NavigationItem[] = [
+   *   {
+   *     type: "route",
+   *     href: "/",
+   *     children: "Home",
+   *   },
+   *   {
+   *     type: "group",
+   *     href: "/group-1",
+   *     children: "Group 1",
+   *     items: [
+   *       {
+   *         type: "group",
+   *         href: "/subgroup-1",
+   *         children: "Subgroup 1",
+   *         items: [
+   *           {
+   *             type: "route",
+   *             href: "/route",
+   *             children: "Group 1 > Subgroup 1 > Route"
+   *           },
+   *         ],
+   *       },
+   *       {
+   *         type: "route",
+   *         href: "/route",
+   *         children: "Group 1 > Route",
+   *       },
+   *     ],
+   *   },
+   * ];
+   * ```
+   *
+   * - `pathname === "/"` - No groups expanded
+   *   - Resolves as `new Set(["/"])`
+   * - `pathname === "/group-1/subgroup-1/route"` - "Group 1" and "Subgroup 1"
+   *   are expanded
+   *   - Resolves as `new Set(["/", "/group-1", "/group-1/route"])`
+   */
+  defaultExpandedItems?: UseStateInitializer<
+    ReadonlySet<string> | readonly string[]
+  >;
+
+  /**
+   * The default behavior is to update the `expandedItems` set as the `pathname`
+   * updates to capture anytime the user might navigate to outer routes outside
+   * of the `Navigation` component. i.e. Click a link within the page.
+   *
+   * Set this to `true` to disable this behavior.
+   *
+   * @defaultValue `false`
+   */
+  disableFollowingPathname?: boolean;
+}
+
+/**
+ * @since 6.0.0
+ */
+export interface NavigationExpansionImplementation extends NavigationExpansion {
+  data: NavigationRenderData;
+  setExpandedItems: UseStateSetter<ReadonlySet<string>>;
+}
+
+/**
+ * Used to create the `data` prop for the `Navigation` component and handling
+ * the expansion of items.
+ *
+ * @example Main Usage
+ * ```tsx
+ * "use client";
+ * import { Navigation } from "@react-md/core/navigation/Navigation";
+ * import { useNavigationExpansion } from "@react-md/core/navigation/useNavigationExpansion";
+ * import Link from "next/link";
+ * import { usePathname } from "next/navigation.js";
+ * import { type ReactElement } from "react";
+ *
+ * import { navItems } from "./navItems.js";
+ *
+ * export function Example(): ReactElement {
+ *   const pathname = usePathname();
+ *   const { data } = useNavigationExpansion({
+ *     pathname,
+ *     linkComponent: Link,
+ *   });
+ *
+ *   return <Navigation data={data} items={navItems} />;
+ * }
+ * ```
+ *
+ * @since 6.0.0
+ */
+export function useNavigationExpansion(
+  options: NavigationExpansionOptions
+): NavigationExpansionImplementation {
+  const {
+    pathname,
+    linkComponent,
+    defaultExpandedItems,
+    disableFollowingPathname,
+  } = options;
+  const {
+    value: expandedItems,
+    setValue: setExpandedItems,
+    toggleValue: toggleExpandedItem,
+  } = useReadonlySet({
+    defaultValue:
+      defaultExpandedItems ?? (() => new Set(getPartsFromPathname(pathname))),
+  });
+
+  const prevPathname = useRef(pathname);
+  useEffect(() => {
+    if (disableFollowingPathname || pathname === prevPathname.current) {
+      return;
+    }
+
+    prevPathname.current = pathname;
+    setExpandedItems((prev) => {
+      const next = new Set([...prev, ...getPartsFromPathname(pathname)]);
+      if (next.size === prev.size) {
+        return prev;
+      }
+
+      return next;
+    });
+  }, [disableFollowingPathname, pathname, setExpandedItems]);
+
+  const data = useMemo<NavigationRenderData>(
+    () => ({
+      pathname,
+      linkComponent,
+      expandedItems,
+      toggleExpandedItem,
+    }),
+    [expandedItems, linkComponent, pathname, toggleExpandedItem]
+  );
+
+  return {
+    data,
+    expandedItems,
+    setExpandedItems,
+    toggleExpandedItem,
+  };
+}

package/src/navigation/utils.ts

@@ -0,0 +1,47 @@
+import { type NavigationItem } from "./types.js";
+
+/**
+ * @since 6.0.0
+ */
+export function getHrefFromParents(parents: readonly NavigationItem[]): string {
+  return parents.reduce<string>((result, parent) => {
+    if ("href" in parent && parent.href) {
+      const { href } = parent;
+      return result + href;
+    }
+
+    return result;
+  }, "");
+}
+
+/**
+ * @since 6.0.0
+ */
+export function getNavigationGroupId(
+  group: NavigationItem,
+  parents: readonly NavigationItem[]
+): string {
+  if ("id" in group && typeof group.id === "string" && group.id) {
+    return group.id;
+  }
+
+  return getHrefFromParents(parents);
+}
+
+/**
+ * @since 6.0.0
+ */
+export function getPartsFromPathname(pathname: string): ReadonlySet<string> {
+  // remove trailing slashes just in case there aren't rewrites in place
+  const href = pathname.replace(/\/{2,}/g, "/").replace(/\/+$/, "");
+  const parts = href.split("/");
+  const set = new Set<string>();
+  let prefix = "";
+  for (const part of parts) {
+    const slashed = `/${part}`;
+    prefix = prefix === "/" ? slashed : prefix + slashed;
+    set.add(prefix);
+  }
+
+  return set;
+}

package/src/objectFit.ts

@@ -0,0 +1,88 @@
+import { cnb } from "cnbuilder";
+import { bem } from "./utils/bem.js";
+
+const styles = bem("rmd-object-fit");
+
+/**
+ * @since 6.0.0
+ */
+export interface ObjectFitOptions {
+  className?: string;
+
+  /**
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit}
+   * @defaultValue `aspectRatio ? "fill" : "contain"`
+   */
+  fit?: "contain" | "cover" | "fill" | "none" | "scale-down";
+
+  /**
+   * Set this to a custom aspect ratio to use.
+   *
+   * @example Valid Aspect Ratios
+   * ```tsx
+   * aspectRatio: "16-9",
+   * aspectRatio: "9-16",
+   * aspectRatio: "3-4",
+   * aspectRatio: "4-3",
+   * aspectRatio: "1-1",
+   * ```
+   *
+   * These values are based on the `$object-fit-aspect-ratios` map.
+   *
+   * @defaultValue `""`
+   */
+  aspectRatio?: `${number}-${number}`;
+}
+
+/**
+ * This is a utility className helper function that should be applied to
+ * `<img>` and `<video>` elements to make them responsive to their content box
+ * container.
+ *
+ * @example Simple Example
+ * ```tsx
+ * import { objectFit } from "@react-md/core/objectFit";
+ *
+ * export function Example() {
+ *   return (
+ *     <img
+ *       alt=""
+ *       src="https://example.com/example.png"
+ *       className={objectFit()}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example Setting Aspect Ratio
+ * ```tsx
+ * import { objectFit } from "@react-md/core/objectFit";
+ *
+ * export function Example() {
+ *   return (
+ *     <img
+ *       alt=""
+ *       src="https://example.com/example.png"
+ *       className={objectFit({
+ *         aspectRatio: "16-9",
+ *       })}
+ *     />
+ *   );
+ * }
+ *
+ * ```
+ *
+ * @since 6.0.0
+ */
+export function objectFit(options: ObjectFitOptions = {}): string {
+  const { className, fit: propFit, aspectRatio = "" } = options;
+  const fit = propFit ?? (aspectRatio ? "fill" : "contain");
+
+  return cnb(
+    styles({
+      [fit]: fit !== "contain",
+      [aspectRatio]: !!aspectRatio,
+    }),
+    className
+  );
+}

package/src/positioning/useFixedPositioning.ts

@@ -15,7 +15,11 @@ import { useEnsuredRef } from "../useEnsuredRef.js";
 import { useIsomorphicLayoutEffect } from "../useIsomorphicLayoutEffect.js";
 import { BELOW_CENTER_ANCHOR } from "./constants.js";
 import { getFixedPosition } from "./getFixedPosition.js";
-import { type CalculateFixedPositionOptions } from "./types.js";
+import {
+  type CalculateFixedPositionOptions,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  type FixedPositionStyle,
+} from "./types.js";
 import { isWithinViewport } from "./utils.js";
 
 const noop = (): undefined => undefined;
@@ -109,7 +113,7 @@ export interface FixedPositioningOptions<
    * some options require the element to be in the DOM for specific
    * calculations.
    */
-  getFixedPositionOptions?(): CalculateFixedPositionOptions;
+  getFixedPositionOptions?: () => CalculateFixedPositionOptions;
 
   /**
    * An optional function to call if the page resizes while the `FixedElement`
@@ -118,6 +122,17 @@ export interface FixedPositioningOptions<
   onResize?: EventListener;
   /** @see {@link TransitionScrollCallback} */
   onScroll?: TransitionScrollCallback<FixedToElement, FixedElement>;
+
+  /**
+   * Set this to `true` to disable the fixed positioning behavior so it can be
+   * customized within CSS or manually instead. This was added mostly to just
+   * support rendering menus inline with other content (like autocompletes
+   * within a dialog).
+   *
+   * @defaultValue `false`
+   * @since 6.0.0
+   */
+  disabled?: boolean;
 }
 
 /**
@@ -135,9 +150,12 @@ export interface FixedPositioningHookReturnValue<E extends HTMLElement> {
   ref: RefCallback<E>;
 
   /**
-   * @see {@link FixedPositionStyle}
+   * This is the {@link FixedPositionStyle} merged with the
+   * {@link FixedPositioningOptions.style}. This will only return `undefined`
+   * when {@link FixedPositioningOptions.disabled} is `true` and no `style` was
+   * provided.
    */
-  style: CSSProperties;
+  style: CSSProperties | undefined;
 
   /**
    * This should really only be used if the {@link transitionOptions} is not
@@ -148,7 +166,7 @@ export interface FixedPositioningHookReturnValue<E extends HTMLElement> {
   /**
    * A function that can be called to update the style for the fixed element.
    */
-  updateStyle(): void;
+  updateStyle: () => void;
 
   /** {@inheritDoc FixedPositioningTransitionOptions} */
   transitionOptions: Readonly<Required<FixedPositioningTransitionOptions<E>>>;
@@ -219,6 +237,7 @@ export function useFixedPositioning<
     style: propStyle,
     nodeRef,
     fixedTo,
+    disabled,
     onEnter = noop,
     onEntering = noop,
     onEntered = noop,
@@ -310,6 +329,10 @@ export function useFixedPositioning<
   );
 
   const updateStyle = useCallback(() => {
+    if (disabled) {
+      return;
+    }
+
     const {
       ref,
       fixedTo,
@@ -348,12 +371,12 @@ export function useFixedPositioning<
     setStyle(style);
     setActive(!!element && !element.hidden);
 
-    // Only changing the initialX and initialY should cause the useEffect below
-    // to trigger, which is why everything else is set in a ref.
-  }, [initialX, initialY]);
+    // Only changing the initialX, initialY, or disabled should cause the
+    // useEffect below to trigger, which is why everything else is set in a ref.
+  }, [disabled, initialX, initialY]);
 
   useEffect(() => {
-    if (!active) {
+    if (!active || disabled) {
       return;
     }
 
@@ -385,7 +408,7 @@ export function useFixedPositioning<
       resizeHandler.remove(resizeCallback);
       scrollHandler.remove(scrollCallback);
     };
-  }, [active, fixedTo, onResize, onScroll, ref, updateStyle]);
+  }, [active, disabled, fixedTo, onResize, onScroll, ref, updateStyle]);
 
   const callbacks: Required<FixedPositioningTransitionCallbacks> = {
     onEnter(appearing) {
@@ -408,7 +431,7 @@ export function useFixedPositioning<
 
   return {
     ref: refHandler,
-    style: { ...style, ...propStyle },
+    style: disabled ? propStyle : { ...style, ...propStyle },
     callbacks,
     updateStyle,
     transitionOptions: {

package/src/progress/CircularProgress.tsx

@@ -115,8 +115,6 @@ export interface CircularProgressProps
 const styles = bem("rmd-circular-progress");
 
 /**
- * **Server Component**
- *
  * @example Indeterminate Example
  * ```tsx
  * import { CircularProgress } from "@react-md/core":

package/src/progress/LinearProgress.tsx

@@ -63,8 +63,6 @@ export interface LinearProgressProps
 const styles = bem("rmd-linear-progress");
 
 /**
- * **Server Component**
- *
  * @example Indeterminate Example
  * ```tsx
  * import { LinearProgress } from "@react-md/core";

package/src/responsive-item/ResponsiveItem.tsx

@@ -0,0 +1,96 @@
+import { forwardRef, type HTMLAttributes } from "react";
+import {
+  responsiveItem,
+  type ResponsiveItemClassNameOptions,
+} from "./responsiveItemStyles.js";
+
+/**
+ * @since 6.0.0 Renamed from `MediaContainerProps` to
+ * `ResponsiveItemProps`
+ * @since 6.0.0 The `height` and `width` props were removed in favor of the
+ * `aspectRatio` props since the latest typescript string interpolation supports
+ * enforcing the correct format.
+ * @since 6.0.0 The `auto` prop was removed in favor of the new
+ * {@link ResponsiveItemProps.responsive} prop.
+ */
+export interface ResponsiveItemProps
+  extends HTMLAttributes<HTMLSpanElement>,
+    ResponsiveItemClassNameOptions {}
+
+/**
+ * @example Image Example
+ * ```tsx
+ * import { ResponsiveItem } from "@react-md/core";
+ * import type { ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   return (
+ *     <ResponsiveItem>
+ *       <img alt="" src="/some-image.png" />
+ *     </ResponsiveItem>
+ *   );
+ * }
+ * ```
+ *
+ * @example Iframe Example
+ * ```tsx
+ * import { ResponsiveItem } from "@react-md/core";
+ * import type { ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   return (
+ *     <ResponsiveItem>
+ *       <iframe
+ *         src="https://youtube.com/some-video-url"
+ *         title="Some YouTube video"
+ *         allowFullScreen
+ *       />
+ *     </ResponsiveItem>
+ *   );
+ * }
+ * ```
+ *
+ * @example Forced Aspect Ratio
+ * ```tsx
+ * import { ResponsiveItem } from "@react-md/core";
+ * import type { ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   return (
+ *     <ResponsiveItem aspectRatio="16-9">
+ *       <img alt="" src="/some-image.png" />
+ *     </ResponsiveItem>
+ *   );
+ * }
+ * ```
+ *
+ * @since 6.0.0 Renamed from `MediaContainer` to
+ * `ResponsiveItem` and renders a `<span>` instead of a `<div>`.
+ */
+export const ResponsiveItem = forwardRef<HTMLSpanElement, ResponsiveItemProps>(
+  function ResponsiveItem(props, ref) {
+    const {
+      className,
+      fullWidth = false,
+      aspectRatio,
+      responsive = "auto",
+      children,
+      ...remaining
+    } = props;
+
+    return (
+      <span
+        {...remaining}
+        ref={ref}
+        className={responsiveItem({
+          className,
+          fullWidth,
+          aspectRatio,
+          responsive,
+        })}
+      >
+        {children}
+      </span>
+    );
+  }
+);