Navigation & Routing

/**
 * Provides navigation utilities for CRUD operations
 * @returns Navigation functions for different CRUD actions
 */
function useNavigation(): UseNavigationReturnType;

interface UseNavigationReturnType {
  /** Navigate to resource list page */
  list: (resource: string, type?: HistoryType, meta?: Record<string, unknown>) => void;
  /** Navigate to resource create page */
  create: (resource: string, type?: HistoryType, meta?: Record<string, unknown>) => void;
  /** Navigate to resource edit page */
  edit: (resource: string, id: BaseKey, type?: HistoryType, meta?: Record<string, unknown>) => void;
  /** Navigate to resource show/detail page */
  show: (resource: string, id: BaseKey, type?: HistoryType, meta?: Record<string, unknown>) => void;
  /** Navigate to resource clone page */
  clone: (resource: string, id: BaseKey, type?: HistoryType, meta?: Record<string, unknown>) => void;
  /** Generate URL for resource list page */
  listUrl: (resource: string, meta?: Record<string, unknown>) => string;
  /** Generate URL for resource create page */
  createUrl: (resource: string, meta?: Record<string, unknown>) => string;
  /** Generate URL for resource edit page */
  editUrl: (resource: string, id: BaseKey, meta?: Record<string, unknown>) => string;
  /** Generate URL for resource show/detail page */
  showUrl: (resource: string, id: BaseKey, meta?: Record<string, unknown>) => string;
  /** Generate URL for resource clone page */
  cloneUrl: (resource: string, id: BaseKey, meta?: Record<string, unknown>) => string;
}

type HistoryType = "push" | "replace";

import { useNavigation } from "@refinedev/core";

function PostActions({ postId }: { postId: string }) {
  const navigation = useNavigation();
  
  const handleEdit = () => {
    // Navigate to edit page
    navigation.edit("posts", postId);
  };
  
  const handleView = () => {
    // Navigate to show page
    navigation.show("posts", postId);
  };
  
  const handleCreateNew = () => {
    // Navigate to create page
    navigation.create("posts");
  };
  
  const handleClone = () => {
    // Navigate to clone page (create with pre-filled data)
    navigation.clone("posts", postId);
  };
  
  // Generate URLs for links
  const editUrl = navigation.editUrl("posts", postId);
  const showUrl = navigation.showUrl("posts", postId);
  
  return (
    <div>
      <button onClick={handleEdit}>Edit</button>
      <button onClick={handleView}>View</button>
      <button onClick={handleCreateNew}>Create New</button>
      <button onClick={handleClone}>Clone</button>
      
      <a href={editUrl}>Edit Link</a>
      <a href={showUrl}>View Link</a>
    </div>
  );
}

/**
 * Provides programmatic navigation with full control
 * @returns Go function for flexible navigation
 */
function useGo(): Go;

interface Go {
  (options: GoConfig): void;
}

interface GoConfig {
  /** Target URL or route to navigate to */
  to: string;
  /** Navigation type - push adds to history, replace replaces current */
  type?: "push" | "replace";
  /** Query parameters to include in URL */
  query?: Record<string, any>;
  /** Navigation options */
  options?: {
    /** Whether to keep existing query parameters */
    keepQuery?: boolean;
    /** Whether to keep existing URL hash */
    keepHash?: boolean;
  };
}

import { useGo } from "@refinedev/core";

function NavigationComponent() {
  const go = useGo();
  
  const handleNavigateToPost = (postId: string) => {
    go({
      to: `/posts/${postId}`,
      type: "push",
      query: {
        tab: "comments",
        sort: "newest"
      },
      options: {
        keepQuery: false,
        keepHash: true
      }
    });
  };
  
  const handleReplaceRoute = () => {
    go({
      to: "/dashboard",
      type: "replace", // Replace current route in history
      query: {
        view: "grid"
      }
    });
  };
  
  return (
    <div>
      <button onClick={() => handleNavigateToPost("123")}>
        View Post with Comments
      </button>
      <button onClick={handleReplaceRoute}>
        Go to Dashboard
      </button>
    </div>
  );
}

