Navigation Components

/**
 * Horizontal command bar for primary actions and overflow menus
 */
function CommandBar(props: ICommandBarProps): JSX.Element;

interface ICommandBar {
  /** Focus on the command bar */
  focus(): void;
}

interface ICommandBarProps {
  /** Reference to access component methods */
  componentRef?: IRefObject<ICommandBar>;
  /** Primary command items */
  items: ICommandBarItemProps[];
  /** Items that appear in the overflow menu */
  overflowItems?: ICommandBarItemProps[];
  /** Items that appear on the far side (right in LTR) */
  farItems?: ICommandBarItemProps[];
  /** Properties for the overflow button */
  overflowButtonProps?: IButtonProps;
  /** Aria label for the overflow button ellipsis */
  elippsisAriaLabel?: string;
  /** Aria label for the command bar */
  ariaLabel?: string;
  /** Custom render function for data */
  onDataReduced?: (movedItem: ICommandBarItemProps) => void;
  /** Custom render function for data grown */
  onDataGrown?: (movedItem: ICommandBarItemProps) => void;
  /** Custom render function for overflow button */
  onRenderOverflowButton?: IRenderFunction<IOverflowButtonProps>;
  /** Custom styles */
  styles?: IStyleFunctionOrObject<ICommandBarStyleProps, ICommandBarStyles>;
  /** Theme provided by higher-order component */
  theme?: ITheme;
  /** Additional CSS class */
  className?: string;
  /** Shift focus on reduce */
  shiftOnReduce?: boolean;
}

interface ICommandBarItemProps extends IContextualMenuItem {
  /** Unique cache key for rendering optimization */
  cacheKey?: string;
  /** Whether the item is rendered in overflow menu */
  renderedInOverflow?: boolean;
  /** Whether to show only icon (no text) */
  iconOnly?: boolean;
  /** Custom styles for the button */
  buttonStyles?: Partial<IButtonStyles>;
  /** Custom render function for the item */
  onRender?: (item: ICommandBarItemProps) => React.ReactNode;
  /** Properties for the command bar item */
  commandBarButtonProps?: ICommandBarItemProps;
}

import React from "react";
import { CommandBar, ICommandBarItemProps } from "office-ui-fabric-react";

function BasicCommandBar() {
  const items: ICommandBarItemProps[] = [
    {
      key: "new",
      text: "New",
      iconProps: { iconName: "Add" },
      onClick: () => console.log("New clicked"),
      subMenuProps: {
        items: [
          {
            key: "newDocument",
            text: "Document",
            iconProps: { iconName: "WordDocument" },
            onClick: () => console.log("New document")
          },
          {
            key: "newSpreadsheet",
            text: "Spreadsheet", 
            iconProps: { iconName: "ExcelDocument" },
            onClick: () => console.log("New spreadsheet")
          }
        ]
      }
    },
    {
      key: "upload",
      text: "Upload",
      iconProps: { iconName: "Upload" },
      onClick: () => console.log("Upload clicked")
    },
    {
      key: "share",
      text: "Share",
      iconProps: { iconName: "Share" },
      onClick: () => console.log("Share clicked")
    }
  ];

  const overflowItems: ICommandBarItemProps[] = [
    {
      key: "export",
      text: "Export",
      iconProps: { iconName: "Download" },
      onClick: () => console.log("Export clicked")
    },
    {
      key: "settings",
      text: "Settings",
      iconProps: { iconName: "Settings" },
      onClick: () => console.log("Settings clicked")
    }
  ];

  const farItems: ICommandBarItemProps[] = [
    {
      key: "search",
      text: "Search",
      iconProps: { iconName: "Search" },
      iconOnly: true,
      onClick: () => console.log("Search clicked")
    },
    {
      key: "help",
      text: "Help",
      iconProps: { iconName: "Help" },
      iconOnly: true,
      onClick: () => console.log("Help clicked")
    }
  ];

  return (
    <CommandBar
      items={items}
      overflowItems={overflowItems}
      farItems={farItems}
      ariaLabel="Main actions"
    />
  );
}

/**
 * Vertical navigation component for hierarchical navigation
 */
function Nav(props: INavProps): JSX.Element;

