@impulse-ui-native/toolkit 15.0.5 → 17.0.0
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 +273 -271
- package/dist/index.js.map +1 -1
- package/package.json +41 -39
package/README.md
CHANGED
|
@@ -1,271 +1,273 @@
|
|
|
1
|
-
# @impulse-ui-native/toolkit
|
|
2
|
-
|
|
3
|
-
The complete Impulse UI Native component library in one package.
|
|
4
|
-
|
|
5
|
-
`@impulse-ui-native/toolkit` provides token-driven React Native primitives, form controls, date and time pickers, charts, loading and empty states, flyouts, portals, and shared utilities through a single package entrypoint. It is the recommended package for applications that want the full library and the package listed in the React Native Directory.
|
|
6
|
-
|
|
7
|
-
## Highlights
|
|
8
|
-
|
|
9
|
-
- React Native components with TypeScript types.
|
|
10
|
-
- Native `FlatList` and a small initial-positioning hook for known row sizes. See the [FlatList API](../flat-list/README.md).
|
|
11
|
-
- `Carousel` with native snapping, centered previews, adaptive pagination, and
|
|
12
|
-
navigation buttons. See the [Carousel API](../carousel/README.md).
|
|
13
|
-
- `IconView` displays icons in a themed surface with IconButton sizes and Badge
|
|
14
|
-
variants and tones. See the [IconView API](../icon-view/README.md).
|
|
15
|
-
- One theme system shared by every component.
|
|
16
|
-
- Works with React Native mobile applications.
|
|
17
|
-
- Gesture-driven flyouts and app-wide overlay management.
|
|
18
|
-
- Compound `Toast` notifications with top/bottom placement, actions, and
|
|
19
|
-
timed dismissal. See the [Toast API](../toast/README.md).
|
|
20
|
-
- `Tooltip` and compound `Popover` with native anchors, safe-area collision
|
|
21
|
-
handling, and Portal rendering. See the [Popover API](../popover/README.md).
|
|
22
|
-
- Single- and multi-select controls, date/time pickers, charts, skeletons, and data states.
|
|
23
|
-
- Modular internals: applications with a narrow use case can install an individual `@impulse-ui-native/*` package instead.
|
|
24
|
-
|
|
25
|
-
## Requirements
|
|
26
|
-
|
|
27
|
-
- React 18 or newer.
|
|
28
|
-
- React Native 0.73 or newer.
|
|
29
|
-
- The native peer dependencies listed below.
|
|
30
|
-
|
|
31
|
-
The toolkit supports the React Native versions expressed by its peer dependencies. When using Expo, install native packages with `expo install` so Expo selects versions compatible with the SDK in your application.
|
|
32
|
-
|
|
33
|
-
## Installation
|
|
34
|
-
|
|
35
|
-
Install the toolkit:
|
|
36
|
-
|
|
37
|
-
```sh
|
|
38
|
-
pnpm add @impulse-ui-native/toolkit
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
Install its native peers:
|
|
42
|
-
|
|
43
|
-
```sh
|
|
44
|
-
pnpm add @shopify/react-native-skia react-native-gesture-handler react-native-reanimated react-native-safe-area-context react-native-svg react-native-worklets
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
In an Expo application, use:
|
|
48
|
-
|
|
49
|
-
```sh
|
|
50
|
-
npx expo install @shopify/react-native-skia react-native-gesture-handler react-native-reanimated react-native-safe-area-context react-native-svg react-native-worklets
|
|
51
|
-
npm install @impulse-ui-native/toolkit
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
Complete the platform setup required by Gesture Handler, Reanimated, Worklets, Skia, and Safe Area Context for the versions used by your project. Native applications must be rebuilt after adding native dependencies.
|
|
55
|
-
|
|
56
|
-
The endpoint factories are included in the toolkit but have two additional peers. Install them only when using the endpoint API:
|
|
57
|
-
|
|
58
|
-
```sh
|
|
59
|
-
pnpm add axios @tanstack/react-query
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
Icons are intentionally distributed separately so the toolkit does not expose thousands of icon modules from its root. Install the icon package when needed:
|
|
63
|
-
|
|
64
|
-
```sh
|
|
65
|
-
pnpm add @impulse-ui-native/icon react-native-svg
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
## Application setup
|
|
69
|
-
|
|
70
|
-
Mount the providers and global renderers once at the application root. This is the recommended Expo Router layout:
|
|
71
|
-
|
|
72
|
-
```tsx
|
|
73
|
-
import { GestureHandlerRootView } from "react-native-gesture-handler";
|
|
74
|
-
import { SafeAreaProvider } from "react-native-safe-area-context";
|
|
75
|
-
import { Stack } from "expo-router";
|
|
76
|
-
|
|
77
|
-
import {
|
|
78
|
-
OverlayHost,
|
|
79
|
-
OverlayProvider,
|
|
80
|
-
OverlayStore,
|
|
81
|
-
PortalProvider,
|
|
82
|
-
PortalsHost,
|
|
83
|
-
PortalStore,
|
|
84
|
-
ThemeProvider,
|
|
85
|
-
} from "@impulse-ui-native/toolkit";
|
|
86
|
-
|
|
87
|
-
const portalStore = new PortalStore();
|
|
88
|
-
const overlayStore = new OverlayStore();
|
|
89
|
-
|
|
90
|
-
export default function RootLayout() {
|
|
91
|
-
return (
|
|
92
|
-
<GestureHandlerRootView style={{ flex: 1 }}>
|
|
93
|
-
<SafeAreaProvider>
|
|
94
|
-
<ThemeProvider>
|
|
95
|
-
<OverlayProvider store={overlayStore}>
|
|
96
|
-
<PortalProvider store={portalStore}>
|
|
97
|
-
<Stack />
|
|
98
|
-
<OverlayHost />
|
|
99
|
-
<PortalsHost />
|
|
100
|
-
</PortalProvider>
|
|
101
|
-
</OverlayProvider>
|
|
102
|
-
</ThemeProvider>
|
|
103
|
-
</SafeAreaProvider>
|
|
104
|
-
</GestureHandlerRootView>
|
|
105
|
-
);
|
|
106
|
-
}
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
Keep `overlayStore` and `portalStore` outside the component so the same stores survive every render. In an application that does not use Expo Router, replace `<Stack />` with your navigator or root application content and keep the surrounding hierarchy unchanged.
|
|
110
|
-
|
|
111
|
-
| Root element | Purpose |
|
|
112
|
-
| ------------------------ | ------------------------------------------------------------------------ |
|
|
113
|
-
| `GestureHandlerRootView` | Enables native gesture handling for flyouts and gesture-driven controls. |
|
|
114
|
-
| `SafeAreaProvider` | Supplies safe-area measurements to primitives and overlays. |
|
|
115
|
-
| `ThemeProvider` | Supplies primitive, semantic, and component design tokens. |
|
|
116
|
-
| `OverlayProvider` | Connects imperative overlays to the stable `OverlayStore`. |
|
|
117
|
-
| `PortalProvider` | Connects the tree to the stable `PortalStore`. |
|
|
118
|
-
| `OverlayHost` | Renders components registered through the app-wide overlay store. |
|
|
119
|
-
| `PortalsHost` | Renders content sent to the default portal host. |
|
|
120
|
-
|
|
121
|
-
`OverlayHost` and `PortalsHost` should be siblings of the navigator and children of their matching providers. Mount only one of each at the root.
|
|
122
|
-
|
|
123
|
-
## Basic usage
|
|
124
|
-
|
|
125
|
-
All toolkit components and public types are available from the package root:
|
|
126
|
-
|
|
127
|
-
```tsx
|
|
128
|
-
import { useState } from "react";
|
|
129
|
-
|
|
130
|
-
import {
|
|
131
|
-
Button,
|
|
132
|
-
Input,
|
|
133
|
-
Typography,
|
|
134
|
-
useSpace,
|
|
135
|
-
View,
|
|
136
|
-
} from "@impulse-ui-native/toolkit";
|
|
137
|
-
|
|
138
|
-
export function SignInForm() {
|
|
139
|
-
const [email, setEmail] = useState("");
|
|
140
|
-
const space = useSpace();
|
|
141
|
-
|
|
142
|
-
return (
|
|
143
|
-
<View gap={space.md} padding={space.lg}>
|
|
144
|
-
<Typography.Title2>Welcome back</Typography.Title2>
|
|
145
|
-
<Input
|
|
146
|
-
autoCapitalize="none"
|
|
147
|
-
keyboardType="email-address"
|
|
148
|
-
label="Email"
|
|
149
|
-
onChangeText={setEmail}
|
|
150
|
-
placeholder="you@example.com"
|
|
151
|
-
value={email}
|
|
152
|
-
/>
|
|
153
|
-
<Button onPress={() => {}}>Continue</Button>
|
|
154
|
-
</View>
|
|
155
|
-
);
|
|
156
|
-
}
|
|
157
|
-
```
|
|
158
|
-
|
|
159
|
-
## Selects and flyouts
|
|
160
|
-
|
|
161
|
-
`Select`, `MultiSelect`, and the date/time pickers use the root `PortalsHost`. Once the application setup above is in place, a select can be rendered anywhere below it:
|
|
162
|
-
|
|
163
|
-
```tsx
|
|
164
|
-
import { useState } from "react";
|
|
165
|
-
|
|
166
|
-
import { Select } from "@impulse-ui-native/toolkit";
|
|
167
|
-
|
|
168
|
-
const options = [
|
|
169
|
-
{ label: "Design", value: "design" },
|
|
170
|
-
{ label: "Engineering", value: "engineering" },
|
|
171
|
-
{ label: "Operations", value: "operations" },
|
|
172
|
-
];
|
|
173
|
-
|
|
174
|
-
export function DepartmentField() {
|
|
175
|
-
const [value, setValue] = useState<string>();
|
|
176
|
-
|
|
177
|
-
return (
|
|
178
|
-
<Select
|
|
179
|
-
label="Department"
|
|
180
|
-
onChange={setValue}
|
|
181
|
-
options={options}
|
|
182
|
-
placeholder="Choose a department"
|
|
183
|
-
value={value}
|
|
184
|
-
/>
|
|
185
|
-
);
|
|
186
|
-
}
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
Do not mount another host beside the control; portal content and registered overlays are rendered by the application-level `PortalsHost` and `OverlayHost`.
|
|
190
|
-
|
|
191
|
-
## Theming
|
|
192
|
-
|
|
193
|
-
`ThemeProvider` uses the light theme by default. Select a scheme and override only the tokens your application needs:
|
|
194
|
-
|
|
195
|
-
```tsx
|
|
196
|
-
<ThemeProvider
|
|
197
|
-
scheme="dark"
|
|
198
|
-
theme={{
|
|
199
|
-
dark: {
|
|
200
|
-
colors: {
|
|
201
|
-
primary: {
|
|
202
|
-
value: "#8b7cff",
|
|
203
|
-
contrast: "#ffffff",
|
|
204
|
-
},
|
|
205
|
-
},
|
|
206
|
-
},
|
|
207
|
-
}}
|
|
208
|
-
>
|
|
209
|
-
{/* application */}
|
|
210
|
-
</ThemeProvider>
|
|
211
|
-
```
|
|
212
|
-
|
|
213
|
-
Theme overrides are deep partials. Hooks including `useTheme`, `useColors`, `useSpace`, `useBorder`, `useRadii`, `useComponentsTokens`, and `useThemedStyles` are available for application components.
|
|
214
|
-
|
|
215
|
-
## Included APIs
|
|
216
|
-
|
|
217
|
-
- Foundations: theme tokens and hooks, shared types, styling utilities, and core helpers.
|
|
218
|
-
- Primitives: `View`, `SafeAreaView`, typography presets, `Pressable`, `Button`, `IconButton`, `Tag`, and compound control primitives.
|
|
219
|
-
- Inputs: `Input`, `Select`, and `MultiSelect`.
|
|
220
|
-
- Date and time: `DatePicker`, `DateRangePicker`, `DatetimePicker`, `DatetimeRangePicker`, and `TimePicker`.
|
|
221
|
-
- Charts: line, bar, pie, multi-series chart components, axes, grids, labels, hooks, and utilities.
|
|
222
|
-
- Feedback: `Skeleton`, `DataView`, `LoadingView`, `EmptyView`, and `ErrorView`.
|
|
223
|
-
- Navigation and overlays: `Pagination`, `Stepper`, `Flyout`, `OverlayHost`, `OverlayProvider`, `OverlayStore`, overlay registration types, `Portal`, `PortalProvider`, `PortalStore`, and portal hosts.
|
|
224
|
-
- Data utilities: `EchoInstance`, echo hooks, and typed Axios/TanStack Query endpoint factories.
|
|
225
|
-
|
|
226
|
-
## Icons
|
|
227
|
-
|
|
228
|
-
Import icons through per-icon entrypoints from `@impulse-ui-native/icon`:
|
|
229
|
-
|
|
230
|
-
```tsx
|
|
231
|
-
import { Icon } from "@impulse-ui-native/icon";
|
|
232
|
-
import { HeartIcon } from "@impulse-ui-native/icon/icons/heart";
|
|
233
|
-
|
|
234
|
-
<Icon icon={HeartIcon} variant="duotone" size="large" color="#6d5dfc" />;
|
|
235
|
-
```
|
|
236
|
-
|
|
237
|
-
Per-icon entrypoints let Metro include only the icons used by the application. Available weights are `bold`, `duotone`, `fill`, `light`, `regular`, and `thin`.
|
|
238
|
-
|
|
239
|
-
## Toolkit or individual packages?
|
|
240
|
-
|
|
241
|
-
Use `@impulse-ui-native/toolkit` when you want one dependency and one import path for the complete component API. Install individual packages such as `@impulse-ui-native/theme`, `@impulse-ui-native/primitives`, or `@impulse-ui-native/select` when you want a smaller, explicit dependency surface.
|
|
242
|
-
|
|
243
|
-
The toolkit uses ES modules and declares itself side-effect free, allowing compatible bundlers to remove exports that are not used. The icon library remains separate because its generated per-icon entrypoints are best consumed directly.
|
|
244
|
-
|
|
245
|
-
## Troubleshooting
|
|
246
|
-
|
|
247
|
-
- If gestures do not respond, verify that `GestureHandlerRootView` is the outermost application view and has `flex: 1`.
|
|
248
|
-
- If a registered flyout does not appear, verify that one `OverlayHost` is mounted inside the matching `OverlayProvider`.
|
|
249
|
-
- If portal content does not appear, verify that `PortalProvider` and `PortalsHost` use the same stable store and host name.
|
|
250
|
-
- If content overlaps a notch or system bar, verify that `SafeAreaProvider` wraps the themed application.
|
|
251
|
-
- If a native dependency was just installed, rebuild the native application rather than relying only on a JavaScript refresh.
|
|
252
|
-
|
|
253
|
-
## Documentation and source
|
|
254
|
-
|
|
255
|
-
The source, package-specific guides, Storybook examples, and issue tracker are available at [github.com/apolyanov/impulse-ui-native](https://github.com/apolyanov/impulse-ui-native).
|
|
256
|
-
|
|
257
|
-
## License
|
|
258
|
-
|
|
259
|
-
Impulse UI Native is released under the [MIT license](./LICENSE).
|
|
260
|
-
|
|
261
|
-
Card, List, and Progress are aggregated from `@impulse-ui-native/card`, `@impulse-ui-native/list`, and `@impulse-ui-native/progress`. Their namespaced composition APIs remain available alongside the ready-made Card and List components.
|
|
262
|
-
|
|
263
|
-
Modal is aggregated from `@impulse-ui-native/modal`. It supplies Root, Header, Content, Footer, Title, and Description, with a convenience Modal composition supporting controlled local Portal usage and global OverlayHost registration.
|
|
264
|
-
|
|
265
|
-
## Color picker
|
|
266
|
-
|
|
267
|
-
ColorPicker selects custom colors with spectrum, hue, opacity, hex/RGB entry, and theme presets. It supports immediate or staged Apply/Cancel updates and exposes composable parts. See the [ColorPicker API](../color-picker/README.md).
|
|
268
|
-
|
|
269
|
-
## Agent and design reference
|
|
270
|
-
|
|
271
|
-
Start with the [capability guide](../../docs/design-system/capabilities/toolkit.md) for supported exports, props, defaults, composition rules, setup, and recipes. Use the [component chooser](../../docs/design-system/component-chooser.md) to select a package. These references describe the repository source; verify your installed package version before copying examples.
|
|
1
|
+
# @impulse-ui-native/toolkit
|
|
2
|
+
|
|
3
|
+
The complete Impulse UI Native component library in one package.
|
|
4
|
+
|
|
5
|
+
`@impulse-ui-native/toolkit` provides token-driven React Native primitives, form controls, date and time pickers, charts, loading and empty states, flyouts, portals, and shared utilities through a single package entrypoint. It is the recommended package for applications that want the full library and the package listed in the React Native Directory.
|
|
6
|
+
|
|
7
|
+
## Highlights
|
|
8
|
+
|
|
9
|
+
- React Native components with TypeScript types.
|
|
10
|
+
- Native `FlatList` and a small initial-positioning hook for known row sizes. See the [FlatList API](../flat-list/README.md).
|
|
11
|
+
- `Carousel` with native snapping, centered previews, adaptive pagination, and
|
|
12
|
+
navigation buttons. See the [Carousel API](../carousel/README.md).
|
|
13
|
+
- `IconView` displays icons in a themed surface with IconButton sizes and Badge
|
|
14
|
+
variants and tones. See the [IconView API](../icon-view/README.md).
|
|
15
|
+
- One theme system shared by every component.
|
|
16
|
+
- Works with React Native mobile applications.
|
|
17
|
+
- Gesture-driven flyouts and app-wide overlay management.
|
|
18
|
+
- Compound `Toast` notifications with top/bottom placement, actions, and
|
|
19
|
+
timed dismissal. See the [Toast API](../toast/README.md).
|
|
20
|
+
- `Tooltip` and compound `Popover` with native anchors, safe-area collision
|
|
21
|
+
handling, and Portal rendering. See the [Popover API](../popover/README.md).
|
|
22
|
+
- Single- and multi-select controls, date/time pickers, charts, skeletons, and data states.
|
|
23
|
+
- Modular internals: applications with a narrow use case can install an individual `@impulse-ui-native/*` package instead.
|
|
24
|
+
|
|
25
|
+
## Requirements
|
|
26
|
+
|
|
27
|
+
- React 18 or newer.
|
|
28
|
+
- React Native 0.73 or newer.
|
|
29
|
+
- The native peer dependencies listed below.
|
|
30
|
+
|
|
31
|
+
The toolkit supports the React Native versions expressed by its peer dependencies. When using Expo, install native packages with `expo install` so Expo selects versions compatible with the SDK in your application.
|
|
32
|
+
|
|
33
|
+
## Installation
|
|
34
|
+
|
|
35
|
+
Install the toolkit:
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
pnpm add @impulse-ui-native/toolkit
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Install its native peers:
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
pnpm add @shopify/react-native-skia react-native-gesture-handler react-native-reanimated react-native-safe-area-context react-native-svg react-native-worklets
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
In an Expo application, use:
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
npx expo install @shopify/react-native-skia react-native-gesture-handler react-native-reanimated react-native-safe-area-context react-native-svg react-native-worklets
|
|
51
|
+
npm install @impulse-ui-native/toolkit
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Complete the platform setup required by Gesture Handler, Reanimated, Worklets, Skia, and Safe Area Context for the versions used by your project. Native applications must be rebuilt after adding native dependencies.
|
|
55
|
+
|
|
56
|
+
The endpoint factories are included in the toolkit but have two additional peers. Install them only when using the endpoint API:
|
|
57
|
+
|
|
58
|
+
```sh
|
|
59
|
+
pnpm add axios @tanstack/react-query
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Icons are intentionally distributed separately so the toolkit does not expose thousands of icon modules from its root. Install the icon package when needed:
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
pnpm add @impulse-ui-native/icon react-native-svg
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Application setup
|
|
69
|
+
|
|
70
|
+
Mount the providers and global renderers once at the application root. This is the recommended Expo Router layout:
|
|
71
|
+
|
|
72
|
+
```tsx
|
|
73
|
+
import { GestureHandlerRootView } from "react-native-gesture-handler";
|
|
74
|
+
import { SafeAreaProvider } from "react-native-safe-area-context";
|
|
75
|
+
import { Stack } from "expo-router";
|
|
76
|
+
|
|
77
|
+
import {
|
|
78
|
+
OverlayHost,
|
|
79
|
+
OverlayProvider,
|
|
80
|
+
OverlayStore,
|
|
81
|
+
PortalProvider,
|
|
82
|
+
PortalsHost,
|
|
83
|
+
PortalStore,
|
|
84
|
+
ThemeProvider,
|
|
85
|
+
} from "@impulse-ui-native/toolkit";
|
|
86
|
+
|
|
87
|
+
const portalStore = new PortalStore();
|
|
88
|
+
const overlayStore = new OverlayStore();
|
|
89
|
+
|
|
90
|
+
export default function RootLayout() {
|
|
91
|
+
return (
|
|
92
|
+
<GestureHandlerRootView style={{ flex: 1 }}>
|
|
93
|
+
<SafeAreaProvider>
|
|
94
|
+
<ThemeProvider>
|
|
95
|
+
<OverlayProvider store={overlayStore}>
|
|
96
|
+
<PortalProvider store={portalStore}>
|
|
97
|
+
<Stack />
|
|
98
|
+
<OverlayHost />
|
|
99
|
+
<PortalsHost />
|
|
100
|
+
</PortalProvider>
|
|
101
|
+
</OverlayProvider>
|
|
102
|
+
</ThemeProvider>
|
|
103
|
+
</SafeAreaProvider>
|
|
104
|
+
</GestureHandlerRootView>
|
|
105
|
+
);
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Keep `overlayStore` and `portalStore` outside the component so the same stores survive every render. In an application that does not use Expo Router, replace `<Stack />` with your navigator or root application content and keep the surrounding hierarchy unchanged.
|
|
110
|
+
|
|
111
|
+
| Root element | Purpose |
|
|
112
|
+
| ------------------------ | ------------------------------------------------------------------------ |
|
|
113
|
+
| `GestureHandlerRootView` | Enables native gesture handling for flyouts and gesture-driven controls. |
|
|
114
|
+
| `SafeAreaProvider` | Supplies safe-area measurements to primitives and overlays. |
|
|
115
|
+
| `ThemeProvider` | Supplies primitive, semantic, and component design tokens. |
|
|
116
|
+
| `OverlayProvider` | Connects imperative overlays to the stable `OverlayStore`. |
|
|
117
|
+
| `PortalProvider` | Connects the tree to the stable `PortalStore`. |
|
|
118
|
+
| `OverlayHost` | Renders components registered through the app-wide overlay store. |
|
|
119
|
+
| `PortalsHost` | Renders content sent to the default portal host. |
|
|
120
|
+
|
|
121
|
+
`OverlayHost` and `PortalsHost` should be siblings of the navigator and children of their matching providers. Mount only one of each at the root.
|
|
122
|
+
|
|
123
|
+
## Basic usage
|
|
124
|
+
|
|
125
|
+
All toolkit components and public types are available from the package root:
|
|
126
|
+
|
|
127
|
+
```tsx
|
|
128
|
+
import { useState } from "react";
|
|
129
|
+
|
|
130
|
+
import {
|
|
131
|
+
Button,
|
|
132
|
+
Input,
|
|
133
|
+
Typography,
|
|
134
|
+
useSpace,
|
|
135
|
+
View,
|
|
136
|
+
} from "@impulse-ui-native/toolkit";
|
|
137
|
+
|
|
138
|
+
export function SignInForm() {
|
|
139
|
+
const [email, setEmail] = useState("");
|
|
140
|
+
const space = useSpace();
|
|
141
|
+
|
|
142
|
+
return (
|
|
143
|
+
<View gap={space.md} padding={space.lg}>
|
|
144
|
+
<Typography.Title2>Welcome back</Typography.Title2>
|
|
145
|
+
<Input
|
|
146
|
+
autoCapitalize="none"
|
|
147
|
+
keyboardType="email-address"
|
|
148
|
+
label="Email"
|
|
149
|
+
onChangeText={setEmail}
|
|
150
|
+
placeholder="you@example.com"
|
|
151
|
+
value={email}
|
|
152
|
+
/>
|
|
153
|
+
<Button onPress={() => {}}>Continue</Button>
|
|
154
|
+
</View>
|
|
155
|
+
);
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## Selects and flyouts
|
|
160
|
+
|
|
161
|
+
`Select`, `MultiSelect`, and the date/time pickers use the root `PortalsHost`. Once the application setup above is in place, a select can be rendered anywhere below it:
|
|
162
|
+
|
|
163
|
+
```tsx
|
|
164
|
+
import { useState } from "react";
|
|
165
|
+
|
|
166
|
+
import { Select } from "@impulse-ui-native/toolkit";
|
|
167
|
+
|
|
168
|
+
const options = [
|
|
169
|
+
{ label: "Design", value: "design" },
|
|
170
|
+
{ label: "Engineering", value: "engineering" },
|
|
171
|
+
{ label: "Operations", value: "operations" },
|
|
172
|
+
];
|
|
173
|
+
|
|
174
|
+
export function DepartmentField() {
|
|
175
|
+
const [value, setValue] = useState<string>();
|
|
176
|
+
|
|
177
|
+
return (
|
|
178
|
+
<Select
|
|
179
|
+
label="Department"
|
|
180
|
+
onChange={setValue}
|
|
181
|
+
options={options}
|
|
182
|
+
placeholder="Choose a department"
|
|
183
|
+
value={value}
|
|
184
|
+
/>
|
|
185
|
+
);
|
|
186
|
+
}
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Do not mount another host beside the control; portal content and registered overlays are rendered by the application-level `PortalsHost` and `OverlayHost`.
|
|
190
|
+
|
|
191
|
+
## Theming
|
|
192
|
+
|
|
193
|
+
`ThemeProvider` uses the light theme by default. Select a scheme and override only the tokens your application needs:
|
|
194
|
+
|
|
195
|
+
```tsx
|
|
196
|
+
<ThemeProvider
|
|
197
|
+
scheme="dark"
|
|
198
|
+
theme={{
|
|
199
|
+
dark: {
|
|
200
|
+
colors: {
|
|
201
|
+
primary: {
|
|
202
|
+
value: "#8b7cff",
|
|
203
|
+
contrast: "#ffffff",
|
|
204
|
+
},
|
|
205
|
+
},
|
|
206
|
+
},
|
|
207
|
+
}}
|
|
208
|
+
>
|
|
209
|
+
{/* application */}
|
|
210
|
+
</ThemeProvider>
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Theme overrides are deep partials. Hooks including `useTheme`, `useColors`, `useSpace`, `useBorder`, `useRadii`, `useComponentsTokens`, and `useThemedStyles` are available for application components.
|
|
214
|
+
|
|
215
|
+
## Included APIs
|
|
216
|
+
|
|
217
|
+
- Foundations: theme tokens and hooks, shared types, styling utilities, and core helpers.
|
|
218
|
+
- Primitives: `View`, `SafeAreaView`, typography presets, `Pressable`, `Button`, `IconButton`, `Tag`, and compound control primitives.
|
|
219
|
+
- Inputs: `Input`, `Select`, and `MultiSelect`.
|
|
220
|
+
- Date and time: `DatePicker`, `DateRangePicker`, `DatetimePicker`, `DatetimeRangePicker`, and `TimePicker`.
|
|
221
|
+
- Charts: line, bar, pie, multi-series chart components, axes, grids, labels, hooks, and utilities.
|
|
222
|
+
- Feedback: `Skeleton`, `DataView`, `LoadingView`, `EmptyView`, and `ErrorView`.
|
|
223
|
+
- Navigation and overlays: `Pagination`, `Stepper`, `Flyout`, `OverlayHost`, `OverlayProvider`, `OverlayStore`, overlay registration types, `Portal`, `PortalProvider`, `PortalStore`, and portal hosts.
|
|
224
|
+
- Data utilities: `EchoInstance`, echo hooks, and typed Axios/TanStack Query endpoint factories.
|
|
225
|
+
|
|
226
|
+
## Icons
|
|
227
|
+
|
|
228
|
+
Import icons through per-icon entrypoints from `@impulse-ui-native/icon`:
|
|
229
|
+
|
|
230
|
+
```tsx
|
|
231
|
+
import { Icon } from "@impulse-ui-native/icon";
|
|
232
|
+
import { HeartIcon } from "@impulse-ui-native/icon/icons/heart";
|
|
233
|
+
|
|
234
|
+
<Icon icon={HeartIcon} variant="duotone" size="large" color="#6d5dfc" />;
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
Per-icon entrypoints let Metro include only the icons used by the application. Available weights are `bold`, `duotone`, `fill`, `light`, `regular`, and `thin`.
|
|
238
|
+
|
|
239
|
+
## Toolkit or individual packages?
|
|
240
|
+
|
|
241
|
+
Use `@impulse-ui-native/toolkit` when you want one dependency and one import path for the complete component API. Install individual packages such as `@impulse-ui-native/theme`, `@impulse-ui-native/primitives`, or `@impulse-ui-native/select` when you want a smaller, explicit dependency surface.
|
|
242
|
+
|
|
243
|
+
The toolkit uses ES modules and declares itself side-effect free, allowing compatible bundlers to remove exports that are not used. The icon library remains separate because its generated per-icon entrypoints are best consumed directly.
|
|
244
|
+
|
|
245
|
+
## Troubleshooting
|
|
246
|
+
|
|
247
|
+
- If gestures do not respond, verify that `GestureHandlerRootView` is the outermost application view and has `flex: 1`.
|
|
248
|
+
- If a registered flyout does not appear, verify that one `OverlayHost` is mounted inside the matching `OverlayProvider`.
|
|
249
|
+
- If portal content does not appear, verify that `PortalProvider` and `PortalsHost` use the same stable store and host name.
|
|
250
|
+
- If content overlaps a notch or system bar, verify that `SafeAreaProvider` wraps the themed application.
|
|
251
|
+
- If a native dependency was just installed, rebuild the native application rather than relying only on a JavaScript refresh.
|
|
252
|
+
|
|
253
|
+
## Documentation and source
|
|
254
|
+
|
|
255
|
+
The source, package-specific guides, Storybook examples, and issue tracker are available at [github.com/apolyanov/impulse-ui-native](https://github.com/apolyanov/impulse-ui-native).
|
|
256
|
+
|
|
257
|
+
## License
|
|
258
|
+
|
|
259
|
+
Impulse UI Native is released under the [MIT license](./LICENSE).
|
|
260
|
+
|
|
261
|
+
Card, List, and Progress are aggregated from `@impulse-ui-native/card`, `@impulse-ui-native/list`, and `@impulse-ui-native/progress`. Their namespaced composition APIs remain available alongside the ready-made Card and List components.
|
|
262
|
+
|
|
263
|
+
Modal is aggregated from `@impulse-ui-native/modal`. It supplies Root, Header, Content, Footer, Title, and Description, with a convenience Modal composition supporting controlled local Portal usage and global OverlayHost registration.
|
|
264
|
+
|
|
265
|
+
## Color picker
|
|
266
|
+
|
|
267
|
+
ColorPicker selects custom colors with spectrum, hue, opacity, hex/RGB entry, and theme presets. It supports immediate or staged Apply/Cancel updates and exposes composable parts. See the [ColorPicker API](../color-picker/README.md).
|
|
268
|
+
|
|
269
|
+
## Agent and design reference
|
|
270
|
+
|
|
271
|
+
Start with the [capability guide](../../docs/design-system/capabilities/toolkit.md) for supported exports, props, defaults, composition rules, setup, and recipes. Use the [component chooser](../../docs/design-system/component-chooser.md) to select a package. These references describe the repository source; verify your installed package version before copying examples.
|
|
272
|
+
|
|
273
|
+
Flyout keyboard-aware bodies and Select require `react-native-keyboard-controller` and an application-level `KeyboardProvider` covering Portal/Overlay hosts. Rebuild the native app after installing it. See the [Flyout keyboard setup](../flyout/README.md#keyboard-aware-body).
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Core foundation\nexport * from \"@impulse-ui-native/core\";\nexport * from \"@impulse-ui-native/theme\";\n\n// Layout & containers\nexport * from \"@impulse-ui-native/flat-list\";\nexport * from \"@impulse-ui-native/scroll-view\";\nexport * from \"@impulse-ui-native/overlay\";\nexport * from \"@impulse-ui-native/pagination\";\nexport * from \"@impulse-ui-native/carousel\";\nexport * from \"@impulse-ui-native/portal\";\n\n// Components\nexport * from \"@impulse-ui-native/accordion\";\nexport * from \"@impulse-ui-native/charts\";\nexport * from \"@impulse-ui-native/checkbox\";\nexport * from \"@impulse-ui-native/primitives\";\nexport * from \"@impulse-ui-native/radio\";\nexport * from \"@impulse-ui-native/segmented-control\";\nexport * from \"@impulse-ui-native/tabs\";\nexport * from \"@impulse-ui-native/flyout\";\nexport * from \"@impulse-ui-native/form-field\";\nexport * from \"@impulse-ui-native/input\";\nexport * from \"@impulse-ui-native/stepper\";\nexport * from \"@impulse-ui-native/switch\";\nexport * from \"@impulse-ui-native/slider\";\nexport * from \"@impulse-ui-native/data-state\";\nexport * from \"@impulse-ui-native/skeleton\";\nexport * from \"@impulse-ui-native/select\";\nexport * from \"@impulse-ui-native/datetime\";\n\n// Utilities\nexport * from \"@impulse-ui-native/echo\";\nexport * from \"@impulse-ui-native/endpoint\";\n\nexport * from \"@impulse-ui-native/toast\";\nexport * from \"@impulse-ui-native/card\";\nexport * from \"@impulse-ui-native/list\";\nexport * from \"@impulse-ui-native/progress\";\nexport * from \"@impulse-ui-native/popover\";\nexport * from \"@impulse-ui-native/modal\";\n\nexport * from \"@impulse-ui-native/color-picker\";\n\nexport * from \"@impulse-ui-native/icon-view\";\n"],"mappings":"AACA,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AAEd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAEd,cAAc;AAEd,cAAc;","names":[]}
|
|
1
|
+
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// Core foundation\r\nexport * from \"@impulse-ui-native/core\";\r\nexport * from \"@impulse-ui-native/theme\";\r\n\r\n// Layout & containers\r\nexport * from \"@impulse-ui-native/flat-list\";\r\nexport * from \"@impulse-ui-native/scroll-view\";\r\nexport * from \"@impulse-ui-native/overlay\";\r\nexport * from \"@impulse-ui-native/pagination\";\r\nexport * from \"@impulse-ui-native/carousel\";\r\nexport * from \"@impulse-ui-native/portal\";\r\n\r\n// Components\r\nexport * from \"@impulse-ui-native/accordion\";\r\nexport * from \"@impulse-ui-native/charts\";\r\nexport * from \"@impulse-ui-native/checkbox\";\r\nexport * from \"@impulse-ui-native/primitives\";\r\nexport * from \"@impulse-ui-native/radio\";\r\nexport * from \"@impulse-ui-native/segmented-control\";\r\nexport * from \"@impulse-ui-native/tabs\";\r\nexport * from \"@impulse-ui-native/flyout\";\r\nexport * from \"@impulse-ui-native/form-field\";\r\nexport * from \"@impulse-ui-native/input\";\r\nexport * from \"@impulse-ui-native/stepper\";\r\nexport * from \"@impulse-ui-native/switch\";\r\nexport * from \"@impulse-ui-native/slider\";\r\nexport * from \"@impulse-ui-native/data-state\";\r\nexport * from \"@impulse-ui-native/skeleton\";\r\nexport * from \"@impulse-ui-native/select\";\r\nexport * from \"@impulse-ui-native/datetime\";\r\n\r\n// Utilities\r\nexport * from \"@impulse-ui-native/echo\";\r\nexport * from \"@impulse-ui-native/endpoint\";\r\n\r\nexport * from \"@impulse-ui-native/toast\";\r\nexport * from \"@impulse-ui-native/card\";\r\nexport * from \"@impulse-ui-native/list\";\r\nexport * from \"@impulse-ui-native/progress\";\r\nexport * from \"@impulse-ui-native/popover\";\r\nexport * from \"@impulse-ui-native/modal\";\r\n\r\nexport * from \"@impulse-ui-native/color-picker\";\r\n\r\nexport * from \"@impulse-ui-native/icon-view\";\r\n"],"mappings":"AACA,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AAEd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAEd,cAAc;AAEd,cAAc;","names":[]}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@impulse-ui-native/toolkit",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "17.0.0",
|
|
4
4
|
"description": "The complete ImpulseUI Native component toolkit for building React Native applications.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"react-native",
|
|
@@ -28,41 +28,41 @@
|
|
|
28
28
|
],
|
|
29
29
|
"sideEffects": false,
|
|
30
30
|
"dependencies": {
|
|
31
|
-
"@impulse-ui-native/popover": "
|
|
32
|
-
"@impulse-ui-native/accordion": "
|
|
33
|
-
"@impulse-ui-native/charts": "
|
|
34
|
-
"@impulse-ui-native/checkbox": "
|
|
35
|
-
"@impulse-ui-native/core": "
|
|
36
|
-
"@impulse-ui-native/echo": "
|
|
37
|
-
"@impulse-ui-native/endpoint": "
|
|
38
|
-
"@impulse-ui-native/flyout": "
|
|
39
|
-
"@impulse-ui-native/form-field": "
|
|
40
|
-
"@impulse-ui-native/stepper": "
|
|
41
|
-
"@impulse-ui-native/switch": "
|
|
42
|
-
"@impulse-ui-native/slider": "
|
|
43
|
-
"@impulse-ui-native/input": "
|
|
44
|
-
"@impulse-ui-native/overlay": "
|
|
45
|
-
"@impulse-ui-native/pagination": "
|
|
46
|
-
"@impulse-ui-native/theme": "
|
|
47
|
-
"@impulse-ui-native/primitives": "
|
|
48
|
-
"@impulse-ui-native/radio": "
|
|
49
|
-
"@impulse-ui-native/segmented-control": "
|
|
50
|
-
"@impulse-ui-native/data-state": "
|
|
51
|
-
"@impulse-ui-native/skeleton": "
|
|
52
|
-
"@impulse-ui-native/select": "
|
|
53
|
-
"@impulse-ui-native/portal": "
|
|
54
|
-
"@impulse-ui-native/datetime": "
|
|
55
|
-
"@impulse-ui-native/carousel": "
|
|
56
|
-
"@impulse-ui-native/toast": "
|
|
57
|
-
"@impulse-ui-native/card": "
|
|
58
|
-
"@impulse-ui-native/list": "
|
|
59
|
-
"@impulse-ui-native/progress": "
|
|
60
|
-
"@impulse-ui-native/modal": "
|
|
61
|
-
"@impulse-ui-native/tabs": "
|
|
62
|
-
"@impulse-ui-native/flat-list": "
|
|
63
|
-
"@impulse-ui-native/scroll-view": "
|
|
64
|
-
"@impulse-ui-native/color-picker": "
|
|
65
|
-
"@impulse-ui-native/icon-view": "
|
|
31
|
+
"@impulse-ui-native/popover": "17.0.0",
|
|
32
|
+
"@impulse-ui-native/accordion": "17.0.0",
|
|
33
|
+
"@impulse-ui-native/charts": "17.0.0",
|
|
34
|
+
"@impulse-ui-native/checkbox": "17.0.0",
|
|
35
|
+
"@impulse-ui-native/core": "17.0.0",
|
|
36
|
+
"@impulse-ui-native/echo": "17.0.0",
|
|
37
|
+
"@impulse-ui-native/endpoint": "17.0.0",
|
|
38
|
+
"@impulse-ui-native/flyout": "17.0.0",
|
|
39
|
+
"@impulse-ui-native/form-field": "17.0.0",
|
|
40
|
+
"@impulse-ui-native/stepper": "17.0.0",
|
|
41
|
+
"@impulse-ui-native/switch": "17.0.0",
|
|
42
|
+
"@impulse-ui-native/slider": "17.0.0",
|
|
43
|
+
"@impulse-ui-native/input": "17.0.0",
|
|
44
|
+
"@impulse-ui-native/overlay": "17.0.0",
|
|
45
|
+
"@impulse-ui-native/pagination": "17.0.0",
|
|
46
|
+
"@impulse-ui-native/theme": "17.0.0",
|
|
47
|
+
"@impulse-ui-native/primitives": "17.0.0",
|
|
48
|
+
"@impulse-ui-native/radio": "17.0.0",
|
|
49
|
+
"@impulse-ui-native/segmented-control": "17.0.0",
|
|
50
|
+
"@impulse-ui-native/data-state": "17.0.0",
|
|
51
|
+
"@impulse-ui-native/skeleton": "17.0.0",
|
|
52
|
+
"@impulse-ui-native/select": "17.0.0",
|
|
53
|
+
"@impulse-ui-native/portal": "17.0.0",
|
|
54
|
+
"@impulse-ui-native/datetime": "17.0.0",
|
|
55
|
+
"@impulse-ui-native/carousel": "17.0.0",
|
|
56
|
+
"@impulse-ui-native/toast": "17.0.0",
|
|
57
|
+
"@impulse-ui-native/card": "17.0.0",
|
|
58
|
+
"@impulse-ui-native/list": "17.0.0",
|
|
59
|
+
"@impulse-ui-native/progress": "17.0.0",
|
|
60
|
+
"@impulse-ui-native/modal": "17.0.0",
|
|
61
|
+
"@impulse-ui-native/tabs": "17.0.0",
|
|
62
|
+
"@impulse-ui-native/flat-list": "17.0.0",
|
|
63
|
+
"@impulse-ui-native/scroll-view": "17.0.0",
|
|
64
|
+
"@impulse-ui-native/color-picker": "17.0.0",
|
|
65
|
+
"@impulse-ui-native/icon-view": "17.0.0"
|
|
66
66
|
},
|
|
67
67
|
"devDependencies": {
|
|
68
68
|
"@shopify/react-native-skia": "2.14.0",
|
|
@@ -79,17 +79,19 @@
|
|
|
79
79
|
"react-native-safe-area-context": "~5.10.1",
|
|
80
80
|
"react-native-svg": "15.16.0",
|
|
81
81
|
"react-native-worklets": "0.13.0",
|
|
82
|
-
"typescript": "~6.0.3"
|
|
82
|
+
"typescript": "~6.0.3",
|
|
83
|
+
"react-native-keyboard-controller": "1.22.7"
|
|
83
84
|
},
|
|
84
85
|
"peerDependencies": {
|
|
85
86
|
"@shopify/react-native-skia": ">=2",
|
|
86
87
|
"react": ">=18",
|
|
87
88
|
"react-native": ">=0.73",
|
|
88
|
-
"react-native-gesture-handler": ">=
|
|
89
|
+
"react-native-gesture-handler": ">=3.0.0",
|
|
89
90
|
"react-native-reanimated": ">=4",
|
|
90
91
|
"react-native-safe-area-context": ">=5.0.0",
|
|
91
92
|
"react-native-svg": ">=13.9.0",
|
|
92
|
-
"react-native-worklets": ">=0.5"
|
|
93
|
+
"react-native-worklets": ">=0.5",
|
|
94
|
+
"react-native-keyboard-controller": ">=1.22.0"
|
|
93
95
|
},
|
|
94
96
|
"publishConfig": {
|
|
95
97
|
"access": "public"
|