aix 0.3.1 → 0.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +101 -159
- package/ios/HybridAix.swift +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,32 +1,12 @@
|
|
|
1
|
-
|
|
2
|
-
alt="aix" width="1600" height="900" />
|
|
1
|
+
# aix
|
|
3
2
|
|
|
4
|
-
|
|
3
|
+
Primitives for building beautiful AI chat apps with React Native.
|
|
5
4
|
|
|
6
|
-
|
|
5
|
+
> aix is currently in alpha preview. The API will change, and it is not yet feature complete.
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
We're rewriting the engine that powers the chat experience in the v0 mobile app with a focus on native feel.
|
|
9
8
|
|
|
10
|
-
|
|
11
|
-
- Animate scrolling to new messages when they send
|
|
12
|
-
- Float messages to the top of the screen with automated "blank size" handling
|
|
13
|
-
- Animate message content as it streams
|
|
14
|
-
- Keyboard handling out-of-the-box with no external dependencies
|
|
15
|
-
- Support for absolute-positioned composers
|
|
16
|
-
- Detect "is scrolled near end" for ScrollToEnd buttons
|
|
17
|
-
|
|
18
|
-
To learn about the motivation behind AIX, you can read our blog post on
|
|
19
|
-
[How we built the v0 iOS app](https://vercel.com/blog/how-we-built-the-v0-ios-app).
|
|
20
|
-
AIX is an opinionated, feature-complete, and extensible way to implement every
|
|
21
|
-
single feature mentioned in that blog post.
|
|
22
|
-
|
|
23
|
-
When building AIX, we started by copying the code from v0 into a separate
|
|
24
|
-
repository. However, as we worked to make it flexible for use cases outside of
|
|
25
|
-
our own app, we decided to rewrite it from scratch in native code. What you see
|
|
26
|
-
here is a Nitro Module which handles all business logic in UIKit. We plan on
|
|
27
|
-
adding support for Android as well and welcome contributions.
|
|
28
|
-
|
|
29
|
-
> aix is currently in alpha preview. The API may change.
|
|
9
|
+
aix is a native module with UIKit with Nitro Modules.
|
|
30
10
|
|
|
31
11
|
## Installation
|
|
32
12
|
|
|
@@ -34,195 +14,133 @@ adding support for Android as well and welcome contributions.
|
|
|
34
14
|
npm i aix react-native-nitro-modules
|
|
35
15
|
```
|
|
36
16
|
|
|
37
|
-
Next, rebuild your native app. For Expo users, run `npx expo prebuild` and
|
|
38
|
-
rebuild.
|
|
39
|
-
|
|
40
|
-
- For a full example, see the [example app](./react-native-aix/example/App.tsx).
|
|
17
|
+
Next, rebuild your native app. For Expo users, run `npx expo prebuild` and rebuild.
|
|
41
18
|
|
|
42
19
|
## Usage
|
|
43
20
|
|
|
44
21
|
Wrap your `ScrollView` with `Aix`, and wrap your messages with `AixCell`.
|
|
45
22
|
|
|
23
|
+
<details>
|
|
24
|
+
<summary>Click here to view a full example</summary>
|
|
25
|
+
</details>
|
|
26
|
+
|
|
46
27
|
```tsx
|
|
47
|
-
import { Aix, AixCell } from 'aix'
|
|
48
|
-
import { Message } from 'path/to/your/message'
|
|
49
|
-
import { Composer } from 'path/to/your/composer'
|
|
28
|
+
import { Aix, AixCell } from 'aix';
|
|
29
|
+
import { Message } from 'path/to/your/message';
|
|
30
|
+
import { Composer } from 'path/to/your/composer';
|
|
50
31
|
|
|
51
32
|
export function ChatScreen({ messages }) {
|
|
52
33
|
return (
|
|
53
|
-
<Aix style={{ flex: 1 }}
|
|
34
|
+
<Aix style={{ flex: 1 }}>
|
|
54
35
|
<ScrollView>
|
|
55
36
|
{messages.map((message) => (
|
|
56
|
-
<AixCell
|
|
37
|
+
<AixCell
|
|
38
|
+
key={message.id}
|
|
39
|
+
index={index}
|
|
40
|
+
isLast={index === messages.length - 1}
|
|
41
|
+
>
|
|
57
42
|
<Message message={message} />
|
|
58
43
|
</AixCell>
|
|
59
44
|
))}
|
|
60
45
|
</ScrollView>
|
|
61
46
|
</Aix>
|
|
62
|
-
)
|
|
47
|
+
);
|
|
63
48
|
}
|
|
64
49
|
```
|
|
65
50
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
To add a floating composer which lets content scroll under it, you can use the
|
|
69
|
-
`AixFooter`. Pair it with `Aix.scrollOnFooterSizeUpdate` to ensure content
|
|
70
|
-
scrolls under the footer when it changes size.
|
|
51
|
+
To add a floating composer which lets content scroll under it, you can use the `AixFooter` and `KeyboardStickyView` from `react-native-keyboard-controller`:
|
|
71
52
|
|
|
72
53
|
```tsx
|
|
73
|
-
import { Aix, AixCell, AixFooter } from 'aix'
|
|
54
|
+
import { Aix, AixCell, AixFooter } from 'aix';
|
|
55
|
+
import { KeyboardStickyView } from 'react-native-keyboard-controller';
|
|
74
56
|
|
|
75
57
|
export function ChatScreen({ messages }) {
|
|
76
|
-
const { bottom } = useSafeAreaInsets()
|
|
77
|
-
|
|
78
58
|
return (
|
|
79
|
-
<Aix
|
|
80
|
-
style={{ flex: 1 }}
|
|
81
|
-
shouldStartAtEnd
|
|
82
|
-
scrollOnFooterSizeUpdate={{
|
|
83
|
-
enabled: true,
|
|
84
|
-
scrolledToEndThreshold: 100,
|
|
85
|
-
animated: false,
|
|
86
|
-
}}
|
|
87
|
-
>
|
|
59
|
+
<Aix style={{ flex: 1 }}>
|
|
88
60
|
<ScrollView>
|
|
89
61
|
{messages.map((message) => (
|
|
90
|
-
<AixCell
|
|
62
|
+
<AixCell
|
|
63
|
+
key={message.id}
|
|
64
|
+
index={index}
|
|
65
|
+
isLast={index === messages.length - 1}
|
|
66
|
+
>
|
|
91
67
|
<Message message={message} />
|
|
92
68
|
</AixCell>
|
|
93
69
|
))}
|
|
94
70
|
</ScrollView>
|
|
95
71
|
|
|
96
|
-
<
|
|
97
|
-
style={{ position: 'absolute', inset: 0, top: 'auto'
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
whenKeyboardOpen: 0,
|
|
102
|
-
whenKeyboardClosed: -bottom,
|
|
103
|
-
},
|
|
104
|
-
}}
|
|
105
|
-
>
|
|
106
|
-
<Composer />
|
|
107
|
-
</AixFooter>
|
|
72
|
+
<KeyboardStickyView offset={{ opened: 0, closed: -bottomInsetPadding }}>
|
|
73
|
+
<AixFooter style={{ position: 'absolute', inset: 0, top: 'auto'}}>
|
|
74
|
+
<Composer />
|
|
75
|
+
</AixFooter>
|
|
76
|
+
</KeyboardStickyView>
|
|
108
77
|
</Aix>
|
|
109
|
-
)
|
|
110
|
-
}
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
### Send a message
|
|
114
|
-
|
|
115
|
-
When sending a message, you will likely want to scroll to it after it gets added
|
|
116
|
-
to the list.
|
|
117
|
-
|
|
118
|
-
Simply call `aix.current?.scrollToIndexWhenBlankSizeReady(index)` in your submit
|
|
119
|
-
handler.
|
|
120
|
-
|
|
121
|
-
The `index` you pass should correspond to the newest message in the list. For AI
|
|
122
|
-
chats, this is typically the next assistant message index.
|
|
123
|
-
|
|
124
|
-
```tsx
|
|
125
|
-
import { Keyboard } from 'react-native'
|
|
126
|
-
import { useAixRef } from 'aix'
|
|
127
|
-
|
|
128
|
-
function Chat() {
|
|
129
|
-
const aix = useAixRef()
|
|
130
|
-
|
|
131
|
-
const onSubmit = () => {
|
|
132
|
-
aix.current?.scrollToIndexWhenBlankSizeReady(messages.length + 1, true)
|
|
133
|
-
requestAnimationFrame(Keyboard.dismiss)
|
|
134
|
-
}
|
|
135
|
-
|
|
136
|
-
return <Aix ref={aix}>{/* ... */}</Aix>
|
|
78
|
+
);
|
|
137
79
|
}
|
|
138
80
|
```
|
|
139
81
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
You can use `onScrolledNearEndChange` to show a "scroll to end" button when the
|
|
143
|
-
user scrolls away from the bottom:
|
|
144
|
-
|
|
145
|
-
```tsx
|
|
146
|
-
import { Aix, useAixRef } from 'aix'
|
|
147
|
-
import { useState } from 'react'
|
|
148
|
-
import { Button } from 'react-native'
|
|
149
|
-
|
|
150
|
-
function Chat() {
|
|
151
|
-
const aix = useAixRef()
|
|
152
|
-
const [isNearEnd, setIsNearEnd] = useState(false)
|
|
153
|
-
|
|
154
|
-
return (
|
|
155
|
-
<Aix ref={aix} scrollEndReachedThreshold={200} onScrolledNearEndChange={setIsNearEnd}>
|
|
156
|
-
{/* ScrollView and messages... */}
|
|
82
|
+
## TODOs
|
|
157
83
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
</Aix>
|
|
162
|
-
)
|
|
163
|
-
}
|
|
164
|
-
```
|
|
84
|
+
- [ ] Android support
|
|
85
|
+
- [ ] LegendList support
|
|
86
|
+
- [ ] FlashList support
|
|
165
87
|
|
|
166
88
|
## API Reference
|
|
167
89
|
|
|
168
90
|
### `Aix`
|
|
169
91
|
|
|
170
|
-
The main container component that provides keyboard-aware behavior and manages
|
|
171
|
-
scrolling for chat interfaces.
|
|
92
|
+
The main container component that provides keyboard-aware behavior and manages scrolling for chat interfaces.
|
|
172
93
|
|
|
173
94
|
#### Props
|
|
174
95
|
|
|
175
|
-
| Prop
|
|
176
|
-
|
|
177
|
-
| `shouldStartAtEnd`
|
|
178
|
-
| `scrollOnFooterSizeUpdate`
|
|
179
|
-
| `scrollEndReachedThreshold`
|
|
180
|
-
| `onScrolledNearEndChange`
|
|
181
|
-
| `additionalContentInsets`
|
|
182
|
-
| `additionalScrollIndicatorInsets` | `object`
|
|
183
|
-
| `mainScrollViewID`
|
|
184
|
-
| `penultimateCellIndex`
|
|
96
|
+
| Prop | Type | Default | Description |
|
|
97
|
+
|------|------|---------|-------------|
|
|
98
|
+
| `shouldStartAtEnd` | `boolean` | - | Whether the scroll view should start scrolled to the end of the content. |
|
|
99
|
+
| `scrollOnFooterSizeUpdate` | `object` | `{ enabled: true, scrolledToEndThreshold: 100, animated: false }` | Control the behavior of scrolling when the footer size changes. By default, changing the height of the footer will shift content up in the scroll view. |
|
|
100
|
+
| `scrollEndReachedThreshold` | `number` | `max(blankSize, 200)` | The number of pixels from the bottom of the scroll view to the end of the content that is considered "near the end". Used by `onScrolledNearEndChange` and to determine if content should shift up when keyboard opens. |
|
|
101
|
+
| `onScrolledNearEndChange` | `(isNearEnd: boolean) => void` | - | Callback fired when the scroll position transitions between "near end" and "not near end" states. Reactive to user scrolling, content size changes, parent size changes, and keyboard height changes. Uses `scrollEndReachedThreshold` to determine the threshold. |
|
|
102
|
+
| `additionalContentInsets` | `object` | - | Additional content insets applied when keyboard is open or closed. Shape: `{ top?: { whenKeyboardOpen, whenKeyboardClosed }, bottom?: { whenKeyboardOpen, whenKeyboardClosed } }` |
|
|
103
|
+
| `additionalScrollIndicatorInsets` | `object` | - | Additional insets for the scroll indicator, added to existing safe area insets. Applied to `verticalScrollIndicatorInsets` on iOS. |
|
|
104
|
+
| `mainScrollViewID` | `string` | - | The `nativeID` of the scroll view to use. If provided, will search for a scroll view with this `accessibilityIdentifier`. |
|
|
105
|
+
| `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. |
|
|
185
106
|
|
|
186
107
|
#### Ref Methods
|
|
187
108
|
|
|
188
109
|
Access these methods via `useAixRef()`:
|
|
189
110
|
|
|
190
111
|
```tsx
|
|
191
|
-
const aix = useAixRef()
|
|
112
|
+
const aix = useAixRef();
|
|
192
113
|
|
|
193
114
|
// Scroll to the end of the content
|
|
194
|
-
aix.current?.scrollToEnd(animated)
|
|
115
|
+
aix.current?.scrollToEnd(animated);
|
|
195
116
|
|
|
196
117
|
// Scroll to a specific index when the blank size is ready
|
|
197
|
-
aix.current?.scrollToIndexWhenBlankSizeReady(index, animated, waitForKeyboardToEnd)
|
|
118
|
+
aix.current?.scrollToIndexWhenBlankSizeReady(index, animated, waitForKeyboardToEnd);
|
|
198
119
|
```
|
|
199
120
|
|
|
200
|
-
| Method
|
|
201
|
-
|
|
202
|
-
| `scrollToEnd`
|
|
121
|
+
| Method | Parameters | Description |
|
|
122
|
+
|--------|------------|-------------|
|
|
123
|
+
| `scrollToEnd` | `animated?: boolean` | Scrolls to the end of the content. |
|
|
203
124
|
| `scrollToIndexWhenBlankSizeReady` | `index: number, animated?: boolean, waitForKeyboardToEnd?: boolean` | Scrolls to a specific cell index once the blank size calculation is ready. |
|
|
204
125
|
|
|
205
126
|
---
|
|
206
127
|
|
|
207
128
|
### `AixCell`
|
|
208
129
|
|
|
209
|
-
A wrapper component for each message in the list. It communicates cell position
|
|
210
|
-
and dimensions to the parent `Aix` component.
|
|
130
|
+
A wrapper component for each message in the list. It communicates cell position and dimensions to the parent `Aix` component.
|
|
211
131
|
|
|
212
132
|
#### Props
|
|
213
133
|
|
|
214
|
-
| Prop
|
|
215
|
-
|
|
216
|
-
| `index`
|
|
217
|
-
| `isLast` | `boolean` | Yes
|
|
134
|
+
| Prop | Type | Required | Description |
|
|
135
|
+
|------|------|----------|-------------|
|
|
136
|
+
| `index` | `number` | Yes | The index of this cell in the message list. |
|
|
137
|
+
| `isLast` | `boolean` | Yes | Whether this cell is the last item in the list. Used for scroll positioning and animations. |
|
|
218
138
|
|
|
219
139
|
---
|
|
220
140
|
|
|
221
141
|
### `AixFooter`
|
|
222
142
|
|
|
223
|
-
A footer component for floating composers that allows content to scroll
|
|
224
|
-
underneath it. The footer's height is automatically tracked for proper scroll
|
|
225
|
-
offset calculations.
|
|
143
|
+
A footer component for floating composers that allows content to scroll underneath it. The footer's height is automatically tracked for proper scroll offset calculations.
|
|
226
144
|
|
|
227
145
|
#### Props
|
|
228
146
|
|
|
@@ -230,8 +148,7 @@ Accepts all standard React Native `View` props.
|
|
|
230
148
|
|
|
231
149
|
#### Important Notes
|
|
232
150
|
|
|
233
|
-
- **Do not apply vertical padding** (`padding`, `paddingBottom`) directly to
|
|
234
|
-
`AixFooter`. Apply padding to a child view instead.
|
|
151
|
+
- **Do not apply vertical padding** (`padding`, `paddingBottom`) directly to `AixFooter`. Apply padding to a child view instead.
|
|
235
152
|
- Position the footer absolutely at the bottom of the `Aix` container:
|
|
236
153
|
|
|
237
154
|
```tsx
|
|
@@ -247,32 +164,57 @@ Accepts all standard React Native `View` props.
|
|
|
247
164
|
A hook that returns a ref to access imperative methods on the `Aix` component.
|
|
248
165
|
|
|
249
166
|
```tsx
|
|
250
|
-
import { useAixRef } from 'aix'
|
|
167
|
+
import { useAixRef } from 'aix';
|
|
251
168
|
|
|
252
169
|
function Chat({ messages }) {
|
|
253
|
-
const aix = useAixRef()
|
|
170
|
+
const aix = useAixRef();
|
|
254
171
|
const send = useSendMessage()
|
|
255
|
-
|
|
172
|
+
|
|
256
173
|
const handleSend = () => {
|
|
257
174
|
// Scroll to end after sending a message
|
|
258
|
-
send(message)
|
|
259
|
-
aix.current?.scrollToIndexWhenBlankSizeReady(messages.length + 1, true)
|
|
260
|
-
requestAnimationFrame(Keyboard.dismiss)
|
|
261
|
-
}
|
|
262
|
-
|
|
263
|
-
return <Aix ref={aix}>{/* ... */}</Aix
|
|
175
|
+
send(message);
|
|
176
|
+
aix.current?.scrollToIndexWhenBlankSizeReady(messages.length + 1, true);
|
|
177
|
+
requestAnimationFrame(Keyboard.dismiss);
|
|
178
|
+
};
|
|
179
|
+
|
|
180
|
+
return <Aix ref={aix}>{/* ... */}</Aix>;
|
|
264
181
|
}
|
|
265
182
|
```
|
|
266
183
|
|
|
267
184
|
---
|
|
268
185
|
|
|
186
|
+
### Scroll to End Button
|
|
187
|
+
|
|
188
|
+
You can use `onScrolledNearEndChange` to show a "scroll to end" button when the user scrolls away from the bottom:
|
|
189
|
+
|
|
190
|
+
```tsx
|
|
191
|
+
import { Aix, useAixRef } from 'aix';
|
|
192
|
+
import { useState } from 'react';
|
|
193
|
+
|
|
194
|
+
function Chat() {
|
|
195
|
+
const aix = useAixRef();
|
|
196
|
+
const [isNearEnd, setIsNearEnd] = useState(false);
|
|
197
|
+
|
|
198
|
+
return (
|
|
199
|
+
<Aix
|
|
200
|
+
ref={aix}
|
|
201
|
+
scrollEndReachedThreshold={200}
|
|
202
|
+
onScrolledNearEndChange={setIsNearEnd}
|
|
203
|
+
>
|
|
204
|
+
{/* ScrollView and messages... */}
|
|
205
|
+
|
|
206
|
+
{!isNearEnd && (
|
|
207
|
+
<Button onPress={() => aix.current?.scrollToEnd(true)} />
|
|
208
|
+
)}
|
|
209
|
+
</Aix>
|
|
210
|
+
);
|
|
211
|
+
}
|
|
212
|
+
```
|
|
213
|
+
|
|
269
214
|
## TODOs
|
|
270
215
|
|
|
271
|
-
- [ ] Android support
|
|
272
|
-
- [ ] LegendList support
|
|
273
|
-
- [ ] FlashList support
|
|
274
216
|
|
|
275
217
|
## Requirements
|
|
276
218
|
|
|
277
219
|
- React Native v0.78.0 or higher
|
|
278
|
-
- Node 18.0.0 or higher
|
|
220
|
+
- Node 18.0.0 or higher
|
package/ios/HybridAix.swift
CHANGED
|
@@ -448,10 +448,10 @@ class HybridAix: HybridAixSpec, AixContext, KeyboardNotificationsDelegate {
|
|
|
448
448
|
)
|
|
449
449
|
|
|
450
450
|
print("[aix] applyContentInset \(targetBottom)")
|
|
451
|
+
onWillApplyContentInsets?(insets)
|
|
451
452
|
|
|
452
453
|
// If shouldApplyContentInsets is explicitly false, call callback and return
|
|
453
454
|
if shouldApplyContentInsets == false {
|
|
454
|
-
onWillApplyContentInsets?(insets)
|
|
455
455
|
return
|
|
456
456
|
}
|
|
457
457
|
|