interface INav {
  /** Selected key */
  selectedKey: string | undefined;
}

interface INavProps {
  /** Reference to access component methods */
  componentRef?: IRefObject<INav>;
  /** Navigation link groups */
  groups?: INavLinkGroup[];
  /** Currently selected key */
  selectedKey?: string;
  /** Initially selected key */
  initialSelectedKey?: string;
  /** ARIA label for the navigation */
  ariaLabel?: string;
  /** Whether the navigation is expanded by default */
  isOnTop?: boolean;
  /** Custom render function for group header */
  onRenderGroupHeader?: IRenderFunction<INavLinkGroup>;
  /** Custom render function for link */
  onRenderLink?: IRenderFunction<INavLink>;
  /** Callback fired when link is clicked */
  onLinkClick?: (ev?: React.MouseEvent<HTMLElement>, item?: INavLink) => void;
  /** Callback fired when group is expanded/collapsed */
  onLinkExpandClick?: (ev?: React.MouseEvent<HTMLElement>, item?: INavLink) => void;
  /** Custom styles */
  styles?: IStyleFunctionOrObject<INavStyleProps, INavStyles>;
  /** Theme provided by higher-order component */
  theme?: ITheme;
  /** Additional CSS class */
  className?: string;
}

interface INavLinkGroup {
  /** Name of the group */
  name?: string;
  /** Links in the group */
  links: INavLink[];
  /** Whether the group is collapsed */
  collapseByDefault?: boolean;
  /** Custom render function for the group */
  onRenderGroupHeader?: IRenderFunction<INavLinkGroup>;
}

interface INavLink {
  /** Display name for the link */
  name: string;
  /** URL for the link */
  url?: string;
  /** Unique key for the link */
  key?: string;
  /** Links nested under this link */
  links?: INavLink[];
  /** Icon to display with the link */
  icon?: string;
  /** Whether the link is expanded */
  isExpanded?: boolean;
  /** Whether the link is disabled */
  disabled?: boolean;
  /** Target for the link */
  target?: string;
  /** Title attribute */
  title?: string;
  /** ARIA label */
  ariaLabel?: string;
  /** Whether to force the link to be an anchor */
  forceAnchor?: boolean;
  /** Additional data */
  [propertyName: string]: any;
}

import React, { useState } from "react";
import { Nav, INavLinkGroup, INavLink } from "office-ui-fabric-react";

function BasicNav() {
  const [selectedKey, setSelectedKey] = useState("dashboard");

  const navGroups: INavLinkGroup[] = [
    {
      name: "Main",
      links: [
        {
          name: "Dashboard",
          key: "dashboard",
          url: "/dashboard",
          icon: "ViewDashboard"
        },
        {
          name: "Documents",
          key: "documents",
          url: "/documents",
          icon: "FabricFolder",
          links: [
            {
              name: "Recent",
              key: "recent",
              url: "/documents/recent"
            },
            {
              name: "Shared",
              key: "shared", 
              url: "/documents/shared"
            }
          ]
        },
        {
          name: "People",
          key: "people",
          url: "/people",
          icon: "People"
        }
      ]
    },
    {
      name: "Settings",
      links: [
        {
          name: "Preferences",
          key: "preferences",
          url: "/settings/preferences",
          icon: "Settings"
        },
        {
          name: "Account",
          key: "account",
          url: "/settings/account",
          icon: "Contact"
        }
      ]
    }
  ];

  return (
    <Nav
      groups={navGroups}
      selectedKey={selectedKey}
      onLinkClick={(ev, item) => {
        if (item) {
          setSelectedKey(item.key || "");
          console.log("Navigate to:", item.url);
        }
      }}
      ariaLabel="Main navigation"
    />
  );
}

/**
 * Hierarchical navigation trail component
 */
function Breadcrumb(props: IBreadcrumbProps): JSX.Element;

interface IBreadcrumb {
  /** Focus on the breadcrumb */
  focus(): void;
}

