@studio-piot/native-ui 0.2.4 → 0.16.0

package/docs/components/form.md

@@ -1,87 +1,122 @@
 # Form — usage
 
-Full-screen modal form shell: keyboard-aware scroll, floating title bar with Cancel, sticky submit footer. Colours default from `ThemeProvider`. Apps own form fields (e.g. `FieldText`) and can swap Cancel via a slot.
+Full-screen form under the native stack header: keyboard-aware scroll, sticky submit footer, and the error banner. The title and close button come from the screen's stack options, like any other screen, so the header is native: the iOS 26 glass bar, the large title, back gestures. Colours default from `ThemeProvider`. Apps own the fields (e.g. `FieldText`).
 
-For `ThemeProvider` and `useThemeColor`, see [theme provider and Button usage](./button.md).
+For `ThemeProvider` and `useThemeColor`, see [theme provider and Button usage](./button.md). For a form over a map, see [FormSheet](./form-sheet.md).
 
 ## Peer dependencies
 
-`Form` needs these installed in the app (same versions you already use for Expo):
-
 - `react-native-keyboard-controller`
 - `react-native-safe-area-context`
+- `react-native-screens` (iOS overlay for the error banner)
 
 Wrap the app (or the form route) with `KeyboardProvider` from `react-native-keyboard-controller` and a safe-area provider.
 
-## Theme roles
-
-| Usage | Theme role |
-|---|---|
-| Screen / fade ground | `background` |
-| Title | `text` |
-| Footer ground | `surface` |
-| Submit fill | `buttonBackground` |
-| Submit label | `buttonLabel` |
-
 ## Basic usage
 
 ```tsx
-import { Form, FieldText } from "@studio-piot/native-ui";
+// app/(app)/create-activity/_layout.tsx
+export default function Layout() {
+  return <Stack />;
+}
+```
 
