@react-md/core 1.0.0-next.11 → 1.0.0-next.13

package/src/navigation/NavItemLink.tsx

@@ -0,0 +1,163 @@
+"use client";
+import {
+  forwardRef,
+  useEffect,
+  type AnchorHTMLAttributes,
+  type LiHTMLAttributes,
+} from "react";
+import { cssUtils } from "../cssUtils.js";
+import { useElementInteraction } from "../interaction/useElementInteraction.js";
+import { Tooltip } from "../tooltip/Tooltip.js";
+import { useTooltip } from "../tooltip/useTooltip.js";
+import { type PropsWithRef } from "../types.js";
+import { useEnsuredRef } from "../useEnsuredRef.js";
+import { NavItem } from "./NavItem.js";
+import { navItemLink } from "./navItemStyles.js";
+import {
+  type NavItemContentProps,
+  type NavigationLinkComponent,
+} from "./types.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface NavItemLinkProps
+  extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "children">,
+    NavItemContentProps {
+  /** @defaultValue `"a"` */
+  as?: NavigationLinkComponent;
+  href: string;
+
+  /**
+   * Any additional props to provide the wrapping `<li>` element such as
+   * `style`, `className`, and `ref`.
+   */
+  liProps?: PropsWithRef<LiHTMLAttributes<HTMLLIElement>, HTMLLIElement>;
+
+  /**
+   * Set this to `true` if the link matches the current `pathname`. This will
+   * enable `aria-current="true"` and apply active styling.
+   */
+  active: boolean;
+
+  /** @defaultValue `cssUtils({ fontWeight: "bold" })` */
+  activeClassName?: string;
+
+  /** @defaultValue `!to && !href` */
+  disabled?: boolean;
+
+  /**
+   * 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
+   * custom implementation has been added so that when the temporary navigation
+   * will show the active route.
+   *
+   * @defaultValue `false`
+   */
+  disableScrollIntoView?: boolean;
+}
+
+/**
+ * **Client Component**
+ *
+ * @since 6.0.0
+ */
+export const NavItemLink = forwardRef<HTMLAnchorElement, NavItemLinkProps>(
+  function NavItemLink(props, propRef) {
+    const {
+      as: Component = "a",
+      href,
+      active,
+      activeClassName,
+      beforeAddon,
+      afterAddon,
+      className,
+      children,
+      liProps,
+      spanProps,
+      disabled = !href,
+      onClick,
+      onBlur,
+      onDragStart,
+      onKeyDown,
+      onKeyUp,
+      onMouseDown,
+      onMouseLeave,
+      onMouseUp,
+      onTouchMove,
+      onTouchEnd,
+      onTouchStart,
+      tooltipOptions,
+      disableScrollIntoView,
+      ...remaining
+    } = props;
+
+    const [linkRef, linkRefCallback] = useEnsuredRef(propRef);
+    const { handlers, ripples } = useElementInteraction({
+      disabled,
+      onClick,
+      onBlur,
+      onDragStart,
+      onKeyDown,
+      onKeyUp,
+      onMouseDown,
+      onMouseLeave,
+      onMouseUp,
+      onTouchMove,
+      onTouchEnd,
+      onTouchStart,
+    });
+
+    const { elementProps, tooltipProps, overflowRef } = useTooltip({
+      overflowOnly: true,
+      defaultPosition: "right",
+      ...tooltipOptions,
+      ...handlers,
+    });
+    useEffect(() => {
+      const link = linkRef.current;
+      if (
+        !active ||
+        !link ||
+        disableScrollIntoView ||
+        document.activeElement === link
+      ) {
+        return;
+      }
+
+      link.scrollIntoView({ block: "center" });
+    }, [active, disableScrollIntoView, linkRef]);
+
+    return (
+      <NavItem {...liProps}>
+        <Component
+          {...remaining}
+          {...handlers}
+          {...elementProps}
+          ref={linkRefCallback}
+          href={href}
+          className={navItemLink({
+            active,
+            activeClassName,
+            className,
+          })}
+        >
+          {beforeAddon}
+          <span
+            {...spanProps}
+            ref={overflowRef}
+            className={cssUtils({
+              className: spanProps?.className,
+              textOverflow: "ellipsis",
+            })}
+          >
+            {children}
+          </span>
+          {afterAddon}
+          {ripples}
+        </Component>
+        <Tooltip {...tooltipProps}>{children}</Tooltip>
+      </NavItem>
+    );
+  }
+);

package/src/navigation/NavSubheader.tsx