interface IBreadcrumbProps {
  /** Reference to access component methods */
  componentRef?: IRefObject<IBreadcrumb>;
  /** Breadcrumb items to display */
  items: IBreadcrumbItem[];
  /** Custom render function for each item */
  onRenderItem?: IRenderFunction<IBreadcrumbItem>;
  /** Custom render function for overflow button */
  onRenderOverflowIcon?: IRenderFunction<IBreadcrumbProps>;
  /** Divider icon name */
  dividerAs?: React.ComponentType<IBreadcrumbProps>;
  /** Maximum number of items to display */
  maxDisplayedItems?: number;
  /** Aria label for the breadcrumb */
  ariaLabel?: string;
  /** Overflow aria label */
  overflowAriaLabel?: string;
  /** Overflow index */
  overflowIndex?: number;
  /** Custom render function for tooltip */
  onRenderTooltip?: IRenderFunction<IBreadcrumbItem>;
  /** Function to reduce data */
  onReduceData?: (data: IBreadcrumbData) => IBreadcrumbData | undefined;
  /** Function to grow data */
  onGrowData?: (data: IBreadcrumbData) => IBreadcrumbData | undefined;
  /** Custom styles */
  styles?: IStyleFunctionOrObject<IBreadcrumbStyleProps, IBreadcrumbStyles>;
  /** Theme provided by higher-order component */
  theme?: ITheme;
  /** Additional CSS class */
  className?: string;
}

interface IBreadcrumbItem {
  /** Display text for the item */
  text: string;
  /** Unique key for the item */
  key: string;
  /** Click handler for the item */
  onClick?: (ev?: React.MouseEvent<HTMLElement>, item?: IBreadcrumbItem) => void;
  /** Href for the item */
  href?: string;
  /** Whether the item is the current page */
  isCurrentItem?: boolean;
  /** Custom render function for the item */
  onRender?: (item?: IBreadcrumbItem) => React.ReactNode;
}

interface IBreadcrumbData {
  /** Breadcrumb items */
  items: IBreadcrumbItem[];
  /** Maximum displayed items */
  maxDisplayedItems: number;
}

/**
 * Tab-like navigation component for content organization
 */
function Pivot(props: IPivotProps): JSX.Element;

/**
 * Individual pivot section
 */
function PivotItem(props: IPivotItemProps): JSX.Element;

interface IPivot {
  /** Focus on the pivot */
  focus(): void;
}

interface IPivotProps {
  /** Reference to access component methods */
  componentRef?: IRefObject<IPivot>;
  /** Currently selected key */
  selectedKey?: string;
  /** Default selected key for uncontrolled usage */
  defaultSelectedKey?: string;
  /** Display format for pivot links */
  linkFormat?: PivotLinkFormat;
  /** Size of pivot links */
  linkSize?: PivotLinkSize;
  /** Whether to render only headers without content */
  headersOnly?: boolean;
  /** Function to get tab ID */
  getTabId?: (itemKey: string, index: number) => string;
  /** Custom render function for pivot link */
  onRenderLink?: (link?: IPivotItemProps, defaultRenderer?: (link?: IPivotItemProps) => React.ReactNode) => React.ReactNode;
  /** Callback fired when pivot link is clicked */
  onLinkClick?: (item?: PivotItem, ev?: React.MouseEvent<HTMLElement>) => void;
  /** Custom styles */
  styles?: IStyleFunctionOrObject<IPivotStyleProps, IPivotStyles>;
  /** Theme provided by higher-order component */
  theme?: ITheme;
  /** Additional CSS class */
  className?: string;
  /** Child PivotItem elements */
  children?: React.ReactNode;
}

interface IPivotItemProps {
  /** Reference to access component methods */
  componentRef?: IRefObject<IPivotItem>;
  /** Display text for the pivot item */
  headerText?: string;
  /** Button properties for the header */
  headerButtonProps?: IButtonProps | { [key: string]: string | number | boolean };
  /** Unique key identifying the pivot item */
  itemKey?: string;
  /** ARIA label for the pivot item */
  ariaLabel?: string;
  /** Count to display in the header */
  itemCount?: number | string;
  /** Icon to display in the header */
  itemIcon?: string;
  /** Key tips properties */
  keytipProps?: IKeytipProps;
  /** Link format override for this item */
  linkFormat?: PivotLinkFormat;
  /** Custom render function for the header */
  onRenderItemLink?: (props?: IPivotItemProps, defaultRender?: (props?: IPivotItemProps) => React.ReactNode) => React.ReactNode;
  /** Additional CSS class */
  className?: string;
  /** Child content for the pivot item */
  children?: React.ReactNode;
}

