Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
9.9 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file TopNavItem.tsx
 * @input Uses React, ReactNode, BaseProps, LinkComponentType
 * @output Exports TopNavItem component and TopNavItemProps
 * @position Navigation item component for TopNav startContent
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/TopNav/TopNav.doc.mjs
 * - /packages/core/src/TopNav/TopNav.test.tsx
 * - /packages/core/src/TopNav/index.ts
 * - /apps/storybook/stories/TopNav.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/TopNav/ (showcase blocks)
 */

import type {ReactNode} from 'react';
import type {BaseProps} from '../BaseProps';
import * as stylex from '@stylexjs/stylex';
import {
  colorVars,
  spacingVars,
  radiusVars,
  durationVars,
  easeVars,
  fontWeightVars,
  typeScaleVars,
} from '../theme/tokens.stylex';
import {useLinkComponent} from '../Link/useLinkComponent';
import type {LinkComponentType} from '../Link/types';
import {useTopNavRenderMode} from './TopNavRenderContext';
import {navItemStyles, type NavItemSize} from '../NavItem/navItemStyles.stylex';
import {mergeProps} from '../utils';
import {useCloseMobileDrawerOnActivate} from '../AppShell/useCloseMobileDrawerOnActivate';
import {themeProps} from '../utils/themeProps';
import {focusOutlineProps} from '../utils/focusOutline.stylex';
import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
import {usePressFeedback} from '../hooks/usePressFeedback';
import {
  disabledInteractionProps,
  withholdCallerHandlers,
} from '../utils/disabledInteraction';

/**
 * NavItem styles with hover/selected states
 */
const styles = stylex.create({
  base: {
    display: 'inline-flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-2'],
    paddingBlock: spacingVars['--spacing-1-5'],
    paddingInline: spacingVars['--spacing-3'],
    borderRadius: radiusVars['--radius-element'],
    fontSize: typeScaleVars['--text-label-size'],
    lineHeight: typeScaleVars['--text-label-leading'],
    fontWeight: fontWeightVars['--font-weight-medium'],
    color: colorVars['--color-text-secondary'],
    textDecoration: 'none',
    cursor: {
      default: 'pointer',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    transitionProperty: 'background-color, color',
    transitionDuration: durationVars['--duration-fast'],
    transitionTimingFunction: easeVars['--ease-standard'],
  },
  selected: {
    color: colorVars['--color-text-primary'],
    fontWeight: fontWeightVars['--font-weight-semibold'],
    backgroundColor: {
      default: colorVars['--color-neutral'],
      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
        '@media (hover: hover)': colorVars['--color-neutral'],
      },
      ':active': colorVars['--color-neutral'],
      // The touch press model writes these instead of `:active`; the selected
      // item keeps its fill under a finger the way it does under a mouse, and
      // paints no overlay at any phase of the press.
      '[data-astryx-press="on"]': colorVars['--color-neutral'],
      '[data-astryx-press="fading"]': colorVars['--color-neutral'],
    },
    backgroundImage: {
      default: null,
      '[data-astryx-press="on"]': 'none',
      '[data-astryx-press="fading"]': 'none',
    },
  },
  iconOnly: {
    paddingInline: spacingVars['--spacing-2'],
  },
  // Drawer mode — focus outline (base item + selected come from navItemStyles)
});

export interface TopNavItemProps extends BaseProps<HTMLAnchorElement> {
  /** Ref forwarded to the root element */
  ref?: React.Ref<HTMLAnchorElement>;
  /** Link destination URL. */
  href?: string;
  /** Where to open the linked document. */
  target?: string;
  /** Link relationship. */
  rel?: string;
  /** Causes the browser to download the linked URL. */
  download?: string | boolean;
  /** Referrer policy for the link. */
  referrerPolicy?: React.HTMLAttributeReferrerPolicy;
  /**
   * Custom component to render instead of `<a>`.
   * Overrides the provider-level default set by LinkProvider.
   * Must accept href, className, style, and children props.
   */
  as?: LinkComponentType;
  /**
   * The accessible label for the nav item.
   * Rendered as visible text by default. When `isIconOnly` is true,
   * used as aria-label instead.
   */
  label: string;
  /**
   * Whether this nav item is currently selected/highlighted.
   * @default false
   */
  isSelected?: boolean;
  /**
   * Whether the nav item is disabled.
   * A disabled item renders as an anchor without an href (and without
   * target), so it cannot navigate; it keeps its Tab stop and is exposed as a
   * disabled link.
   * @default false
   */
  isDisabled?: boolean;
  /**
   * Renders the item as a square icon-only element.
   * When true, `label` becomes the aria-label and visible text is hidden.
   * Requires `icon` to be set.
   * @default false
   */
  isIconOnly?: boolean;
  /**
   * Optional icon to display before the label.
   */
  icon?: ReactNode;
  /**
   * Optional content to render instead of the label.
   */
  children?: ReactNode;
  /**
   * Size variant for the nav item. Has no effect in horizontal mode;
   * controls height/padding in drawer mode.
   * @default 'md'
   */
  size?: NavItemSize;
}

