@impulse-ui-native/popover 15.0.4 → 16.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 +81 -81
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,81 +1,81 @@
|
|
|
1
|
-
# @impulse-ui-native/popover
|
|
2
|
-
|
|
3
|
-
Native anchored overlays with theme tokens and Portal rendering. Tooltip and Popover share measurement and collision handling; no Overlay store or animation runtime is required.
|
|
4
|
-
|
|
5
|
-
## Installation and providers
|
|
6
|
-
|
|
7
|
-
```sh
|
|
8
|
-
pnpm add @impulse-ui-native/popover @impulse-ui-native/portal @impulse-ui-native/theme react-native-safe-area-context
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
Install `SafeAreaProvider`, `ThemeProvider`, and `PortalProvider` at the app root. Render `PortalsHost` last, inside a full-screen native View and the same theme/safe-area providers. Create the `PortalStore` once outside render. A custom `portalName` must match its host's `name`. Positioning measures both anchor and host in window coordinates, so an inset host also works within its own bounds.
|
|
12
|
-
|
|
13
|
-
## Compound popover
|
|
14
|
-
|
|
15
|
-
```tsx
|
|
16
|
-
import { Popover, Tooltip } from "@impulse-ui-native/popover";
|
|
17
|
-
import { Typography } from "@impulse-ui-native/primitives";
|
|
18
|
-
|
|
19
|
-
<Popover.Root placement="bottom">
|
|
20
|
-
<Popover.Trigger>
|
|
21
|
-
<Typography.Label>Visibility</Typography.Label>
|
|
22
|
-
</Popover.Trigger>
|
|
23
|
-
<Popover.Content>
|
|
24
|
-
<Popover.Title>Project visibility</Popover.Title>
|
|
25
|
-
<Popover.Description>Choose who can view this project.</Popover.Description>
|
|
26
|
-
{/* Supply any selection controls or actions here. */}
|
|
27
|
-
<Popover.Close>
|
|
28
|
-
<Typography.Label>Done</Typography.Label>
|
|
29
|
-
</Popover.Close>
|
|
30
|
-
</Popover.Content>
|
|
31
|
-
</Popover.Root>;
|
|
32
|
-
|
|
33
|
-
<Tooltip content="Syncs when you’re online">
|
|
34
|
-
<Typography.Label>Auto-sync info</Typography.Label>
|
|
35
|
-
</Tooltip>;
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
All compound parts render supplied children. `Popover.Content` owns Portal rendering and carries popover context to the host, so `Close` can dismiss there. Header, Footer, Title, and Description use independent theme styling. Other app-local React providers around an anchor do not automatically move with it; put those providers above the host or inside Content.
|
|
39
|
-
|
|
40
|
-
The convenience form composes Trigger, Content, Header, Title, Close, and Footer:
|
|
41
|
-
|
|
42
|
-
```tsx
|
|
43
|
-
<Popover
|
|
44
|
-
trigger={<Typography.Label>Details</Typography.Label>}
|
|
45
|
-
title="Project details"
|
|
46
|
-
>
|
|
47
|
-
<Popover.Description>Updated just now.</Popover.Description>
|
|
48
|
-
</Popover>
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
A truthy header replaces the generated title. The header includes a neutral X close icon by default; hideClose omits it. A truthy footer renders Popover.Footer with trailing, wrapping actions. Header and Footer are child-only View parts available for compound composition. Pass body content as children; triggerProps and contentProps continue to customize the trigger and positioned panel. Titles can wrap beside the close control instead of pushing it outside the header.
|
|
52
|
-
|
|
53
|
-
## Contract
|
|
54
|
-
|
|
55
|
-
- `open`, `defaultOpen` (false), and `onOpenChange` support controlled and uncontrolled state. Controlled consumers must apply requested changes.
|
|
56
|
-
- `placement` accepts `top`, `bottom`, `left`, and `right`. Popover defaults to bottom; Tooltip defaults to top. Left/right are physical placements.
|
|
57
|
-
- A press toggles Popover. Tooltip defaults to long-press. `triggerProps.trigger` or `Popover.Trigger`'s `trigger` selects either behavior. Consumer press/long-press callbacks are preserved.
|
|
58
|
-
- Root `disabled` suppresses the overlay and blocks trigger changes. Trigger/Close `disabled` or `loading` blocks that part's interaction. Supply a single Trigger and Content per Root; use non-interactive visual children inside Trigger rather than nesting another pressable.
|
|
59
|
-
- Outside taps and Android Back request dismissal. Outside taps are consumed; there is no dim scrim. Content sizes naturally without internal scrolling. Keep popovers compact; use a sheet, dialog, or screen for larger content. Keyboard avoidance and nested overlay coordination are outside this initial API.
|
|
60
|
-
- Tooltip `duration` defaults to 3000ms from opening; zero persists until dismissal. Timers clean up on close/unmount. Supply strings/numbers for token-styled text or a React node for custom content.
|
|
61
|
-
- Popover uses `colors.surface.elevated.value` with a subtle border and no default shadow. Override `components.popover` on ThemeProvider for geometry, typography, and panel styling. Tooltip owns its compact inverse styling through `components.popover.tooltip`, without a surface variant in Root or context.
|
|
62
|
-
- Popover content defaults to 320dp wide; Tooltip sizes to its content. Both are constrained to the available host width. Content spacing and width can be customized with primitive style props or `style`.
|
|
63
|
-
- Anchors and host bounds are measured on opening and polled every 100ms while open, following scrolling and layout changes. Only one measurement is in flight; slow native callbacks are allowed to finish. Closed overlays have no measurement timer. Content stays hidden until measured and when its anchor is outside the usable host bounds.
|
|
64
|
-
- Popover and Tooltip use rounded panels without arrows. Collision handling flips to the opposite side when it has more space, then shifts into safe-area bounds. Extremely large content can overlap the anchor after clamping.
|
|
65
|
-
|
|
66
|
-
## Exports and verification
|
|
67
|
-
|
|
68
|
-
`Popover`, `Tooltip`, and their prop and placement types are available directly or through `@impulse-ui-native/toolkit`. Storybook covers composition, controlled state, disabled triggers, long-press, and edge placements. Use the on-device Storybook host to verify rendering and interaction on iOS and Android.
|
|
69
|
-
|
|
70
|
-
## Surface migration
|
|
71
|
-
|
|
72
|
-
The surface prop and PopoverSurface type have been removed. Move former
|
|
73
|
-
components.popover.surfaces.elevated customizations to the flat panel tokens
|
|
74
|
-
(backgroundColor, borderColor, borderWidth, borderRadius, paddingHorizontal,
|
|
75
|
-
and paddingVertical). Move inverse hint styling to components.popover.tooltip;
|
|
76
|
-
its text color is named color. Customize Popover.Content directly for custom
|
|
77
|
-
panel styling.
|
|
78
|
-
|
|
79
|
-
## Agent and design reference
|
|
80
|
-
|
|
81
|
-
Start with the [capability guide](../../docs/design-system/capabilities/popover.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/popover
|
|
2
|
+
|
|
3
|
+
Native anchored overlays with theme tokens and Portal rendering. Tooltip and Popover share measurement and collision handling; no Overlay store or animation runtime is required.
|
|
4
|
+
|
|
5
|
+
## Installation and providers
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
pnpm add @impulse-ui-native/popover @impulse-ui-native/portal @impulse-ui-native/theme react-native-safe-area-context
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Install `SafeAreaProvider`, `ThemeProvider`, and `PortalProvider` at the app root. Render `PortalsHost` last, inside a full-screen native View and the same theme/safe-area providers. Create the `PortalStore` once outside render. A custom `portalName` must match its host's `name`. Positioning measures both anchor and host in window coordinates, so an inset host also works within its own bounds.
|
|
12
|
+
|
|
13
|
+
## Compound popover
|
|
14
|
+
|
|
15
|
+
```tsx
|
|
16
|
+
import { Popover, Tooltip } from "@impulse-ui-native/popover";
|
|
17
|
+
import { Typography } from "@impulse-ui-native/primitives";
|
|
18
|
+
|
|
19
|
+
<Popover.Root placement="bottom">
|
|
20
|
+
<Popover.Trigger>
|
|
21
|
+
<Typography.Label>Visibility</Typography.Label>
|
|
22
|
+
</Popover.Trigger>
|
|
23
|
+
<Popover.Content>
|
|
24
|
+
<Popover.Title>Project visibility</Popover.Title>
|
|
25
|
+
<Popover.Description>Choose who can view this project.</Popover.Description>
|
|
26
|
+
{/* Supply any selection controls or actions here. */}
|
|
27
|
+
<Popover.Close>
|
|
28
|
+
<Typography.Label>Done</Typography.Label>
|
|
29
|
+
</Popover.Close>
|
|
30
|
+
</Popover.Content>
|
|
31
|
+
</Popover.Root>;
|
|
32
|
+
|
|
33
|
+
<Tooltip content="Syncs when you’re online">
|
|
34
|
+
<Typography.Label>Auto-sync info</Typography.Label>
|
|
35
|
+
</Tooltip>;
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
All compound parts render supplied children. `Popover.Content` owns Portal rendering and carries popover context to the host, so `Close` can dismiss there. Header, Footer, Title, and Description use independent theme styling. Other app-local React providers around an anchor do not automatically move with it; put those providers above the host or inside Content.
|
|
39
|
+
|
|
40
|
+
The convenience form composes Trigger, Content, Header, Title, Close, and Footer:
|
|
41
|
+
|
|
42
|
+
```tsx
|
|
43
|
+
<Popover
|
|
44
|
+
trigger={<Typography.Label>Details</Typography.Label>}
|
|
45
|
+
title="Project details"
|
|
46
|
+
>
|
|
47
|
+
<Popover.Description>Updated just now.</Popover.Description>
|
|
48
|
+
</Popover>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
A truthy header replaces the generated title. The header includes a neutral X close icon by default; hideClose omits it. A truthy footer renders Popover.Footer with trailing, wrapping actions. Header and Footer are child-only View parts available for compound composition. Pass body content as children; triggerProps and contentProps continue to customize the trigger and positioned panel. Titles can wrap beside the close control instead of pushing it outside the header.
|
|
52
|
+
|
|
53
|
+
## Contract
|
|
54
|
+
|
|
55
|
+
- `open`, `defaultOpen` (false), and `onOpenChange` support controlled and uncontrolled state. Controlled consumers must apply requested changes.
|
|
56
|
+
- `placement` accepts `top`, `bottom`, `left`, and `right`. Popover defaults to bottom; Tooltip defaults to top. Left/right are physical placements.
|
|
57
|
+
- A press toggles Popover. Tooltip defaults to long-press. `triggerProps.trigger` or `Popover.Trigger`'s `trigger` selects either behavior. Consumer press/long-press callbacks are preserved.
|
|
58
|
+
- Root `disabled` suppresses the overlay and blocks trigger changes. Trigger/Close `disabled` or `loading` blocks that part's interaction. Supply a single Trigger and Content per Root; use non-interactive visual children inside Trigger rather than nesting another pressable.
|
|
59
|
+
- Outside taps and Android Back request dismissal. Outside taps are consumed; there is no dim scrim. Content sizes naturally without internal scrolling. Keep popovers compact; use a sheet, dialog, or screen for larger content. Keyboard avoidance and nested overlay coordination are outside this initial API.
|
|
60
|
+
- Tooltip `duration` defaults to 3000ms from opening; zero persists until dismissal. Timers clean up on close/unmount. Supply strings/numbers for token-styled text or a React node for custom content.
|
|
61
|
+
- Popover uses `colors.surface.elevated.value` with a subtle border and no default shadow. Override `components.popover` on ThemeProvider for geometry, typography, and panel styling. Tooltip owns its compact inverse styling through `components.popover.tooltip`, without a surface variant in Root or context.
|
|
62
|
+
- Popover content defaults to 320dp wide; Tooltip sizes to its content. Both are constrained to the available host width. Content spacing and width can be customized with primitive style props or `style`.
|
|
63
|
+
- Anchors and host bounds are measured on opening and polled every 100ms while open, following scrolling and layout changes. Only one measurement is in flight; slow native callbacks are allowed to finish. Closed overlays have no measurement timer. Content stays hidden until measured and when its anchor is outside the usable host bounds.
|
|
64
|
+
- Popover and Tooltip use rounded panels without arrows. Collision handling flips to the opposite side when it has more space, then shifts into safe-area bounds. Extremely large content can overlap the anchor after clamping.
|
|
65
|
+
|
|
66
|
+
## Exports and verification
|
|
67
|
+
|
|
68
|
+
`Popover`, `Tooltip`, and their prop and placement types are available directly or through `@impulse-ui-native/toolkit`. Storybook covers composition, controlled state, disabled triggers, long-press, and edge placements. Use the on-device Storybook host to verify rendering and interaction on iOS and Android.
|
|
69
|
+
|
|
70
|
+
## Surface migration
|
|
71
|
+
|
|
72
|
+
The surface prop and PopoverSurface type have been removed. Move former
|
|
73
|
+
components.popover.surfaces.elevated customizations to the flat panel tokens
|
|
74
|
+
(backgroundColor, borderColor, borderWidth, borderRadius, paddingHorizontal,
|
|
75
|
+
and paddingVertical). Move inverse hint styling to components.popover.tooltip;
|
|
76
|
+
its text color is named color. Customize Popover.Content directly for custom
|
|
77
|
+
panel styling.
|
|
78
|
+
|
|
79
|
+
## Agent and design reference
|
|
80
|
+
|
|
81
|
+
Start with the [capability guide](../../docs/design-system/capabilities/popover.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.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@impulse-ui-native/popover",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "16.0.0",
|
|
4
4
|
"description": "Portal-rendered tooltips and compound anchored popovers for ImpulseUI Native.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"react-native",
|
|
@@ -27,11 +27,11 @@
|
|
|
27
27
|
],
|
|
28
28
|
"sideEffects": false,
|
|
29
29
|
"dependencies": {
|
|
30
|
-
"@impulse-ui-native/icon": "
|
|
31
|
-
"@impulse-ui-native/core": "
|
|
32
|
-
"@impulse-ui-native/theme": "
|
|
33
|
-
"@impulse-ui-native/primitives": "
|
|
34
|
-
"@impulse-ui-native/portal": "
|
|
30
|
+
"@impulse-ui-native/icon": "16.0.0",
|
|
31
|
+
"@impulse-ui-native/core": "16.0.0",
|
|
32
|
+
"@impulse-ui-native/theme": "16.0.0",
|
|
33
|
+
"@impulse-ui-native/primitives": "16.0.0",
|
|
34
|
+
"@impulse-ui-native/portal": "16.0.0"
|
|
35
35
|
},
|
|
36
36
|
"devDependencies": {
|
|
37
37
|
"@impulse-ui-native/eslint-config": "1.0.0",
|