enum PivotLinkFormat {
  links = 0,
  tabs = 1
}

enum PivotLinkSize {
  normal = 0,
  large = 1
}

import React, { useState } from "react";
import { Pivot, PivotItem, PivotLinkFormat, PivotLinkSize } from "office-ui-fabric-react";

function BasicPivot() {
  return (
    <Pivot>
      <PivotItem headerText="Overview" itemKey="overview">
        <div>Overview content goes here</div>
      </PivotItem>
      
      <PivotItem headerText="Details" itemKey="details" itemCount={5}>
        <div>Details content with 5 items</div>
      </PivotItem>
      
      <PivotItem headerText="Settings" itemKey="settings" itemIcon="Settings">
        <div>Settings content with icon</div>
      </PivotItem>
    </Pivot>
  );
}

function ControlledPivot() {
  const [selectedKey, setSelectedKey] = useState("tab1");

  return (
    <Pivot
      selectedKey={selectedKey}
      onLinkClick={(item) => {
        if (item?.props.itemKey) {
          setSelectedKey(item.props.itemKey);
        }
      }}
      linkFormat={PivotLinkFormat.tabs}
      linkSize={PivotLinkSize.large}
    >
      <PivotItem headerText="First Tab" itemKey="tab1">
        <div>Content for first tab</div>
      </PivotItem>
      
      <PivotItem headerText="Second Tab" itemKey="tab2">
        <div>Content for second tab</div>
      </PivotItem>
      
      <PivotItem headerText="Third Tab" itemKey="tab3">
        <div>Content for third tab</div>
      </PivotItem>
    </Pivot>
  );
}

// Common navigation interfaces
interface IContextualMenuItem {
  /** Unique key for the item */
  key: string;
  /** Display text */
  text?: string;
  /** Secondary text */
  secondaryText?: string;
  /** Item type (normal, divider, header, section) */
  itemType?: ContextualMenuItemType;
  /** Icon properties */
  iconProps?: IIconProps;
  /** Submenu items */
  subMenuProps?: IContextualMenuProps;
  /** Whether the item is disabled */
  disabled?: boolean;
  /** Whether the item is checked */
  checked?: boolean;
  /** Whether the item can be checked */
  canCheck?: boolean;
  /** Whether the item is split */
  split?: boolean;
  /** Additional data */
  data?: any;
  /** Click handler */
  onClick?: (ev?: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>, item?: IContextualMenuItem) => boolean | void;
  /** Custom render function */
  onRender?: (item: IContextualMenuItem, dismissMenu: (ev?: any, dismissAll?: boolean) => void) => React.ReactNode;
  /** ARIA label */
  ariaLabel?: string;
  /** Title attribute */
  title?: string;
  /** CSS class name */
  className?: string;
  /** Custom styles */
  style?: React.CSSProperties;
  /** HTML role */
  role?: string;
  /** Primary disabled state (for split items) */
  primaryDisabled?: boolean;
  /** Short name */
  shortName?: string;
}

enum ContextualMenuItemType {
  Normal = 0,
  Divider = 1,
  Header = 2,
  Section = 3
}

// Button interfaces for navigation components
interface IButtonProps {
  /** Button text */
  text?: string;
  /** Whether button is primary */
  primary?: boolean;
  /** Whether button is disabled */
  disabled?: boolean;
  /** Click handler */
  onClick?: (event?: React.MouseEvent<HTMLAnchorElement | HTMLButtonElement | HTMLDivElement>) => void;
  /** Icon properties */
  iconProps?: IIconProps;
  /** Menu properties */
  menuProps?: IContextualMenuProps;
  /** Custom styles */
  styles?: IStyleFunctionOrObject<IButtonStyleProps, IButtonStyles>;
  /** Additional CSS class */
  className?: string;
  /** ARIA label */
  ariaLabel?: string;
}

// Render function interface
interface IRenderFunction<TProps> {
  (props?: TProps, defaultRender?: (props?: TProps) => React.ReactNode | null): React.ReactNode | null;
}