State Navigation

/**
 * State navigation and querying service
 */
interface StateService {
  /** Navigate to a state */
  go(to: StateOrName, params?: RawParams, options?: TransitionOptions): Promise<StateDeclaration>;
  /** Reload current or specified state */
  reload(reloadState?: StateOrName): Promise<StateDeclaration>;
  /** Get state definition(s) */
  get(stateOrName?: StateOrName): StateDeclaration | StateDeclaration[];
  /** Check if current state includes another state */
  includes(stateOrName: StateOrName, params?: RawParams, options?: { relative?: StateOrName }): boolean;
  /** Check if current state exactly matches another state */
  is(stateOrName: StateOrName, params?: RawParams, options?: { relative?: StateOrName }): boolean;
  /** Generate URL for a state */
  href(stateOrName: StateOrName, params?: RawParams, options?: HrefOptions): string;
  /** Create TargetState object */
  target(stateOrName: StateOrName, params?: RawParams, options?: TransitionOptions): TargetState;
  /** Current state object */
  current: StateDeclaration;
  /** Current state parameters */
  params: StateParams;
  /** Transition currently in progress */
  transition: Transition;
}

angular.module('myApp').controller('NavigationController', 
  ['$state', '$stateParams', function($state, $stateParams) {
    
    // Navigate to state
    $state.go('users.detail', { userId: 123 });
    
    // Navigate with options
    $state.go('home', {}, { reload: true, notify: false });
    
    // Navigate with promise handling
    $state.go('dashboard').then(function(state) {
      console.log('Navigated to:', state.name);
    }).catch(function(error) {
      console.error('Navigation failed:', error);
    });
    
    // Check current state
    if ($state.is('users.detail')) {
      console.log('Currently viewing user detail');
    }
    
    // Check state inclusion
    if ($state.includes('users')) {
      console.log('Currently in users section');
    }
    
    // Get URL for state
    const userDetailUrl = $state.href('users.detail', { userId: 456 });
    
    // Reload current state
    $state.reload();
    
    // Reload specific state
    $state.reload('users');
  }]);

/**
 * Navigate to a state
 * @param to - Target state name or state object
 * @param params - State parameters object
 * @param options - Transition options
 * @returns Promise resolving to target state declaration
 */
go(to: StateOrName, params?: RawParams, options?: TransitionOptions): Promise<StateDeclaration>;

interface TransitionOptions {
  /** Relative state context for state resolution */
  relative?: StateOrName;
  /** Inherit parameters from current state */
  inherit?: boolean;
  /** Notify $urlRouter of URL changes */
  notify?: boolean;
  /** Force reload of states */
  reload?: boolean | string;
  /** Custom transition data */
  custom?: { [key: string]: any };
}

// Basic navigation
$state.go('home');

// Navigation with parameters
$state.go('users.detail', { userId: 123, tab: 'profile' });

// Navigation with relative state resolution
$state.go('.child', { id: 456 }, { relative: 'parent.state' });

// Navigation with parameter inheritance
$state.go('users.edit', {}, { inherit: true });

// Silent navigation (no URL update)
$state.go('modal', {}, { notify: false });

// Force reload during navigation
$state.go('dashboard', {}, { reload: true });

// Reload specific state and descendants
$state.go('users.list', {}, { reload: 'users' });

/**
 * Reload current or specified state and its children
 * @param reloadState - State to reload (defaults to current state)
 * @returns Promise resolving to reloaded state declaration
 */
reload(reloadState?: StateOrName): Promise<StateDeclaration>;

// Reload current state
$state.reload();

// Reload specific state
$state.reload('users');

// Reload with promise handling
$state.reload().then(function(state) {
  console.log('Reloaded state:', state.name);
});

/**
 * Get state definition(s)
 * @param stateOrName - Specific state name/object, or undefined for all states
 * @returns Single state declaration or array of all states
 */
get(stateOrName?: StateOrName): StateDeclaration | StateDeclaration[];

// Get all registered states
const allStates = $state.get();

// Get specific state
const homeState = $state.get('home');

// Check if state exists
const userState = $state.get('users.detail');
if (userState) {
  console.log('State exists:', userState.url);
}

