aix 0.7.1-alpha.8 → 0.8.0

package/README.md

@@ -5,6 +5,7 @@ alt="aix" width="1600" height="900" />
 
 UI Primitives for building AI apps in React Native.
 
+> [!WARNING]
 > aix is currently in alpha preview. The API is likely to change.
 
 ## Features
@@ -121,27 +122,35 @@ export function ChatScreen({ messages }) {
 ### Send a message
 
 When sending a message, you will likely want to scroll to it after it gets added
-to the list.
-
-Simply call `aix.current?.scrollToIndexWhenBlankSizeReady(index)` in your submit
-handler.
+to the list. Use the `scrollToIndex` prop to declaratively trigger an animated
+scroll, and `onDidScrollToIndex` to reset the state when the scroll completes.
 
 The `index` you pass should correspond to the newest message in the list. For AI
-chats, this is typically the next assistant message index.
+chats, this is typically the next assistant message index. Use a nullish value (`null | undefined`) to indicate
+no scroll target.
 
 ```tsx
 import { Keyboard } from 'react-native'
-import { useAixRef } from 'aix'
+import { useState } from 'react'
 
 function Chat() {
-  const aix = useAixRef()
+  const [scrollToIndex, setScrollToIndex] = useState<number | null>(null)
 
   const onSubmit = () => {
-    aix.current?.scrollToIndexWhenBlankSizeReady(messages.length + 1, true)
+    const newMessageIndex = messages.length + 1
+    setScrollToIndex(newMessageIndex)
+    sendMessage(message)
     requestAnimationFrame(Keyboard.dismiss)
   }
 
-  return <Aix ref={aix}>{/* ... */}</Aix>
+  return (
+    <Aix
+      scrollToIndex={scrollToIndex}
+      onDidScrollToIndex={() => setScrollToIndex(null)}
+    >
+      {/* ... */}
+    </Aix>
+  )
 }
 ```
 
@@ -197,6 +206,8 @@ scrolling for chat interfaces.
 | `additionalScrollIndicatorInsets` | `object`                       | -                                                                 | Additional insets for the scroll indicator, added to existing safe area insets. Applied to `verticalScrollIndicatorInsets` on iOS.                                                                                                                                 |
 | `mainScrollViewID`                | `string`                       | -                                                                 | The `nativeID` of the scroll view to use. If provided, will search for a scroll view with this `accessibilityIdentifier`.                                                                                                                                          |
 | `penultimateCellIndex`            | `number`                       | -                                                                 | The index of the second-to-last message (typically the last user message in AI chat apps). Used to determine which message will be scrolled into view. Useful when you have custom message types like timestamps in your list.                                     |
+| `scrollToIndex`                   | `number`                       | -                                                                 | When set, triggers an animated scroll to this cell index. Use a nullish value (`null` or `undefined`) to indicate no scroll target. After the scroll completes, `onDidScrollToIndex` is called. Reset after receiving the callback. |
+| `onDidScrollToIndex`              | `() => void`                   | -                                                                 | Called when the animated scroll to `scrollToIndex` completes. Use this to clear the `scrollToIndex` state.                                                                                                                                                         |
 
 #### Ref Methods
 
@@ -207,19 +218,14 @@ const aix = useAixRef()
 
 // Scroll to the end of the content
 aix.current?.scrollToEnd(animated)
-
-// Scroll to a specific index when the blank size is ready
-aix.current?.scrollToIndexWhenBlankSizeReady(
-  index,
-  animated,
-  waitForKeyboardToEnd
-)
 ```
 
-| Method                            | Parameters                                                          | Description                                                                |
-| --------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `scrollToEnd`                     | `animated?: boolean`                                                | Scrolls to the end of the content.                                         |
-| `scrollToIndexWhenBlankSizeReady` | `index: number, animated?: boolean, waitForKeyboardToEnd?: boolean` | Scrolls to a specific cell index once the blank size calculation is ready. |
+| Method        | Parameters           | Description                        |
+| ------------- | -------------------- | ---------------------------------- |
+| `scrollToEnd` | `animated?: boolean` | Scrolls to the end of the content. |
+
+> **Note:** For scrolling to a specific message index, prefer using the
+> declarative `scrollToIndex` prop instead of imperative methods.
 
 ---
 
@@ -258,31 +264,8 @@ Accepts all standard React Native `View` props.
   <Composer />
 </AixFooter>
 ```
-
 ---
 
-### `useAixRef`
-
-A hook that returns a ref to access imperative methods on the `Aix` component.
-
-```tsx
-import { useAixRef } from 'aix'
-
-function Chat({ messages }) {
-  const aix = useAixRef()
-  const send = useSendMessage()
-
-  const handleSend = () => {
-    // Scroll to end after sending a message
-    send(message)
-    aix.current?.scrollToIndexWhenBlankSizeReady(messages.length + 1, true)
-    requestAnimationFrame(Keyboard.dismiss)
-  }
-
-  return <Aix ref={aix}>{/* ... */}</Aix>
-}
-```
-
 ### Rules
 
 - Do **NOT** apply padding to `contentContainerStyle`. Instead, use padding on

package/ios/HybridAix.swift

@@ -326,7 +326,7 @@ class HybridAix: HybridAixSpec, AixContext, KeyboardNotificationsDelegate {
     }
 
     private func calculateBlankSize(keyboardHeight: CGFloat, additionalContentInsetBottom: CGFloat) -> CGFloat {
-        guard let scrollView, let blankView else { 
+        guard let scrollView, let blankView else {
             return lastCalculatedBlankSize
         }
 
@@ -646,7 +646,15 @@ class HybridAix: HybridAixSpec, AixContext, KeyboardNotificationsDelegate {
             return
         }
 
-        // Skip when animated scroll is in progress to avoid interfering
+        // Check if this blankView matches the scrollToIndex target
+        // This handles the case where isLast prop updates after cell registration
+        if let target = scrollToIndexTarget, target == index {
+            print("[Aix] reportBlankViewSizeChange - scrollToIndex target matches")
+            performScrollToIndex()
+            return
+        }
+
+        // Skip regular inset updates when animated scroll is in progress to avoid interfering
         if scrollToIndexTarget != nil {
             print("[Aix] reportBlankViewSizeChange - skipping, scrollToIndex active")
             return
@@ -740,47 +748,47 @@ class HybridAix: HybridAixSpec, AixContext, KeyboardNotificationsDelegate {
         cells.setObject(cell, forKey: NSNumber(value: cell.index))
 
         if cell.isLast {
-            print("[Aix] registerCell - this is blankView, setting and reporting size")
+            print("[Aix] registerCell - this is blankView")
             blankView = cell
+
+            if let target = scrollToIndexTarget, target == Int(cell.index) {
+                print("[Aix] registerCell - scrollToIndex target matches!")
+                performScrollToIndex()
+                return
+            }
+
             let currentSize = cell.view.bounds.size
             reportBlankViewSizeChange(size: currentSize, index: Int(cell.index))
         } else if !didScrollToEndInitially {
-            // During initial mount, check if all cells are now registered
             print("[Aix] registerCell - during initial mount, checking completion")
             tryCompleteInitialLayout()
         } else {
-            // After initial layout, apply insets for blankSize compensation
             print("[Aix] registerCell - post-initial, applying insets")
 
-            // Only perform animated scroll when scrollToIndex is explicitly set.
-            // This happens when a new user message is added (becomes penultimate cell).
             if let target = scrollToIndexTarget, let blankView, target == Int(blankView.index) {
-                let isKeyboardTransitioning = startEvent != nil
                 print("[Aix] registerCell - scrollToIndex target matches")
-
-                applyAllInsets()
-
-                if isKeyboardTransitioning {
-                    // Keyboard is animating - defer our scroll to avoid conflicts
-                    // handleKeyboardDidMove will execute the scroll when keyboard animation ends
-                    print("[Aix] registerCell - deferring animated scroll until keyboard animation completes")
-                    pendingAnimatedScroll = true
-                    // onDidScrollToIndex will be called when keyboard animation completes
-                } else {
-                    // No keyboard animation - scroll immediately
-                    // Call onDidScrollToIndex after animation completes so scrollToIndexTarget
-                    // stays set during animation (used by skip logic in reportCellHeightChange)
-                    scrollToEndInternal(animated: true) { [weak self] in
-                        self?.onDidScrollToIndex?()
-                    }
-                }
+                performScrollToIndex()
             } else if scrollToIndexTarget == nil {
-                // Only apply insets when no animated scroll is active
                 applyAllInsets()
             }
         }
     }
 
+    /// Performs animated scroll to end with proper keyboard transition handling.
+    /// If keyboard is animating, defers scroll until animation completes.
+    private func performScrollToIndex() {
+        applyAllInsets()
+
+        if startEvent != nil {
+            print("[Aix] performScrollToIndex - deferring until keyboard animation completes")
+            pendingAnimatedScroll = true
+        } else {
+            scrollToEndInternal(animated: true) { [weak self] in
+                self?.onDidScrollToIndex?()
+            }
+        }
+    }
+
     func unregisterCell(_ cell: HybridAixCellView) {
         cells.removeObject(forKey: NSNumber(value: cell.index))
 

package/ios/HybridAixComposer.swift

@@ -21,15 +21,15 @@ class HybridAixComposer: HybridAixComposerSpec {
             if let ctx = cachedAixContext {
                 applyKeyboardTransform(height: ctx.keyboardHeight, heightWhenOpen: ctx.keyboardHeightWhenOpen, animated: false)
             }
+            // Re-apply text input fixes (content inset adjustment depends on stickToKeyboard)
+            applyTextInputFixes()
         }
     }
 
     var fixInput: Bool? = nil {
         didSet {
             cachedTextInput = nil
-            if fixInput == true {
-                resolveTextInput()
-            }
+            applyTextInputFixes()
         }
     }
 
@@ -141,8 +141,8 @@ class HybridAixComposer: HybridAixComposerSpec {
             applyKeyboardTransform(height: ctx.keyboardHeight, heightWhenOpen: ctx.keyboardHeightWhenOpen, animated: false)
         }
 
-        // Resolve text input once the hierarchy is connected
-        resolveTextInput()
+        // Apply text input fixes once the hierarchy is connected
+        applyTextInputFixes()
     }
 
     /// Called when the view is about to be removed from superview
@@ -179,12 +179,20 @@ class HybridAixComposer: HybridAixComposerSpec {
         return input
     }
 
-    /// Resolve the text input and apply patches
-    private func resolveTextInput() {
-        print("[Aix] resolveTextInput: fixInput=\(fixInput), textInput=\(textInput)")
-        guard fixInput == true, let input = textInput else { return }
+    /// Apply fixes to the text input based on current props
+    private func applyTextInputFixes() {
+        guard let input = textInput else { return }
         guard let scrollView = input as? UIScrollView else { return }
-        print("[Aix] resolveTextInput: scrollView=\(scrollView)")
+
+        // When stickToKeyboard is enabled, the footer uses transforms to position above keyboard.
+        // iOS calculates safe area based on frame (not visual position), so it incorrectly adds
+        // bottom safe area insets. Disable automatic adjustment since we manage positioning.
+        if stickToKeyboard?.enabled == true {
+            scrollView.contentInsetAdjustmentBehavior = .never
+        }
+
+        // Apply fixInput patches
+        guard fixInput == true else { return }
         scrollView.showsVerticalScrollIndicator = false
         scrollView.showsHorizontalScrollIndicator = false
         scrollView.bounces = false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aix",
-  "version": "0.7.1-alpha.8",
+  "version": "0.8.0",
   "author": "Fernando Rojo",
   "repository": {
     "type": "git",