@react-md/core 1.0.0-next.16 → 1.0.0-next.18

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/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>
+    );
+  }
+);

package/src/responsive-item/ResponsiveItemOverlay.tsx

@@ -1,50 +1,10 @@
-import { cnb } from "cnbuilder";
 import { forwardRef, type HTMLAttributes } from "react";
-import { bem } from "../utils/bem.js";
-
-const styles = bem("rmd-responsive-item-overlay");
-
-/**
- * The overlay positions relative to the `MediaContainer` component.  Most of
- * the sizes are self-explanatory, but the `middle` position will be centered
- * vertically while `center` will be centered `horizontally`.
- *
- * @since 6.0.0 Renamed from `MediaOverlayPosition` to
- * `ResponsiveItemOverlayProps`.
- */
-export type ResponsiveItemOverlayPosition =
-  | "top"
-  | "right"
-  | "bottom"
-  | "left"
-  | "middle"
-  | "center"
-  | "absolute-center";
-
-/** @since 6.0.0 */
-export interface ResponsiveItemOverlayClassNameOptions {
-  className?: string;
-  /** @defaultValue `"bottom"` */
-  position?: ResponsiveItemOverlayPosition;
-}
-
-/**
- * @since 6.0.0
- */
-export function responsiveItemOverlay(
-  options: ResponsiveItemOverlayClassNameOptions = {}
-): string {
-  const { className, position = "bottom" } = options;
-
-  return cnb(
-    styles({
-      [position]: true,
-      horizontal:
-        position !== "top" && position !== "bottom" && position !== "middle",
-    }),
-    className
-  );
-}
+import {
+  responsiveItemOverlay,
+  type ResponsiveItemOverlayClassNameOptions,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  type ResponsiveItemOverlayPosition,
+} from "./responsiveItemOverlayStyles.js";
 
 /**
  * @since 6.0.0 Renamed from `MediaOverlayProps` to

package/src/responsive-item/responsiveItemOverlayStyles.ts

@@ -0,0 +1,46 @@
+import { cnb } from "cnbuilder";
+import { bem } from "../utils/bem.js";
+
+const styles = bem("rmd-responsive-item-overlay");
+
+/**
+ * The overlay positions relative to the `MediaContainer` component.  Most of
+ * the sizes are self-explanatory, but the `middle` position will be centered
+ * vertically while `center` will be centered `horizontally`.
+ *
+ * @since 6.0.0 Renamed from `MediaOverlayPosition` to
+ * `ResponsiveItemOverlayProps`.
+ */
+export type ResponsiveItemOverlayPosition =
+  | "top"
+  | "right"
+  | "bottom"
+  | "left"
+  | "middle"
+  | "center"
+  | "absolute-center";
+
+/** @since 6.0.0 */
+export interface ResponsiveItemOverlayClassNameOptions {
+  className?: string;
+  /** @defaultValue `"bottom"` */
+  position?: ResponsiveItemOverlayPosition;
+}
+
+/**
+ * @since 6.0.0
+ */
+export function responsiveItemOverlay(
+  options: ResponsiveItemOverlayClassNameOptions = {}
+): string {
+  const { className, position = "bottom" } = options;
+
+  return cnb(
+    styles({
+      [position]: true,
+      horizontal:
+        position !== "top" && position !== "bottom" && position !== "middle",
+    }),
+    className
+  );
+}

package/src/responsive-item/responsiveItemStyles.ts

@@ -0,0 +1,81 @@
+import { cnb } from "cnbuilder";
+import { bem } from "../utils/bem.js";
+
+const styles = bem("rmd-responsive-item");
+
+/** @since 6.0.0 */
+export interface ResponsiveItemClassNameOptions {
+  className?: string;
+
+  /**
+   * Set this to `true` if the container should gain the following styles:
+   *
+   * ```scss
+   * display: block;
+   * width: 100%;
+   * ```
+   *
+   * @defaultValue `false`
+   */
+  fullWidth?: boolean;
+
+  /**
+   * 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 `core.$responsive-item-aspect-ratios` map.
+   *
+   * @defaultValue `""`
+   */
+  aspectRatio?: `${number}-${number}`;
+
+  /**
+   * Set this to `"manual"` if you want to manually specify which elements are
+   * responsive items using custom class names. You probably don't really want
+   * to use this.
+   *
+   * Set this to `"auto"` to automatically update all visual media that appear
+   * as a child in this component to a responsive item.
+   *
+   * Set this to `"container"` to automatically update all visual media that
+   * appear as a child in this component to be a responsive item that scales to
+   * the container's dimensions.
+   *
+   * Note: The `"auto"` and `"container"` values use the
+   * `core.$responsive-item-selectors` value for their behavior.
+   *
+   * @defaultValue `"auto"`
+   */
+  responsive?: "auto" | "manual" | "container";
+}
+
+/** @since 6.0.0 */
+export function responsiveItem(
+  options: ResponsiveItemClassNameOptions = {}
+): string {
+  const {
+    className,
+    fullWidth = false,
+    aspectRatio = "",
+    responsive = "auto",
+  } = options;
+
+  return cnb(
+    styles({
+      auto: responsive !== "manual",
+      "auto-scale": responsive === "container",
+      "aspect-ratio": aspectRatio,
+      [aspectRatio]: aspectRatio,
+      "full-width": fullWidth,
+    }),
+    className
+  );
+}