/**
 * Check if current state exactly matches specified state
 * @param stateOrName - State to compare against
 * @param params - Parameters to compare
 * @param options - Comparison options
 * @returns True if current state exactly matches
 */
is(stateOrName: StateOrName, params?: RawParams, options?: { relative?: StateOrName }): boolean;

// Check exact state match
if ($state.is('users.detail')) {
  console.log('Viewing user detail page');
}

// Check state with parameters
if ($state.is('users.detail', { userId: '123' })) {
  console.log('Viewing user 123');
}

// Relative state checking
if ($state.is('child', {}, { relative: 'parent' })) {
  console.log('In parent.child state');
}

/**
 * Check if current state includes specified state
 * @param stateOrName - State to check inclusion for
 * @param params - Parameters to compare
 * @param options - Comparison options
 * @returns True if current state includes specified state
 */
includes(stateOrName: StateOrName, params?: RawParams, options?: { relative?: StateOrName }): boolean;

// Check state inclusion (useful for nested states)
if ($state.includes('users')) {
  console.log('Currently in users section');
}

// Check inclusion with parameters
if ($state.includes('users.detail', { userId: '123' })) {
  console.log('Viewing details for user 123');
}

// Menu highlighting based on state inclusion
$scope.isActiveSection = function(section) {
  return $state.includes(section);
};

/**
 * Generate URL for a state
 * @param stateOrName - Target state
 * @param params - State parameters  
 * @param options - URL generation options
 * @returns Generated URL string
 */
href(stateOrName: StateOrName, params?: RawParams, options?: HrefOptions): string;

interface HrefOptions {
  /** Relative state context */
  relative?: StateOrName;
  /** Lossy parameter matching */
  lossy?: boolean;
  /** Inherit parameters from current state */
  inherit?: boolean;
  /** Generate absolute URL */
  absolute?: boolean;
}

// Generate basic URL
const homeUrl = $state.href('home');

// Generate URL with parameters
const userUrl = $state.href('users.detail', { userId: 123 });

// Generate absolute URL
const absoluteUrl = $state.href('home', {}, { absolute: true });

// Generate URL with parameter inheritance
const inheritUrl = $state.href('users.edit', {}, { inherit: true });

// Use in templates for links
$scope.getUserUrl = function(userId) {
  return $state.href('users.detail', { userId: userId });
};

/**
 * Current state properties
 */
interface StateService {
  /** Currently active state declaration */
  current: StateDeclaration;
  /** Current state parameters */
  params: StateParams;
  /** Currently running transition (null if none) */
  transition: Transition | null;
}

type StateParams = { [key: string]: any };

angular.module('myApp').controller('AppController', 
  ['$scope', '$state', function($scope, $state) {
    
    // Watch current state changes
    $scope.$watch(function() {
      return $state.current.name;
    }, function(newState, oldState) {
      console.log('State changed from', oldState, 'to', newState);
    });
    
    // Access current parameters
    console.log('Current user ID:', $state.params.userId);
    
    // Check for active transition
    if ($state.transition) {
      console.log('Transition in progress:', $state.transition.to().name);
    }
    
    // Use current state in templates
    $scope.currentStateName = $state.current.name;
    $scope.currentParams = $state.params;
  }]);

/**
 * Create TargetState object
 * @param stateOrName - Target state
 * @param params - State parameters
 * @param options - Target state options
 * @returns TargetState object for transition use
 */
target(stateOrName: StateOrName, params?: RawParams, options?: TransitionOptions): TargetState;

// Create target state for custom transition handling
const targetState = $state.target('users.detail', { userId: 123 });

// Use in transition hooks
$transitions.onBefore({}, function(transition) {
  const target = $state.target('login');
  if (!isAuthenticated() && transition.to().data.requiresAuth) {
    return target;  // Redirect to login
  }
});

// Handle navigation failures
$state.go('invalidState').catch(function(error) {
  console.error('Navigation failed:', error.message);
  $state.go('home'); // Fallback navigation
});

// Check state existence before navigation
if ($state.get('targetState')) {
  $state.go('targetState');
} else {
  console.warn('State does not exist');
}

// Handle parameter validation errors
$state.go('users.detail', { userId: 'invalid' }).catch(function(error) {
  if (error.type === 'INVALID_PARAMS') {
    console.error('Invalid parameters:', error.detail);
  }
});