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

package/src/navigation/CollapsibleNavGroup.tsx

@@ -1,9 +1,11 @@
 "use client";
 import { forwardRef, type LiHTMLAttributes, type ReactNode } from "react";
 import { type ButtonProps } from "../button/Button.js";
-import { useCollapseTransition } from "../transition/useCollapseTransition.js";
-import { type PropsWithRef, type UseStateInitializer } from "../types.js";
-import { useToggle } from "../useToggle.js";
+import {
+  type CollapseTransitionHookOptions,
+  useCollapseTransition,
+} from "../transition/useCollapseTransition.js";
+import { type PropsWithRef } from "../types.js";
 import { NavGroup, type NavGroupProps } from "./NavGroup.js";
 import { NavItem } from "./NavItem.js";
 import {
@@ -23,6 +25,10 @@ export interface CollapsibleNavGroupProps
     NavItemButtonRotatorProps {
   liProps?: PropsWithRef<LiHTMLAttributes<HTMLLIElement>, HTMLLIElement>;
   buttonProps?: PropsWithRef<ButtonProps, HTMLButtonElement>;
+  collapseOptions?: Omit<
+    CollapseTransitionHookOptions<HTMLUListElement>,
+    "nodeRef" | "className" | "transitionIn"
+  >;
 
   /**
    * The children to render in the {@link NavItemButton} that toggles the
@@ -35,8 +41,8 @@ export interface CollapsibleNavGroupProps
    */
   children: ReactNode;
 
-  /** @defaultValue `false` */
-  defaultCollapsed?: UseStateInitializer<boolean>;
+  collapsed: boolean;
+  toggleCollapsed: () => void;
 }
 
 /**
@@ -57,12 +63,14 @@ export const CollapsibleNavGroup = forwardRef<
     disableIconRotator,
     className,
     children,
-    defaultCollapsed,
+    collapsed,
+    toggleCollapsed,
+    collapseOptions,
     ...remaining
   } = props;
 
-  const { toggled: collapsed, toggle } = useToggle(defaultCollapsed);
   const { rendered, elementProps } = useCollapseTransition({
+    ...collapseOptions,
     nodeRef: ref,
     className,
     transitionIn: !collapsed,
@@ -75,7 +83,7 @@ export const CollapsibleNavGroup = forwardRef<
         {...buttonProps}
         onClick={(event) => {
           onButtonClick(event);
-          toggle();
+          toggleCollapsed();
         }}
         collapsed={collapsed}
         icon={icon}

package/src/navigation/DefaultNavigationRenderer.tsx

@@ -4,16 +4,16 @@ import { type RenderRecursiveItemsProps } from "../utils/RenderRecursively.js";
 import { CollapsibleNavGroup } from "./CollapsibleNavGroup.js";
 import { NavItemLink } from "./NavItemLink.js";
 import { NavSubheader } from "./NavSubheader.js";
-import { getHrefFromParents } from "./getHrefFromParents.js";
 import { type NavigationItem, type NavigationRenderData } from "./types.js";
+import { getHrefFromParents, getNavigationGroupId } from "./utils.js";
 
 /**
  * @since 6.0.0
  */
-export interface DefaultNavigationRendererProps<
+export type DefaultNavigationRendererProps<
   Item extends NavigationItem = NavigationItem,
   Data extends NavigationRenderData = NavigationRenderData,
-> extends RenderRecursiveItemsProps<Item, Data> {}
+> = RenderRecursiveItemsProps<Item, Data>;
 
 /**
  * **Client Component**
@@ -46,13 +46,15 @@ export function DefaultNavigationRenderer<
 
   if (item.items) {
     const nextParents = [item, ...parents];
+    const id = getNavigationGroupId(item, nextParents);
     return (
       <CollapsibleNavGroup
         depth={nextParents.length}
-        defaultCollapsed={() =>
-          !data?.pathname.includes(getHrefFromParents(nextParents))
-        }
+        collapsed={!data?.expandedItems.has(id)}
         buttonChildren={item.children}
+        toggleCollapsed={() => {
+          data?.toggleExpandedItem(id);
+        }}
       >
         {children}
       </CollapsibleNavGroup>

package/src/navigation/NavItemButton.tsx

@@ -15,7 +15,7 @@ import { type NavItemContentProps } from "./types.js";
 export interface NavItemButtonRotatorProps {
   /** @defaultValue `getIcon("dropdown")` */
   icon?: ReactNode;
-  iconRotatorProps?: IconRotatorBaseProps;
+  iconRotatorProps?: Omit<IconRotatorBaseProps, "rotated">;
   disableIconRotator?: boolean;
 }
 