@@ -0,0 +1,36 @@
+import { forwardRef } from "react";
+import {
+  ListSubheader,
+  type ListSubheaderProps,
+} from "../list/ListSubheader.js";
+import { navItem } from "./navItemStyles.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface NavSubheaderProps extends ListSubheaderProps {}
+
+/**
+ * **Server Component**
+ *
+ * A simple wrapper around the {@Link ListSubheader} that updates the padding
+ * based on the current navigation item depth to match the other items.
+ *
+ * @since 6.0.0
+ */
+export const NavSubheader = forwardRef<HTMLLIElement, NavSubheaderProps>(
+  function NavSubheader(props, ref) {
+    const { textProps, ...remaining } = props;
+
+    return (
+      <ListSubheader
+        {...remaining}
+        ref={ref}
+        textProps={{
+          ...textProps,
+          className: navItem({ className: textProps?.className }),
+        }}
+      />
+    );
+  }
+);

package/src/navigation/Navigation.tsx

@@ -0,0 +1,91 @@
+import { type ComponentType, type ReactElement } from "react";
+import { type ListProps } from "../list/List.js";
+import {
+  RenderRecursively,
+  getRecursiveItemKey,
+  type RecursiveItem,
+  type RecursiveItemKeyOptions,
+  type RenderRecursiveItemsProps,
+} from "../utils/RenderRecursively.js";
+import { DefaultNavigationRenderer } from "./DefaultNavigationRenderer.js";
+import { NavGroup } from "./NavGroup.js";
+import { type NavigationItem, type NavigationRenderData } from "./types.js";
+
+/**
+ * The default implementation for the nav item keys. It will attempt to set the
+ * key in the following order:
+ * - `href` if it exists and has length
+ * - `children` if it's a string and has length
+ * - default {@link getRecursiveItemKey} behavior of `${depth}-${index}`
+ *
+ * @since 6.0.0
+ */
+export function getRecursiveNavItemKey<
+  Item extends NavigationItem = NavigationItem,
+>(options: RecursiveItemKeyOptions<Item>): string {
+  const { item } = options;
+  // if it's a route, try setting the key to the href since they are generally
+  // unique
+  if ("href" in item && item.href) {
+    return item.href;
+  }
+
+  // if children exist in the item (group, route, subheader), try to set that as
+  // the key since they are usually unique
+  if (
+    "children" in item &&
+    typeof item.children === "string" &&
+    item.children
+  ) {
+    return item.children;
+  }
+
+  // use the default key behavior if all else fails
+  return getRecursiveItemKey(options);
+}
+
+/**
+ * @since 6.0.0
+ */
+export interface NavigationProps<
+  Item extends NavigationItem = NavigationItem,
+  Data extends NavigationRenderData = NavigationRenderData,
+> extends Omit<ListProps, "children"> {
+  data: Data;
+  items: readonly RecursiveItem<Item>[];
+
+  /** @see {@link DefaultNavigationRenderer} */
+  render?: ComponentType<RenderRecursiveItemsProps<Item, Data>>;
+
+  /** @see {@link getRecursiveNavItemKey} */
+  getItemKey?(options: RecursiveItemKeyOptions<Item>): string;
+}
+
+/**
+ * **Client Component**
+ *
+ * @since 6.0.0
+ */
+export function Navigation<
+  Item extends NavigationItem,
+  Data extends NavigationRenderData,
+>(props: NavigationProps<Item, Data>): ReactElement {
+  const {
+    data,
+    items,
+    render = DefaultNavigationRenderer,
+    getItemKey = getRecursiveNavItemKey,
+    ...remaining
+  } = props;
+
+  return (
+    <NavGroup depth={0} {...remaining}>
+      <RenderRecursively
+        data={data}
+        items={items}
+        render={render}
+        getItemKey={getItemKey}
+      />
+    </NavGroup>
+  );
+}

