@studio-piot/native-ui 0.2.5 → 0.17.0

package/dist/theme/resolveThemeSpacing.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_THEME_SPACING = void 0;
+exports.resolveThemeSpacing = resolveThemeSpacing;
+exports.DEFAULT_THEME_SPACING = {
+    screen: 16,
+    pageTop: 16,
+    pageBottom: 24,
+};
+/** App spacing over the package defaults. Pure so it can be unit-tested. */
+function resolveThemeSpacing(spacing) {
+    return { ...exports.DEFAULT_THEME_SPACING, ...spacing };
+}
+//# sourceMappingURL=resolveThemeSpacing.js.map

package/dist/theme/resolveThemeSpacing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveThemeSpacing.js","sourceRoot":"","sources":["../../src/theme/resolveThemeSpacing.ts"],"names":[],"mappings":";;;AAgBA,kDAIC;AAXY,QAAA,qBAAqB,GAAiB;IACjD,MAAM,EAAE,EAAE;IACV,OAAO,EAAE,EAAE;IACX,UAAU,EAAE,EAAE;CACf,CAAC;AAEF,4EAA4E;AAC5E,SAAgB,mBAAmB,CACjC,OAA0C;IAE1C,OAAO,EAAE,GAAG,6BAAqB,EAAE,GAAG,OAAO,EAAE,CAAC;AAClD,CAAC"}

package/dist/theme/types.d.ts

