RNSTabsNavigationState.h

#pragma once

#import <Foundation/Foundation.h>

NS_ASSUME_NONNULL_BEGIN

/**
 * Origin (actor) that requested a tab transition. Mirrors the public `actionOrigin` event field.
 */
typedef NS_ENUM(NSInteger, RNSTabsActionOrigin) {
  /**
   * Direct native UI interaction (tab bar tap, drag-and-drop).
   */
  RNSTabsActionOriginUser = 0,
  /**
   * JS-initiated request delivered via the `navStateRequest` prop.
   */
  RNSTabsActionOriginProgrammaticJs,
  /**
   * Request initiated from the native side by some actor, e.g. a downstream
   * library integrating directly against `RNSTabBarController`.
   */
  RNSTabsActionOriginProgrammaticNative,
  /**
   * Platform side effect not attributable to an explicit actor — UIKit changed the selection
   * as a side effect of another operation (e.g. More navigation controller disappearing during a
   * horizontal size class transition on iPad).
   */
  RNSTabsActionOriginImplicit,
};

/**
 * Reason why a navigation state update was rejected by the container.
 */
typedef NS_ENUM(NSInteger, RNSTabsNavigationStateRejectionReason) {
  /**
   * The update's provenance is based on a stale state.
   */
  RNSTabsNavigationStateRejectionReasonStale = 0,
  /**
   * The requested tab is already selected.
   */
  RNSTabsNavigationStateRejectionReasonRepeated,
};

/**
 * Describes navigation state of a tabs container.
 *
 * It holds information about key of a selected screen AND state provenance.
 * The provenance describes *a history of the state*. Conceptually, the state with provenance `N + 1`
 * MUST BE derived from state with provenance `N`.
 */
@interface RNSTabsNavigationState : NSObject

/**
 * Screen key of the currently selected tab.
 */
@property (nonatomic, strong, readonly, nonnull) NSString *selectedScreenKey;

/**
 * Monotonically increasing number describing the generation of this state instance.
 * Used for stale update detection.
 */
@property (nonatomic, readonly) int provenance;

- (instancetype)initWithSelectedScreenKey:(nonnull NSString *)selectedScreenKey provenance:(int)provenance;

- (instancetype)cloneState;

+ (instancetype)stateWithSelectedScreenKey:(nonnull NSString *)selectedScreenKey provenance:(int)provenance;

@end

/**
 * A request to change navigation state.
 *
 * Carries the target `selectedScreenKey`, the `baseProvenance` of the state the request was derived from,
 * and the `actionOrigin` (actor) that initiated it. Mirrors the public
 * `TabsHostNavStateRequest` TS type plus an `actionOrigin` carried internally.
 */
@interface RNSTabsNavigationStateUpdateRequest : NSObject

@property (nonatomic, strong, readonly, nonnull) NSString *selectedScreenKey;
@property (nonatomic, readonly) int baseProvenance;
@property (nonatomic, readonly) RNSTabsActionOrigin actionOrigin;

- (instancetype)initWithSelectedScreenKey:(nonnull NSString *)selectedScreenKey
                           baseProvenance:(int)baseProvenance
                             actionOrigin:(RNSTabsActionOrigin)actionOrigin;

- (instancetype)cloneRequest;

+ (instancetype)requestWithSelectedScreenKey:(nonnull NSString *)selectedScreenKey
                              baseProvenance:(int)baseProvenance
                                actionOrigin:(RNSTabsActionOrigin)actionOrigin;

@end

/**
 * Bundles a navigation state change together with metadata about the selection context.
 */
@interface RNSTabsNavigationStateUpdateContext : NSObject

/**
 * The navigation state after the change.
 */
@property (nonatomic, readonly, strong, nonnull) RNSTabsNavigationState *navState;
/**
 * Whether the same tab that was already selected has been selected again.
 */
@property (nonatomic, readonly) BOOL isRepeated;
/**
 * Whether a special effect (e.g. scroll-to-top) was triggered by the selection.
 */
@property (nonatomic, readonly) BOOL hasTriggeredSpecialEffect;
/**
 * Origin (actor) that requested this transition.
 */
@property (nonatomic, readonly) RNSTabsActionOrigin actionOrigin;

- (instancetype)initWithNavState:(nonnull RNSTabsNavigationState *)navState
                      isRepeated:(BOOL)isRepeated
       hasTriggeredSpecialEffect:(BOOL)hasTriggeredSpecialEffect
                    actionOrigin:(RNSTabsActionOrigin)actionOrigin;

@end

NS_ASSUME_NONNULL_END