📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,27 @@
|
||||
# Drop-in replacements for RN community libraries
|
||||
|
||||
`@expo/ui` ships API-compatible replacements for popular React Native community libraries, powered by native `@expo/ui` components (Jetpack Compose on Android, SwiftUI on iOS). Use these when migrating an existing app off a community UI dependency — the API matches the library being replaced, so the swap is usually just the import path.
|
||||
|
||||
## Available replacements
|
||||
|
||||
Every drop-in lives under `@expo/ui/community/<kebab-case-name>`. Note which are default vs named imports.
|
||||
|
||||
| Replaces | Import |
|
||||
|----------|--------|
|
||||
| `@gorhom/bottom-sheet` | `import BottomSheet, { BottomSheetView } from '@expo/ui/community/bottom-sheet'` |
|
||||
| `@react-native-community/datetimepicker` | `import DateTimePicker from '@expo/ui/community/datetime-picker'` |
|
||||
| `@react-native-masked-view/masked-view` | `import { MaskedView } from '@expo/ui/community/masked-view'` |
|
||||
| `@react-native-menu/menu` | `import { MenuView } from '@expo/ui/community/menu'` |
|
||||
| `react-native-pager-view` | `import PagerView from '@expo/ui/community/pager-view'` |
|
||||
| `@react-native-picker/picker` | `import { Picker } from '@expo/ui/community/picker'` |
|
||||
| `@react-native-segmented-control/segmented-control` | `import SegmentedControl from '@expo/ui/community/segmented-control'` |
|
||||
| `@react-native-community/slider` | `import Slider from '@expo/ui/community/slider'` |
|
||||
|
||||
## Confirming the API
|
||||
|
||||
Each component has a dedicated docs page with setup and usage:
|
||||
|
||||
- Overview — https://docs.expo.dev/versions/latest/sdk/ui/drop-in-replacements/index.md
|
||||
- Per component — https://docs.expo.dev/versions/latest/sdk/ui/drop-in-replacements/{component}/index.md (slug is the component name lowercased, no hyphens, e.g. `bottomsheet`, `datetimepicker`, `segmentedcontrol`)
|
||||
|
||||
The installed package's TypeScript types (`.d.ts`) are the most reliable source of truth for the exact props on your SDK version (@expo/ui is versioned with the SDK and its API can change between versions). Use the doc page to find platform support and any props that differ from the library being replaced.
|
||||
@@ -0,0 +1,73 @@
|
||||
# Platform-specific Android UI: `@expo/ui/jetpack-compose`
|
||||
|
||||
> **Android only.** Code that imports from `@expo/ui/jetpack-compose` will crash on iOS with "Unable to get view config" errors. Always place this code in an `.android.tsx` component file or guard it with `Platform.OS === 'android'`. `Host` must be imported from `@expo/ui` (the universal root), not from `@expo/ui/jetpack-compose`.
|
||||
|
||||
Use this layer only when the universal `@expo/ui` components don't cover what you need on Android (see `./universal.md` first). This requires a platform-specific tree.
|
||||
|
||||
### File placement with Expo Router
|
||||
|
||||
**Do not put `.android.tsx` files inside `app/` or `src/app/`.** Expo Router does not support platform-extension suffixes for route files and will throw a "no fallback sibling" Render Error.
|
||||
|
||||
Place platform-specific component files in `components/` (or any directory outside the route tree), then import them from a regular route file:
|
||||
|
||||
```
|
||||
src/components/ProductList.android.tsx ← Compose tree lives here
|
||||
src/app/product-list.tsx ← regular Expo Router route, imports the component
|
||||
```
|
||||
|
||||
`src/app/product-list.tsx`:
|
||||
```tsx
|
||||
import ProductList from '../components/ProductList';
|
||||
export default ProductList;
|
||||
```
|
||||
|
||||
Alternatively, keep everything in one regular route file and branch on `Platform.OS`:
|
||||
|
||||
```tsx
|
||||
// src/app/product-list.tsx
|
||||
import { Platform } from 'react-native';
|
||||
const ComposeList = Platform.OS === 'android' ? require('../components/ProductList.android').default : null;
|
||||
```
|
||||
|
||||
## Instructions
|
||||
|
||||
- Expo UI's API mirrors Jetpack Compose's API. Use Jetpack Compose and Material Design 3 knowledge to decide which components or modifiers to use. If you need deeper Jetpack Compose or Material 3 guidance (e.g. which component to pick, layout patterns, theming), spawn a subagent to research [Jetpack Compose](https://developer.android.com/develop/ui/compose/components) and [Material Design 3](https://m3.material.io/) best practices.
|
||||
- Components are imported from `@expo/ui/jetpack-compose`, modifiers from `@expo/ui/jetpack-compose/modifiers`.
|
||||
- **Before writing any code, run the list-components script** to get the exact components and modifiers available in the installed version:
|
||||
```bash
|
||||
node <skill-root>/scripts/list-components.js <project-path> # names only (compact)
|
||||
node <skill-root>/scripts/list-components.js <project-path> --docs # with one-line descriptions
|
||||
```
|
||||
(`<skill-root>` is the directory containing this `references/` folder.)
|
||||
- **Always read the `.d.ts` type files** to confirm prop shapes and signatures — read the relevant `{ComponentName}/index.d.ts` from the installed `@expo/ui/jetpack-compose` package in `node_modules`. This is the most reliable source of truth.
|
||||
- When about to use a component, fetch its docs to confirm the API — https://docs.expo.dev/versions/latest/sdk/ui/jetpack-compose/{component-name}/index.md
|
||||
- When unsure about a modifier's API, refer to the docs — https://docs.expo.dev/versions/latest/sdk/ui/jetpack-compose/modifiers/index.md
|
||||
- Every Jetpack Compose tree must be wrapped in `Host`. Use `<Host matchContents>` for intrinsic sizing, or `<Host style={{ flex: 1 }}>` when you need explicit size (e.g. as a parent of `LazyColumn`). Example:
|
||||
|
||||
```jsx
|
||||
import { Host } from "@expo/ui"; // Host always from universal root
|
||||
import { Column, Button, Text } from "@expo/ui/jetpack-compose";
|
||||
import { fillMaxWidth, paddingAll } from "@expo/ui/jetpack-compose/modifiers";
|
||||
|
||||
<Host matchContents>
|
||||
<Column verticalArrangement={{ spacedBy: 8 }} modifiers={[fillMaxWidth(), paddingAll(16)]}>
|
||||
<Text style={{ typography: "titleLarge" }}>Hello</Text>
|
||||
<Button onPress={() => alert("Pressed!")}>Press me</Button>
|
||||
</Column>
|
||||
</Host>;
|
||||
```
|
||||
|
||||
- `RNHostView` embeds React Native components inside a Jetpack Compose tree (the same concept as in `@expo/ui/swift-ui`) — wrap any RN child in `<RNHostView>`.
|
||||
- If a required composable or modifier is missing in Expo UI, it can be extended via a local Expo module. See: https://docs.expo.dev/guides/expo-ui-jetpack-compose/extending/index.md. Confirm with the user before extending.
|
||||
|
||||
## Key Components
|
||||
|
||||
- **LazyColumn** — Use instead of react-native `ScrollView`/`FlatList` for scrollable lists. Wrap in `<Host style={{ flex: 1 }}>`. Not suitable for large lists — each item is a JSX node processed on the JS thread, which causes noticeable slowdowns at scale.
|
||||
- **Icon** — Use `<Icon source={require('./icon.xml')} size={24} />` with Android XML vector drawables. To get icons: go to [Material Symbols](https://fonts.google.com/icons), select an icon, choose the Android platform, and download the XML vector drawable. Save these as `.xml` files in your project's `assets/` directory (e.g. `assets/icons/wifi.xml`). Metro bundles `.xml` assets automatically — no metro config changes needed.
|
||||
|
||||
## useNativeState
|
||||
|
||||
`useNativeState` creates observable state that updates synchronously on the UI thread via worklets, enabling immediate native state changes without waiting for a React render cycle. Requires `react-native-worklets` — without it updates still go through React and flickering remains. Best for real-time interactions where synchronous updates matter, e.g. a text field that masks or formats input as the user types.
|
||||
|
||||
- `ObservableState.value` is readable/writable from worklets; `onChange` fires a worklet listener on state change.
|
||||
- Docs — https://docs.expo.dev/versions/latest/sdk/ui/jetpack-compose/usenativestate/index.md
|
||||
@@ -0,0 +1,73 @@
|
||||
# Platform-specific iOS UI: `@expo/ui/swift-ui`
|
||||
|
||||
> **iOS only.** Code that imports from `@expo/ui/swift-ui` will crash on Android with "Unable to get view config" errors. Always place this code in an `.ios.tsx` component file or guard it with `Platform.OS === 'ios'`. `Host` must be imported from `@expo/ui` (the universal root), not from `@expo/ui/swift-ui`.
|
||||
|
||||
Use this layer only when the universal `@expo/ui` components don't cover what you need on iOS (see `./universal.md` first). This requires a platform-specific tree.
|
||||
|
||||
### File placement with Expo Router
|
||||
|
||||
**Do not put `.ios.tsx` files inside `app/` or `src/app/`.** Expo Router does not support platform-extension suffixes for route files and will throw a "no fallback sibling" Render Error.
|
||||
|
||||
Place platform-specific component files in `components/` (or any directory outside the route tree), then import them from a regular route file:
|
||||
|
||||
```
|
||||
src/components/ProfileEditor.ios.tsx ← SwiftUI tree lives here
|
||||
src/app/profile-editor.tsx ← regular Expo Router route, imports the component
|
||||
```
|
||||
|
||||
`src/app/profile-editor.tsx`:
|
||||
```tsx
|
||||
import ProfileEditor from '../components/ProfileEditor';
|
||||
export default ProfileEditor;
|
||||
```
|
||||
|
||||
Alternatively, keep everything in one regular route file and branch on `Platform.OS`:
|
||||
|
||||
```tsx
|
||||
// src/app/profile-editor.tsx
|
||||
import { Platform } from 'react-native';
|
||||
// import SwiftUI components only when on iOS to avoid Android crash
|
||||
const SwiftUIForm = Platform.OS === 'ios' ? require('../components/ProfileEditor.ios').default : null;
|
||||
```
|
||||
|
||||
Or more simply, put the `Platform.OS` guard and the SwiftUI import in the same route file (safe because Metro only bundles `.ios.tsx` imports on iOS builds when using platform extensions in `components/`).
|
||||
|
||||
## Instructions
|
||||
|
||||
- Expo UI's API mirrors SwiftUI's API. Use SwiftUI knowledge to decide which components or modifiers to use.
|
||||
- Components are imported from `@expo/ui/swift-ui`, modifiers from `@expo/ui/swift-ui/modifiers`.
|
||||
- **Before writing any code, run the list-components script** to get the exact components and modifiers available in the installed version:
|
||||
```bash
|
||||
node <skill-root>/scripts/list-components.js <project-path> # names only (compact)
|
||||
node <skill-root>/scripts/list-components.js <project-path> --docs # with one-line descriptions
|
||||
```
|
||||
(`<skill-root>` is the directory containing this `references/` folder.)
|
||||
- **The installed package's TypeScript types (`.d.ts`) are the most reliable source of truth** for prop shapes and signatures — read the relevant `{Component}/index.d.ts` from the installed `@expo/ui/swift-ui` package in `node_modules`. Use the docs below as the human-readable reference.
|
||||
- When about to use a component, fetch its docs to confirm the API — https://docs.expo.dev/versions/latest/sdk/ui/swift-ui/{component-name}/index.md
|
||||
- When unsure about a modifier's API, refer to the docs — https://docs.expo.dev/versions/latest/sdk/ui/swift-ui/modifiers/index.md
|
||||
- Every SwiftUI tree must be wrapped in `Host`.
|
||||
- `RNHostView` is specifically for embedding RN components inside a SwiftUI tree. Example:
|
||||
|
||||
```jsx
|
||||
import { Host } from "@expo/ui"; // Host always from universal root
|
||||
import { VStack, RNHostView } from "@expo/ui/swift-ui"; // platform components from swift-ui
|
||||
import { Pressable } from "react-native";
|
||||
|
||||
<Host matchContents>
|
||||
<VStack>
|
||||
<RNHostView matchContents>
|
||||
// Here, `Pressable` is an RN component so it is wrapped in `RNHostView`.
|
||||
<Pressable />
|
||||
</RNHostView>
|
||||
</VStack>
|
||||
</Host>;
|
||||
```
|
||||
|
||||
- If a required modifier or View is missing in Expo UI, it can be extended via a local Expo module. See: https://docs.expo.dev/guides/expo-ui-swift-ui/extending/index.md. Confirm with the user before extending.
|
||||
|
||||
## useNativeState
|
||||
|
||||
`useNativeState` creates observable state that updates synchronously on the UI thread via worklets, enabling immediate native state changes without waiting for a React render cycle. Requires `react-native-worklets` — without it updates still go through React and flickering remains. Best for real-time interactions where synchronous updates matter, e.g. a text field that masks or formats input as the user types.
|
||||
|
||||
- `ObservableState.value` is readable/writable from worklets; `onChange` fires a worklet listener on state change.
|
||||
- Docs — https://docs.expo.dev/versions/latest/sdk/ui/swift-ui/usenativestate/index.md
|
||||
@@ -0,0 +1,73 @@
|
||||
# Universal `@expo/ui` components
|
||||
|
||||
> Requires Expo SDK 56+.
|
||||
|
||||
Universal components are a single-API layer over the platform-native UI toolkits: Jetpack Compose on Android, SwiftUI on iOS, and `react-native-web` / `react-dom` on web. You write one component tree that runs unmodified on all three platforms while keeping a native look and feel — no `.ios.tsx` / `.android.tsx` split.
|
||||
|
||||
## Usage
|
||||
|
||||
Import everything, including `Host`, from the package root (`@expo/ui`). Every tree must be wrapped in `Host`.
|
||||
|
||||
```tsx
|
||||
import { Host, Column, Button, Text } from '@expo/ui';
|
||||
|
||||
<Host matchContents>
|
||||
<Column>
|
||||
<Text>Hello</Text>
|
||||
<Button onPress={() => alert('Pressed!')}>Press me</Button>
|
||||
</Column>
|
||||
</Host>;
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
| Category | Components |
|
||||
|----------|------------|
|
||||
| Container | `Host` (required root wrapper) |
|
||||
| Layout | `Column`, `Row`, `Spacer`, `ScrollView` |
|
||||
| Display | `Text`, `Icon` |
|
||||
| Controls | `Button`, `Switch`, `Checkbox`, `Slider`, `TextInput`, `Picker` |
|
||||
| Disclosure & presentation | `BottomSheet`, `Collapsible` |
|
||||
| Collections & forms | `List` (with `ListItem`), `FieldGroup` |
|
||||
|
||||
> **`List` is not suitable for large lists.** Each `ListItem` is a JSX node processed on the JS thread — for large datasets this causes noticeable slowdowns.
|
||||
|
||||
## TextInput and useNativeState
|
||||
|
||||
`TextInput` from `@expo/ui` is **not like React Native's TextInput** — its `value` and `selection` props take an `ObservableState` object (from `useNativeState`), not a plain string. This is what enables synchronous, flicker-free updates: when the user types, `onChangeText` runs as a worklet on the UI thread and writes directly to `value` without a React render cycle.
|
||||
|
||||
Requires `react-native-worklets`. Without it the worklet directive has no effect and flickering remains.
|
||||
|
||||
```tsx
|
||||
import { Host, TextInput, useNativeState } from '@expo/ui';
|
||||
import { useCallback } from 'react';
|
||||
|
||||
export default function MyInput() {
|
||||
const text = useNativeState('');
|
||||
|
||||
const handleChangeText = useCallback((value: string) => {
|
||||
'worklet';
|
||||
// transform synchronously on the UI thread — no React re-render
|
||||
text.value = value === 'Hello' ? 'World' : value;
|
||||
}, [text]);
|
||||
|
||||
return (
|
||||
<Host matchContents>
|
||||
<TextInput value={text} onChangeText={handleChangeText} placeholder="Type here" />
|
||||
</Host>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
Docs — https://docs.expo.dev/versions/latest/sdk/ui/universal/textinput/index.md
|
||||
|
||||
## Confirming the API
|
||||
|
||||
`@expo/ui` is versioned with the Expo SDK (e.g. `56.0.x` for SDK 56) and its API can change between SDK versions, so the **installed package's TypeScript types (`.d.ts`) are the most reliable source of truth** — they match the version in your project, while the docs track latest. Read the relevant component's `.d.ts` from the installed `@expo/ui` package in `node_modules`. Use the docs as the human-readable reference:
|
||||
|
||||
- Overview — https://docs.expo.dev/versions/latest/sdk/ui/universal/index.md
|
||||
- Per component — https://docs.expo.dev/versions/latest/sdk/ui/universal/{component-name}/index.md
|
||||
|
||||
## When to drop down to a platform-specific layer
|
||||
|
||||
Choose universal components whenever they cover the requirement. Drop down to `@expo/ui/swift-ui` or `@expo/ui/jetpack-compose` only when the universal API doesn't expose the component, modifier, or platform-specific behavior you need — accepting the per-platform file split that requires. See `./swift-ui.md` and `./jetpack-compose.md`.
|
||||
Reference in New Issue
Block a user