@@ -1,8 +1,10 @@
+import type { ThemeSpacing } from "./resolveThemeSpacing";
 export type ThemeColors = Record<string, string>;
 export type ThemeContextValue = {
     colors: {
         light: ThemeColors;
         dark: ThemeColors;
     };
+    spacing: ThemeSpacing;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/theme/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/theme/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,IAAI,EAAE,WAAW,CAAA;KAAE,CAAC;CACnD,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/theme/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,IAAI,EAAE,WAAW,CAAA;KAAE,CAAC;IAClD,OAAO,EAAE,YAAY,CAAC;CACvB,CAAC"}

package/dist/theme/useThemeSpacing.d.ts

@@ -0,0 +1,4 @@
+import { type ThemeSpacing } from "./resolveThemeSpacing";
+/** Spacing from `ThemeProvider`, or the package defaults outside one. */
+export declare function useThemeSpacing(): ThemeSpacing;
+//# sourceMappingURL=useThemeSpacing.d.ts.map

package/dist/theme/useThemeSpacing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useThemeSpacing.d.ts","sourceRoot":"","sources":["../../src/theme/useThemeSpacing.ts"],"names":[],"mappings":"AACA,OAAO,EAAyB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGjF,yEAAyE;AACzE,wBAAgB,eAAe,IAAI,YAAY,CAE9C"}

package/dist/theme/useThemeSpacing.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useThemeSpacing = useThemeSpacing;
+const react_1 = require("react");
+const resolveThemeSpacing_1 = require("./resolveThemeSpacing");
+const ThemeProvider_1 = require("./ThemeProvider");
+/** Spacing from `ThemeProvider`, or the package defaults outside one. */
+function useThemeSpacing() {
+    return (0, react_1.useContext)(ThemeProvider_1.ThemeContext)?.spacing ?? resolveThemeSpacing_1.DEFAULT_THEME_SPACING;
+}
+//# sourceMappingURL=useThemeSpacing.js.map

package/dist/theme/useThemeSpacing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useThemeSpacing.js","sourceRoot":"","sources":["../../src/theme/useThemeSpacing.ts"],"names":[],"mappings":";;AAKA,0CAEC;AAPD,iCAAmC;AACnC,+DAAiF;AACjF,mDAA+C;AAE/C,yEAAyE;AACzE,SAAgB,eAAe;IAC7B,OAAO,IAAA,kBAAU,EAAC,4BAAY,CAAC,EAAE,OAAO,IAAI,2CAAqB,CAAC;AACpE,CAAC"}

package/docs/components/button.md

@@ -29,16 +29,36 @@ export function Root({ children }: { children: React.ReactNode }) {
 // Example app colours — role names are yours
 export const Colors = {
   light: {
-    buttonBackground: "#FF4F16",
-    buttonLabel: "#22201D",
+    buttonBackground: "#2563EB",
+    buttonLabel: "#FFFFFF",
   },
   dark: {
-    buttonBackground: "#FF4F16",
-    buttonLabel: "#22201D",
+    buttonBackground: "#2563EB",
+    buttonLabel: "#FFFFFF",
   },
 } as const;
 ```
 
+### Spacing
+
+`ThemeProvider` also takes optional `spacing`. Omitted keys keep the package default, so most apps don't set it.
+
+```tsx
+<ThemeProvider colors={Colors} spacing={{ screen: 20 }}>
+```
+
+| Key | Default | Used by |
+|---|---|---|
+| `screen` | `16` | Side padding of `Page` and `Form` content, `ErrorBanner`, the `TabAccessoryButton` fallback pill |
+| `pageTop` | `16` | Gap between the header and the first item of a `Page` |
+| `pageBottom` | `24` | Gap after the last item of a `Page` |
+
+Read it in your own components with `useThemeSpacing()`. Outside `ThemeProvider` it returns the defaults (`DEFAULT_THEME_SPACING`). A component's own padding prop, such as `Form`'s `paddingHorizontal`, still wins.
+
+```tsx
+const { screen } = useThemeSpacing();
+```
+
 ### `useThemeColor`
 
 Resolves a role for the current scheme (React Native `useColorScheme`; anything other than `"dark"` is light):
@@ -70,42 +90,82 @@ The package does not store preferences or call `Appearance.setColorScheme`. If y
 
 ## Button
 
-`Button` is presentational. Pass the colours you want. Full width of its parent is fixed.
+`Button` is presentational. Colours default from `ThemeProvider`; pass props only to override. Full width of its parent by default; override with `style`.
 
 ```tsx
-import { Button, useThemeColor } from "@studio-piot/native-ui";
+import { Button } from "@studio-piot/native-ui";
 
 export function SaveButton({ onPress }: { onPress: () => void }) {
-  return (
-    <Button
-      label="Save"
-      onPress={onPress}
-      backgroundColor={useThemeColor("buttonBackground")}
-      labelColor={useThemeColor("buttonLabel")}
-    />
-  );
+  return <Button label="Save" onPress={onPress} />;
 }
 ```
 
+### Theme roles
+
+Add these keys to both light and dark maps when you omit the colour props. `Form` uses the same roles for its submit button.
+
+| Prop | Default theme role | Filled | Outline |
+|---|---|---|---|
+| `backgroundColor` | `buttonBackground` | Fill | Border, label, icon, spinner |
+| `labelColor` | `buttonLabel` | Label, icon, spinner | Unused |
+
+Explicit props always win, so existing code that passes both colours keeps working:
+
+```tsx
+<Button
+  label="Delete"
+  onPress={onDelete}
+  backgroundColor={useThemeColor("danger")}
+  labelColor={useThemeColor("onDanger")}
+/>
+```
+
 ### Props
 
 | Prop | Type | Default | Notes |
 |---|---|---|---|
-| `label` | `string` | — | Required |
+| `label` | `string` | — | Required. Shown text and accessibility label |
 | `onPress` | `() => void` | — | Required |
-| `backgroundColor` | `string` | — | Required. Filled: fill. Outline: border + label |
-| `labelColor` | `string` | — | Required. Filled: label + spinner |
+| `backgroundColor` | `string` | theme `buttonBackground` | Optional override |
+| `labelColor` | `string` | theme `buttonLabel` | Optional override |
 | `variant` | `"filled" \| "outline"` | `"filled"` | |
 | `radius` | see below | `"xl"` | Tailwind-style steps |
-| `disabled` | `boolean` | `false` | Opacity treatment; same colours |
-| `loading` | `boolean` | `false` | Spinner instead of label; non-interactive |
+| `icon` | `ButtonIcon` | — | `({ color, size }) => ReactNode` |
+| `iconPosition` | `"start" \| "end" \| "only"` | `"start"` | `"only"` hides the label text |
+| `iconSize` | `number` | `20` | |
+| `disabled` | `boolean` | `false` | 40% opacity; not pressable |
+| `loading` | `boolean` | `false` | Spinner over the content; not pressable; full opacity |
 | `style` | view style | — | Merged after the shell |
 | `labelStyle` | text style | — | Merged after the label |
 
 ### Variants
 
-- **filled** — `backgroundColor` fill, `labelColor` text/spinner  
-- **outline** — transparent fill, border and label from `backgroundColor`. `labelColor` is still required but unused for the outline label; the outline spinner uses `backgroundColor`.
+- **filled** — `backgroundColor` fill; label, icon and spinner in `labelColor`.
+- **outline** — transparent fill with a 1pt border; border, label, icon and spinner all in `backgroundColor`.
+
+### Icons
+
+The package has no Expo dependency, so the icon is a render function. It receives the content colour for the variant and `iconSize`; return an expo-symbols `SymbolView` or any other icon.
+
+```tsx
+import { SymbolView } from "expo-symbols";
+
+<Button
+  label="Share"
+  onPress={onShare}
+  icon={({ color, size }) => (
+    <SymbolView name="square.and.arrow.up" size={size} tintColor={color} />
+  )}
+/>
+
+// Icon after the label
+<Button label="Next" iconPosition="end" icon={arrow} onPress={onNext} />
+
+// Icon only — label is still read by VoiceOver
+<Button label="Add" iconPosition="only" icon={plus} radius="full" style={{ width: 52 }} onPress={onAdd} />
+```
+
+The icon and label are 8pt apart and centred together.
 
 ### Radius
 
@@ -121,39 +181,33 @@ export function SaveButton({ onPress }: { onPress: () => void }) {
 | `full` | pill (`999`) |
 
 ```tsx
-<Button
-  label="Continue"
-  onPress={onContinue}
-  backgroundColor={backgroundColor}
-  labelColor={labelColor}
-  radius="full"
-  variant="outline"
-/>
+<Button label="Continue" onPress={onContinue} radius="full" variant="outline" />
 ```
 
+### Layout
+
+Minimum height 52, 20pt horizontal and 12pt vertical padding. Long labels wrap and stay centred inside the padding. The label is 17pt, weight 600.
+
 ### Loading and disabled
 
 ```tsx
-<Button
-  label="Saving…"
-  onPress={onSave}
-  backgroundColor={backgroundColor}
-  labelColor={labelColor}
-  loading={isSaving}
-  disabled={!canSave}
-/>
+<Button label="Save" onPress={onSave} loading={isSaving} disabled={!canSave} />
 ```
 
-When `loading` or `disabled` is true, the control does not fire `onPress` and uses reduced opacity.
+Neither state fires `onPress`. Disabled fades the button to 40%. Loading keeps full opacity and shows a spinner over the content. The label stays in the layout, invisible, so the button keeps its size. Screen readers get `busy` while loading.
 
 ## Imports
 
 ```ts
 import {
   Button,
+  BUTTON_THEME_ROLES,
   ThemeProvider,
+  type ButtonIcon,
+  type ButtonProps,
   useColorScheme,
   useThemeColor,
+  useThemeSpacing,
   version,
 } from "@studio-piot/native-ui";
 

package/docs/components/choice.md

@@ -0,0 +1,111 @@
+# Choice — usage
+
+One option in a list of next steps: an icon, a title and an optional description, in a filled row. Tapping it acts straight away, usually to open the next screen, as in "What are you doing? Running / HIIT".
+
+Use `Choice` for a short list of destinations, or, with `selected`, for picking one of a few visual options such as candidate routes. To pick a value that stays on the screen, use [RadioField](./radio-field.md), [SegmentedControl](./segmented-control.md) or [Select](./select.md). For a settings list of links, use [LinkBlocks](./link-blocks.md).
+
+## Basic usage
+
+```tsx
+import { Choice, Page } from "@studio-piot/native-ui";
+import { router } from "expo-router";
+import { SymbolView } from "expo-symbols";
+import { View } from "react-native";
+
+export default function NewActivity() {
+  return (
+    <Page>
+      <View style={{ gap: 16 }}>
+        <Choice
+          title="Running"
+          description="Outdoors, with GPS"
+          icon={({ color, size }) => (
+            <SymbolView name="figure.run" size={size} tintColor={color} />
+          )}
+          onPress={() => router.push("/new-activity/running")}
+        />
+        <Choice
+          title="HIIT"
+          description="Intervals, anywhere"
+          icon={({ color, size }) => (
+            <SymbolView name="stopwatch" size={size} tintColor={color} />
+          )}
+          onPress={() => router.push("/new-activity/hiit")}
+        />
+      </View>
+    </Page>
+  );
+}
+```
+
+- **Icon.** A render function, like `Button` and `HeaderIcon`: it receives the icon colour and `iconSize` (default 28). Icons sit in a 32pt column so titles line up down the list; a larger icon widens its column instead of overflowing.
+- **Title only.** `description` is optional.
+- **Spacing.** Put choices in a stack with a 16pt gap. The row has no margin of its own.
+
+## Selectable choices
+
+Pass `selected` to make the choices a set where one is picked, for example candidate routes with a drawing of each in the icon slot. The selected row gets a highlight border (`choiceSelected`); the others keep a transparent border of the same width, so nothing shifts when the selection moves. Tapping still calls `onPress`, where you update the selection.
+
+```tsx
+{routes.map((route) => (
+  <Choice
+    key={route.id}
+    title={route.name}
+    description={`${route.km} km`}
+    icon={({ color, size }) => <RouteThumbnail route={route} color={color} size={size} />}
+    iconSize={48}
+    selected={route.id === selectedId}
+    onPress={() => setSelectedId(route.id)}
+  />
+))}
+```
+
+Pair it with one action that uses the selection, e.g. **Use this route**. Leave `selected` out when tapping should just act.
+
+## Accessibility
+
+The row is one button. VoiceOver reads its text together, for example "Running, Outdoors, with GPS, button". With `selected`, it is a radio option instead, read as selected or not. The icon is decorative and hidden from screen readers. `disabled` sets the disabled state, fades the row to 40% and blocks presses.
+
+## Theme roles
+
+Add these keys to both the light and dark maps.
+
+| Usage | Role |
+|---|---|
+| Row fill | `choiceBackground` |
+| Title | `choiceTitle` |
+| Description | `choiceDescription` |
+| Icon | `choiceIcon` |
+| Selected border (with `selected`) | `choiceSelected` |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `title` | `string` | — | Required |
+| `onPress` | `() => void` | — | Required |
+| `description` | `string` | — | Second line under the title; may wrap to more lines |
+| `selected` | `boolean` | — | Makes it a selectable option: highlight border when true, radio semantics |
+| `icon` | `ButtonIcon` | — | `({ color, size }) => ReactNode` |
+| `iconSize` | `number` | `28` | Icon box |
+| `disabled` | `boolean` | `false` | 40% opacity; not pressable |
+| `radius` | `ButtonRadius` | `"xl"` | Same scale as `Button` (12) |
+| `backgroundColor` | `string` | theme `choiceBackground` | Optional override |
+| `titleColor` | `string` | theme `choiceTitle` | Optional override |
+| `descriptionColor` | `string` | theme `choiceDescription` | Optional override |
+| `iconColor` | `string` | theme `choiceIcon` | Optional override |
+| `selectedColor` | `string` | theme `choiceSelected` | Optional override |
+| `style` | view style | — | Merged after the row |
+
+Layout: 72pt minimum height, 16pt horizontal and 14pt vertical padding, 12pt between the icon and the text. The title is 17pt semibold and the description 13pt, the same as the rest of the package.
+
+## Imports
+
+```ts
+import {
+  Choice,
+  CHOICE_ICON_SIZE,
+  CHOICE_THEME_ROLES,
+  type ChoiceProps,
+} from "@studio-piot/native-ui";
+```

package/docs/components/error-banner.md

@@ -12,7 +12,7 @@ npx expo install react-native-svg
 
 ## Theme roles
 
-Set these in both light and dark. The Ribe banner stays charcoal with a flare disc in both schemes.
+Set these in both the light and dark maps, with values that suit each scheme, so the banner follows the system appearance like the rest of the screen. A light banner in light mode and a dark one in dark mode both work. The status bar text switches to stay readable: dark text over a light fill, light text over a dark one.
 
 | Usage | Role |
 |---|---|
@@ -22,6 +22,39 @@ Set these in both light and dark. The Ribe banner stays charcoal with a flare di
 | Row dividers | `errorBannerDivider` |
 | Megaphone disc | `errorBannerAccent` |
 
+```ts
+const Colors = {
+  light: {
+    errorBannerBackground: "#FFFFFF",
+    errorBannerText: "#111827",
+    errorBannerSecondary: "#6B7280",
+    errorBannerDivider: "#E5E7EB",
+    errorBannerAccent: "#DC2626",
+  },
+  dark: {
+    errorBannerBackground: "#1F2937",
+    errorBannerText: "#F9FAFB",
+    errorBannerSecondary: "#9CA3AF",
+    errorBannerDivider: "#374151",
+    errorBannerAccent: "#DC2626",
+  },
+};
+```
+
+The megaphone is drawn in `errorBannerBackground`, so pick an accent that contrasts with the fill in both schemes.
+
+## Sizes
+
+Text matches the 17pt body text of `Button`, `FieldText` and `Select`.
+
+| Element | Value |
+|---|---|
+| Title and row text | 17pt, line height 22 (title weight 600) |
+| Megaphone disc | 32×32, icon 18 |
+| Dismiss cross | 18 |
+| Row arrow | 20 |
+| Row height | at least 44 (tap target) |
+
 ## With Form
 
 Give each field a `name` that matches `FieldError.field`. On submit, set `errors`. `Form` opens the banner. Typing in a field, changing a choice, or pressing ✕ hides it. The next submit shows it again. While an error is listed, that field keeps the error border and does not repeat the message underneath.
@@ -56,7 +89,8 @@ export function NewActivity({ onClose }: { onClose: () => void }) {
   };
 
   return (
-    <Form title="New activity" errors={errors} onClose={onClose} onSubmit={submit}>
+    // Title and close button live in the screen's stack options; see Form.
+    <Form errors={errors} onSubmit={submit}>
       <FieldText name="name" label="Name" value={name} onChangeText={setName} />
       <Select
         name="type"
@@ -74,7 +108,16 @@ List errors in the same order as the fields, top to bottom.
 
 ## Without Form
 
-`ErrorBanner`, `useErrorBanner`, and `ErrorBannerProvider` work with any scroll view. Put the banner inside the provider and call `jump` from context so a row scrolls the matching `ErrorBannerField` (or a package field with `name`) into view. Call `present` on submit and `dismiss` when the runner edits the screen.
+`ErrorBanner`, `useErrorBanner`, and `ErrorBannerProvider` work with any scroll view. `Form` and `FormSheet` wire them up for you. Put the banner inside the provider and call `jump` from context so a row scrolls the matching `ErrorBannerField` (or a package field with `name`) into view. Call `present` on submit and `dismiss` when the runner edits the screen.
+
+`ErrorBannerProvider` props:
+
+| Prop | Notes |
+|---|---|
+| `scrollRef` | Anything with `scrollTo({ y, animated })`: a `ScrollView`, `KeyboardAwareScrollView` or `BottomSheetScrollView` |
+| `bannerHeightRef` | How far the banner covers the top of the scroll area |
+| `measureRef` | Optional. A view at the top of the scroll content to measure fields against. Defaults to `scrollRef`, which works for a plain `ScrollView` |
+| `onBeforeJump` | Optional. Runs before scrolling to a field, e.g. to expand a sheet |
 
 ## FieldError
 

package/docs/components/form-sheet.md

@@ -0,0 +1,140 @@
+# FormSheet — usage
+
+A form in a draggable sheet over a full-screen background, usually a map. Use it when the screen is about the background and the form adjusts it: choose a start point on a map, set a radius, preview a route.
+
+- **Title on the sheet.** `title` sits at the top of the sheet, under the drag indicator. The native header keeps only the close button, transparent so the background shows behind it.
+- **Three stops.** `0` shows just the handle and the title. `1` puts the sheet top at half the screen. `2` takes it up to the bottom of the native header, never further.
+- **Sticky submit.** The submit button sits in a footer that stays above the keyboard, the same footer as `Form`.
+- **Errors.** Pass `errors` and the `ErrorBanner` works as it does in `Form`. A banner row expands the sheet and scrolls to that field.
+
+Use `Form` instead when the screen is only the form.
+
+## Peer dependencies
+
+The same as `Form` and `Select`: `@gorhom/bottom-sheet`, `react-native-gesture-handler`, `react-native-reanimated`, `react-native-keyboard-controller` and `react-native-safe-area-context`, plus `react-native-screens` for the iOS banner overlay. Wrap the app in `GestureHandlerRootView` and `KeyboardProvider`.
+
+## Basic usage
+
+```tsx
+// app/(app)/run/_layout.tsx
+export default function Layout() {
+  return <Stack screenOptions={{ headerTransparent: true }} />;
+}
+```
+
+```tsx
+// app/(app)/run/index.tsx
+import { FormSheet, HeaderIcon, Slider } from "@studio-piot/native-ui";
+import { router, Stack } from "expo-router";
+import { useHeaderHeight } from "expo-router/react-navigation";
+
+export default function RunSetup() {
+  const [distance, setDistance] = useState(5);
+
+  return (
+    <>
+      <Stack.Screen
+        options={{
+          headerShown: true,
+          headerTransparent: true,
+          title: "", // the title is on the sheet
+          headerLeft: () => (
+            <HeaderIcon label="Close" icon={closeIcon} onPress={() => router.back()} />
+          ),
+        }}
+      />
+      <FormSheet
+        title="Run"
+        headerHeight={useHeaderHeight()}
+        initialIndex={1}
+        background={(inset) => <RouteMap chromeInset={inset} radiusKm={distance / 2} />}
+        onSubmit={generate}
+        submitLabel="Generate route"
+      >
+        <Slider label="Distance" value={distance} onValueChange={setDistance} />
+      </FormSheet>
+    </>
+  );
+}
+```
+
+- **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.
+- **Use `headerTransparent: true`.** Without it the header is opaque, the map starts below it, and the sheet's top stop still works, but the map doesn't show behind the bar.
+- **Pass `headerHeight={useHeaderHeight()}`** (from `expo-router/react-navigation`). The top stop ends there. Without it, `FormSheet` assumes the status bar plus a standard bar (44pt on iOS, 56pt on Android), which is wrong for a large title or a custom header.
+
+## The background and its insets
+
+`background` is a function so the layer can keep its own controls and camera clear of the chrome. It receives a `FormSheetInset`:
+
+| Field | Meaning |
+|---|---|
+| `top` | Bottom of the native header, from the screen top |
+| `bottom` | Top of the sheet at its current stop, from the screen bottom (includes the footer) |
+| `bottomAtHalf` | Top of the sheet at the middle stop. Doesn't change while dragging, so it suits map camera padding |
+
+The background fills the whole screen behind the sheet. Its top corners are rounded (`SHEET_TOP_RADIUS`, 20), so a map that should show through those corners should continue a little past `bottom`, for example `bottom - SHEET_TOP_RADIUS - 8`.
+
+## Errors
+
+The same contract as `Form`: give each field a `name` matching `FieldError.field`, then set `errors` when submit fails.
+
+```tsx
+<FormSheet errors={errors} onSubmit={submit} …>
+  <FieldText name="name" label="Name" value={name} onChangeText={setName} />
+</FormSheet>
+```
+
+On iOS the banner covers the top of the screen, including the native header (it is drawn in a native overlay window). On Android it slides down directly below the header. Tapping a row expands the sheet to stop `2`, scrolls the field clear of the banner and focuses it if it can take focus. Editing a field dismisses the banner, and the next submit shows it again.
+
+## Theme roles
+
+| Usage | Role |
+|---|---|
+| Sheet fill and handle | `formSheetBackground` |
+| Sheet title | `formSheetTitle` |
+| Footer ground | `formSheetFooterBackground` |
+| Drag indicator | `formSheetHandle` |
+| Submit fill | `buttonBackground` |
+| Submit label | `buttonLabel` |
+
+With `errors`, the banner also reads the `errorBanner*` roles.
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `title` | `string` | — | Top of the sheet, under the indicator. Always visible at the lowest stop |
+| `children` | `ReactNode` | — | Required. Sheet content; scrolls inside the sheet |
+| `background` | `(inset: FormSheetInset) => ReactNode` | — | Required. Full-screen layer behind the sheet |
+| `onSubmit` | `() => void` | — | Required |
+| `errors` | `FieldError[]` | `[]` | Screen banner. Empty hides it |
+| `submitLabel` | `string` | `"Save"` | |
+| `submitting` | `boolean` | `false` | Spinner on the submit button |
+| `submitDisabled` | `boolean` | `false` | |
+| `submitRadius` | `ButtonRadius` | `"lg"` | |
+| `initialIndex` | `0 \| 1 \| 2` | `0` | Stop on first paint |
+| `headerHeight` | `number` | status bar + standard bar | `useHeaderHeight()`. Where the top stop ends |
+| `paddingHorizontal` | `number` | theme `spacing.screen` | Content and footer |
+| `backgroundColor` | `string` | theme `formSheetBackground` | |
+| `titleColor` | `string` | theme `formSheetTitle` | |
+| `footerBackgroundColor` | `string` | theme `formSheetFooterBackground` | |
+| `handleColor` | `string` | theme `formSheetHandle` | |
+| `buttonBackgroundColor` | `string` | theme `buttonBackground` | |
+| `buttonLabelColor` | `string` | theme `buttonLabel` | |
+
+## Migrating from 0.12
+
+`onClose` and `closeButton` are gone. Move the close button to the screen's stack options (`headerLeft`) with `headerShown: true` and `headerTransparent: true`. `title`, `titleColor` and the `formSheetTitle` role still put the title on the sheet. Leave the header's `title` empty so it isn't shown twice.
+
+## Imports
+
+```ts
+import {
+  FormSheet,
+  FORM_SHEET_THEME_ROLES,
+  SHEET_TOP_RADIUS,
+  formSheetSnapPoints,
+  type FormSheetInset,
+  type FormSheetProps,
+} from "@studio-piot/native-ui";
+```