package/src/navigation/__tests__/Navigation.tsx

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "@jest/globals";
+import { FontIcon } from "../../icon/FontIcon.js";
+import { render, screen, userEvent, within } from "../../test-utils/index.js";
+import { Navigation, type NavigationProps } from "../Navigation.js";
+import { type NavigationItem } from "../types.js";
+
+const items: NavigationItem[] = [
+  {
+    type: "route",
+    href: "/",
+    children: "Home",
+    beforeAddon: <FontIcon>home</FontIcon>,
+  },
+  { type: "divider" },
+  {
+    type: "subheader",
+    children: "Subheader",
+  },
+  {
+    type: "group",
+    href: "/path-1",
+    children: "Path 1",
+    items: [
+      {
+        type: "route",
+        href: "/route-1",
+        children: "Route 1",
+      },
+      {
+        type: "route",
+        href: "/route-2",
+        children: "Route 2",
+      },
+    ],
+  },
+  {
+    type: "group",
+    href: "/path-2",
+    children: "Path 2",
+    items: [
+      { type: "subheader", children: "Routes" },
+      {
+        type: "route",
+        href: "/route-1",
+        children: "Route 1",
+      },
+      {
+        type: "divider",
+        inset: true,
+      },
+      {
+        type: "route",
+        href: "/route-2",
+        children: "Route 2",
+      },
+    ],
+  },
+];
+
+const BASE_PROPS: NavigationProps = {
+  "data-testid": "nav",
+  data: { pathname: "/", linkComponent: "a" },
+  items,
+};
+
+describe("Navigation", () => {
+  it("should be able to render dividers, subheaders, groups, links, and nested items out of the box", () => {
+    render(<Navigation {...BASE_PROPS} />);
+
+    const nav = screen.getByTestId("nav");
+    expect(nav).toMatchSnapshot();
+    const path2 = screen.getByRole("button", { name: "Path 2" });
+    const path2Parent = path2.parentElement;
+    if (!path2Parent) {
+      throw new Error();
+    }
+
+    expect(() => within(path2Parent).getByText("Route 1")).toThrow();
+  });
+
+  it("should allow route groups to be expanded", async () => {
+    const user = userEvent.setup();
+    render(<Navigation {...BASE_PROPS} />);
+    const path2 = screen.getByRole("button", { name: "Path 2" });
+    const path2Parent = path2.parentElement;
+    if (!path2Parent) {
+      throw new Error();
+    }
+
+    await user.click(path2);
+    const route1 = within(path2Parent).getByText("Route 1");
+    expect(path2Parent).toMatchSnapshot();
+
+    await user.click(path2);
+    expect(route1).not.toBeInTheDocument();
+  });
+});

package/src/navigation/__tests__/__snapshots__/Navigation.tsx.snap

