@studio-piot/native-ui 0.2.5 → 0.17.0

package/docs/components/page.md

@@ -0,0 +1,183 @@
+# Page — usage
+
+The standard scrolling screen for a tab: a native stack screen inside `NativeTabs`, such as Today.
+
+- **Header clearance.** At rest, the content sits just below the header, including the large title. When you scroll, it moves behind the header. When the large title collapses, the content follows it. On iOS this comes from UIKit through `contentInsetAdjustmentBehavior="automatic"`, which `Page` always sets. On Android the native stack header is laid out above the screen, so nothing overlaps.
+- **Tab bar clearance.** The same automatic inset keeps the last item clear of the tab bar and home indicator on iOS. On Android the tab bar sits outside the screen.
+- **Tab accessory clearance.** Pass `tabAccessory` and `Page` renders the floating fallback pill (`TabAccessoryButton placement="screen"`) and adds bottom room for it. On iOS 26+ the accessory belongs to the native tab bar, so the in-screen pill and the extra room are left out.
+- **Padding.** Content gets the theme spacing: `spacing.screen` at the sides, `spacing.pageTop` at the top and `spacing.pageBottom` at the bottom (defaults 16, 16 and 24; see [Spacing](./button.md#spacing)). Turn it off with `padded={false}`.
+
+## Title
+
+The title belongs to the header, not the page. Set it in the stack options and turn on the large title to get the iOS collapsing title:
+
+```tsx
+// app/(tabs)/today/_layout.tsx
+<Stack screenOptions={{ headerLargeTitle: true }}>
+  <Stack.Screen name="index" options={{ title: "Today" }} />
+</Stack>
+```
+
+For a page with no title, leave `title` empty or set `headerShown: false`. `Page` needs no change either way.
+
+## Basic
+
+```tsx
+// app/(tabs)/today/index.tsx
+import { Page } from "@studio-piot/native-ui";
+
+export default function TodayScreen() {
+  return (
+    <Page>
+      <SummaryCard />
+      <RecentActivities />
+    </Page>
+  );
+}
+```
+
+## With the tab accessory
+
+Mount the iOS 26 copy in the tabs layout as usual (see [TabAccessoryButton](./tab-accessory-button.md)). `Page` handles the in-screen copy:
+
+```tsx
+import { Page } from "@studio-piot/native-ui";
+import { router } from "expo-router";
+import { SymbolView } from "expo-symbols";
+
+export default function TodayScreen() {
+  return (
+    <Page
+      tabAccessory={{
+        label: "New activity",
+        icon: ({ color, size }) => (
+          <SymbolView name={{ ios: "plus", android: "add" }} size={size} tintColor={color} />
+        ),
+        onPress: () => router.push("/new-activity"),
+      }}
+    >
+      {/* content */}
+    </Page>
+  );
+}
+```
+
+`tabAccessory` takes the same props as `TabAccessoryButton`, except `placement`, `variant` and `color`, which only apply to the iOS 26 copy.
+
+## Full-width sections
+
+To take one section out to the screen edges, such as an image, a map or a horizontal carousel, wrap it in `PageBleed`. It cancels exactly the side padding the page has: `spacing.screen` normally, or nothing with `padded={false}`.
+
+```tsx
+import { Page, PageBleed } from "@studio-piot/native-ui";
+
+<Page>
+  <Text>Padded text</Text>
+  <PageBleed>
+    <Image source={hero} style={{ width: "100%", aspectRatio: 16 / 9 }} />
+  </PageBleed>
+  <Text>Padded again</Text>
+</Page>
+```
+
+For a page where everything is full width, use `padded={false}` instead.
+
+`PageBleed` only knows the padding `Page` itself applies. If you change the side padding with `contentContainerStyle`, it won't follow; set `spacing.screen` on the theme instead.
+
+## Content under the header
+
+For a hero image or map that should start at the very top, behind the header, pass the header height as `contentUnderHeader`. Expo Router provides it through `useHeaderHeight()`:
+
+```tsx
+// app/(tabs)/today/_layout.tsx
+<Stack.Screen
+  name="index"
+  options={{ title: "", headerTransparent: true, headerLargeTitle: false }}
+/>
+```
+
+```tsx
+// app/(tabs)/today/index.tsx
+import { Page, PageBleed } from "@studio-piot/native-ui";
+import { useHeaderHeight } from "expo-router/react-navigation";
+
+export default function TodayScreen() {
+  const headerHeight = useHeaderHeight();
+
+  return (
+    <Page contentUnderHeader={headerHeight}>
+      <PageBleed>
+        <Image source={hero} style={{ width: "100%", height: 320 }} />
+      </PageBleed>
+      <Text>Padded content below the hero</Text>
+    </Page>
+  );
+}
+```
+
+- **What changes.** iOS adds `contentInset` on top of its automatic inset. `Page` sets a negative top inset equal to the header height, which cancels only the header clearance. The tab bar and accessory clearance stay automatic, and `spacing.pageTop` is dropped so the first item touches the top.
+- **Use a small, transparent header.** A large title collapses as you scroll, so its height changes and no single value cancels it. Set `headerLargeTitle: false` and `headerTransparent: true` on hero screens.
+- **Wrap the hero in `PageBleed`** so it also reaches the side edges.
+- **Android.** The native header adds no inset, so `contentUnderHeader` does nothing. With `headerTransparent: true` the content already starts under the header. With an opaque header, content can't go under it.
+
+## ScrollView props
+
+`Page` passes everything else to its `ScrollView`: `ref`, `refreshControl`, `onScroll`, `keyboardShouldPersistTaps` and so on. `contentContainerStyle` is merged after the built-in padding, so it can override it.
+
+```tsx
+const scrollRef = useRef<ScrollView>(null);
+
+<Page ref={scrollRef} refreshControl={<RefreshControl refreshing={loading} onRefresh={reload} />}>
+  …
+</Page>
+```
+
+`contentInsetAdjustmentBehavior` can't be changed. It is what gives the header and tab bar clearance. Your own `contentInset` is kept, and `contentUnderHeader` is added to it.
+
+## Theme roles
+
+| Usage | Role |
+|---|---|
+| Screen fill | `pageBackground` |
+
+When `tabAccessory` is set, the fallback pill also reads `buttonBackground` and `buttonLabel`.
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `children` | `ReactNode` | — | Page content |
+| `tabAccessory` | `PageTabAccessory` | — | Floating fallback pill and its bottom room |
+| `backgroundColor` | `string` | theme `pageBackground` | Optional override |
+| `padded` | `boolean` | `true` | Side, top and bottom padding from the theme spacing |
+| `contentUnderHeader` | `number` | — | Header height. Content starts at the very top, behind the header (iOS) |
+| `ref` | `Ref<ScrollView>` | — | Forwarded to the scroll view |
+| `style` | view style | — | Scroll view style, merged after `flex: 1` and the background |
+| …`ScrollViewProps` | | | Everything except `contentInsetAdjustmentBehavior` |
+
+### PageBleed
+
+| Prop | Type | Notes |
+|---|---|---|
+| `children` | `ReactNode` | The full-width section |
+| `style` | view style | Merged after the bleed margin |
+
+## Gotchas
+
+- **Make `Page` the screen's root element.** react-native-screens only links the header (large title collapse and insets) to a `ScrollView` that is a direct child of the screen. `Page` renders its `ScrollView` as that direct child, with no wrapper view. If you wrap `Page` in a `View`, content starts at the very top, under the header. `<Stack.Screen options>` next to it in a fragment is fine, because it renders nothing.
+- **Don't wrap `Page` in a `SafeAreaView` or add `insets.top` padding.** That clears the header twice, leaving a gap under it.
+- **The header must be translucent for content to scroll behind it.** That is the default on iOS. An opaque `headerStyle: { backgroundColor }` still works, but content then scrolls under a solid bar.
+- **On iOS 26, check that the last item clears the native accessory on a device.** If it doesn't, add room with `contentContainerStyle={{ paddingBottom: … }}`.
+
+## Imports
+
+```ts
+import {
+  Page,
+  PageBleed,
+  PAGE_THEME_ROLES,
+  type PageBleedProps,
+  type PageProps,
+  type PageTabAccessory,
+} from "@studio-piot/native-ui";
+```

package/docs/components/select.md

@@ -36,7 +36,7 @@ Import `react-native-gesture-handler` at the top of the entry layout (before oth
 
 ## Theme roles
 
-Uses Field roles: `fieldBackground`, `fieldText`, `fieldPlaceholder`, `fieldLabel`, `fieldDescription`, `fieldBorder`, `fieldError`, plus **`fieldSelectSelected`** for the selected option check / label tint.
+Uses Field roles: `fieldBackground`, `fieldText`, `fieldPlaceholder`, `fieldLabel`, `fieldDescription`, `fieldBorder`, `fieldError`, plus **`fieldSelectSelected`** for the selected option check / label tint, and **`selectCloseBackground`** / **`selectCloseIcon`** for the default sheet close disc and its cross. Each has a matching optional prop (`closeBackgroundColor`, `closeIconColor`).
 
 ## Basic usage
 
@@ -58,7 +58,7 @@ import { Select } from "@studio-piot/native-ui";
 
 ## Close control
 
-Default is a dark disc with a white × (`SelectCloseButton`). Override:
+The default is a filled disc with a cross (`SelectCloseButton`), coloured by `selectCloseBackground` and `selectCloseIcon`. Override:
 
 ```tsx
 closeButton={(dismiss) => <YourClose onPress={dismiss} />}

package/docs/components/tab-accessory-button.md

@@ -0,0 +1,146 @@
+# TabAccessoryButton — usage
+
+A primary action that floats above the bottom tabs, such as "New activity" on a Today tab.
+
+- **iOS 26 and later.** Expo Router's `NativeTabs.BottomAccessory` is UIKit's tab bar accessory: the glass strip above the tabs that Apple Music uses for its mini player. iOS draws the glass, sets the position and handles safe areas. `TabAccessoryButton` supplies the content only: an icon and a label, no fill. A filled button inside the accessory would give two shapes, one inside the other.
+- **Android and iOS 18 and earlier.** There is no accessory. The button floats a filled pill (a `Button` with `radius="full"`) at the bottom of the tab screen, just above the tabs.
+
+You mount it twice, and `placement` makes each copy render only where it belongs. You don't need a platform check in the app.
+
+| `placement` | Mount it in | Renders on |
+|---|---|---|
+| `"accessory"` | `NativeTabs.BottomAccessory` | iOS 26+ |
+| `"screen"` | The tab screen, after the scroll view | Android, iOS 18 and earlier |
+
+## Tabs layout
+
+```tsx
+// app/(tabs)/_layout.tsx
+import { TabAccessoryButton } from "@studio-piot/native-ui";
+import { router, useSegments } from "expo-router";
+import { NativeTabs } from "expo-router/unstable-native-tabs";
+import { SymbolView } from "expo-symbols";
+
+export default function TabsLayout() {
+  const onToday = useSegments().some((segment) => segment === "today");
+
+  return (
+    <NativeTabs minimizeBehavior="never">
+      {onToday ? (
+        <NativeTabs.BottomAccessory>
+          <TabAccessoryButton
+            placement="accessory"
+            label="New activity"
+            icon={({ color, size }) => (
+              <SymbolView name="plus" size={size} weight="semibold" tintColor={color} />
+            )}
+            onPress={() => router.push("/new-activity")}
+          />
+        </NativeTabs.BottomAccessory>
+      ) : null}
+      <NativeTabs.Trigger name="today">{/* … */}</NativeTabs.Trigger>
+    </NativeTabs>
+  );
+}
+```
+
+The accessory belongs to the tab bar, not to a tab, so render it conditionally to show it on one tab only. Without that check it shows on every tab.
+
+## Tab screen
+
+```tsx
+// app/(tabs)/today/index.tsx
+import {
+  TabAccessoryButton,
+  tabAccessoryScreenInset,
+  useThemeSpacing,
+} from "@studio-piot/native-ui";
+
+export default function TodayScreen() {
+  const { screen } = useThemeSpacing();
+
+  return (
+    <View style={{ flex: 1 }}>
+      <ScrollView contentContainerStyle={{ paddingBottom: tabAccessoryScreenInset(screen) }}>
+        {/* content */}
+      </ScrollView>
+      <TabAccessoryButton
+        placement="screen"
+        label="New activity"
+        icon={plusIcon}
+        onPress={() => router.push("/new-activity")}
+      />
+    </View>
+  );
+}
+```
+
+The screen's root `View` needs `flex: 1`, because the pill is positioned absolutely against it. It sits `spacing.screen` from the theme (default 16) from each side and from the bottom, so the gap around it is even. `tabAccessoryScreenInset(spacing.screen)` keeps the last item of the scroll view clear of the pill: the pill height plus that gap below and above it. `TAB_ACCESSORY_SCREEN_INSET` (84) is the same value with the default spacing. On iOS 26 the in-screen copy renders nothing, so the padding is only extra space at the end of the scroll.
+
+`Page` does all of this for you with its `tabAccessory` prop. See [Page](./page.md).
+
+## Filled (brand colour)
+
+The accessory takes no tint, so `variant="filled"` covers the glass with a pill in the button colours instead (`buttonBackground` and `buttonLabel`). The pill fills the accessory edge to edge and is fully rounded, so you see one coloured capsule above the tabs, not a shape inside the glass. It matches the fallback pill on other platforms.
+
+```tsx
+<NativeTabs.BottomAccessory>
+  <TabAccessoryButton
+    placement="accessory"
+    variant="filled"
+    label="New activity"
+    icon={plusIcon}
+    onPress={() => router.push("/new-activity")}
+  />
+</NativeTabs.BottomAccessory>
+```
+
+Use it for one primary brand action. For anything secondary, keep the default glass so the tab bar area stays calm.
+
+## Icons
+
+`icon` is a `ButtonIcon` render function, the same one `Button` takes: `({ color, size }) => ReactNode`. The colour is `tabAccessoryLabel` for the glass variant and `buttonLabel` for the filled variant and the fallback pill. Icon size is 20. SF Symbols are iOS only; on Android use a platform name (`name={{ ios: "plus", android: "add" }}` with recent expo-symbols) or another icon set.
+
+## Theme roles
+
+| Usage | Role |
+|---|---|
+| Glass label and icon (iOS 26+) | `tabAccessoryLabel` |
+| Filled variant and fallback pill: fill | `buttonBackground` |
+| Filled variant and fallback pill: label and icon | `buttonLabel` |
+
+Only the roles for the platform you are on are read, but add all three to both light and dark maps. `tabAccessoryLabel` is usually your `text` colour, since it sits on glass like the tab labels.
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `placement` | `"accessory" \| "screen"` | — | Required. See above |
+| `label` | `string` | — | Required. Shown text and accessibility label |
+| `onPress` | `() => void` | — | Required |
+| `icon` | `ButtonIcon` | — | Before the label |
+| `variant` | `"glass" \| "filled"` | `"glass"` | iOS 26+ look. The fallback is always filled |
+| `disabled` | `boolean` | `false` | 40% opacity; not pressable |
+| `color` | `string` | theme `tabAccessoryLabel` | Glass content override |
+| `backgroundColor` | `string` | theme `buttonBackground` | Filled and fallback pill fill override |
+| `labelColor` | `string` | theme `buttonLabel` | Filled and fallback pill label override |
+
+## Gotchas
+
+- **Don't put a `Button` in the accessory.** Its padding leaves a smaller shape inside the system glass. For a coloured accessory, use `variant="filled"`, which fills it edge to edge.
+- **The accessory is full width.** iOS sets its size. If you need a small centred pill instead, that is a custom `GlassView` from expo-glass-effect, not this component.
+- **`minimizeBehavior`.** With `"onScrollDown"`, iOS moves the accessory inline with the collapsed tab bar, and the content gets less room. Keep the label short.
+
+## Imports
+
+```ts
+import {
+  TabAccessoryButton,
+  TAB_ACCESSORY_SCREEN_INSET,
+  TAB_ACCESSORY_THEME_ROLES,
+  tabAccessoryScreenInset,
+  type TabAccessoryButtonProps,
+  type TabAccessoryPlacement,
+  type TabAccessoryVariant,
+} from "@studio-piot/native-ui";
+```

package/docs/specifications/Liquid Glass header buttons in Expo Router.md

@@ -0,0 +1,327 @@
+# Liquid Glass header buttons in Expo Router
+
+Oct 2, 2026 · @Guillaume
+
+## How it works
+
+On iOS 26, the native stack puts whatever `headerLeft` or `headerRight` returns inside a native `UIBarButtonItem`. iOS draws the Liquid Glass background around it automatically. Your job is to supply the content only: an icon, or an icon and a label.
+
+- **Never add your own background or border.** A styled button inside the glass gives you two shapes, one inside the other.
+- **The shape follows the content.** A square (36×36) gives a circle. Wider content gives a capsule.
+- **One function, one glass shape.** Everything returned by `headerRight` shares one capsule, even when it contains several buttons.
+- **Android and iOS 18 and earlier have no glass.** The same code shows plain icons there.
+
+## Icon only (round)
+
+A 36×36 `Pressable` holding one SF Symbol becomes a glass circle. `size` sets the icon size and defaults to 17. The other examples reuse this component.
+
+```tsx
+// components/header/HeaderIcon.tsx
+import { useThemeColor } from "@/hooks/useThemeColor";
+import { SFSymbol, SymbolView } from "expo-symbols";
+import { Pressable } from "react-native";
+
+type HeaderIconProps = {
+  name: SFSymbol;
+  label: string; // accessibility label, required for icon-only buttons
+  onPress: () => void;
+  size?: number; // icon size, default 17
+  weight?: "regular" | "medium" | "semibold" | "bold";
+};
+
+export function HeaderIcon({
+  name,
+  label,
+  onPress,
+  size = 17,
+  weight = "semibold",
+}: HeaderIconProps) {
+  const text = useThemeColor("text");
+
+  return (
+    <Pressable
+      onPress={onPress}
+      hitSlop={6}
+      accessibilityRole="button"
+      accessibilityLabel={label}
+      style={({ pressed }) => ({
+        width: 36,
+        height: 36,
+        alignItems: "center",
+        justifyContent: "center",
+        opacity: pressed ? 0.5 : 1,
+      })}
+    >
+      <SymbolView name={name} size={size} weight={weight} tintColor={text} />
+    </Pressable>
+  );
+}
+```
+
+Usage:
+
+```tsx
+<Stack.Screen
+  name="index"
+  options={{
+    headerLeft: () => (
+      <HeaderIcon name="xmark" label="Close" size={18} onPress={() => router.back()} />
+    ),
+  }}
+/>
+```
+
+## Capsule (icon and label)
+
+An icon, a gap, a label and horizontal padding make content wider than it is tall, so iOS draws a pill. The icon defaults to 15 so it sits close to the height of the 16pt label.
+
+```tsx
+// components/header/HeaderCapsule.tsx
+import { useThemeColor } from "@/hooks/useThemeColor";
+import { SFSymbol, SymbolView } from "expo-symbols";
+import { Pressable, Text } from "react-native";
+
+type HeaderCapsuleProps = {
+  icon: SFSymbol;
+  label: string;
+  onPress: () => void;
+  iconSize?: number; // default 15
+  fontSize?: number; // default 16
+};
+
+export function HeaderCapsule({
+  icon,
+  label,
+  onPress,
+  iconSize = 15,
+  fontSize = 16,
+}: HeaderCapsuleProps) {
+  const text = useThemeColor("text");
+
+  return (
+    <Pressable
+      onPress={onPress}
+      accessibilityRole="button"
+      accessibilityLabel={label}
+      style={({ pressed }) => ({
+        flexDirection: "row",
+        alignItems: "center",
+        gap: 6,
+        height: 36,
+        paddingHorizontal: 12,
+        opacity: pressed ? 0.5 : 1,
+      })}
+    >
+      <SymbolView name={icon} size={iconSize} weight="semibold" tintColor={text} />
+      <Text style={{ color: text, fontSize, fontWeight: "600" }}>{label}</Text>
+    </Pressable>
+  );
+}
+```
+
+Usage:
+
+```tsx
+headerLeft: () => (
+  <HeaderCapsule icon="xmark" label="Close" iconSize={16} onPress={() => router.back()} />
+),
+```
+
+## Multiple icons (bundled)
+
+Put several `HeaderIcon`s in one row `View` and they share a single glass capsule. Each icon keeps its own size and action.
+
+```tsx
+// components/header/HeaderGroup.tsx
+import { ReactNode } from "react";
+import { View } from "react-native";
+
+export function HeaderGroup({ children }: { children: ReactNode }) {
+  return (
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 4 }}>
+      {children}
+    </View>
+  );
+}
+```
+
+Usage:
+
+```tsx
+headerRight: () => (
+  <HeaderGroup>
+    <HeaderIcon
+      name="bookmark"
+      label="Saved routes"
+      size={19}
+      onPress={() => router.push("/new-activity/saved-routes")}
+    />
+    <HeaderIcon
+      name="gearshape"
+      label="Settings"
+      onPress={() => router.push("/settings")}
+    />
+  </HeaderGroup>
+),
+```
+
+A custom-view `headerRight` gives you one shared capsule. To get two separate circles, each button has to be its own native bar button item, which needs the native bar-button-items API in your Expo Router or react-native-screens version.
+
+## Header left and right
+
+The full `_layout.tsx` for the New activity flow has a Close capsule on the left and a bundled pair of icons on the right. Child screens keep the default back button.
+
+```tsx
+// app/new-activity/_layout.tsx
+import { HeaderCapsule } from "@/components/header/HeaderCapsule";
+import { HeaderGroup } from "@/components/header/HeaderGroup";
+import { HeaderIcon } from "@/components/header/HeaderIcon";
+import { useThemeColor } from "@/hooks/useThemeColor";
+import { router, Stack } from "expo-router";
+
+export default function NewActivityLayout() {
+  const background = useThemeColor("background");
+  const text = useThemeColor("text");
+
+  return (
+    <Stack
+      screenOptions={{
+        headerLargeTitle: false,
+        headerTintColor: text,
+        headerTitleStyle: { color: text },
+        headerStyle: { backgroundColor: background },
+        headerShadowVisible: false,
+        contentStyle: { backgroundColor: background },
+      }}
+    >
+      <Stack.Screen
+        name="index"
+        options={{
+          title: "New activity",
+          headerBackVisible: false,
+          headerLeft: () => (
+            <HeaderCapsule icon="xmark" label="Close" onPress={() => router.back()} />
+          ),
+          headerRight: () => (
+            <HeaderGroup>
+              <HeaderIcon
+                name="bookmark"
+                label="Saved routes"
+                size={19}
+                onPress={() => router.push("/new-activity/saved-routes")}
+              />
+              <HeaderIcon
+                name="gearshape"
+                label="Settings"
+                onPress={() => router.push("/settings")}
+              />
+            </HeaderGroup>
+          ),
+        }}
+      />
+      <Stack.Screen name="running" options={{ title: "Running" }} />
+      <Stack.Screen name="saved-routes" options={{ title: "Saved routes" }} />
+      <Stack.Screen name="hiit" options={{ title: "HIIT" }} />
+    </Stack>
+  );
+}
+```
+
+Route paths such as `/new-activity/saved-routes` and `/settings` are placeholders. Change them to match your app.
+
+**Setting buttons from inside a screen.** When a button needs the screen's state, set the options in the screen file with `<Stack.Screen options={{ headerRight: … }} />` instead of in the layout:
+
+```tsx
+// app/new-activity/running.tsx
+export default function RunningScreen() {
+  const [favourite, setFavourite] = useState(false);
+
+  return (
+    <>
+      <Stack.Screen
+        options={{
+          headerRight: () => (
+            <HeaderIcon
+              name={favourite ? "heart.fill" : "heart"}
+              label={favourite ? "Remove favourite" : "Add favourite"}
+              onPress={() => setFavourite((f) => !f)}
+            />
+          ),
+        }}
+      />
+      {/* screen content */}
+    </>
+  );
+}
+```
+
+## Actions
+
+Every button takes an `onPress`, so any function works. These are the common ones.
+
+| Goal | Call | Notes |
+| --- | --- | --- |
+| Go back one screen | `router.back()` | From the first screen of a nested stack, this closes the modal |
+| Close the modal | `router.dismiss()` | Use when the stack is presented with `presentation: "modal"` |
+| Close the whole flow from a deep screen | `router.dismissAll()` | Returns to the first screen of the stack. Follow with `router.back()` to leave the modal |
+| Open another screen | `router.push("/path")` | Adds to the history |
+| Swap the current screen | `router.replace("/path")` | No back step to the old screen |
+| Open a sheet | `router.push("/sheet-route")` | Set `presentation: "formSheet"` on that route |
+| Share | `Share.share({ message })` | From `react-native` |
+| Toggle state | `setState(...)` | Define the button in the screen file (see above) |
+
+**Safe close.** This closes the modal whether or not there is something to go back to:
+
+```tsx
+import { router } from "expo-router";
+
+export function closeFlow() {
+  if (router.canDismiss()) {
+    router.dismissAll();
+  }
+  router.back();
+}
+```
+
+**Confirm before discarding.** Ask before closing when the user has unsaved changes:
+
+```tsx
+import { Alert } from "react-native";
+
+function confirmClose(hasChanges: boolean) {
+  if (!hasChanges) return router.back();
+
+  Alert.alert("Discard activity?", "Your changes will be lost.", [
+    { text: "Keep editing", style: "cancel" },
+    { text: "Discard", style: "destructive", onPress: () => router.back() },
+  ]);
+}
+```
+
+**Haptic tap.** A light haptic makes the button feel native. Add it inside `HeaderIcon`'s `onPress`:
+
+```tsx
+import * as Haptics from "expo-haptics";
+
+onPress={() => {
+  Haptics.selectionAsync();
+  onPress();
+}}
+```
+
+## Sizing and gotchas
+
+| Element | Value | Why |
+| --- | --- | --- |
+| Round button box | 36×36 | Gives a circle that matches system buttons |
+| Icon in a round button | 17 (range 15–20) | Above about 24 the icon fills the circle and looks cramped |
+| Icon in a capsule | 15–16 | Close to the height of a 16pt label |
+| Capsule label | 16pt, weight 600 | Matches system bar button text |
+| Gap between bundled icons | 4 | Keeps the capsule tight |
+| `hitSlop` | 6–8 | A bigger tap area without changing the glass size |
+
+- **Thin symbols look smaller.** `xmark` fills less of its box than `gearshape` at the same size. Going about 1pt bigger on thin symbols makes up for it.
+- **`SymbolView` `size` is a box, not a font size.** Wide or tall symbols are shrunk to fit, so check alignment on a device.
+- **An empty `View` still shows glass.** `headerLeft: () => <View />` draws an empty circle. Hide the button with `headerLeft: undefined` instead.
+- **Always set `accessibilityLabel`.** VoiceOver has no text to read on icon-only buttons otherwise.
+- **No glass outside iOS 26.** If you want a visible circle on Android or older iOS, add a background only on those platforms.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studio-piot/native-ui",
-  "version": "0.2.5",
+  "version": "0.17.0",
   "description": "Shared React Native components for Studio Piot apps.",
   "homepage": "https://github.com/Studio-Piot/studio-native-ui#readme",
   "bugs": {