react-native-tinyui 3.0.0 → 3.2.0

package/README.md

@@ -11,6 +11,7 @@ staying close to native APIs. It uses UIKit by default and SwiftUI where needed.
 | Component                          | What it does                                                   |
 | ---------------------------------- | -------------------------------------------------------------- |
 | [Menu](#menu)                      | Present native menus with actions, submenus, and sections       |
+| [SwipeActions](#swipeactions)      | Reveal native action buttons by swiping React Native rows      |
 | [Popover](#popover)                | Show interactive React Native content in a native popover      |
 | [TipKit](#tipkit)                  | Present contextual tips using Apple's TipKit framework         |
 | [LiquidGlassText](#liquidglasstext) | Render text with native glass effects inside the glyphs        |
@@ -75,12 +76,13 @@ use in your app's `package.json`:
 Available components:
 
 - `Menu`
+- `SwipeActions`
 - `Popover`
 - `LiquidGlassText`
 - `Stepper`
 - `ConcentricView`
 - `SFSymbol`
-- `TipKit` (enables `TipKit.View`, `TipKit.Popover`, `TipKit.configure`, `TipKit.resetDatastore` and `TipKit.invalidate`)
+- `TipKit` (enables `TipKit.Group`, `TipKit.View`, `TipKit.Popover`, `TipKit.configure`, `TipKit.resetDatastore` and `TipKit.invalidate`)
 
 `TipKit` is one optional module containing both native views,
 `TinyuiTipPopoverView` and `TinyuiTipView`. Select it once in your app's
@@ -107,6 +109,7 @@ Component-specific JavaScript entry points are also available:
 
 ```tsx
 import { Menu } from 'react-native-tinyui/menu';
+import { SwipeActions } from 'react-native-tinyui/swipe-actions';
 import { Popover } from 'react-native-tinyui/popover';
 import { LiquidGlassText } from 'react-native-tinyui/liquid-glass-text';
 import { Stepper } from 'react-native-tinyui/stepper';
@@ -221,6 +224,62 @@ deprecated `titleColor` field is retained only for source compatibility; use
 `destructive` for system red styling. Submenus support the same label fields
 plus `destructive`, `disabled`, `hidden`, and `displayInline`.
 
+## SwipeActions
+
+`SwipeActions` wraps React Native row content in a native, non-scrolling
+`UITableView` row and uses `UISwipeActionsConfiguration`. It provides the edge
+and full-swipe behavior of SwiftUI's
+[`swipeActions`](https://developer.apple.com/documentation/swiftui/view/swipeactions(edge:allowsfullswipe:content:))
+without requiring a SwiftUI `List`. Use it inside a `FlatList` or `ScrollView`;
+Yoga measures the children, so a fixed row height is optional.
+
+```tsx
+import { SwipeActions } from 'react-native-tinyui/swipe-actions';
+
+<SwipeActions
+  edge="trailing"
+  allowsFullSwipe={false}
+  contentContainerStyle={{ backgroundColor: 'white', borderRadius: 12 }}
+  actions={[
+    { id: 'archive', title: 'Archive', systemImage: 'archivebox', tintColor: '#007AFF' },
+    { id: 'delete', title: 'Delete', systemImage: 'trash', destructive: true },
+  ]}
+  onActionPress={({ nativeEvent }) => handleAction(nativeEvent.id)}
+>
+  <Pressable onPress={openMessage} style={{ padding: 16 }}>
+    <Text>Weekend plans</Text>
+  </Pressable>
+</SwipeActions>;
+```
+
+| Prop | Description | Default |
+| --- | --- | --- |
+| `actions` | Ordered array of native buttons; an empty array disables swiping | Required |
+| `edge` | `leading` or `trailing`, following the row's layout direction | `trailing` |
+| `allowsFullSwipe` | A full swipe performs the **first** action | `true` |
+| `disabled` | Disables swipe actions while preserving child interactions | `false` |
+| `onActionPress` | Receives `{ nativeEvent: { id, title } }` | — |
+| `children` | React Native row content, including pressable children | Required |
+| `contentContainerStyle` | Styles the moving row, including its background, corners and padding | — |
+
+Each action accepts `title`, optional `id` (defaults to `item.<index>`),
+`systemImage` (SF Symbol), `tintColor` (button background), and `destructive`.
+IDs must be unique within the row; use explicit IDs when reordering actions.
+Colors support `PlatformColor` and `DynamicColorIOS`. Buttons appear from the
+selected edge inward in array order. `destructive` changes the native appearance;
+your callback decides whether to remove the row from React state.
+
+Standard `ViewProps` and a native view ref are supported. `style` applies to the
+stationary outer container; use it for layout, sizing and margins. Put the row's
+background, corners and padding in `contentContainerStyle` (or on your children)
+so they move with the content. A background on `style` stays behind the revealed
+actions. Keep stable list keys.
+Opening another `SwipeActions` row closes the previous one. Updating the action
+configuration, disabling, resizing or unmounting a row dismisses its actions.
+One edge is supported per wrapper; do not nest wrappers to add a second edge.
+This component hosts one native table per mounted row, so use list virtualization
+for large datasets. It does not expose SwiftUI's arbitrary action view content.
+
 ## Popover
 
 <img src="docs/screenshots/popover.png" alt="Popover displaying resizable content above its trigger" width="320" />
@@ -372,8 +431,77 @@ The remaining props are shared by both components:
 | `ignoresDisplayFrequency` | Exempts this tip from the app-wide display interval | `false` |
 | `arrowEdge` | `top`, `bottom`, `leading`, `trailing`; Popover also accepts `auto`, View accepts `none` | Popover: `auto`; View: `none` |
 | `onActionPress` | Receives the selected `{ id, title }`; does not automatically invalidate | — |
+| `onInvalidated` | Receives `{ reason }` when invalidated, including persisted invalidation on mount; Popover waits until dismissal finishes | — |
 | `onError` | Receives `{ code, message }`; otherwise a warning is logged | — |
 
+`TipKit.Popover` also accepts `invalidateOnOutsideDismiss`. It defaults to
+`false`, or inherits its Group's value. When enabled, tapping outside the bubble
+invalidates the tip with `tipClosed`. Programmatic hiding, disabling, unmounting
+and leaving the screen do not themselves invalidate it.
+
+### Ordered groups
+
+`TipKit.Group` presents tips in the explicit `tipIds` order. It is a React
+coordinator available on **iOS 17+**, backed by native TipKit eligibility and
+persisted invalidation; it does not wrap Apple's iOS 18 `TipGroup` API.
+`priority` currently supports only `ordered` and defaults to it. The Group adds
+no layout view, so its tips can be nested in ordinary layout components.
+
+```tsx
+// At app startup, before mounting tips:
+await TipKit.configure({ displayFrequency: 'immediate' });
+
+// In your screen:
+<TipKit.Group
+  priority="ordered"
+  tipIds={['favorite-v1', 'share-v1']}
+  enabled={isScreenFocused}
+  invalidateOnOutsideDismiss
+>
+  <TipKit.Popover tipId="favorite-v1" title="Save your favorites">
+    <Button
+      title="Favorite"
+      onPress={async () => {
+        await TipKit.invalidate('favorite-v1', 'actionPerformed');
+        saveFavorite();
+      }}
+    />
+  </TipKit.Popover>
+  <TipKit.Popover tipId="share-v1" title="Share with a friend">
+    <Button
+      title="Share"
+      onPress={async () => {
+        await TipKit.invalidate('share-v1', 'actionPerformed');
+        shareItem();
+      }}
+    />
+  </TipKit.Popover>
+</TipKit.Group>;
+```
+
+- The system close button, `TipKit.invalidate`, or native display limits complete
+  a step. The next tip is enabled after the preceding popover has finished
+  dismissing. Action buttons still require explicit invalidation.
+- Outside dismissal does **not** complete a step by default. Opt in with
+  `invalidateOnOutsideDismiss`, either on the Group or an individual Popover.
+  An explicit Popover value overrides the Group's value.
+- Already-invalidated tips are skipped when the group mounts again. Keep IDs
+  stable across launches. Progress is driven by native state, not JS storage.
+- The next tip still obeys native eligibility and display frequency. Use
+  `immediate` at startup for consecutive tips; TinyUI otherwise defaults to
+  `daily`.
+- Use each declared ID for one `TipKit.View` or `TipKit.Popover` in the group.
+  A missing, disabled or ineligible current tip blocks later tips. Keep the
+  current tip mounted and enabled until it reports invalidation; invalidate it
+  instead of immediately disabling it when its feature is used.
+- `enabled={false}` pauses the group without completing a step. Groups are
+  independent; this is not a global queue for other tips, sheets or screens.
+
+`onInvalidated` reports `actionPerformed`, `tipClosed`, `displayCountExceeded`,
+`displayDurationExceeded`, or `unknown` for an unrecognized native reason.
+It is a state notification, not an outside-dismiss callback, and can fire again
+when an already-invalidated tip resumes observation.
+
 Both components accept standard `ViewProps` and a native view ref. For Popover,
 `style` lays out the anchor, not the bubble. UIKit chooses the bubble's size and may adapt
 the arrow to available space; leading/trailing follow layout direction. Bubble
@@ -422,8 +550,9 @@ launch will erase users' tip history on every launch.
 requires configuration first. It persistently invalidates the ID even when no
 view for that tip is mounted. `reason` may be `actionPerformed` or `tipClosed`.
 
-Both native views observe TipKit's `shouldDisplayUpdates` to show or remove
-the tip. Eligibility and visibility changes are not sent to JavaScript.
+Both native views observe TipKit's `statusUpdates` to show or remove
+the tip. Invalidation is sent to JavaScript through `onInvalidated`; other
+eligibility and visibility changes are not sent to JavaScript.
 Call `invalidate` with `actionPerformed` after the feature is used, or with
 `tipClosed` to permanently dismiss the tip. TipKit also handles the system
 close button and display limits.
@@ -437,7 +566,7 @@ with the same ID share their TipKit history. Keep `maxDisplayCount` and
 tip. Hiding a tip, unmounting it or reconfiguring TinyUI never resets history.
 
 Use `enabled={isScreenFocused && businessCondition}` with your navigation
-library. Each mounted, enabled Popover anchor starts its own `shouldDisplayUpdates`
+library. Each mounted, enabled Popover anchor starts its own `statusUpdates`
 observation once it has a size and a parent view controller. Disabling,
 detaching or recycling the component stops observation and dismisses its
 bubble; changing `tipId` starts a new observation. This follows the independent
@@ -458,7 +587,8 @@ detached or recycled. They do not present a view controller or block interaction
 with the rest of the screen. Both presentations use the same datastore; an
 invalidation affects every instance of the same `tipId`.
 
-Native rule/event builders and TipGroup are not exposed. The example's
+Native rule/event builders and Apple's TipGroup are not exposed. Use the
+React `TipKit.Group` above for ordered presentation. The example's
 **Inline view** switch toggles between both presentations. Its **New demo tip**
 button deliberately creates another
 ID for trying the behavior again without clearing the app's TipKit datastore.
@@ -744,7 +874,7 @@ visibility state changes apply instantly. Set it to `false` to opt out.
 
 ## Example App
 
-The [example app](example/src/App.tsx) demonstrates Menu, Popover, TipKit,
+The [example app](example/src/App.tsx) demonstrates Menu, SwipeActions, Popover, TipKit,
 LiquidGlassText, Stepper, ConcentricView, and SFSymbol. It includes all native
 components, so building it requires Xcode 26+. Use iOS 26+ to try the glass effects
 and the latest SF Symbol features.

package/ios/Core/Tinyui.mm

@@ -12,6 +12,9 @@
 #if TINYUI_FEATURE_MENU
   [components addObject:@"Menu"];
 #endif
+#if TINYUI_FEATURE_SWIPE_ACTIONS
+  [components addObject:@"SwipeActions"];
+#endif
 #if TINYUI_FEATURE_POPOVER
   [components addObject:@"Popover"];
 #endif

package/ios/Core/TinyuiComponentClasses.mm

@@ -29,6 +29,12 @@ TINYUI_DISABLED_COMPONENT(TinyuiMenuView, TinyuiMenuViewComponentDescriptor)
 TINYUI_DISABLED_COMPONENT(TinyuiPopoverView, TinyuiPopoverViewComponentDescriptor)
 #endif
 
+#if TINYUI_FEATURE_SWIPE_ACTIONS
+#import "TinyuiSwipeActionsView.h"
+#else
+TINYUI_DISABLED_COMPONENT(TinyuiSwipeActionsView, TinyuiSwipeActionsViewComponentDescriptor)
+#endif
+
 #if TINYUI_FEATURE_LIQUID_GLASS_TEXT
 #import "TinyuiLiquidGlassTextView.h"
 #else
@@ -68,6 +74,11 @@ Class<RCTComponentViewProtocol> TinyuiMenuViewCls(void)
   return TinyuiMenuView.class;
 }
 
+Class<RCTComponentViewProtocol> TinyuiSwipeActionsViewCls(void)
+{
+  return TinyuiSwipeActionsView.class;
+}
+
 Class<RCTComponentViewProtocol> TinyuiPopoverViewCls(void)
 {
   return TinyuiPopoverView.class;

package/ios/SwipeActions/TinyuiSwipeActionsView.h

@@ -0,0 +1,12 @@
+#if TINYUI_FEATURE_SWIPE_ACTIONS
+
+#import <React/RCTViewComponentView.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface TinyuiSwipeActionsView : RCTViewComponentView
+@end
+
+NS_ASSUME_NONNULL_END
+
+#endif

package/ios/SwipeActions/TinyuiSwipeActionsView.mm

@@ -0,0 +1,289 @@
+#if TINYUI_FEATURE_SWIPE_ACTIONS
+
+#import "TinyuiSwipeActionsView.h"
+
+#import <React/RCTConvert.h>
+#import <React/RCTSurfacePointerHandler.h>
+#import <React/RCTSurfaceTouchHandler.h>
+#import <react/utils/FollyConvert.h>
+#import <react/renderer/components/TinyuiSpec/ComponentDescriptors.h>
+#import <react/renderer/components/TinyuiSpec/EventEmitters.h>
+#import <react/renderer/components/TinyuiSpec/Props.h>
+
+using namespace facebook::react;
+
+@interface TinyuiSwipeActionsView () <UITableViewDataSource, UITableViewDelegate>
+@end
+
+@implementation TinyuiSwipeActionsView {
+  UITableView *_tableView;
+  UITableViewCell *_cell;
+  UIView *_rowView;
+  NSArray<NSDictionary *> *_actions;
+  BOOL _leading;
+  BOOL _allowsFullSwipe;
+  BOOL _disabled;
+  BOOL _needsConfiguration;
+  BOOL _actionsPresented;
+  NSUInteger _configurationVersion;
+}
+
+// UIKit normally coordinates open rows within one table. Each React row has
+// its own table, so coordinate them without retaining mounted Fabric views.
+static __weak TinyuiSwipeActionsView *activeSwipeView;
+
++ (ComponentDescriptorProvider)componentDescriptorProvider
+{
+  return concreteComponentDescriptorProvider<TinyuiSwipeActionsViewComponentDescriptor>();
+}
+
+- (instancetype)initWithFrame:(CGRect)frame
+{
+  if (self = [super initWithFrame:frame]) {
+    _props = std::make_shared<const TinyuiSwipeActionsViewProps>();
+    _actions = @[];
+    _allowsFullSwipe = YES;
+
+    _cell = [[UITableViewCell alloc] initWithStyle:UITableViewCellStyleDefault reuseIdentifier:nil];
+    _cell.backgroundColor = UIColor.clearColor;
+    _cell.contentView.backgroundColor = UIColor.clearColor;
+    _cell.selectionStyle = UITableViewCellSelectionStyleNone;
+    _cell.isAccessibilityElement = NO;
+
+    _tableView = [[UITableView alloc] initWithFrame:CGRectZero style:UITableViewStylePlain];
+    _tableView.backgroundColor = UIColor.clearColor;
+    _tableView.separatorStyle = UITableViewCellSeparatorStyleNone;
+    _tableView.scrollEnabled = NO;
+    _tableView.showsVerticalScrollIndicator = NO;
+    _tableView.showsHorizontalScrollIndicator = NO;
+    _tableView.bounces = NO;
+    _tableView.delaysContentTouches = NO;
+    _tableView.contentInsetAdjustmentBehavior = UIScrollViewContentInsetAdjustmentNever;
+    _tableView.insetsContentViewsToSafeArea = NO;
+    _tableView.sectionHeaderTopPadding = 0;
+    _tableView.estimatedRowHeight = 0;
+    _tableView.estimatedSectionHeaderHeight = 0;
+    _tableView.estimatedSectionFooterHeight = 0;
+    _tableView.dataSource = self;
+    _tableView.delegate = self;
+    // Cover the entire row. Yoga owns the child's frame, including any padding;
+    // using RCTView's inset contentView frame would apply that padding twice.
+    [self addSubview:_tableView];
+  }
+  return self;
+}
+
+- (void)mountChildComponentView:(UIView<RCTComponentViewProtocol> *)childComponentView
+                         index:(NSInteger)index
+{
+  _rowView = childComponentView;
+  [_cell.contentView addSubview:childComponentView];
+}
+
+- (void)unmountChildComponentView:(UIView<RCTComponentViewProtocol> *)childComponentView
+                           index:(NSInteger)index
+{
+  [childComponentView removeFromSuperview];
+  if (_rowView == childComponentView) {
+    _rowView = nil;
+    [self closeActions];
+  }
+}
+
+- (void)layoutSubviews
+{
+  [super layoutSubviews];
+  UISemanticContentAttribute direction = _layoutMetrics.layoutDirection == LayoutDirection::RightToLeft
+      ? UISemanticContentAttributeForceRightToLeft
+      : UISemanticContentAttributeForceLeftToRight;
+  if (!CGSizeEqualToSize(_tableView.bounds.size, self.bounds.size) ||
+      _tableView.semanticContentAttribute != direction) {
+    [self closeActions];
+  }
+  _tableView.frame = self.bounds;
+  CGFloat height = MAX(1, CGRectGetHeight(self.bounds));
+  if (_tableView.rowHeight != height) {
+    _tableView.rowHeight = height;
+    [_tableView reloadData];
+  }
+  // Map Yoga's resolved direction to UIKit's logical leading/trailing edges.
+  _tableView.semanticContentAttribute = direction;
+}
+
+- (UIView *)hitTest:(CGPoint)point withEvent:(UIEvent *)event
+{
+  UIView *hit = [super hitTest:point withEvent:event];
+  // A tap on the exposed row dismisses its actions. Keep that tap in UIKit,
+  // rather than also activating a React child while the row is sliding back.
+  if (_actionsPresented && _rowView != nil && [hit isDescendantOfView:_rowView]) {
+    return _cell.contentView;
+  }
+  return hit;
+}
+
+- (SharedTouchEventEmitter)touchEventEmitterAtPoint:(CGPoint)point
+{
+  // Native action buttons have no Fabric ancestor until this view. Do not let
+  // their taps bubble to an outer React Pressable. Child React views still own
+  // normal row touches and keep their usual event bubbling.
+  return _actionsPresented ? nullptr : [super touchEventEmitterAtPoint:point];
+}
+
+- (void)updateProps:(Props::Shared const &)props oldProps:(Props::Shared const &)oldProps
+{
+  const auto &previous = *std::static_pointer_cast<const TinyuiSwipeActionsViewProps>(_props);
+  const auto &next = *std::static_pointer_cast<const TinyuiSwipeActionsViewProps>(props);
+  if (_needsConfiguration || previous.actionsConfig != next.actionsConfig || previous.edge != next.edge ||
+      previous.allowsFullSwipe != next.allowsFullSwipe || previous.disabled != next.disabled) {
+    [self closeActions];
+    id config = convertFollyDynamicToId(next.actionsConfig);
+    _actions = [config isKindOfClass:NSArray.class] ? config : @[];
+    _leading = next.edge == TinyuiSwipeActionsViewEdge::Leading;
+    _allowsFullSwipe = next.allowsFullSwipe;
+    _disabled = next.disabled;
+    _needsConfiguration = NO;
+  }
+  [super updateProps:props oldProps:oldProps];
+}
+
+- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section
+{
+  return 1;
+}
+
+- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
+{
+  return _cell;
+}
+
+- (BOOL)tableView:(UITableView *)tableView canEditRowAtIndexPath:(NSIndexPath *)indexPath
+{
+  return !_disabled && _actions.count > 0 && _rowView != nil;
+}
+
+- (UISwipeActionsConfiguration *)tableView:(UITableView *)tableView
+    leadingSwipeActionsConfigurationForRowAtIndexPath:(NSIndexPath *)indexPath
+{
+  return _leading ? [self swipeConfiguration] : nil;
+}
+
+- (UISwipeActionsConfiguration *)tableView:(UITableView *)tableView
+    trailingSwipeActionsConfigurationForRowAtIndexPath:(NSIndexPath *)indexPath
+{
+  return _leading ? nil : [self swipeConfiguration];
+}
+
+- (UISwipeActionsConfiguration *)swipeConfiguration
+{
+  if (_disabled || _actions.count == 0 || _rowView == nil) {
+    return nil;
+  }
+
+  NSMutableArray<UIContextualAction *> *actions = [NSMutableArray array];
+  NSUInteger version = _configurationVersion;
+  __weak TinyuiSwipeActionsView *weakSelf = self;
+  for (NSDictionary *item in _actions) {
+    if (![item isKindOfClass:NSDictionary.class] ||
+        ![item[@"id"] isKindOfClass:NSString.class] ||
+        ![item[@"title"] isKindOfClass:NSString.class]) {
+      continue;
+    }
+    NSString *identifier = item[@"id"];
+    NSString *title = item[@"title"];
+    UIContextualActionStyle style = [item[@"destructive"] boolValue]
+        ? UIContextualActionStyleDestructive : UIContextualActionStyleNormal;
+    UIContextualAction *action = [UIContextualAction contextualActionWithStyle:style
+        title:title handler:^(UIContextualAction *selectedAction, UIView *sourceView,
+                              void (^completionHandler)(BOOL)) {
+      TinyuiSwipeActionsView *view = weakSelf;
+      if (view == nil || view->_disabled || view.window == nil || view->_rowView == nil ||
+          version != view->_configurationVersion) {
+        completionHandler(NO);
+        return;
+      }
+      // Finish UIKit's interaction before JS can update or remove the row.
+      completionHandler(YES);
+      if (view->_eventEmitter != nullptr) {
+        std::static_pointer_cast<const TinyuiSwipeActionsViewEventEmitter>(view->_eventEmitter)
+            ->onActionPress(TinyuiSwipeActionsViewEventEmitter::OnActionPress{
+                .id = std::string(identifier.UTF8String ?: ""),
+                .title = std::string(title.UTF8String ?: "")});
+      }
+    }];
+    if ([item[@"systemImage"] isKindOfClass:NSString.class]) {
+      action.image = [UIImage systemImageNamed:item[@"systemImage"]];
+    }
+    if (item[@"tintColor"] != nil && item[@"tintColor"] != NSNull.null) {
+      action.backgroundColor = [RCTConvert UIColor:item[@"tintColor"]];
+    }
+    [actions addObject:action];
+  }
+  UISwipeActionsConfiguration *configuration = [UISwipeActionsConfiguration configurationWithActions:actions];
+  configuration.performsFirstActionWithFullSwipe = _allowsFullSwipe;
+  return configuration;
+}
+
+- (void)tableView:(UITableView *)tableView willBeginEditingRowAtIndexPath:(NSIndexPath *)indexPath
+{
+  _actionsPresented = YES;
+  // Fabric keeps observing touches handled by recognizers inside its surface.
+  // Once UIKit starts a swipe, cancel that React sequence so a child/ancestor
+  // Pressable cannot also complete an onPress when the finger is lifted.
+  for (UIView *view = self; view != nil; view = view.superview) {
+    for (UIGestureRecognizer *recognizer in view.gestureRecognizers) {
+      if (recognizer.enabled &&
+          ([recognizer isKindOfClass:RCTSurfaceTouchHandler.class] ||
+           [recognizer isKindOfClass:RCTSurfacePointerHandler.class])) {
+        recognizer.enabled = NO;
+        recognizer.enabled = YES;
+      }
+    }
+  }
+  if (activeSwipeView != self) {
+    [activeSwipeView closeActions];
+  }
+  activeSwipeView = self;
+}
+
+- (void)tableView:(UITableView *)tableView didEndEditingRowAtIndexPath:(NSIndexPath *)indexPath
+{
+  _actionsPresented = NO;
+  if (activeSwipeView == self) {
+    activeSwipeView = nil;
+  }
+}
+
+- (void)closeActions
+{
+  _configurationVersion += 1;
+  _actionsPresented = NO;
+  [_tableView setEditing:NO animated:NO];
+  if (activeSwipeView == self) {
+    activeSwipeView = nil;
+  }
+}
+
+- (void)didMoveToWindow
+{
+  [super didMoveToWindow];
+  if (self.window == nil) {
+    [self closeActions];
+  }
+}
+
+- (void)prepareForRecycle
+{
+  [self closeActions];
+  [_rowView removeFromSuperview];
+  _rowView = nil;
+  _actions = @[];
+  _leading = NO;
+  _allowsFullSwipe = YES;
+  _disabled = NO;
+  _needsConfiguration = YES;
+  [super prepareForRecycle];
+}
+
+@end
+
+#endif

package/ios/TipKit/TinyuiTipPopoverProvider.swift

@@ -4,6 +4,7 @@ import UIKit
 @objc public protocol TinyuiTipPopoverDelegate: AnyObject {
   func onTipAction(tipId: String, id: String, title: String)
   func onTipError(tipId: String, code: String, message: String)
+  func onTipInvalidated(tipId: String, reason: String)
 }
 
 @MainActor
@@ -26,6 +27,8 @@ import UIKit
   private var presentedTipId: String?
   private var isPresenting = false
   private var isDismissing = false
+  private var invalidateOnOutsideDismiss = false
+  private var pendingInvalidation: (tipId: String, reason: String)?
 
   @objc public convenience init(delegate: TinyuiTipPopoverDelegate) {
     self.init(frame: .zero)
@@ -34,6 +37,7 @@ import UIKit
 
   @objc public func configure(_ configuration: [String: Any], enabled: Bool, arrowEdge: String) {
     let nextTip = TinyuiTip(configuration: configuration)
+    if tip?.id != nextTip.id { pendingInvalidation = nil }
     if tip?.id != nextTip.id || self.enabled != enabled {
       stop()
       lastError = nil
@@ -41,6 +45,7 @@ import UIKit
     tip = nextTip
     self.enabled = enabled
     self.arrowEdge = arrowEdge
+    invalidateOnOutsideDismiss = configuration["invalidateOnOutsideDismiss"] as? Bool ?? false
     // Validate changed options even when an observation is already running.
     do {
       try TinyuiTipsRuntime.shared.remember(nextTip)
@@ -87,10 +92,16 @@ import UIKit
     }
 
     observation = Task { @MainActor [weak self] in
-      for await shouldDisplay in tip.shouldDisplayUpdates {
+      var reportedInvalidation = false
+      for await status in tip.statusUpdates {
         guard !Task.isCancelled, let self else { break }
-        self.shouldDisplay = shouldDisplay
+        if case .available = status { self.shouldDisplay = true } else { self.shouldDisplay = false }
+        if case .invalidated(let reason) = status, !reportedInvalidation {
+          reportedInvalidation = true
+          self.pendingInvalidation = (tip.id, TinyuiTipsRuntime.invalidationReason(reason))
+        }
         self.updatePresentation()
+        self.reportInvalidationIfDismissed()
       }
     }
   }
@@ -178,11 +189,25 @@ import UIKit
     presentedTipId = nil
     isPresenting = false
     isDismissing = false
+    reportInvalidationIfDismissed()
+  }
+
+  private func reportInvalidationIfDismissed() {
+    // The next grouped anchor must not present until this transition finishes.
+    guard controller == nil, let event = pendingInvalidation else { return }
+    pendingInvalidation = nil
+    delegate?.onTipInvalidated(tipId: event.tipId, reason: event.reason)
   }
 
   public func presentationControllerDidDismiss(_ presentationController: UIPresentationController) {
     guard let controller, presentationController.presentedViewController === controller else { return }
+    let dismissedTip = presentedTipId == tip?.id ? tip : nil
+    let shouldInvalidate = invalidateOnOutsideDismiss && !isDismissing
     finishDismissal(controller)
+    // Programmatic hiding, navigation and recycling do not complete a tip.
+    if shouldInvalidate, let dismissedTip, case .available = dismissedTip.status {
+      dismissedTip.invalidate(reason: .tipClosed)
+    }
   }
 
   public func adaptivePresentationStyle(for controller: UIPresentationController) -> UIModalPresentationStyle { .none }
@@ -199,6 +224,8 @@ import UIKit
     enabled = false
     tip = nil
     lastError = nil
+    pendingInvalidation = nil
+    invalidateOnOutsideDismiss = false
     stop()
     parentViewController = nil
   }

package/ios/TipKit/TinyuiTipPopoverView.mm

@@ -65,6 +65,7 @@ using namespace facebook::react;
     @"actions": actions,
     @"maxDisplayCount": @(next.maxDisplayCount),
     @"ignoresDisplayFrequency": @(next.ignoresDisplayFrequency),
+    @"invalidateOnOutsideDismiss": @(next.invalidateOnOutsideDismiss),
   } enabled:next.enabled arrowEdge:RCTNSStringFromString(next.arrowEdge)];
   [super updateProps:props oldProps:oldProps];
 }
@@ -87,6 +88,15 @@ using namespace facebook::react;
   });
 }
 
+- (void)onTipInvalidatedWithTipId:(NSString *)tipId reason:(NSString *)reason
+{
+  if (_eventEmitter == nullptr) return;
+  std::static_pointer_cast<const TinyuiTipPopoverViewEventEmitter>(_eventEmitter)->onTipInvalidated({
+    .tipId = std::string(tipId.UTF8String ?: ""),
+    .reason = std::string(reason.UTF8String ?: "unknown"),
+  });
+}
+
 - (void)prepareForRecycle
 {
   [_provider reset];

package/ios/TipKit/TinyuiTipView.mm

@@ -83,6 +83,15 @@ using namespace facebook::react;
   });
 }
 
+- (void)onTipInvalidatedWithTipId:(NSString *)tipId reason:(NSString *)reason
+{
+  if (_eventEmitter == nullptr) return;
+  std::static_pointer_cast<const TinyuiTipViewEventEmitter>(_eventEmitter)->onTipInvalidated({
+    .tipId = std::string(tipId.UTF8String ?: ""),
+    .reason = std::string(reason.UTF8String ?: "unknown"),
+  });
+}
+
 - (void)prepareForRecycle
 {
   _state.reset();