/**
 * Click handler for disabled items. The disabled anchor renders without an
 * href, so there is no navigation to block in practice; preventDefault is a
 * defensive guard against synthetic/programmatic clicks.
 */
function preventDefaultClick(event: React.MouseEvent<HTMLAnchorElement>): void {
  event.preventDefault();
}

/**
 * A navigation item for use within TopNav startContent.
 *
 * Renders as an anchor element with hover/selected states.
 * Supports icons and selected state indication with highlighted appearance.
 *
 * @example
 * ```
 * <TopNav
 *   startContent={
 *     <>
 *       <TopNavItem label="Home" href="/" isSelected />
 *       <TopNavItem label="Products" href="/products" />
 *       <TopNavItem label="Settings" href="/settings" icon={<GearIcon />} isIconOnly />
 *     </>
 *   }
 * />
 * ```
 */
export function TopNavItem({
  as,
  href,
  target,
  onClick,
  label,
  isSelected = false,
  isDisabled = false,
  isIconOnly = false,
  icon,
  children,
  size = 'md',
  xstyle,
  className,
  style,
  ref,
  ...props
}: TopNavItemProps) {
  const pressable = usePressFeedback();
  const LinkComponent = useLinkComponent(as);
  const renderMode = useTopNavRenderMode();
  const closeDrawerAfter = useCloseMobileDrawerOnActivate(
    renderMode === 'drawer',
  );

  // A disabled item renders as an <a> with no href. Enter, assistive
  // technology commands and a middle click cannot navigate or run the caller's
  // onClick. The item keeps its Tab stop and the link role, so keyboard and
  // screen-reader users still find it. It does not navigate, so it skips the
  // router LinkComponent, which can require a live href. The target goes with
  // the href.
  const Root = isDisabled ? 'a' : LinkComponent;

  // A disabled item runs no caller handler except `onFocus` and `onBlur`, as a
  // natively disabled control runs none.
  const callerProps = withholdCallerHandlers(props, isDisabled);

  // =========================================================================
  // Drawer mode — render as a SideNavItem-style vertical list element
  // =========================================================================
  if (renderMode === 'drawer') {
    const activate = closeDrawerAfter(onClick);
    const handleDrawerClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
      if (isDisabled) {
        preventDefaultClick(e);
        return;
      }
      activate?.(e);
    };

    return (
      <Root
        ref={ref}
        href={isDisabled ? undefined : href}
        target={isDisabled ? undefined : target}
        aria-label={isIconOnly ? label : undefined}
        aria-current={isSelected ? 'page' : undefined}
        role={isDisabled ? 'link' : undefined}
        aria-disabled={isDisabled || undefined}
        tabIndex={isDisabled ? 0 : undefined}
        {...pressable}
        {...mergeProps(
          themeProps('top-nav-item', {
            mode: 'drawer',
            selected: isSelected ? 'selected' : null,
          }),
          focusOutlineProps.focusVisible(
            navItemStyles.item,
            interactionOverlayStyles.backgroundColor,
            navItemStyles[size],
            isSelected && navItemStyles.selected,
            isDisabled && navItemStyles.disabled,
            xstyle,
          ),
          className,
          style,
        )}
        {...callerProps}
        {...(isDisabled ? disabledInteractionProps() : null)}
        onClick={handleDrawerClick}>
        {icon}
        {!isIconOnly && (children ?? label)}
      </Root>
    );
  }

  // =========================================================================
  // Default / mobile-bar mode — standard horizontal nav item
  // =========================================================================

  return (
    <Root
      ref={ref}
      href={isDisabled ? undefined : href}
      target={isDisabled ? undefined : target}
      onClick={isDisabled ? preventDefaultClick : onClick}
      aria-label={isIconOnly ? label : undefined}
      aria-current={isSelected ? 'page' : undefined}
      role={isDisabled ? 'link' : undefined}
      aria-disabled={isDisabled || undefined}
      tabIndex={isDisabled ? 0 : undefined}
      {...pressable}
      {...mergeProps(
        themeProps('top-nav-item', {
          selected: isSelected ? 'selected' : null,
        }),
        focusOutlineProps.focusVisible(
          styles.base,
          interactionOverlayStyles.backgroundColor,
          isSelected && styles.selected,
          isDisabled && navItemStyles.disabled,
          isIconOnly && styles.iconOnly,
          xstyle,
        ),
        className,
        style,
      )}
      {...callerProps}
      {...(isDisabled ? disabledInteractionProps() : null)}>
      {icon}
      {!isIconOnly && (children ?? label)}
    </Root>
  );
}

TopNavItem.displayName = 'TopNavItem';