@@ -0,0 +1,165 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Navigation should allow route groups to be expanded 1`] = `
+<li
+  class="rmd-nav-item"
+>
+  <button
+    class="rmd-button rmd-button--text rmd-interaction-surface rmd-nav-item__content"
+    id=":ra:"
+    type="button"
+  >
+    <span
+      class="rmd-nowrap rmd-ellipsis"
+    >
+      Path 2
+    </span>
+    <span
+      aria-hidden="true"
+      class="rmd-icon rmd-icon--font material-icons rmd-icon-rotator rmd-icon-rotator--animate rmd-icon-rotator--rotated"
+    >
+      arrow_drop_down
+    </span>
+  </button>
+  <ul
+    class="rmd-list rmd-nav-group rmd-nav-group--np rmd-collapse"
+    role="none"
+    style="padding-top: 0px; padding-bottom: 0px; --rmd-tree-depth: 1;"
+  >
+    <li
+      class="rmd-list-subheader"
+      role="presentation"
+    >
+      <span
+        class="rmd-list-item__text rmd-nav-item"
+      >
+        Routes
+      </span>
+    </li>
+    <li
+      class="rmd-nav-item"
+    >
+      <a
+        class="rmd-nav-item__content rmd-nav-item__link rmd-button rmd-button--text rmd-interaction-surface rmd-none"
+        href="/path-2/route-1"
+        id=":rc:"
+        type="route"
+      >
+        <span
+          class="rmd-nowrap rmd-ellipsis"
+        >
+          Route 1
+        </span>
+      </a>
+    </li>
+    <hr
+      class="rmd-divider rmd-divider--inset"
+      role="separator"
+    />
+    <li
+      class="rmd-nav-item"
+    >
+      <a
+        class="rmd-nav-item__content rmd-nav-item__link rmd-button rmd-button--text rmd-interaction-surface rmd-none"
+        href="/path-2/route-2"
+        id=":re:"
+        type="route"
+      >
+        <span
+          class="rmd-nowrap rmd-ellipsis"
+        >
+          Route 2
+        </span>
+      </a>
+    </li>
+  </ul>
+</li>
+`;
+
+exports[`Navigation should be able to render dividers, subheaders, groups, links, and nested items out of the box 1`] = `
+<ul
+  class="rmd-list rmd-nav-group"
+  data-testid="nav"
+  role="none"
+  style="--rmd-tree-depth: 0;"
+>
+  <li
+    class="rmd-nav-item"
+  >
+    <a
+      class="rmd-nav-item__content rmd-nav-item__link rmd-nav-item__link--active rmd-button rmd-button--text rmd-interaction-surface rmd-none rmd-bold"
+      href="/"
+      id=":r0:"
+      type="route"
+    >
+      <span
+        aria-hidden="true"
+        class="rmd-icon rmd-icon--font material-icons"
+      >
+        home
+      </span>
+      <span
+        class="rmd-nowrap rmd-ellipsis"
+      >
+        Home
+      </span>
+    </a>
+  </li>
+  <hr
+    class="rmd-divider"
+    role="separator"
+  />
+  <li
+    class="rmd-list-subheader"
+    role="presentation"
+  >
+    <span
+      class="rmd-list-item__text rmd-nav-item"
+    >
+      Subheader
+    </span>
+  </li>
+  <li
+    class="rmd-nav-item"
+  >
+    <button
+      class="rmd-button rmd-button--text rmd-interaction-surface rmd-nav-item__content"
+      id=":r2:"
+      type="button"
+    >
+      <span
+        class="rmd-nowrap rmd-ellipsis"
+      >
+        Path 1
+      </span>
+      <span
+        aria-hidden="true"
+        class="rmd-icon rmd-icon--font material-icons rmd-icon-rotator rmd-icon-rotator--animate"
+      >
+        arrow_drop_down
+      </span>
+    </button>
+  </li>
+  <li
+    class="rmd-nav-item"
+  >
+    <button
+      class="rmd-button rmd-button--text rmd-interaction-surface rmd-nav-item__content"
+      id=":r4:"
+      type="button"
+    >
+      <span
+        class="rmd-nowrap rmd-ellipsis"
+      >
+        Path 2
+      </span>
+      <span
+        aria-hidden="true"
+        class="rmd-icon rmd-icon--font material-icons rmd-icon-rotator rmd-icon-rotator--animate"
+      >
+        arrow_drop_down
+      </span>
+    </button>
+  </li>
+</ul>
+`;

package/src/navigation/_navigation.scss

@@ -0,0 +1,99 @@
+@use "sass:list";
+@use "sass:map";
+@use "../utils";
+@use "../tree/tree";
+@use "../interaction/interaction";
+
+$disable-everything: false !default;
+$border-radius: 3rem !default;
+$horizontal-padding: 0.25rem !default;
+$padding-incrementor: 0.75rem !default;
+
+$variables: (border-radius, horizontal-padding, padding-incrementor);
+
+@function get-var($name, $fallback: null) {
+  $var: utils.get-var-name($variables, $name, "navigation");
+  @if $fallback {
+    @return var(#{$var}, #{$fallback});
+  }
+
+  @return var(#{$var});
+}
+
+@mixin set-var($name, $value) {
+  @if $value {
+    #{utils.get-var-name($variables, $name, "navigation")}: #{$value};
+  }
+}
+
+@mixin use-var($property, $name: $property, $fallback: null) {
+  #{$property}: get-var($name, $fallback);
+}
+
+@mixin variables {
+  @if not $disable-everything {
+    @include set-var(border-radius, $border-radius);
+    @include set-var(horizontal-padding, $horizontal-padding);
+    @include set-var(padding-incrementor, $padding-incrementor);
+  }
+}
+
+@mixin styles($disable-layer: false) {
+  $increasing-padding: calc(
+    tree.get-var(depth) * get-var(padding-incrementor) +
+      get-var(horizontal-padding)
+  );
+
+  @if not $disable-everything {
+    @include utils.optional-layer(navigation, $disable-layer) {
+      .rmd-nav-group {
+        min-width: 0;
+
+        &--np {
+          padding: 0;
+        }
+      }
+
+      .rmd-nav-item {
+        @include utils.rtl {
+          @include use-var(padding-left, horizontal-padding);
+
+          padding-right: $increasing-padding;
+        }
+        @include use-var(padding-right, horizontal-padding);
+
+        padding-left: $increasing-padding;
+        padding-right: $horizontal-padding;
+
+        // this is applied to both the `NavItemButton` and `NavItemLink`
+        &__content {
+          @include use-var(border-radius);
+
+          font-size: inherit;
+          justify-content: space-between;
+          letter-spacing: inherit;
+          line-height: initial;
+          width: 100%;
+        }
+
+        &__link {
+          justify-content: flex-start;
+
+          &::after {
+            @include utils.pseudo-element;
+            @include interaction.use-var(
+              background-color,
+              selected-background-color
+            );
+
+            opacity: 0;
+          }
+
+          &--active::after {
+            opacity: 1;
+          }
+        }
+      }
+    }
+  }
+}

package/src/navigation/getHrefFromParents.ts

@@ -0,0 +1,15 @@
+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;
+  }, "");
+}

package/src/navigation/navGroupStyles.ts

@@ -0,0 +1,21 @@
+import { cnb } from "cnbuilder";
+import { bem } from "../utils/bem.js";
+
+const styles = bem("rmd-nav-group");
+
+/**
+ * @since 6.0.0
+ */
+export interface NavGroupClassNameOptions {
+  className?: string;
+  disablePadding?: boolean;
+}
+
+/**
+ * @since 6.0.0
+ */
+export function navGroup(options: NavGroupClassNameOptions = {}): string {
+  const { className, disablePadding } = options;
+
+  return cnb(styles({ np: disablePadding }), className);
+}