@@ -74,6 +74,7 @@ export const NavItemButton = forwardRef<HTMLButtonElement, NavItemButtonProps>(
     return (
       <>
         <Button
+          aria-expanded={!collapsed}
           {...remaining}
           {...elementProps}
           ref={ref}

package/src/navigation/NavItemLink.tsx

@@ -6,6 +6,7 @@ import {
   type LiHTMLAttributes,
 } from "react";
 import { cssUtils } from "../cssUtils.js";
+import { type ComponentWithRippleProps } from "../interaction/types.js";
 import { useElementInteraction } from "../interaction/useElementInteraction.js";
 import { Tooltip } from "../tooltip/Tooltip.js";
 import { useTooltip } from "../tooltip/useTooltip.js";
@@ -23,7 +24,8 @@ import {
  */
 export interface NavItemLinkProps
   extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "children">,
-    NavItemContentProps {
+    NavItemContentProps,
+    ComponentWithRippleProps {
   /** @defaultValue `"a"` */
   as?: NavigationLinkComponent;
   href: string;
@@ -48,7 +50,7 @@ export interface NavItemLinkProps
 
   /**
    * Set this to `true` to prevent this item from scrolling into view when it
-   * becomes active. It is generally recommended to keep this `true` unless a
+   * becomes active. It is generally recommended to keep this `false` unless a
    * custom implementation has been added so that when the temporary navigation
    * will show the active route.
    *
@@ -88,12 +90,14 @@ export const NavItemLink = forwardRef<HTMLAnchorElement, NavItemLinkProps>(
       onTouchEnd,
       onTouchStart,
       tooltipOptions,
+      disableRipple,
       disableScrollIntoView,
       ...remaining
     } = props;
 
     const [linkRef, linkRefCallback] = useEnsuredRef(propRef);
     const { handlers, ripples } = useElementInteraction({
+      mode: disableRipple ? "none" : undefined,
       disabled,
       onClick,
       onBlur,
@@ -120,7 +124,10 @@ export const NavItemLink = forwardRef<HTMLAnchorElement, NavItemLinkProps>(
         !active ||
         !link ||
         disableScrollIntoView ||
-        document.activeElement === link
+        document.activeElement === link ||
+        // do not scroll into view if the collapse transition is occurring since
+        // it makes it animate weirdly
+        link.closest(".rmd-collapse--enter")
       ) {
         return;
       }
@@ -131,6 +138,7 @@ export const NavItemLink = forwardRef<HTMLAnchorElement, NavItemLinkProps>(
     return (
       <NavItem {...liProps}>
         <Component
+          aria-current={active ? "page" : undefined}
           {...remaining}
           {...handlers}
           {...elementProps}

package/src/navigation/NavSubheader.tsx

@@ -8,7 +8,7 @@ import { navItem } from "./navItemStyles.js";
 /**
  * @since 6.0.0
  */
-export interface NavSubheaderProps extends ListSubheaderProps {}
+export type NavSubheaderProps = ListSubheaderProps;
 
 /**
  * A simple wrapper around the {@Link ListSubheader} that updates the padding

package/src/navigation/Navigation.tsx

@@ -58,7 +58,7 @@ export interface NavigationProps<
   render?: ComponentType<RenderRecursiveItemsProps<Item, Data>>;
 
   /** @see {@link getRecursiveNavItemKey} */
-  getItemKey?(options: RecursiveItemKeyOptions<Item>): string;
+  getItemKey?: (options: RecursiveItemKeyOptions<Item>) => string;
 }
 
 /**

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