panelui-native 0.108.0 → 0.110.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.
Files changed (95) hide show
  1. package/lib/module/components/avatar-cropper/avatar-cropper-math.js +320 -0
  2. package/lib/module/components/avatar-cropper/avatar-cropper-math.js.map +1 -0
  3. package/lib/module/components/avatar-cropper/index.js +656 -0
  4. package/lib/module/components/avatar-cropper/index.js.map +1 -0
  5. package/lib/module/components/badge/index.js +85 -4
  6. package/lib/module/components/badge/index.js.map +1 -1
  7. package/lib/module/components/button/index.js +12 -0
  8. package/lib/module/components/button/index.js.map +1 -1
  9. package/lib/module/components/button-group/index.js +3 -0
  10. package/lib/module/components/button-group/index.js.map +1 -1
  11. package/lib/module/components/checkbox/index.js +54 -4
  12. package/lib/module/components/checkbox/index.js.map +1 -1
  13. package/lib/module/components/chip/index.js +23 -1
  14. package/lib/module/components/chip/index.js.map +1 -1
  15. package/lib/module/components/input/index.js +14 -0
  16. package/lib/module/components/input/index.js.map +1 -1
  17. package/lib/module/components/map/index.js +157 -5
  18. package/lib/module/components/map/index.js.map +1 -1
  19. package/lib/module/components/map/map-insets.js +174 -0
  20. package/lib/module/components/map/map-insets.js.map +1 -0
  21. package/lib/module/components/radio-group/index.js +49 -3
  22. package/lib/module/components/radio-group/index.js.map +1 -1
  23. package/lib/module/components/select/index.js +54 -2
  24. package/lib/module/components/select/index.js.map +1 -1
  25. package/lib/module/components/switch/index.js +42 -3
  26. package/lib/module/components/switch/index.js.map +1 -1
  27. package/lib/module/components/tabs/index.js +147 -1
  28. package/lib/module/components/tabs/index.js.map +1 -1
  29. package/lib/module/components/textarea/index.js +18 -0
  30. package/lib/module/components/textarea/index.js.map +1 -1
  31. package/lib/module/components/toggle-button/index.js +34 -2
  32. package/lib/module/components/toggle-button/index.js.map +1 -1
  33. package/lib/module/icons/index.js +6 -0
  34. package/lib/module/icons/index.js.map +1 -1
  35. package/lib/module/index.js +1 -0
  36. package/lib/module/index.js.map +1 -1
  37. package/lib/module/providers/panel-ui-provider.js +22 -10
  38. package/lib/module/providers/panel-ui-provider.js.map +1 -1
  39. package/lib/typescript/src/components/avatar-cropper/avatar-cropper-math.d.ts +98 -0
  40. package/lib/typescript/src/components/avatar-cropper/avatar-cropper-math.d.ts.map +1 -0
  41. package/lib/typescript/src/components/avatar-cropper/index.d.ts +168 -0
  42. package/lib/typescript/src/components/avatar-cropper/index.d.ts.map +1 -0
  43. package/lib/typescript/src/components/badge/index.d.ts +68 -0
  44. package/lib/typescript/src/components/badge/index.d.ts.map +1 -1
  45. package/lib/typescript/src/components/button/index.d.ts +12 -0
  46. package/lib/typescript/src/components/button/index.d.ts.map +1 -1
  47. package/lib/typescript/src/components/button-group/index.d.ts +9 -0
  48. package/lib/typescript/src/components/button-group/index.d.ts.map +1 -1
  49. package/lib/typescript/src/components/checkbox/index.d.ts +89 -0
  50. package/lib/typescript/src/components/checkbox/index.d.ts.map +1 -1
  51. package/lib/typescript/src/components/chip/index.d.ts +24 -0
  52. package/lib/typescript/src/components/chip/index.d.ts.map +1 -1
  53. package/lib/typescript/src/components/input/index.d.ts +30 -0
  54. package/lib/typescript/src/components/input/index.d.ts.map +1 -1
  55. package/lib/typescript/src/components/map/index.d.ts +67 -1
  56. package/lib/typescript/src/components/map/index.d.ts.map +1 -1
  57. package/lib/typescript/src/components/map/map-insets.d.ts +80 -0
  58. package/lib/typescript/src/components/map/map-insets.d.ts.map +1 -0
  59. package/lib/typescript/src/components/radio-group/index.d.ts +188 -1
  60. package/lib/typescript/src/components/radio-group/index.d.ts.map +1 -1
  61. package/lib/typescript/src/components/select/index.d.ts +9 -1
  62. package/lib/typescript/src/components/select/index.d.ts.map +1 -1
  63. package/lib/typescript/src/components/switch/index.d.ts +38 -0
  64. package/lib/typescript/src/components/switch/index.d.ts.map +1 -1
  65. package/lib/typescript/src/components/tabs/index.d.ts +10 -1
  66. package/lib/typescript/src/components/tabs/index.d.ts.map +1 -1
  67. package/lib/typescript/src/components/textarea/index.d.ts +18 -0
  68. package/lib/typescript/src/components/textarea/index.d.ts.map +1 -1
  69. package/lib/typescript/src/components/toggle-button/index.d.ts +24 -0
  70. package/lib/typescript/src/components/toggle-button/index.d.ts.map +1 -1
  71. package/lib/typescript/src/icons/index.d.ts +2 -0
  72. package/lib/typescript/src/icons/index.d.ts.map +1 -1
  73. package/lib/typescript/src/index.d.ts +8 -7
  74. package/lib/typescript/src/index.d.ts.map +1 -1
  75. package/lib/typescript/src/providers/panel-ui-provider.d.ts.map +1 -1
  76. package/package.json +9 -1
  77. package/src/components/avatar-cropper/avatar-cropper-math.ts +311 -0
  78. package/src/components/avatar-cropper/index.tsx +808 -0
  79. package/src/components/badge/index.tsx +30 -4
  80. package/src/components/button/index.tsx +9 -2
  81. package/src/components/button-group/index.tsx +1 -0
  82. package/src/components/checkbox/index.tsx +47 -3
  83. package/src/components/chip/index.tsx +5 -1
  84. package/src/components/input/index.tsx +6 -0
  85. package/src/components/map/index.tsx +215 -5
  86. package/src/components/map/map-insets.ts +169 -0
  87. package/src/components/radio-group/index.tsx +56 -4
  88. package/src/components/select/index.tsx +50 -1
  89. package/src/components/switch/index.tsx +16 -4
  90. package/src/components/tabs/index.tsx +61 -0
  91. package/src/components/textarea/index.tsx +6 -0
  92. package/src/components/toggle-button/index.tsx +16 -1
  93. package/src/icons/index.tsx +3 -0
  94. package/src/index.ts +24 -3
  95. package/src/providers/panel-ui-provider.tsx +21 -11