/**
 * Navigate back in history with fallback
 * @returns Back function for history navigation
 */
function useBack(): Back;

interface Back {
  (): void;
}

import { useBack } from "@refinedev/core";

function BackButton() {
  const back = useBack();
  
  return (
    <button onClick={back}>
      ← Go Back
    </button>
  );
}

/**
 * Gets parsed route information
 * @returns Parsed route parameters and resource information
 */
function useParsed(): ParsedParams;

interface ParsedParams {
  /** Current pathname */
  pathname: string;
  /** Extracted route parameters */
  params: Record<string, string | string[]>;
  /** Identified resource from route */
  resource?: IResourceItem;
  /** Current action (list, create, edit, show, clone) */
  action?: Action;
  /** Record ID if present in route */
  id?: BaseKey;
}

interface IResourceItem {
  /** Resource name */
  name: string;
  /** Display label */
  label?: string;
  /** Resource icon */
  icon?: React.ReactNode;
  /** Route definitions */
  route?: string;
  /** Whether resource can be deleted */
  canDelete?: boolean;
  /** Parent resource name */
  parentName?: string;
  /** Resource metadata */
  meta?: Record<string, any>;
}

type Action = "list" | "create" | "edit" | "show" | "clone";

import { useParsed } from "@refinedev/core";

function RouteInfo() {
  const { pathname, params, resource, action, id } = useParsed();
  
  return (
    <div>
      <p>Current Path: {pathname}</p>
      <p>Resource: {resource?.name}</p>
      <p>Action: {action}</p>
      <p>ID: {id}</p>
      <p>Params: {JSON.stringify(params)}</p>
    </div>
  );
}

// Usage in a breadcrumb component
function Breadcrumb() {
  const { resource, action, id } = useParsed();
  
  const breadcrumbItems = [
    { label: "Home", url: "/" },
    { label: resource?.label || resource?.name, url: `/${resource?.name}` }
  ];
  
  if (action === "edit" && id) {
    breadcrumbItems.push({
      label: `Edit ${id}`,
      url: `/${resource?.name}/edit/${id}`
    });
  } else if (action === "create") {
    breadcrumbItems.push({
      label: "Create",
      url: `/${resource?.name}/create`
    });
  }
  
  return (
    <nav>
      {breadcrumbItems.map((item, index) => (
        <span key={index}>
          <a href={item.url}>{item.label}</a>
          {index < breadcrumbItems.length - 1 && " > "}
        </span>
      ))}
    </nav>
  );
}

/**
 * Creates router-aware links
 * @param params - Link configuration
 * @returns Link component with router integration
 */
function useLink(): LinkComponent;

interface LinkComponent {
  (props: LinkProps): JSX.Element;
}

interface LinkProps {
  /** Destination URL */
  to: string;
  /** Link content */
  children: React.ReactNode;
  /** Whether to replace current history entry */
  replace?: boolean;
  /** Additional HTML attributes */
  [key: string]: any;
}

/**
 * Router provider interface for navigation integration
 */
interface RouterProvider {
  /** Navigate to a route */
  go: () => Go;
  /** Navigate back in history */
  back: () => Back;
  /** Parse current route */
  parse: () => ParsedParams;
  /** Create a Link component */
  Link: LinkComponent;
}

/**
 * Generates menu items from resources
 * @param params - Menu configuration
 * @returns Menu items and selection state
 */
function useMenu(params?: UseMenuConfig): UseMenuReturnType;

interface UseMenuConfig {
  /** Hide items that require missing parameters */
  hideOnMissingParameter?: boolean;
  /** Additional metadata for menu generation */
  meta?: Record<string, unknown>;
}

