react-native-tinyui 1.1.1 → 3.0.0

package/README.md

@@ -80,7 +80,23 @@ Available components:
 - `Stepper`
 - `ConcentricView`
 - `SFSymbol`
-- `TipKit` (enables `TipKit.Popover`, `TipKit.configure` and `TipKit.invalidate`)
+- `TipKit` (enables `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
+`package.json` to include both:
+
+```json
+{
+  "react-native-tinyui": {
+    "components": ["TipKit"]
+  }
+}
+```
+
+The JavaScript API is also `TipKit`, imported from `react-native-tinyui` or
+`react-native-tinyui/tip-kit`. The library's Codegen configuration registers the
+two native view classes individually; it is not the optional-module selection.
 
 All components are enabled by default. Use an empty `components` array to
 compile only the TurboModule core. Run `pod install` again whenever this list
@@ -256,12 +272,16 @@ outer container, not the presented content.
 
 <img src="docs/screenshots/tip-kit.png" alt="TipKit popover with a save action anchored to the favorite button" width="320" />
 
+`TipKit.View` embeds a native `TipUIView` directly in your layout.
 `TipKit.Popover` anchors a native TipKit `TipUIPopoverViewController` to ordinary
 React Native children on iOS 17+. The children retain their own touch handlers;
 the tip appears automatically when both `enabled` and TipKit's eligibility allow
 it. Its text, SF Symbol, action buttons, display history and invalidation use
 Apple's TipKit framework. No additional package is required.
 
+Both components support the same tip content, action callbacks, display options
+and persistent history on iOS 17+.
+
 Configure TipKit once, **before mounting tips** (for example, during app startup):
 
 ```tsx
@@ -278,12 +298,18 @@ await TipKit.configure({ displayFrequency: 'daily' });
   systemImage="star"
   enabled={isScreenFocused && !hasFavorites}
   maxDisplayCount={3}
-  actions={[{ id: 'learn-more', title: 'Learn more' }]}
-  onActionPress={({ id }) => {
-    if (id === 'learn-more') openHelp();
+  actions={[
+    { id: 'save', title: 'Save this item' },
+    { id: 'learn-more', title: 'Learn more' },
+  ]}
+  onActionPress={async ({ id }) => {
+    if (id === 'save') {
+      await saveFavorite();
+      await TipKit.invalidate('favorite-feature-v1', 'actionPerformed');
+    } else if (id === 'learn-more') {
+      openHelp();
+    }
   }}
-  onStatusChange={(status) => console.log(status)}
-  onVisibleChange={(visible) => console.log({ visible })}
   onError={(error) => console.warn(error.message)}
 >
   <Pressable onPress={async () => {
@@ -295,28 +321,73 @@ await TipKit.configure({ displayFrequency: 'daily' });
 </TipKit.Popover>;
 ```
 
+For an inline tip, use `TipKit.View` without anchor children (after the same
+startup configuration):
+
+```tsx
+<TipKit.View
+  tipId="favorite-inline-v1"
+  title="Keep your favorites close"
+  message="Save an item to find it quickly next time."
+  systemImage="star"
+  enabled={isScreenFocused && !hasFavorites}
+  actions={[
+    { id: 'save', title: 'Save this item' },
+    { id: 'learn-more', title: 'Learn more' },
+  ]}
+  onActionPress={async ({ id }) => {
+    if (id === 'save') {
+      await saveFavorite();
+      await TipKit.invalidate('favorite-inline-v1', 'actionPerformed');
+    } else if (id === 'learn-more') {
+      openHelp();
+    }
+  }}
+/>
+```
+
+`TipKit.View` fills the available width and measures its native content height.
+The card keeps TipKit's preferred width within that space and aligns to the
+leading edge; the system also chooses the action buttons' layout.
+Give it a bounded width (for example, a stretched child of a column or an
+explicit `style.width`); no fixed height is needed. When disabled or ineligible,
+its content height becomes zero. Explicit height/min-height, padding, margins
+and a parent's `gap` still follow normal React Native layout rules. Native
+measurement updates Fabric directly, including after width and Dynamic Type
+changes; there is no JavaScript size or status callback. The inline arrow is
+optional: `arrowEdge` accepts `top`, `bottom`, `leading`, `trailing` or `none`
+(default). `children` is only supported by `TipKit.Popover`.
+
+The remaining props are shared by both components:
+
 | Prop | Description | Default |
 | --- | --- | --- |
 | `tipId` | Required stable identity for persistent history | — |
 | `title` | Required nonempty title, already localized by the app | — |
 | `message` | Supporting plain text | — |
 | `systemImage` | SF Symbol name | — |
-| `actions` | Buttons with unique nonempty `{ id, title }` values | `[]` |
+| `actions` | Native buttons with unique nonempty `id` and nonempty `title`; TipKit chooses their layout | `[]` |
 | `enabled` | Allows presentation; does not override TipKit eligibility | `true` |
 | `maxDisplayCount` | Positive integer; automatically invalidates after this many displays | Unlimited |
 | `ignoresDisplayFrequency` | Exempts this tip from the app-wide display interval | `false` |
-| `arrowEdge` | Preferred bubble edge: `top`, `bottom`, `leading`, `trailing`, `auto` | `auto` |
-| `onStatusChange` | `{ status: 'pending' \| 'available' }` or `{ status: 'invalidated', reason }` | — |
-| `onVisibleChange` | Whether the native bubble is actually visible | — |
+| `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 | — |
 | `onError` | Receives `{ code, message }`; otherwise a warning is logged | — |
 
-The component accepts standard `ViewProps` and a native view ref. `style` lays
-out the anchor, not the bubble. UIKit chooses the bubble's size and may adapt
+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
 content is native text/images/actions; `children` supplies only the anchor.
-Content edits apply to the next presentation; the currently visible bubble
-retains the content and action labels it was presented with.
+Content and arrow edits on an inline tip apply the next time it is shown.
+Content edits on a popover apply to the next presentation. A currently visible
+tip retains the content and action labels it was shown with.
+
+To show two action buttons, provide two entries in `actions`, as above. Each
+`title` controls that button's label. `onActionPress` receives the clicked
+button's `{ id, title }`; use `id` to handle the buttons separately. Titles may
+be translated without changing action IDs. To temporarily hide a tip in response
+to an action, set `enabled` to `false`; to permanently complete it, call
+`TipKit.invalidate`.
 
 ### Configuration and lifetime
 
@@ -326,13 +397,38 @@ app-wide TipKit setting. Repeating the same configuration is safe, including
 after Fast Refresh; changing it later rejects with `E_TIPS_ALREADY_CONFIGURED`.
 Coordinate this startup configuration with any other native TipKit integration.
 Initialization errors reject the promise; an enabled view mounted too early
-reports `E_TIPS_NOT_CONFIGURED` and can recover after configuration succeeds.
+reports `E_TIPS_NOT_CONFIGURED`. Await configuration before mounting tips. If a
+tip was already mounted, remount it or toggle `enabled` after configuration to
+start observing it.
+
+`TipKit.resetDatastore()` returns a promise and clears all persisted tip, event
+and parameter records, making previously invalidated tips eligible again when
+their display conditions allow. It is primarily for testing the first-launch
+experience and **must be awaited before `TipKit.configure()`**:
+
+```ts
+// At app startup, when deliberately resetting tip history for testing:
+await TipKit.resetDatastore();
+await TipKit.configure({ displayFrequency: 'immediate' });
+```
+
+Once TinyUI has configured TipKit, resetting rejects with
+`E_TIPS_ALREADY_CONFIGURED`; restart the app process to run this sequence again.
+Fast Refresh does not reset native configuration. Other native reset failures
+also reject the promise (fallback code `E_TIPS_RESET`). Calling reset on every
+launch will erase users' tip history on every launch.
 
 `TipKit.invalidate(tipId, reason = 'actionPerformed')` also returns a promise and
 requires configuration first. It persistently invalidates the ID even when no
 view for that tip is mounted. `reason` may be `actionPerformed` or `tipClosed`.
-System invalidations can additionally report `displayCountExceeded`,
-`displayDurationExceeded`, or `unknown` through `onStatusChange`.
+
+Both native views observe TipKit's `shouldDisplayUpdates` to show or remove
+the tip. 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.
+Action buttons only emit `onActionPress`; they do not automatically invalidate.
+Setting `enabled={false}` or unmounting a tip does not itself invalidate it.
 
 Keep IDs stable across renders, app launches and translations. All instances
 with the same ID share their TipKit history. Keep `maxDisplayCount` and
@@ -341,16 +437,30 @@ 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. TinyUI also waits for a visible anchor and a free presenter, and
-dismisses on detachment or when the anchor leaves the visible area. It presents
-at most one TinyUI tip at a time and waits while another modal occupies the
-presenter. An outside dismissal suppresses immediate reopening for that mount;
-toggle `enabled` off and on to allow another attempt, subject to TipKit's state.
-The system close button can permanently invalidate a tip.
-
-This first version exposes popover tips and JS eligibility conditions. Inline
-`TipUIView`, native rule/event builders, TipGroup and datastore reset APIs are
-not exposed. The example's **New demo tip** button deliberately creates another
+library. Each mounted, enabled Popover anchor starts its own `shouldDisplayUpdates`
+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
+`start()` / `stop()` structure of
+[Tipster's TipPresenter](https://github.com/chockenberry/Tipster/blob/081922aa9421d764c436cbe16ad9e2601cd52740/Tipster/TipKitHelper.swift).
+
+Popover presentation is skipped when the host view controller or an ancestor already
+presents another controller. There is no global anchor registry, presentation
+queue, polling timer, app-state observer or scroll visibility tracking.
+Closing another tip or modal does not automatically retry a skipped
+presentation. A later eligibility update, remount or re-enabling the component
+can trigger another attempt. An outside dismissal only cleans up the current
+presentation; there is no additional per-mount suppression policy. The system
+close button can permanently invalidate a tip.
+
+Inline tips start observing when attached to a window and stop when disabled,
+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
+**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.
 
 ## LiquidGlassText
@@ -389,7 +499,7 @@ import { LiquidGlassText } from 'react-native-tinyui';
 | Prop                     | Values                                           | Default   |
 | ------------------------ | ------------------------------------------------ | --------- |
 | `text`                   | String (including text translated in JavaScript) | Required  |
-| `effect`                 | `clear`, `regular`, `identity`                   | `clear`   |
+| `effect`                 | `clear`, `regular`                               | `clear`   |
 | `tint`                   | React Native `ColorValue`                        | —         |
 | `interactive`            | Whether the glass responds to interaction        | `false`   |
 | `fontDesign`             | `default`, `serif`, `monospaced`, `rounded`      | `default` |
@@ -403,7 +513,7 @@ precedence. `fontFamily` accepts the PostScript name of a font installed in the
 app, and `fontDesign` only applies to system fonts.
 
 `tint` accepts a React Native `ColorValue`, including `PlatformColor` and
-`DynamicColorIOS`. `identity` applies no glass effect.
+`DynamicColorIOS`.
 The component also accepts standard `ViewProps`, including `style`, `testID`,
 accessibility props and a native view ref. The supplied text is used for
 the default accessibility label; pass `accessibilityLabel` to override it.
@@ -564,9 +674,7 @@ function Favorite() {
 | `size` | Positive point size; default `17`. |
 | `weight` | `unspecified` (default), `ultraLight`, `thin`, `light`, `regular`, `medium`, `semibold`, `bold`, `heavy`, `black`. |
 | `scale` | `default`, `unspecified`, `small`, `medium`, `large`. |
-| `textStyle` | `extraLargeTitle`, `extraLargeTitle2`, `largeTitle`, `title1`–`title3`, `headline`, `subheadline`, `body`, `callout`, `footnote`, `caption1`, `caption2`. Overrides `size` and supplies the style's weight unless explicitly set. |
-| `fontFamily` | Font/PostScript name used to derive symbol metrics; unknown fonts use system metrics. |
-| `allowFontScaling` | Default `true`. Scales the base point size by React Native's `fontScale`, including when using `textStyle`. |
+| `allowFontScaling` | Default `true`. Scales the base point size by React Native's `fontScale`. |
 | `maxFontSizeMultiplier` | Cap on that scale, >= 1. Omitted or `0` means unlimited. |
 | `renderingMode` | `automatic` (default), `monochrome`, `hierarchical`, `palette`, `multicolor`. |
 | `color` | React Native `ColorValue`, including `PlatformColor` and `DynamicColorIOS`. Defaults to semantic label color. |

package/ios/Core/Tinyui.mm

@@ -35,6 +35,24 @@
   return components;
 }
 
+- (void)resetTipsDatastore:(RCTPromiseResolveBlock)resolve
+                    reject:(RCTPromiseRejectBlock)reject
+{
+#if TINYUI_FEATURE_TIP_KIT
+  dispatch_async(dispatch_get_main_queue(), ^{
+    [TinyuiTipsRuntime resetDatastore:^(NSError *error) {
+      if (error != nil) {
+        reject(error.userInfo[@"code"] ?: @"E_TIPS_RESET", error.localizedDescription, error);
+      } else {
+        resolve(nil);
+      }
+    }];
+  });
+#else
+  reject(@"E_TIP_NOT_INSTALLED", @"Enable TipKit in react-native-tinyui.components and run pod install.", nil);
+#endif
+}
+
 - (void)configureTips:(NSString *)displayFrequency
              resolve:(RCTPromiseResolveBlock)resolve
               reject:(RCTPromiseRejectBlock)reject

package/ios/Core/TinyuiComponentClasses.mm

@@ -55,8 +55,10 @@ TINYUI_DISABLED_COMPONENT(TinyuiSFSymbolView, TinyuiSFSymbolViewComponentDescrip
 
 #if TINYUI_FEATURE_TIP_KIT
 #import "TinyuiTipPopoverView.h"
+#import "TinyuiTipView.h"
 #else
 TINYUI_DISABLED_COMPONENT(TinyuiTipPopoverView, TinyuiTipPopoverViewComponentDescriptor)
+TINYUI_DISABLED_COMPONENT(TinyuiTipView, TinyuiTipViewComponentDescriptor)
 #endif
 
 #undef TINYUI_DISABLED_COMPONENT
@@ -95,3 +97,8 @@ Class<RCTComponentViewProtocol> TinyuiTipPopoverViewCls(void)
 {
   return TinyuiTipPopoverView.class;
 }
+
+Class<RCTComponentViewProtocol> TinyuiTipViewCls(void)
+{
+  return TinyuiTipView.class;
+}

package/ios/LiquidGlassText/TinyuiLiquidGlassTextProvider.swift

@@ -138,7 +138,6 @@ private struct LiquidGlassTextEffect: View {
     var result: Glass
     switch effect {
     case "regular": result = .regular
-    case "identity": result = .identity
     default: result = .clear
     }
     if let tintColor {

package/ios/SFSymbol/TinyuiSFSymbolEffects.swift

@@ -0,0 +1,184 @@
+import Symbols
+import UIKit
+
+// Preserve the native Swift effect protocols so UIKit checks supported effects
+// at compile time, including the availability of newer presets.
+enum TinyuiSFSymbolEffect {
+  case discrete(any SymbolEffect & DiscreteSymbolEffect)
+  case indefinite(any SymbolEffect & IndefiniteSymbolEffect)
+
+  static func make(_ configuration: [String: Any]) -> TinyuiSFSymbolEffect? {
+    let scope = configuration["scope"] as? String
+    let direction = configuration["direction"] as? String
+    switch configuration["type"] as? String {
+    case "pulse":
+      var effect: PulseSymbolEffect = .pulse
+      if scope == "byLayer" { effect = effect.byLayer }
+      if scope == "wholeSymbol" { effect = effect.wholeSymbol }
+      return .discrete(effect)
+    case "bounce":
+      var effect: BounceSymbolEffect = .bounce
+      if direction == "up" { effect = effect.up }
+      if direction == "down" { effect = effect.down }
+      if scope == "byLayer" { effect = effect.byLayer }
+      if scope == "wholeSymbol" { effect = effect.wholeSymbol }
+      return .discrete(effect)
+    case "scale":
+      var effect: ScaleSymbolEffect = .scale
+      if direction == "up" { effect = effect.up }
+      if direction == "down" { effect = effect.down }
+      if scope == "byLayer" { effect = effect.byLayer }
+      if scope == "wholeSymbol" { effect = effect.wholeSymbol }
+      return .indefinite(effect)
+    case "appear":
+      var effect: AppearSymbolEffect = .appear
+      if direction == "up" { effect = effect.up }
+      if direction == "down" { effect = effect.down }
+      if scope == "byLayer" { effect = effect.byLayer }
+      if scope == "wholeSymbol" { effect = effect.wholeSymbol }
+      return .indefinite(effect)
+    case "disappear":
+      var effect: DisappearSymbolEffect = .disappear
+      if direction == "up" { effect = effect.up }
+      if direction == "down" { effect = effect.down }
+      if scope == "byLayer" { effect = effect.byLayer }
+      if scope == "wholeSymbol" { effect = effect.wholeSymbol }
+      return .indefinite(effect)
+    case "variableColor":
+      var effect: VariableColorSymbolEffect = .variableColor
+      if configuration["iteration"] as? String == "iterative" { effect = effect.iterative }
+      if configuration["iteration"] as? String == "cumulative" { effect = effect.cumulative }
+      if let reversing = configuration["reversing"] as? NSNumber {
+        effect = reversing.boolValue ? effect.reversing : effect.nonReversing
+      }
+      if configuration["inactiveLayers"] as? String == "hide" { effect = effect.hideInactiveLayers }
+      if configuration["inactiveLayers"] as? String == "dim" { effect = effect.dimInactiveLayers }
+      return .discrete(effect)
+    case "wiggle":
+      guard #available(iOS 18.0, *) else { return nil }
+      var effect: WiggleSymbolEffect = .wiggle
+      switch direction {
+      case "up": effect = effect.up
+      case "down": effect = effect.down
+      case "left": effect = effect.left
+      case "right": effect = effect.right
+      case "forward": effect = effect.forward
+      case "backward": effect = effect.backward
+      case "clockwise": effect = effect.clockwise
+      case "counterClockwise": effect = effect.counterClockwise
+      default: break
+      }
+      if let angle = (configuration["angle"] as? NSNumber)?.doubleValue, angle.isFinite {
+        effect = WiggleSymbolEffect.wiggle.custom(angle: angle)
+      }
+      if scope == "byLayer" { effect = effect.byLayer }
+      if scope == "wholeSymbol" { effect = effect.wholeSymbol }
+      return .discrete(effect)
+    case "rotate":
+      guard #available(iOS 18.0, *) else { return nil }
+      var effect: RotateSymbolEffect = .rotate
+      if direction == "clockwise" { effect = effect.clockwise }
+      if direction == "counterClockwise" { effect = effect.counterClockwise }
+      if scope == "byLayer" { effect = effect.byLayer }
+      if scope == "wholeSymbol" { effect = effect.wholeSymbol }
+      return .discrete(effect)
+    case "breathe":
+      guard #available(iOS 18.0, *) else { return nil }
+      var effect: BreatheSymbolEffect = .breathe
+      if configuration["style"] as? String == "plain" { effect = effect.plain }
+      if configuration["style"] as? String == "pulse" { effect = effect.pulse }
+      if scope == "byLayer" { effect = effect.byLayer }
+      if scope == "wholeSymbol" { effect = effect.wholeSymbol }
+      return .discrete(effect)
+    case "drawOn":
+      guard #available(iOS 26.0, *) else { return nil }
+      var effect: DrawOnSymbolEffect = .drawOn
+      if scope == "byLayer" { effect = effect.byLayer }
+      if scope == "wholeSymbol" { effect = effect.wholeSymbol }
+      if scope == "individually" { effect = effect.individually }
+      return .indefinite(effect)
+    case "drawOff":
+      guard #available(iOS 26.0, *) else { return nil }
+      var effect: DrawOffSymbolEffect = .drawOff
+      if scope == "byLayer" { effect = effect.byLayer }
+      if scope == "wholeSymbol" { effect = effect.wholeSymbol }
+      if scope == "individually" { effect = effect.individually }
+      if let reversed = configuration["reversed"] as? NSNumber {
+        effect = reversed.boolValue ? effect.reversed : effect.nonReversed
+      }
+      return .indefinite(effect)
+    default: return nil
+    }
+  }
+
+  @MainActor
+  func add(to imageView: UIImageView, options: SymbolEffectOptions, animated: Bool) {
+    switch self {
+    case .discrete(let effect): imageView.addSymbolEffect(effect, options: options, animated: animated)
+    case .indefinite(let effect): imageView.addSymbolEffect(effect, options: options, animated: animated)
+    }
+  }
+
+  @MainActor
+  func remove(from imageView: UIImageView, options: SymbolEffectOptions, animated: Bool) {
+    switch self {
+    case .discrete(let effect):
+      imageView.removeSymbolEffect(ofType: effect, options: options, animated: animated)
+    case .indefinite(let effect):
+      imageView.removeSymbolEffect(ofType: effect, options: options, animated: animated)
+    }
+  }
+}
+
+func tinyuiSFSymbolOptions(_ configuration: [String: Any]?) -> SymbolEffectOptions {
+  var options = SymbolEffectOptions.default
+  guard let configuration else { return options }
+  let speed = (configuration["speed"] as? NSNumber)?.doubleValue ?? 1
+  if speed.isFinite, speed > 0 { options = options.speed(speed) }
+  let repetition = configuration["repeat"] as? NSNumber
+  if repetition == NSNumber(value: false) { return options.nonRepeating }
+  // JS validates safe integers; cap the conversion at the native integer range.
+  let rawCount = repetition?.doubleValue ?? 1
+  let count = rawCount.isFinite ? Int(max(1, min(rawCount, Double(Int.max) / 2))) : 1
+  let behavior = configuration["repeatBehavior"] as? String
+  let delayValue = configuration["repeatDelay"] as? NSNumber
+  let rawDelay = delayValue?.doubleValue ?? 0
+  let delay = rawDelay.isFinite && rawDelay >= 0 ? rawDelay : 0
+  let forever = configuration["repeat"] as? String == "forever" || behavior != nil || delayValue != nil
+
+  if #available(iOS 18.0, *) {
+    if behavior == "continuous" {
+      options = options.repeat(.continuous)
+    } else if repetition != nil {
+      options = options.repeat(.periodic(count, delay: delayValue == nil ? nil : delay))
+    } else if forever {
+      options = options.repeat(.periodic(nil, delay: delayValue == nil ? nil : delay))
+    }
+  } else {
+    if repetition != nil { options = options.repeat(count) }
+    else if forever { options = options.repeating }
+  }
+  return options
+}
+
+func tinyuiSFSymbolTransition(
+  _ configuration: [String: Any]
+) -> (any SymbolEffect & ContentTransitionSymbolEffect)? {
+  let type = configuration["type"] as? String
+  if type == "automatic" { return AutomaticSymbolEffect.automatic }
+  guard type == "replace" || type == "magicReplace" else { return nil }
+
+  var transition: ReplaceSymbolEffect = .replace
+  switch configuration["direction"] as? String {
+  case "downUp": transition = transition.downUp
+  case "upUp": transition = transition.upUp
+  case "offUp": transition = transition.offUp
+  default: break
+  }
+  if configuration["scope"] as? String == "byLayer" { transition = transition.byLayer }
+  if configuration["scope"] as? String == "wholeSymbol" { transition = transition.wholeSymbol }
+  if #available(iOS 18.0, *), type == "magicReplace" {
+    return ReplaceSymbolEffect.replace.magic(fallback: transition)
+  }
+  return transition
+}

package/ios/SFSymbol/TinyuiSFSymbolImage.swift

@@ -0,0 +1,103 @@
+import React
+import UIKit
+
+// Shared by Fabric measurement and the mounted view so their metrics match.
+// Keep image creation independent of UIView and the main actor: Fabric measures
+// on a background thread without dispatching synchronously to the main queue.
+@objc(TinyuiSFSymbolImage)
+public final class TinyuiSFSymbolImage: NSObject {
+  @objc(imageWithConfiguration:includeColors:)
+  public static func image(
+    configuration: [String: Any],
+    includeColors: Bool
+  ) -> UIImage? {
+    guard let name = configuration["name"] as? String, !name.isEmpty else { return nil }
+
+    var size = (configuration["size"] as? NSNumber)?.doubleValue ?? 17
+    if !size.isFinite || size <= 0 { size = 17 }
+    let weight = symbolWeight(configuration["weight"] as? String)
+    let scale = symbolScale(configuration["scale"] as? String)
+    if let fontScale = (configuration["fontScale"] as? NSNumber)?.doubleValue,
+      fontScale.isFinite, fontScale > 0
+    {
+      size *= fontScale
+    }
+
+    var symbol = UIImage.SymbolConfiguration(pointSize: CGFloat(size), weight: weight, scale: scale)
+
+    if includeColors {
+      let color = configuration["color"].flatMap(RCTConvert.uiColor) ?? .label
+      let colors: UIImage.SymbolConfiguration?
+      switch configuration["renderingMode"] as? String {
+      case "monochrome": colors = .preferringMonochrome()
+      case "multicolor": colors = .preferringMulticolor()
+      case "hierarchical": colors = UIImage.SymbolConfiguration(hierarchicalColor: color)
+      case "palette":
+        let values = configuration["paletteColors"] as? [Any] ?? []
+        let palette = Array(values.compactMap(RCTConvert.uiColor).prefix(3))
+        colors = UIImage.SymbolConfiguration(paletteColors: palette.isEmpty ? [color] : palette)
+      default: colors = nil
+      }
+      if let colors { symbol = symbol.applying(colors) }
+    }
+
+    if #available(iOS 26.0, *) {
+      let variableMode: UIImage.SymbolVariableValueMode
+      switch configuration["variableValueMode"] as? String {
+      case "color": variableMode = .color
+      case "draw": variableMode = .draw
+      default: variableMode = .automatic
+      }
+      symbol = symbol.applying(UIImage.SymbolConfiguration(variableValueMode: variableMode))
+
+      let colorMode: UIImage.SymbolColorRenderingMode
+      switch configuration["colorRenderingMode"] as? String {
+      case "flat": colorMode = .flat
+      case "gradient": colorMode = .gradient
+      default: colorMode = .automatic
+      }
+      symbol = symbol.applying(UIImage.SymbolConfiguration(colorRenderingMode: colorMode))
+    }
+
+    let asset = configuration["source"] as? String == "asset"
+    let image: UIImage?
+    if let variableValue = configuration["variableValue"] as? NSNumber {
+      let value = variableValue.doubleValue
+      let clamped = value.isFinite ? min(1, max(0, value)) : 0
+      image = asset
+        ? UIImage(named: name, in: .main, variableValue: clamped, configuration: symbol)
+        : UIImage(systemName: name, variableValue: clamped, configuration: symbol)
+    } else {
+      image = asset
+        ? UIImage(named: name, in: .main, with: symbol)
+        : UIImage(systemName: name, withConfiguration: symbol)
+    }
+    // Symbol content transitions are undefined for ordinary bitmap assets.
+    return image?.isSymbolImage == true ? image : nil
+  }
+
+  private static func symbolWeight(_ value: String?) -> UIImage.SymbolWeight {
+    switch value {
+    case "ultraLight": return .ultraLight
+    case "thin": return .thin
+    case "light": return .light
+    case "regular": return .regular
+    case "medium": return .medium
+    case "semibold": return .semibold
+    case "bold": return .bold
+    case "heavy": return .heavy
+    case "black": return .black
+    default: return .unspecified
+    }
+  }
+
+  private static func symbolScale(_ value: String?) -> UIImage.SymbolScale {
+    switch value {
+    case "small": return .small
+    case "medium": return .medium
+    case "large": return .large
+    case "unspecified": return .unspecified
+    default: return .default
+    }
+  }
+}