@@ -5,10 +5,22 @@ import { Text, textChildren } from '../../primitives/text';
5
5
 
6
6
  const badgeVariants = tv({
7
7
  slots: {
8
- root: 'flex-row items-center justify-center gap-1 self-start rounded-sm border border-transparent px-2 py-0.5',
9
- label: 'text-xs font-medium',
8
+ root: 'flex-row items-center justify-center gap-1 self-start rounded-sm border border-transparent',
9
+ label: 'font-medium',
10
10
  },
11
11
  variants: {
12
+ /*
13
+ * Listed before `shape` on purpose. Later variants win a conflict, and a
14
+ * dot or a count has to keep its own padding whatever size it is given;
15
+ * their dimensions per size are the compound variants below.
16
+ */
17
+ size: {
18
+ xs: { root: 'px-1 py-px', label: 'text-[10px]' },
19
+ sm: { root: 'px-1.5 py-px', label: 'text-[11px]' },
20
+ md: { root: 'px-2 py-0.5', label: 'text-xs' },
21
+ lg: { root: 'px-2.5 py-1', label: 'text-sm' },
22
+ xl: { root: 'px-3 py-1.5', label: 'text-base' },
23
+ },
12
24
  shape: {
13
25
  default: {},
14
26
  /** A bare status dot, no label. */
@@ -29,12 +41,26 @@ const badgeVariants = tv({
29
41
  info: { root: 'bg-info-subtle', label: 'text-info-foreground' },
30
42
  },
31
43
  },
44
+ compoundVariants: [
45
+ { shape: 'dot', size: 'xs', class: { root: 'h-1 w-1' } },
46
+ { shape: 'dot', size: 'sm', class: { root: 'h-1.5 w-1.5' } },
47
+ { shape: 'dot', size: 'lg', class: { root: 'h-2.5 w-2.5' } },
48
+ { shape: 'dot', size: 'xl', class: { root: 'h-3 w-3' } },
49
+ { shape: 'count', size: 'xs', class: { root: 'h-3.5 min-w-3.5 px-1' } },
50
+ { shape: 'count', size: 'sm', class: { root: 'h-4 min-w-4 px-1' } },
51
+ { shape: 'count', size: 'lg', class: { root: 'h-6 min-w-6 px-2' } },
52
+ { shape: 'count', size: 'xl', class: { root: 'h-7 min-w-7 px-2' } },
53
+ ],
32
54
  defaultVariants: {
33
55
  variant: 'default',
34
56
  shape: 'default',
57
+ size: 'md',
35
58
  },
36
59
  });
37
60
 
61
+ /** How big a badge is. */
62
+ export type BadgeSize = NonNullable<VariantProps<typeof badgeVariants>['size']>;
63
+
38
64
  /** Counts past this render as "99+" so the badge keeps its shape. */
39
65
  const MAX_COUNT = 99;
40
66
 
@@ -52,9 +78,9 @@ export interface BadgeProps
52
78
  }
53
79
 
54
80
  export const Badge = forwardRef<View, BadgeProps>(
55
- ({ children, className, labelClassName, variant, shape, count, ...props }, ref) => {
81
+ ({ children, className, labelClassName, variant, shape, size, count, ...props }, ref) => {
56
82
  const resolvedShape = shape ?? (count !== undefined ? 'count' : 'default');
57
- const { root, label } = badgeVariants({ variant, shape: resolvedShape });
83
+ const { root, label } = badgeVariants({ variant, shape: resolvedShape, size });
58
84
 
59
85
  const content =
60
86
  count !== undefined
@@ -60,6 +60,11 @@ const buttonVariants = tv({
60
60
  // These padding + intrinsic-font pairs equal the old 36/44/48dp boxes
61
61
  // at the default scale. `min-h-*`, rather than `h-*`, lets the same box
62
62
  // grow when the label's system-scaled glyphs or wrapped lines need it.
63
+ //
64
+ // `xs` is for a row that is already dense: a toolbar, a table cell, a
65
+ // filter beside a heading. At 28pt the default radius starts to read as
66
+ // a pill, so it steps down one with the height.
67
+ xs: { root: 'min-h-7 min-w-7 gap-1 rounded-md px-2 py-1', label: 'text-[12px]' },
63
68
  sm: { root: 'min-h-9 min-w-9 gap-1.5 px-2.5 py-2', label: 'text-[14px]' },
64
69
  md: { root: 'min-h-11 min-w-11 px-4 py-2.5', label: 'text-[16px]' },
65
70
  lg: { root: 'min-h-12 px-6 py-2.5', label: 'text-[18px]' },
@@ -146,10 +151,10 @@ export function useButtonGroup(): ButtonGroupContextValue | null {
146
151
  */
147
152
  const ATTACHED = 'rounded-none border-transparent shadow-none active:bg-accent';
148
153
 
149
- const SPINNER_SIZE = { sm: 'sm', md: 'sm', lg: 'md', xl: 'md', icon: 'sm' } as const;
154
+ const SPINNER_SIZE = { xs: 'sm', sm: 'sm', md: 'sm', lg: 'md', xl: 'md', icon: 'sm' } as const;
150
155
 
151
156
  /** Extra room around the styled sizes so even the compact button reaches 48dp. */
152
- const BUTTON_HIT_SLOP = { sm: 6, md: 2, lg: 0, xl: 0, icon: 2 } as const;
157
+ const BUTTON_HIT_SLOP = { xs: 10, sm: 6, md: 2, lg: 0, xl: 0, icon: 2 } as const;
153
158
 
154
159
  /**
155
160
  * The theme token each variant's content reads against. Icons in the content
@@ -265,6 +270,7 @@ export interface ButtonProps
265
270
  * axis that is genuinely unknown. See the host in the native branch below.
266
271
  */
267
272
  const NATIVE_HEIGHT: Record<NonNullable<ButtonVariantProps['size']>, number> = {
273
+ xs: 28,
268
274
  sm: 36,
269
275
  md: 44,
270
276
  lg: 48,
@@ -310,6 +316,7 @@ const NATIVE_ICON_FRAME = 44;
310
316
  * measurement to get wrong — so there is no reason to find out on both at once.
311
317
  */
312
318
  const NATIVE_CONTROL_SIZE = {
319
+ xs: 'mini',
313
320
  sm: 'small',
314
321
  md: 'regular',
315
322
  lg: 'large',
@@ -82,6 +82,7 @@ const buttonGroupVariants = tv({
82
82
  /* Matched to the height the buttons will be, since a radius that suited a
83
83
  36pt run reads as a rectangle around a 48pt one. */
84
84
  size: {
85
+ xs: { root: 'rounded-md' },
85
86
  sm: { root: 'rounded-lg' },
86
87
  md: { root: 'rounded-xl' },
87
88
  lg: { root: 'rounded-xl' },
@@ -21,6 +21,42 @@ const checkboxVariants = tv({
21
21
  description: 'text-sm text-muted-foreground',
22
22
  },
23
23
  variants: {
24
+ /*
25
+ * The box, its tick and the text beside it move together. The row does
26
+ * not: it stays 48 points tall at every size, because that is the touch
27
+ * target and a smaller box is not a reason for a smaller one.
28
+ *
29
+ * Listed before `variant` so the card keeps the label weight it sets.
30
+ */
31
+ size: {
32
+ xs: {
33
+ row: 'gap-2',
34
+ box: 'h-3.5 w-3.5 rounded-sm',
35
+ fill: 'rounded-sm',
36
+ label: 'text-xs',
37
+ description: 'text-xs',
38
+ },
39
+ sm: {
40
+ row: 'gap-2',
41
+ box: 'h-4 w-4 rounded-sm',
42
+ fill: 'rounded-sm',
43
+ label: 'text-[13px]',
44
+ description: 'text-xs',
45
+ },
46
+ md: {},
47
+ lg: {
48
+ row: 'gap-3',
49
+ box: 'h-6 w-6',
50
+ label: 'text-base',
51
+ },
52
+ xl: {
53
+ row: 'gap-3',
54
+ box: 'h-7 w-7 rounded-lg',
55
+ fill: 'rounded-lg',
56
+ label: 'text-lg',
57
+ description: 'text-base',
58
+ },
59
+ },
24
60
  variant: {
25
61
  default: {},
26
62
  /**
@@ -48,9 +84,16 @@ const checkboxVariants = tv({
48
84
  ],
49
85
  defaultVariants: {
50
86
  variant: 'default',
87
+ size: 'md',
51
88
  },
52
89
  });
53
90
 
91
+ /** How big a checkbox is. */
92
+ export type CheckboxSize = NonNullable<VariantProps<typeof checkboxVariants>['size']>;
93
+
94
+ /** The tick and the dash, sized to leave the same share of the box around them. */
95
+ const GLYPH_SIZE: Record<CheckboxSize, number> = { xs: 8, sm: 10, md: 12, lg: 14, xl: 16 };
96
+
54
97
  export interface CheckboxProps extends VariantProps<typeof checkboxVariants> {
55
98
  /**
56
99
  * Styles the pressable row — layout, border, fill. It does not reach the
@@ -92,6 +135,7 @@ export const Checkbox = forwardRef<View, CheckboxProps>(
92
135
  description,
93
136
  descriptionClassName,
94
137
  variant,
138
+ size = 'md',
95
139
  },
96
140
  ref
97
141
  ) => {
@@ -99,7 +143,7 @@ export const Checkbox = forwardRef<View, CheckboxProps>(
99
143
  // what changes is the glyph, not whether the fill is shown.
100
144
  const on = checked || !!indeterminate;
101
145
  const progress = useSharedValue(on ? 1 : 0);
102
- const slots = checkboxVariants({ variant, checked: on, disabled: !!disabled });
146
+ const slots = checkboxVariants({ variant, size, checked: on, disabled: !!disabled });
103
147
  const checkColor = useCSSVariable('--color-primary-foreground');
104
148
 
105
149
  useEffect(() => {
@@ -118,9 +162,9 @@ export const Checkbox = forwardRef<View, CheckboxProps>(
118
162
  <View className={slots.box()}>
119
163
  <Animated.View style={fillStyle} className={slots.fill()}>
120
164
  {indeterminate ? (
121
- <MinusIcon size={12} color={glyphColor} />
165
+ <MinusIcon size={GLYPH_SIZE[size]} color={glyphColor} />
122
166
  ) : (
123
- <CheckIcon size={12} color={glyphColor} />
167
+ <CheckIcon size={GLYPH_SIZE[size]} color={glyphColor} />
124
168
  )}
125
169
  </Animated.View>
126
170
  </View>
@@ -72,9 +72,11 @@ const chipVariants = tv({
72
72
  },
73
73
  },
74
74
  size: {
75
+ xs: { root: 'h-5 gap-0.5 px-1.5', label: 'text-[11px]' },
75
76
  sm: { root: 'h-6 gap-1 px-2', label: 'text-xs' },
76
77
  md: { root: 'h-7 gap-1.5 px-2.5', label: 'text-sm' },
77
78
  lg: { root: 'h-9 gap-2 px-3.5', label: 'text-base' },
79
+ xl: { root: 'h-11 gap-2 px-4', label: 'text-base' },
78
80
  },
79
81
  /**
80
82
  * The filter "on" state — a loud accent surface that wins over the resting
@@ -95,9 +97,11 @@ const chipVariants = tv({
95
97
  },
96
98
  },
97
99
  compoundVariants: [
100
+ { size: 'xs', closable: true, class: { close: 'h-3.5' } },
98
101
  { size: 'sm', closable: true, class: { close: 'h-4' } },
99
102
  { size: 'md', closable: true, class: { close: 'h-5' } },
100
103
  { size: 'lg', closable: true, class: { close: 'h-6' } },
104
+ { size: 'xl', closable: true, class: { close: 'h-7' } },
101
105
  ],
102
106
  defaultVariants: {
103
107
  variant: 'default',
@@ -121,7 +125,7 @@ const TINT_VAR: Record<ChipVariant, string> = {
121
125
  };
122
126
 
123
127
  /** The ✕ scales with the pill so it never looks stranded in a large chip. */
124
- const CLOSE_ICON: Record<ChipSize, number> = { sm: 11, md: 13, lg: 15 };
128
+ const CLOSE_ICON: Record<ChipSize, number> = { xs: 9, sm: 11, md: 13, lg: 15, xl: 17 };
125
129
 
126
130
  /* -------------------------------------------------------------------------- */
127
131
  /* State context */
@@ -105,9 +105,15 @@ const inputVariants = tv({
105
105
  */
106
106
  // The content boxes take the field's own horizontal padding, so an icon
107
107
  // sits at exactly the inset the text would have started at.
108
+ //
109
+ // Eight points a step, 32 to 64. `xs` is for a field inside something
110
+ // else that is already compact, such as a table cell or a toolbar; `xl`
111
+ // is for the one field a screen is about, such as a search or an amount.
112
+ xs: { field: 'h-8 px-2.5 text-[13px]', startContent: 'px-2.5', endContent: 'px-2.5' },
108
113
  sm: { field: 'h-10 px-3 text-[14px]', startContent: 'px-3', endContent: 'px-3' },
109
114
  md: { field: 'h-12 px-3.5 text-[16px]', startContent: 'px-3.5', endContent: 'px-3.5' },
110
115
  lg: { field: 'h-14 px-4 text-[16px]', startContent: 'px-4', endContent: 'px-4' },
116
+ xl: { field: 'h-16 px-5 text-[18px]', startContent: 'px-5', endContent: 'px-5' },
111
117
  },
112
118
  multiline: {
113
119
  // A multiline field grows, so a fixed height would crop it. Text starts
@@ -18,6 +18,19 @@
18
18
  * </Map>
19
19
  * ```
20
20
  *
21
+ * Anything else drawn over the map goes in a `Map.Overlay`. It is pinned to an
22
+ * edge or a corner and tells the map how much room it takes, so a control
23
+ * stack in the same corner sits past it rather than underneath:
24
+ *
25
+ * ```tsx
26
+ * <Map center={[-0.12, 51.5]} zoom={11}>
27
+ * <Map.Overlay position="bottom" safeArea>
28
+ * <Card>…</Card>
29
+ * </Map.Overlay>
30
+ * <Map.Controls position="bottom-right" />
31
+ * </Map>
32
+ * ```
33
+ *
21
34
  * The renderer is native and optional, so `Map` has a state no other component
22
35
  * here does: it may be unable to draw at all. It says so in place rather than
23
36
  * throwing, because the usual way to reach that state is running in a client
@@ -37,13 +50,22 @@ import {
37
50
  useCallback,
38
51
  useContext,
39
52
  useEffect,
53
+ useId,
40
54
  useImperativeHandle,
41
55
  useMemo,
42
56
  useRef,
43
57
  useState,
44
58
  type ReactNode,
45
59
  } from 'react';
46
- import { Pressable, StyleSheet, View, type PressableProps, type ViewProps } from 'react-native';
60
+ import {
61
+ Pressable,
62
+ StyleSheet,
63
+ View,
64
+ type LayoutChangeEvent,
65
+ type PressableProps,
66
+ type ViewProps,
67
+ } from 'react-native';
68
+ import { SafeAreaInsetsContext } from 'react-native-safe-area-context';
47
69
  import { useCSSVariable } from 'uniwind';
48
70
  import { tv } from 'tailwind-variants';
49
71
  import {
@@ -80,6 +102,16 @@ import {
80
102
  type MapFeatureAccessibilityDescription,
81
103
  } from './map-accessibility';
82
104
  import { asMapLayer, partitionMapChildren } from './map-children';
105
+ import {
106
+ controlsOffsets,
107
+ overlayOffsets,
108
+ overlayReservation,
109
+ reservedAt,
110
+ resolveMapInsets,
111
+ type MapOffsets,
112
+ type MapOverlayPosition,
113
+ type MapReservation,
114
+ } from './map-insets';
83
115
  import { useNativeStyle } from './native-style';
84
116
 
85
117
  export { hasMapLibre, CARTO_SOURCE };
@@ -93,11 +125,16 @@ export type {
93
125
  ViewState,
94
126
  };
95
127
  export type { MapFeatureAccessibility } from './map-accessibility';
128
+ export type { MapOverlayPosition } from './map-insets';
129
+
130
+ /** The room `Map.Controls` and `Map.Overlay` leave between themselves and an edge. */
131
+ const EDGE_GAP = 12;
96
132
 
97
133
  const mapVariants = tv({
98
134
  slots: {
99
135
  root: 'flex-1 overflow-hidden',
100
136
  controls: 'absolute gap-2',
137
+ overlay: 'absolute',
101
138
  // A control group is one surface split by hairlines rather than separate
102
139
  // buttons: at 36pt a gap between them reads as damage, not as spacing.
103
140
  group: 'overflow-hidden rounded-xl border border-border bg-card shadow-sm',
@@ -211,6 +248,33 @@ interface InternalMapContextValue extends MapContextValue {
211
248
 
212
249
  const MapContext = createContext<InternalMapContextValue | null>(null);
213
250
 
251
+ /**
252
+ * What the overlays have claimed, and how one claims it.
253
+ *
254
+ * Two contexts rather than a field on `MapContext`, because they change at
255
+ * different times. A claim changes whenever an overlay is laid out, and only
256
+ * the controls care; everything that reads `useMap()` for the camera would
257
+ * otherwise re-render each time a card above the map changed height.
258
+ */
259
+ const MapReservationsContext = createContext<readonly MapReservation[]>([]);
260
+ const MapReserveContext = createContext<
261
+ ((id: string, reservation: MapReservation | null) => void) | null
262
+ >(null);
263
+
264
+ const NO_SAFE_AREA = { top: 0, right: 0, bottom: 0, left: 0 };
265
+
266
+ /**
267
+ * The device's safe-area insets, or zeros when nothing provides them.
268
+ *
269
+ * Read from the context rather than through the package's hook, which throws
270
+ * outside a provider. A map does not need one to draw, so asking for one would
271
+ * turn a prop most maps never set into a requirement for all of them.
272
+ */
273
+ function useSafeArea(enabled: boolean) {
274
+ const insets = useContext(SafeAreaInsetsContext);
275
+ return enabled && insets ? insets : NO_SAFE_AREA;
276
+ }
277
+
214
278
  /**
215
279
  * The map's camera and view state, from inside it.
216
280
  *
@@ -386,6 +450,32 @@ const MapRoot = forwardRef<MapHandle, MapProps>(function MapRoot(
386
450
  []
387
451
  );
388
452
 
453
+ const [reservations, setReservations] = useState<
454
+ ReadonlyMap<string, MapReservation>
455
+ >(() => new globalThis.Map());
456
+
457
+ const reserve = useCallback((id: string, reservation: MapReservation | null) => {
458
+ setReservations((current) => {
459
+ const held = current.get(id);
460
+ // An overlay reports again whenever its insets are recomputed, usually
461
+ // with the figure it already gave. Keeping the old map when nothing
462
+ // moved is what stops that from re-rendering the controls.
463
+ if (
464
+ reservation
465
+ ? held?.position === reservation.position && held.extent === reservation.extent
466
+ : held === undefined
467
+ ) {
468
+ return current;
469
+ }
470
+ const next = new globalThis.Map(current);
471
+ if (reservation) next.set(id, reservation);
472
+ else next.delete(id);
473
+ return next;
474
+ });
475
+ }, []);
476
+
477
+ const reserved = useMemo(() => [...reservations.values()], [reservations]);
478
+
389
479
  // Every colour the style needs, resolved from the active theme. Hooks run
390
480
  // unconditionally, so they sit above the renderer check rather than inside it.
391
481
  const tokens: BasemapTokens = {
@@ -548,9 +638,13 @@ const MapRoot = forwardRef<MapHandle, MapProps>(function MapRoot(
548
638
  </MapLibreMap>
549
639
  ) : null}
550
640
  {overlay.length > 0 ? (
551
- <View style={StyleSheet.absoluteFill} pointerEvents="box-none">
552
- {textChildren(overlay)}
553
- </View>
641
+ <MapReserveContext.Provider value={reserve}>
642
+ <MapReservationsContext.Provider value={reserved}>
643
+ <View style={StyleSheet.absoluteFill} pointerEvents="box-none">
644
+ {textChildren(overlay)}
645
+ </View>
646
+ </MapReservationsContext.Provider>
647
+ </MapReserveContext.Provider>
554
648
  ) : null}
555
649
  <View
556
650
  accessibilityRole="list"
@@ -814,6 +908,19 @@ asMapLayer(MapPopup);
814
908
  export interface MapControlsProps {
815
909
  /** Which corner the stack sits in. */
816
910
  position?: MapControlsPosition;
911
+ /**
912
+ * How far the stack sits from the map's edges, in points: one number for
913
+ * every side, or only the sides that need one. Defaults to 12. For chrome
914
+ * that floats over the map without being inside it, such as a translucent
915
+ * tab bar or a header.
916
+ */
917
+ inset?: number | ViewPadding;
918
+ /**
919
+ * Keep clear of the status bar and the home indicator, for a map that runs
920
+ * underneath them. Reads the insets from the nearest `SafeAreaProvider` and
921
+ * does nothing without one.
922
+ */
923
+ safeArea?: boolean;
817
924
  /** Zoom in and out. On by default — it is the one control a map always needs. */
818
925
  zoom?: boolean;
819
926
  /** Recentre on the device's location. Needs a location permission. */
@@ -862,6 +969,8 @@ function ControlButton({
862
969
  */
863
970
  function MapControls({
864
971
  position = 'bottom-right',
972
+ inset,
973
+ safeArea = false,
865
974
  zoom = true,
866
975
  locate = false,
867
976
  compass = false,
@@ -871,6 +980,24 @@ function MapControls({
871
980
  }: MapControlsProps) {
872
981
  const slots = mapVariants({ position });
873
982
  const { mapRef, cameraRef, recenter: returnToStart } = useMap();
983
+ const safeAreaInsets = useSafeArea(safeArea);
984
+ const reservations = useContext(MapReservationsContext);
985
+ const offsets = controlsOffsets(position, {
986
+ gap: EDGE_GAP,
987
+ inset: resolveMapInsets(inset, EDGE_GAP, safeAreaInsets),
988
+ reserved: reservedAt(position, reservations),
989
+ });
990
+ /*
991
+ * Only the sides that have actually moved are set here. The corner itself
992
+ * comes from the classes, so a stack that nothing has pushed is styled
993
+ * exactly as it was before any of this existed, and a `className` that
994
+ * repositions it still wins.
995
+ */
996
+ const moved: MapOffsets = {};
997
+ for (const side of ['top', 'right', 'bottom', 'left'] as const) {
998
+ const value = offsets[side];
999
+ if (value !== undefined && value !== EDGE_GAP) moved[side] = value;
1000
+ }
874
1001
  // Every glyph takes the theme's icon colour from here rather than from its
875
1002
  // own default, which was chosen for wherever that icon first appeared — the
876
1003
  // minus sign's is white, for a checked checkbox, and vanished on the card.
@@ -925,7 +1052,7 @@ function MapControls({
925
1052
 
926
1053
  return (
927
1054
  <IconColorProvider color={iconTint}>
928
- <View className={slots.controls({ className })}>
1055
+ <View className={slots.controls({ className })} style={moved}>
929
1056
  {zoom ? (
930
1057
  <View className={slots.group()}>
931
1058
  <ControlButton label="Zoom in" onPress={() => nudgeZoom(1)}>
@@ -964,6 +1091,88 @@ function MapControls({
964
1091
  }
965
1092
  MapControls.displayName = 'Map.Controls';
966
1093
 
1094
+ export interface MapOverlayProps extends Omit<ViewProps, 'children'> {
1095
+ children?: ReactNode;
1096
+ /**
1097
+ * Where it is pinned: `top` or `bottom` for a band across the map between
1098
+ * its insets, or a corner (`top-left`, `top-right`, `bottom-left`,
1099
+ * `bottom-right`), which is as wide as what is inside it.
1100
+ */
1101
+ position?: MapOverlayPosition;
1102
+ /**
1103
+ * How far it sits from the map's edges, in points: one number for every
1104
+ * side, or only the sides that need one. Defaults to 12. Pass `0` for a card
1105
+ * that runs edge to edge.
1106
+ */
1107
+ inset?: number | ViewPadding;
1108
+ /**
1109
+ * Keep clear of the status bar and the home indicator, for a map that runs
1110
+ * underneath them. Reads the insets from the nearest `SafeAreaProvider` and
1111
+ * does nothing without one.
1112
+ */
1113
+ safeArea?: boolean;
1114
+ className?: string;
1115
+ }
1116
+
1117
+ /**
1118
+ * A place for your own views over the map.
1119
+ *
1120
+ * Any view can already be a child of `Map` and positioned by hand. What this
1121
+ * adds is that the map knows about it: it is measured, and a `Map.Controls`
1122
+ * in the same corner moves past it. Without that each is positioned without
1123
+ * knowing where the other is, and the card lands on the zoom buttons.
1124
+ *
1125
+ * The container itself takes no touches, so the map underneath still pans in
1126
+ * the gaps around whatever is inside it.
1127
+ */
1128
+ function MapOverlay({
1129
+ position = 'bottom',
1130
+ inset,
1131
+ safeArea = false,
1132
+ className,
1133
+ style,
1134
+ onLayout,
1135
+ children,
1136
+ ...props
1137
+ }: MapOverlayProps) {
1138
+ const slots = mapVariants();
1139
+ const id = useId();
1140
+ const reserve = useContext(MapReserveContext);
1141
+ const safeAreaInsets = useSafeArea(safeArea);
1142
+ const insets = resolveMapInsets(inset, EDGE_GAP, safeAreaInsets);
1143
+ const { top, right, bottom, left } = insets;
1144
+ const [height, setHeight] = useState(0);
1145
+
1146
+ useEffect(() => {
1147
+ reserve?.(id, overlayReservation(position, { top, right, bottom, left }, height));
1148
+ }, [reserve, id, position, top, right, bottom, left, height]);
1149
+
1150
+ // Its own effect, so the claim is given up once on unmount rather than
1151
+ // dropped and re-made every time the card changes height.
1152
+ useEffect(() => () => reserve?.(id, null), [reserve, id]);
1153
+
1154
+ const handleLayout = useCallback(
1155
+ (event: LayoutChangeEvent) => {
1156
+ setHeight(event.nativeEvent.layout.height);
1157
+ onLayout?.(event);
1158
+ },
1159
+ [onLayout]
1160
+ );
1161
+
1162
+ return (
1163
+ <View
1164
+ pointerEvents="box-none"
1165
+ className={slots.overlay({ className })}
1166
+ style={[overlayOffsets(position, insets), style]}
1167
+ onLayout={handleLayout}
1168
+ {...props}
1169
+ >
1170
+ {textChildren(children)}
1171
+ </View>
1172
+ );
1173
+ }
1174
+ MapOverlay.displayName = 'Map.Overlay';
1175
+
967
1176
  /** Turns a token into a colour a style layer can use. */
968
1177
  function useLineColor(color?: string) {
969
1178
  const fallback = useToken('--color-primary', '#262626');
@@ -1547,6 +1756,7 @@ export const Map = Object.assign(MapRoot, {
1547
1756
  Label: MapLabel,
1548
1757
  Popup: MapPopup,
1549
1758
  Controls: MapControls,
1759
+ Overlay: MapOverlay,
1550
1760
  Route: MapRoute,
1551
1761
  Arc: MapArc,
1552
1762
  GeoJSON: MapGeoJSON,