interface UseMenuReturnType {
  /** Generated menu items */
  menuItems: MenuItem[];
  /** Currently selected menu item key */
  selectedKey: string | undefined;
}

interface MenuItem {
  /** Menu item key */
  key: string;
  /** Display name */
  name: string;
  /** Display label */
  label?: string;
  /** Menu icon */
  icon?: React.ReactNode;
  /** Navigation URL */
  url?: string;
  /** Navigation route */
  route?: string;
  /** Parent menu item */
  parentName?: string;
  /** Child menu items */
  children?: MenuItem[];
  /** Additional metadata */
  meta?: Record<string, any>;
}

import { useMenu } from "@refinedev/core";

function NavigationMenu() {
  const { menuItems, selectedKey } = useMenu();
  
  const renderMenuItem = (item: MenuItem) => (
    <li key={item.key} className={selectedKey === item.key ? "active" : ""}>
      <a href={item.route}>
        {item.icon}
        <span>{item.label || item.name}</span>
      </a>
      {item.children && (
        <ul>
          {item.children.map(renderMenuItem)}
        </ul>
      )}
    </li>
  );
  
  return (
    <nav>
      <ul>
        {menuItems.map(renderMenuItem)}
      </ul>
    </nav>
  );
}

/**
 * Generates breadcrumb navigation
 * @returns Breadcrumb items for current route
 */
function useBreadcrumb(): UseBreadcrumbReturnType;

interface UseBreadcrumbReturnType {
  /** Breadcrumb items */
  breadcrumbs: BreadcrumbItem[];
}

interface BreadcrumbItem {
  /** Breadcrumb label */
  label: string;
  /** Navigation URL */
  href?: string;
  /** Menu icon */
  icon?: React.ReactNode;
}

import { useBreadcrumb } from "@refinedev/core";

function BreadcrumbNavigation() {
  const { breadcrumbs } = useBreadcrumb();
  
  return (
    <nav aria-label="Breadcrumb">
      <ol>
        {breadcrumbs.map((crumb, index) => (
          <li key={index}>
            {crumb.href ? (
              <a href={crumb.href}>
                {crumb.icon}
                {crumb.label}
              </a>
            ) : (
              <span>
                {crumb.icon}
                {crumb.label}
              </span>
            )}
            {index < breadcrumbs.length - 1 && <span> / </span>}
          </li>
        ))}
      </ol>
    </nav>
  );
}

/**
 * Navigation utilities for nested resources
 */
interface NestedResourceNavigation {
  /** Navigate to nested resource list */
  listNested: (parentResource: string, parentId: BaseKey, childResource: string) => void;
  /** Navigate to nested resource create */
  createNested: (parentResource: string, parentId: BaseKey, childResource: string) => void;
  /** Generate nested resource URLs */
  nestedUrl: (parentResource: string, parentId: BaseKey, childResource: string, action?: Action, childId?: BaseKey) => string;
}

// Navigate to comments for a specific post
const handleViewComments = (postId: string) => {
  navigation.listNested("posts", postId, "comments");
  // Results in: /posts/123/comments
};

// Create new comment for a post
const handleCreateComment = (postId: string) => {
  navigation.createNested("posts", postId, "comments");
  // Results in: /posts/123/comments/create
};

interface RouteParams {
  /** Resource name from route */
  resource?: string;
  /** Action from route */
  action?: string;
  /** Record ID from route */
  id?: BaseKey;
  /** Additional route parameters */
  [key: string]: string | number | undefined;
}

interface NavigationContext {
  /** Current route information */
  current: ParsedParams;
  /** Navigation history */
  history: string[];
  /** Whether navigation is in progress */
  isNavigating: boolean;
}

interface RedirectConfig {
  /** Target route for redirect */
  to: string;
  /** Redirect type */
  type?: "push" | "replace";
  /** Query parameters for redirect */
  query?: Record<string, any>;
}