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

package/src/movement/types.ts

@@ -26,7 +26,7 @@ import type {
  * - the container element specifies an `aria-activedescendant` pointing to one
  *   of the ids for the child "focusable" elements
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type TabIndexBehavior = "roving" | "virtual";
 
@@ -52,7 +52,7 @@ export type GetFocusableElements = (
 ) => readonly HTMLElement[];
 
 /**
- * @remarks \@since 5.0.0
+ * @since 5.0.0
  */
 export interface KeyboardMovementConfiguration {
   /**
@@ -88,12 +88,12 @@ export interface KeyboardMovementConfiguration {
  * The defined {@link KeyboardMovementConfiguration} that should be used for
  * custom keyboard focus behavior.
  *
- * @remarks \@since 5.0.0
+ * @since 5.0.0
  */
 export type KeyboardMovementConfig = Required<KeyboardMovementConfiguration>;
 
 /**
- * @remarks \@since 5.0.0
+ * @since 5.0.0
  */
 export interface KeyboardMovementBehavior {
   /**
@@ -129,16 +129,15 @@ export interface KeyboardMovementBehavior {
    * updates the default keyboard config to use `ArrowRight` and `ArrowLeft`
    * instead of `ArrowDown` and `ArrowUp`,
    *
-   * @remarks \@since 5.1.2
+   * @since 5.1.2
    * @defaultValue `false`
    */
   horizontal?: boolean;
 }
 
 /**
- * @remarks
- * \@since 5.0.0
- * \@since 6.0.0 Removed `attach`, `detach` and `watching`
+ * @since 5.0.0
+ * @since 6.0.0 Removed `attach`, `detach` and `watching`
  * @internal
  */
 export interface KeyboardMovementContext
@@ -157,7 +156,7 @@ export interface KeyboardMovementContext
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export interface FocusableIndexOptions {
@@ -166,13 +165,13 @@ export interface FocusableIndexOptions {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export type GetDefaultFocusedIndex = (options: FocusableIndexOptions) => number;
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export type ExtendKeyDown<E extends HTMLElement> = (
@@ -180,7 +179,7 @@ export type ExtendKeyDown<E extends HTMLElement> = (
 ) => void;
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export interface KeyboardMovementFocusChangeEvent {
@@ -189,7 +188,7 @@ export interface KeyboardMovementFocusChangeEvent {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export type KeyboardMovementFocusChangeEventHandler = (
@@ -197,7 +196,7 @@ export type KeyboardMovementFocusChangeEventHandler = (
 ) => void;
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export interface KeyboardMovementExtensionData<E extends HTMLElement>
@@ -209,7 +208,7 @@ export interface KeyboardMovementExtensionData<E extends HTMLElement>
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export interface KeyboardMovementProviderOptions<E extends HTMLElement>
@@ -265,7 +264,7 @@ export interface KeyboardMovementProviderOptions<E extends HTMLElement>
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export interface KeyboardMovementProps<E extends HTMLElement> {
@@ -291,7 +290,7 @@ export interface KeyboardMovementProps<E extends HTMLElement> {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export interface KeyboardMovementProviderImplementation<E extends HTMLElement> {

package/src/movement/useKeyboardMovementProvider.ts

@@ -37,7 +37,7 @@ import {
 } from "./utils.js";
 
 /**
- * @remarks \@since 5.0.0
+ * @since 5.0.0
  * @internal
  */
 const context = createContext<KeyboardMovementContext>({
@@ -53,7 +53,7 @@ context.displayName = "KeyboardMovement";
 export const { Provider: KeyboardMovementProvider } = context;
 
 /**
- * @remarks \@since 5.0.0
+ * @since 5.0.0
  * @internal
  */
 export function useKeyboardMovementContext(): Readonly<KeyboardMovementContext> {
@@ -70,8 +70,7 @@ const returnNegative1 = (): number => -1;
  * Implements the custom keyboard movement behavior throughout react-md. Using
  * the "Find References" will be the best way to see example usage.
  *
- * @example
- * Default Keyboard Movement for any Focusable Element
+ * @example Default Keyboard Movement for any Focusable Element
  * ```tsx
  * import {
  *   KeyboardMovementProvider,
@@ -94,8 +93,7 @@ const returnNegative1 = (): number => -1;
  * }
  * ```
  *
- * @example
- * Active Descendant Movement
+ * @example Active Descendant Movement
  * ```tsx
  * import {
  *   KeyboardMovementProvider,
@@ -141,8 +139,7 @@ const returnNegative1 = (): number => -1;
  * }
  * ```
  *
- * @example
- * Roving Tab Index
+ * @example Roving Tab Index
  * ```tsx
  * import {
  *   KeyboardMovementProvider,
@@ -187,7 +184,7 @@ const returnNegative1 = (): number => -1;
  *   );
  * }
  * ```
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export function useKeyboardMovementProvider<E extends HTMLElement>(

package/src/movement/utils.ts

@@ -3,7 +3,7 @@ import { loop } from "../utils/loop.js";
 import { type FocusableIndexOptions, type TabIndexBehavior } from "./types.js";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export const isElementDisabled = (element: HTMLElement): boolean =>
@@ -11,7 +11,7 @@ export const isElementDisabled = (element: HTMLElement): boolean =>
   element.getAttribute("aria-disabled") === "true";
 
 /**
- * @remarks \@since 5.0.0
+ * @since 5.0.0
  * @internal
  */
 export const isNotFocusable = (
@@ -30,7 +30,7 @@ export const isNotFocusable = (
 };
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export interface VirtualFocusableIndexOptions {
@@ -40,7 +40,7 @@ export interface VirtualFocusableIndexOptions {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export const getVirtualFocusDefaultIndex = (
@@ -62,7 +62,7 @@ export const getVirtualFocusDefaultIndex = (
 };
 
 /**
- * @remarks \@since 5.0.0
+ * @since 5.0.0
  * @internal
  */
 export const getFirstFocusableIndex = (
@@ -90,7 +90,7 @@ export const getFirstFocusableIndex = (
 };
 
 /**
- * @remarks \@since 5.0.0
+ * @since 5.0.0
  * @internal
  */
 export const getLastFocusableIndex = (
@@ -118,7 +118,7 @@ export const getLastFocusableIndex = (
 };
 
 /**
- * @remarks \@since 5.0.0
+ * @since 5.0.0
  * @internal
  */
 interface NextFocusableIndexOptions extends FocusableIndexOptions {
@@ -128,7 +128,7 @@ interface NextFocusableIndexOptions extends FocusableIndexOptions {
 }
 
 /**
- * @remarks \@since 5.0.0
+ * @since 5.0.0
  * @internal
  */
 export const getNextFocusableIndex = (
@@ -173,7 +173,7 @@ export const getNextFocusableIndex = (
 };
 
 /**
- * @remarks \@since 5.0.0
+ * @since 5.0.0
  * @internal
  */
 export function getSearchText(
@@ -202,7 +202,7 @@ export function getSearchText(
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export interface RecalculateOptions {
@@ -217,7 +217,7 @@ export interface RecalculateOptions {
  * between renders (i.e. expanding all tree items on the same level with `*`).
  * There might be a better way to handle this in the future.
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export function recalculateFocusIndex(options: RecalculateOptions): number {
@@ -245,7 +245,7 @@ export function recalculateFocusIndex(options: RecalculateOptions): number {
  * The shift key **is allowed** because holding shift means "search from the
  * beginning" instead of "search from current location".
  *
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export function isSearchableEvent(event: KeyboardEvent): boolean {
@@ -262,7 +262,7 @@ export function isSearchableEvent(event: KeyboardEvent): boolean {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export function isTypeEvent(event: KeyboardEvent): boolean {

package/src/navigation/CollapsibleNavGroup.tsx

@@ -0,0 +1,94 @@
+"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 { NavGroup, type NavGroupProps } from "./NavGroup.js";
+import { NavItem } from "./NavItem.js";
+import {
+  NavItemButton,
+  type NavItemButtonRotatorProps,
+} from "./NavItemButton.js";
+
+const noop = (): void => {
+  // do nothing
+};
+
+/**
+ * @since 6.0.0
+ */
+export interface CollapsibleNavGroupProps
+  extends NavGroupProps,
+    NavItemButtonRotatorProps {
+  liProps?: PropsWithRef<LiHTMLAttributes<HTMLLIElement>, HTMLLIElement>;
+  buttonProps?: PropsWithRef<ButtonProps, HTMLButtonElement>;
+
+  /**
+   * The children to render in the {@link NavItemButton} that toggles the
+   * collapsed state
+   */
+  buttonChildren: ReactNode;
+
+  /**
+   * The content that should be rendered in the non-collapsed {@link NavGroup}.
+   */
+  children: ReactNode;
+
+  /** @defaultValue `false` */
+  defaultCollapsed?: UseStateInitializer<boolean>;
+}
+
+/**
+ * **Client Component**
+ *
+ * @since 6.0.0
+ */
+export const CollapsibleNavGroup = forwardRef<
+  HTMLUListElement,
+  CollapsibleNavGroupProps
+>(function CollapsibleNavGroup(props, ref) {
+  const {
+    liProps,
+    buttonProps,
+    buttonChildren,
+    icon,
+    iconRotatorProps,
+    disableIconRotator,
+    className,
+    children,
+    defaultCollapsed,
+    ...remaining
+  } = props;
+
+  const { toggled: collapsed, toggle } = useToggle(defaultCollapsed);
+  const { rendered, elementProps } = useCollapseTransition({
+    nodeRef: ref,
+    className,
+    transitionIn: !collapsed,
+  });
+  const onButtonClick = buttonProps?.onClick ?? noop;
+
+  return (
+    <NavItem {...liProps}>
+      <NavItemButton
+        {...buttonProps}
+        onClick={(event) => {
+          onButtonClick(event);
+          toggle();
+        }}
+        collapsed={collapsed}
+        icon={icon}
+        iconRotatorProps={iconRotatorProps}
+        disableIconRotator={disableIconRotator}
+      >
+        {buttonChildren}
+      </NavItemButton>
+      {rendered && (
+        <NavGroup {...remaining} {...elementProps}>
+          {children}
+        </NavGroup>
+      )}
+    </NavItem>
+  );
+});

package/src/navigation/DefaultNavigationRenderer.tsx

@@ -0,0 +1,71 @@
+import { type ReactElement } from "react";
+import { Divider } from "../divider/Divider.js";
+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";
+
+/**
+ * @since 6.0.0
+ */
+export interface DefaultNavigationRendererProps<
+  Item extends NavigationItem = NavigationItem,
+  Data extends NavigationRenderData = NavigationRenderData,
+> extends RenderRecursiveItemsProps<Item, Data> {}
+
+/**
+ * **Client Component**
+ *
+ * The default behavior is attempt to render in order:
+ * - `const { type, items, ...props } = item`
+ * - `type === "divider"` - `<Divider {...props} />`
+ * - `type === "subheader"` - `<NavSubheader {...props} />`
+ * - `type === "group"` - `<><NavSubheader {...props} />{children}</>`
+ * - `!!items` - `<CollapsibleNavGroup />`
+ * - `<NavItemLink {...item} as={linkComponent} active={pathname === href} />`
+ *
+ * @since 6.0.0
+ */
+export function DefaultNavigationRenderer<
+  Item extends NavigationItem,
+  Data extends NavigationRenderData,
+>(props: DefaultNavigationRendererProps<Item, Data>): ReactElement {
+  const { item, data, children, parents } = props;
+  switch (item.type) {
+    case "divider": {
+      const { type: _type, items: _items, ...divider } = item;
+      return <Divider {...divider} />;
+    }
+    case "subheader": {
+      const { type: _type, items: _items, ...subheader } = item;
+      return <NavSubheader {...subheader} />;
+    }
+  }
+
+  if (item.items) {
+    const nextParents = [item, ...parents];
+    return (
+      <CollapsibleNavGroup
+        depth={nextParents.length}
+        defaultCollapsed={() =>
+          !data?.pathname.includes(getHrefFromParents(nextParents))
+        }
+        buttonChildren={item.children}
+      >
+        {children}
+      </CollapsibleNavGroup>
+    );
+  }
+
+  const href = `${getHrefFromParents(parents)}${item.href}`;
+  return (
+    <NavItemLink
+      {...item}
+      as={data?.linkComponent}
+      active={("active" in item && !!item.active) || data?.pathname === href}
+      href={href}
+    />
+  );
+}

package/src/navigation/NavGroup.tsx

@@ -0,0 +1,39 @@
+import { forwardRef, type ReactNode } from "react";
+import { List, type ListProps } from "../list/List.js";
+import { navGroup } from "./navGroupStyles.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface NavGroupProps extends ListProps {
+  depth: number;
+  children: ReactNode;
+}
+
+/**
+ * **Server Component**
+ *
+ * A simple wrapper around the {@link Link} component that ads the
+ * `--rmd-tree-depth: depth` custom property to allow for incremented padding.
+ *
+ * @since 6.0.0
+ */
+export const NavGroup = forwardRef<HTMLUListElement, NavGroupProps>(
+  function NavGroup(props, ref) {
+    const { style, depth, className, children, ...remaining } = props;
+
+    return (
+      <List
+        {...remaining}
+        ref={ref}
+        style={{ ...style, "--rmd-tree-depth": depth }}
+        className={navGroup({
+          className,
+          disablePadding: depth > 0,
+        })}
+      >
+        {children}
+      </List>
+    );
+  }
+);

package/src/navigation/NavItem.tsx

@@ -0,0 +1,29 @@
+import { forwardRef, type LiHTMLAttributes, type ReactNode } from "react";
+import { navItem } from "./navItemStyles.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface NavItemProps extends LiHTMLAttributes<HTMLLIElement> {
+  children: ReactNode;
+}
+
+/**
+ * **Server Component**
+ *
+ * This component is just used to add padding based on the depth of the nav item
+ * and should not be used on its own. See the `CollapsibleNavGroup` and
+ * `NavItemLink` instead.
+ *
+ * @since 6.0.0
+ */
+export const NavItem = forwardRef<HTMLLIElement, NavItemProps>(
+  function NavItem(props, ref) {
+    const { className, children, ...remaining } = props;
+    return (
+      <li {...remaining} ref={ref} className={navItem({ className })}>
+        {children}
+      </li>
+    );
+  }
+);

package/src/navigation/NavItemButton.tsx

@@ -0,0 +1,104 @@
+"use client";
+import { forwardRef, type MouseEventHandler, type ReactNode } from "react";
+import { Button, type ButtonProps } from "../button/Button.js";
+import { cssUtils } from "../cssUtils.js";
+import { IconRotator, type IconRotatorBaseProps } from "../icon/IconRotator.js";
+import { getIcon } from "../icon/iconConfig.js";
+import { Tooltip } from "../tooltip/Tooltip.js";
+import { useTooltip } from "../tooltip/useTooltip.js";
+import { navItemContent } from "./navItemStyles.js";
+import { type NavItemContentProps } from "./types.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface NavItemButtonRotatorProps {
+  /** @defaultValue `getIcon("dropdown")` */
+  icon?: ReactNode;
+  iconRotatorProps?: IconRotatorBaseProps;
+  disableIconRotator?: boolean;
+}
+
+/**
+ * @since 6.0.0
+ */
+export interface NavItemButtonProps
+  extends Omit<ButtonProps, "children">,
+    NavItemButtonRotatorProps,
+    NavItemContentProps {
+  onClick: MouseEventHandler<HTMLButtonElement>;
+  collapsed: boolean;
+}
+
+/**
+ * **Client Component**
+ *
+ * @since 6.0.0
+ */
+export const NavItemButton = forwardRef<HTMLButtonElement, NavItemButtonProps>(
+  function NavItemButton(props, ref) {
+    const {
+      className,
+      collapsed,
+      icon,
+      iconRotatorProps,
+      disableIconRotator,
+      children,
+      beforeAddon,
+      afterAddon,
+      spanProps,
+      onBlur,
+      onContextMenu,
+      onFocus,
+      onMouseEnter,
+      onMouseLeave,
+      onTouchEnd,
+      onTouchStart,
+      tooltipOptions,
+      ...remaining
+    } = props;
+
+    const { elementProps, tooltipProps, overflowRef } = useTooltip({
+      overflowOnly: true,
+      defaultPosition: "right",
+      ...tooltipOptions,
+      onBlur,
+      onContextMenu,
+      onFocus,
+      onMouseEnter,
+      onMouseLeave,
+      onTouchEnd,
+      onTouchStart,
+    });
+
+    return (
+      <>
+        <Button
+          {...remaining}
+          {...elementProps}
+          ref={ref}
+          className={navItemContent({ className })}
+        >
+          {beforeAddon}
+          <span
+            {...spanProps}
+            ref={overflowRef}
+            className={cssUtils({
+              className: spanProps?.className,
+              textOverflow: "ellipsis",
+            })}
+          >
+            {children}
+          </span>
+          {afterAddon}
+          {!disableIconRotator && (
+            <IconRotator {...iconRotatorProps} rotated={!collapsed}>
+              {getIcon("dropdown", icon)}
+            </IconRotator>
+          )}
+        </Button>
+        <Tooltip {...tooltipProps}>{children}</Tooltip>
+      </>
+    );
+  }
+);