-export function NewItemScreen({ onClose, onSave }: Props) {
+```tsx
+// app/(app)/create-activity/index.tsx
+import { Form, FieldText, HeaderIcon } from "@studio-piot/native-ui";
+import { router, Stack } from "expo-router";
+import { SymbolView } from "expo-symbols";
+
+export default function CreateActivity() {
   return (
-    <Form title="New item" onClose={onClose} onSubmit={onSave}>
-      <FieldText label="Name" value={name} onChangeText={setName} />
-    </Form>
+    <>
+      <Stack.Screen
+        options={{
+          headerShown: true,
+          title: "New activity",
+          headerLeft: () => (
+            <HeaderIcon
+              label="Close"
+              icon={({ color, size }) => <SymbolView name="xmark" size={size} tintColor={color} />}
+              onPress={() => router.back()}
+            />
+          ),
+        }}
+      />
+      <Form onSubmit={save} errors={errors}>
+        <FieldText name="name" label="Name" value={name} onChangeText={setName} />
+      </Form>
+    </>
   );
 }
 ```
 
-## Close button slot
+- **Modal routes need their own stack.** On iOS a screen presented as a modal (`presentation: "modal"` or `"fullScreenModal"`) sits outside the navigation controller, so its header options are ignored and no header appears. Make the route a folder with its own `_layout.tsx` that returns a `<Stack />`, and put the screen in `index.tsx`. The parent still presents the folder as a modal, and the URL doesn't change.
+- **Make `Form` the screen's root element.** Its scroll view must be a direct child of the screen so iOS insets it for the header and content scrolls behind the bar. A `<Stack.Screen>` next to it in a fragment is fine. Don't wrap `Form` in a `View`.
+- **Header buttons.** Use `HeaderIcon` / `HeaderCapsule` for glass buttons, or `FormCloseButton` for a plain text "Cancel": `headerLeft: () => <FormCloseButton onPress={close} />`.
+- **Large title.** `headerLargeTitle: true` works. The content starts under the large title and follows it as it collapses.
+
+## Header fade
 
-Pass `closeButton` to replace the default plain Cancel (e.g. Expo liquid-glass Cancel in the app):
+For a wash behind a transparent header, with fields fading as they scroll under it, use [`HeaderWash`](./header-wash.md) as the stack's `headerBackground`:
 
 ```tsx
-import { Form } from "@studio-piot/native-ui";
-import { FormCloseButton } from "@/components/FormCloseButton";
-
-<Form
-  title="New activity"
-  onClose={() => router.back()}
-  onSubmit={save}
-  closeButton={<FormCloseButton onPress={() => router.back()} />}
->
-  {children}
-</Form>
+<Stack
+  screenOptions={{
+    headerTransparent: true,
+    headerBackground: () => <HeaderWash />,
+    scrollEdgeEffects: { top: "hidden" },
+  }}
+/>
 ```
 
-The default package `FormCloseButton` is a themed text Cancel. Export it if you want that control outside `Form`.
+On iOS the content still starts below the header and scrolls behind it. On Android a transparent toolbar overlaps the content, so keep the Android header opaque for forms, or pad the first field yourself.
+
+## Error banner
+
+Pass `errors` to show the banner (see [ErrorBanner](./error-banner.md)). A row scrolls its field clear of both the header and the banner. Pass `headerHeight={useHeaderHeight()}` (from `expo-router/react-navigation`) so that works with a large title or a custom header. Without it, `Form` assumes the status bar plus a standard bar.
+
+- **iOS:** the banner covers the top of the screen, including the native header. It is drawn in a native overlay window (`FullWindowOverlay` from react-native-screens), because the header bar sits above all React content.
+- **Android:** the native header doesn't overlap the screen, so the banner slides down directly below it.
+
+## Theme roles
+
+| Usage | Theme role |
+|---|---|
+| Scroll ground | `formBackground` |
+| Footer ground | `formFooterBackground` |
+| `FormCloseButton` label | `formClose` |
+| Submit fill | `buttonBackground` |
+| Submit label | `buttonLabel` |
+
+The header's colours come from your stack options (`headerTintColor`, `headerTitleStyle`, `headerStyle`).
 
 ## Props
 
 | Prop | Type | Default | Notes |
 |---|---|---|---|
-| `title` | `string` | — | Required. Header title |
 | `children` | `ReactNode` | — | Required. Scroll body |
-| `onClose` | `() => void` | — | Required. Wired to default Cancel |
-| `onSubmit` | `() => void` | — | Required. Sticky Save. Presents the error banner, then runs. |
-| `errors` | `FieldError[]` | `[]` | Field errors. The banner lists them and scrolls to each `name`. Editing a field dismisses the banner; the next submit shows it again. |
+| `onSubmit` | `() => void` | — | Required. Sticky submit. Presents the error banner, then runs |
+| `errors` | `FieldError[]` | `[]` | Field errors. The banner lists them and scrolls to each `name`. Editing a field dismisses the banner; the next submit shows it again |
 | `submitLabel` | `string` | `"Save"` | |
 | `submitting` | `boolean` | `false` | Loading on submit |
 | `submitDisabled` | `boolean` | `false` | |
-| `closeButton` | `ReactNode` | package Cancel | Slot for app Cancel |
 | `submitRadius` | `ButtonRadius` | `"lg"` | Submit button radius |
-| `paddingHorizontal` | `number` | `16` | Shared inset for header, content, and footer. Override per screen if needed. |
-| `backgroundColor` | `string` | theme `background` | Optional override |
-| `titleColor` | `string` | theme `text` | Optional override |
-| `footerBackgroundColor` | `string` | theme `surface` | Optional override |
+| `headerHeight` | `number` | status bar + standard bar | `useHeaderHeight()`. For scrolling an error's field clear of the header |
+| `paddingHorizontal` | `number` | theme `spacing.screen` | Side inset for the content and footer |
+| `backgroundColor` | `string` | theme `formBackground` | Optional override |
+| `footerBackgroundColor` | `string` | theme `formFooterBackground` | Optional override |
 | `buttonBackgroundColor` | `string` | theme `buttonBackground` | Optional override |
 | `buttonLabelColor` | `string` | theme `buttonLabel` | Optional override |
 
+The content starts `spacing.pageTop` below the header, the same as `Page`.
+
+## Migrating from 0.12
+
+`title`, `onClose`, `closeButton` and `titleColor` are gone, along with the `formTitle` role. Move them to the screen's stack options: `title`, `headerLeft`, and `headerTitleStyle`. Set `headerShown: true` if the route hid its header.
+
 ## Imports
 
 ```ts
-import { Form, FormCloseButton, type FormProps } from "@studio-piot/native-ui";
+import { Form, FormCloseButton, FORM_THEME_ROLES, type FormProps } from "@studio-piot/native-ui";
 ```
-
-Header, scroll content, and footer share one horizontal inset (default `16`). Override with `paddingHorizontal` when a screen needs a different gutter; apps keep their own layout tokens and do not import the package default.

package/docs/components/header-button.md

@@ -0,0 +1,310 @@
+# HeaderIcon, HeaderCapsule, HeaderGroup — usage
+
+Content for native stack header buttons (`headerLeft` / `headerRight` in Expo Router or React Navigation). On iOS 26 the native stack wraps whatever those functions return in a `UIBarButtonItem` and draws the Liquid Glass background itself. These components supply the content only: an icon, or an icon and a label.
+
+- **No background or border of their own on iOS 26+.** A styled button inside the glass gives two shapes, one inside the other.
+- **The shape follows the content.** `HeaderIcon` is 36×36, which gives a circle. `HeaderCapsule` is wider than tall, which gives a pill.
+- **One function, one glass shape.** Everything returned by `headerRight` shares one capsule; `HeaderGroup` lays several buttons out inside it.
+- **Fallback.** Android and iOS 18 and earlier have no glass. The same code shows plain icons there. Pass `fallbackBackgroundColor` to draw a circle or pill on those platforms only.
+
+The package has no Expo dependency, so the icon is a render function. It receives the resolved `color` and `size`; return an expo-symbols `SymbolView` or any other icon component.
+
+## HeaderIcon (round)
+
+```tsx
+import { HeaderIcon } from "@studio-piot/native-ui";
+import { SymbolView } from "expo-symbols";
+import { router, Stack } from "expo-router";
+
+<Stack.Screen
+  name="index"
+  options={{
+    headerLeft: () => (
+      <HeaderIcon
+        label="Close"
+        size={18}
+        icon={({ color, size }) => (
+          <SymbolView name="xmark" size={size} weight="semibold" tintColor={color} />
+        )}
+        onPress={() => router.back()}
+      />
+    ),
+  }}
+/>
+```
+
+`label` is required: it is the accessibility label, and VoiceOver has nothing else to read on an icon-only button.
+
+## HeaderCapsule (icon and label)
+
+```tsx
+headerLeft: () => (
+  <HeaderCapsule
+    label="Close"
+    icon={({ color, size }) => (
+      <SymbolView name="xmark" size={size} weight="semibold" tintColor={color} />
+    )}
+    onPress={() => router.back()}
+  />
+),
+```
+
+`icon` is optional; without it the capsule shows the label only.
+
+## HeaderGroup (bundled)
+
+Several buttons in one `HeaderGroup` share a single glass capsule. Each keeps its own size and action.
+
+```tsx
+headerRight: () => (
+  <HeaderGroup>
+    <HeaderIcon
+      label="Saved routes"
+      size={19}
+      icon={({ color, size }) => <SymbolView name="bookmark" size={size} tintColor={color} />}
+      onPress={() => router.push("/new-activity/saved-routes")}
+    />
+    <HeaderIcon
+      label="Settings"
+      icon={({ color, size }) => <SymbolView name="gearshape" size={size} tintColor={color} />}
+      onPress={() => router.push("/settings")}
+    />
+  </HeaderGroup>
+),
+```
+
+To get two separate glass circles instead of one shared capsule, 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.
+
+## Full layout
+
+```tsx
+// app/new-activity/_layout.tsx
+import {
+  HeaderCapsule,
+  HeaderGroup,
+  HeaderIcon,
+  type HeaderButtonIcon,
+  useThemeColor,
+} from "@studio-piot/native-ui";
+import { router, Stack } from "expo-router";
+import { SFSymbol, SymbolView } from "expo-symbols";
+
+const symbol =
+  (name: SFSymbol): HeaderButtonIcon =>
+  ({ color, size }) => <SymbolView name={name} size={size} weight="semibold" tintColor={color} />;
+
+export default function NewActivityLayout() {
+  const background = useThemeColor("background");
+  const text = useThemeColor("text");
+
+  return (
+    <Stack
+      screenOptions={{
+        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 label="Close" icon={symbol("xmark")} onPress={() => router.back()} />
+          ),
+          headerRight: () => (
+            <HeaderGroup>
+              <HeaderIcon
+                label="Saved routes"
+                size={19}
+                icon={symbol("bookmark")}
+                onPress={() => router.push("/new-activity/saved-routes")}
+              />
+              <HeaderIcon
+                label="Settings"
+                icon={symbol("gearshape")}
+                onPress={() => router.push("/settings")}
+              />
+            </HeaderGroup>
+          ),
+        }}
+      />
+      <Stack.Screen name="running" options={{ title: "Running" }} />
+    </Stack>
+  );
+}
+```
+
+A small `symbol()` helper like this keeps call sites short. Child screens keep the default back button.
+
+**Buttons that need screen state.** Set the options in the screen file instead of the layout:
+
+```tsx
+export default function RunningScreen() {
+  const [favourite, setFavourite] = useState(false);
+
+  return (
+    <>
+      <Stack.Screen
+        options={{
+          headerRight: () => (
+            <HeaderIcon
+              label={favourite ? "Remove favourite" : "Add favourite"}
+              icon={symbol(favourite ? "heart.fill" : "heart")}
+              onPress={() => setFavourite((f) => !f)}
+            />
+          ),
+        }}
+      />
+      {/* screen content */}
+    </>
+  );
+}
+```
+
+## Android and older iOS
+
+SF Symbols are iOS only. Pick the icon per platform inside the render function, or use an icon set that works everywhere:
+
+```tsx
+icon={({ color, size }) =>
+  Platform.OS === "ios" ? (
+    <SymbolView name="xmark" size={size} tintColor={color} />
+  ) : (
+    <MaterialIcons name="close" size={size + 4} color={color} />
+  )
+}
+```
+
+Without glass the buttons are plain icons. For a visible shape on those platforms only:
+
+```tsx
+<HeaderIcon label="Close" icon={symbol("xmark")} fallbackBackgroundColor="#0000000F" onPress={close} />
+```
+
+On iOS 26+ `fallbackBackgroundColor` is ignored, so you never get a shape inside the glass. Inside a `HeaderGroup`, put `fallbackBackgroundColor` on the group, not on each icon. `supportsLiquidGlass(Platform.OS, Platform.Version)` is exported if you need the same check elsewhere.
+
+## Actions
+
+Every button takes an `onPress`, so any function works.
+
+| 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()` | When the stack is presented with `presentation: "modal"` |
+| Close the whole flow from a deep screen | `router.dismissAll()` | Then `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 |
+| 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 |
+
+**Safe close** — closes the modal whether or not there is something to go back to:
+
+```tsx
+export function closeFlow() {
+  if (router.canDismiss()) {
+    router.dismissAll();
+  }
+  router.back();
+}
+```
+
+**Confirm before discarding:**
+
+```tsx
+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** — wrap `onPress`:
+
+```tsx
+onPress={() => {
+  Haptics.selectionAsync();
+  router.back();
+}}
+```
+
+## Theme roles
+
+Apps must add this key to both light and dark maps when `color` is omitted.
+
+| Usage | Role |
+|---|---|
+| Icon tint and capsule label | `headerButton` |
+
+Usually the same value as the header's `headerTintColor`.
+
+## Props
+
+### HeaderIcon
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `icon` | `HeaderButtonIcon` | — | Required. `({ color, size }) => ReactNode` |
+| `label` | `string` | — | Required. Accessibility label |
+| `onPress` | `() => void` | — | Required |
+| `size` | `number` | `17` | Icon box. Range 15–20; above ~24 the icon crowds the circle |
+| `color` | `string` | theme `headerButton` | Optional override |
+| `fallbackBackgroundColor` | `string` | — | Circle on non-glass platforms only |
+| `disabled` | `boolean` | `false` | 40% opacity; not pressable |
+| `hitSlop` | `number` | `6` | Bigger tap area without changing the glass size |
+| `style` | view style | — | Button box |
+
+### HeaderCapsule
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `string` | — | Required. Shown text and accessibility label |
+| `onPress` | `() => void` | — | Required |
+| `icon` | `HeaderButtonIcon` | — | Optional, before the label |
+| `iconSize` | `number` | `15` | Close to the height of the 16pt label |
+| `fontSize` | `number` | `16` | Label weight is 600, matching system bar button text |
+| `color` | `string` | theme `headerButton` | Optional override |
+| `fallbackBackgroundColor` | `string` | — | Pill on non-glass platforms only |
+| `disabled` | `boolean` | `false` | 40% opacity; not pressable |
+| `hitSlop` | `number` | `6` | |
+| `style` | view style | — | Button row |
+
+### HeaderGroup
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `children` | `ReactNode` | — | Usually `HeaderIcon`s |
+| `fallbackBackgroundColor` | `string` | — | Shared pill on non-glass platforms only |
+| `style` | view style | — | Row; gap between children is 4 |
+
+## Gotchas
+
+- **Thin symbols look smaller.** `xmark` fills less of its box than `gearshape` at the same size; go about 1pt bigger on thin symbols.
+- **`SymbolView` `size` is a box, not a font size.** Wide or tall symbols are shrunk to fit; check alignment on a device.
+- **An empty `View` still shows glass.** `headerLeft: () => <View />` draws an empty circle. Hide the button with `headerLeft: undefined`.
+
+## Imports
+
+```ts
+import {
+  HeaderCapsule,
+  HeaderGroup,
+  HeaderIcon,
+  HEADER_BUTTON_THEME_ROLES,
+  supportsLiquidGlass,
+  type HeaderButtonIcon,
+  type HeaderCapsuleProps,
+  type HeaderGroupProps,
+  type HeaderIconProps,
+} from "@studio-piot/native-ui";
+
+// Or components only:
+import { HeaderIcon } from "@studio-piot/native-ui/components";
+```

package/docs/components/header-wash.md

@@ -0,0 +1,40 @@
+# HeaderWash — usage
+
+A background for a transparent native header: your screen colour, nearly opaque at the top, fading to clear at the bottom of the header. The native title and buttons sit on the wash, and content fades as it scrolls up under the bar.
+
+Use it as the stack's `headerBackground`, together with `headerTransparent: true`:
+
+```tsx
+// app/(app)/create-activity/_layout.tsx
+import { HeaderWash } from "@studio-piot/native-ui";
+import { Stack } from "expo-router";
+
+export default function Layout() {
+  return (
+    <Stack
+      screenOptions={{
+        headerTransparent: true,
+        headerBackground: () => <HeaderWash />,
+        // iOS 26 adds its own soft edge under a transparent bar; hide it so the two don't stack.
+        scrollEdgeEffects: { top: "hidden" },
+      }}
+    />
+  );
+}
+```
+
+- **Sizing and stacking come from the native stack.** With `headerTransparent: true`, the stack draws `headerBackground` above the screen content and sizes it to the header's measured height, including a large title as it collapses.
+- **Colour.** Defaults to the `formBackground` role, so it matches `Form`. Pass `color` to match another screen.
+- **Content.** The screen's scroll view still starts below the header (`Form` and `Page` do this), so nothing sits under the wash until you scroll.
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `color` | `string` | theme `formBackground` | The wash colour, opaque end |
+
+## Imports
+
+```ts
+import { HeaderWash } from "@studio-piot/native-ui";
+```