@studio-piot/native-ui 0.1.0

package/docs/components/form.md

@@ -0,0 +1,86 @@
+# 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.
+
+For `ThemeProvider` and `useThemeColor`, see [theme provider and Button usage](./button.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`
+
+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";
+
+export function NewItemScreen({ onClose, onSave }: Props) {
+  return (
+    <Form title="New item" onClose={onClose} onSubmit={onSave}>
+      <FieldText label="Name" value={name} onChangeText={setName} />
+    </Form>
+  );
+}
+```
+
+## Close button slot
+
+Pass `closeButton` to replace the default plain Cancel (e.g. Expo liquid-glass Cancel in the app):
+
+```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>
+```
+
+The default package `FormCloseButton` is a themed text Cancel. Export it if you want that control outside `Form`.
+
+## 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 |
+| `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 |
+| `buttonBackgroundColor` | `string` | theme `buttonBackground` | Optional override |
+| `buttonLabelColor` | `string` | theme `buttonLabel` | Optional override |
+
+## Imports
+
+```ts
+import { Form, FormCloseButton, 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/link-blocks.md

@@ -0,0 +1,120 @@
+# LinkBlocks — usage
+
+Config-driven groups of tappable rows (optional icon, label, trailing chevron). Section titles sit above each rounded surface. Your app owns colours, icons, and navigation.
+
+For the design contract, see [LinkBlocks design](../superpowers/specs/2026-09-24-link-blocks-design.md).
+
+For `ThemeProvider` and `useThemeColor`, see [theme provider and Button usage](./button.md).
+
+## LinkBlocks
+
+`LinkBlocks` is presentational. Pass colour strings and a `blocks` config. Full width of its parent is fixed. The package does not import Expo Router, Linking, or icon libraries — wire `onPress` and optional `icon` nodes in the app.
+
+```tsx
+import { LinkBlocks, useThemeColor } from "@studio-piot/native-ui";
+import Ionicons from "@expo/vector-icons/Ionicons";
+import { router } from "expo-router";
+
+export function SettingsLinks() {
+  const surface = useThemeColor("surface");
+  const text = useThemeColor("text");
+  const textSecondary = useThemeColor("textSecondary");
+  const border = useThemeColor("border");
+
+  return (
+    <LinkBlocks
+      surfaceColor={surface}
+      labelColor={text}
+      dividerColor={border}
+      chevronColor={textSecondary}
+      titleColor={textSecondary}
+      blocks={[
+        {
+          key: "settings",
+          title: "Settings",
+          items: [
+            {
+              key: "units",
+              label: "Units of Measure",
+              icon: <Ionicons name="options-outline" size={22} color={text} />,
+              onPress: () => router.push("/settings/units"),
+            },
+            {
+              key: "notifications",
+              label: "Notification Settings",
+              icon: (
+                <Ionicons name="notifications-outline" size={22} color={text} />
+              ),
+              onPress: () => router.push("/settings/notifications"),
+            },
+          ],
+        },
+      ]}
+    />
+  );
+}
+```
+
+On a grey page background, pass a lighter `surface` (e.g. white). On a white page, choose a contrasting surface — the component does not compute “lighter than background”.
+
+### Data shape
+
+```ts
+type LinkBlockItem = {
+  key: string;
+  label: string;
+  onPress: () => void;
+  icon?: React.ReactNode;
+  disabled?: boolean;
+};
+
+type LinkBlockGroup = {
+  key: string;
+  title?: string;
+  items: LinkBlockItem[];
+};
+```
+
+- `key` on groups and items is for stable React lists; you choose the string.
+- A group renders only when `items` is non-empty after filtering. Empty groups are skipped (no surface, no orphan title).
+- If any item in a group has an `icon`, all rows in that group reserve a leading icon column so labels align.
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `blocks` | `LinkBlockGroup[]` | — | Required |
+| `surfaceColor` | `string` | — | Required. Rounded container fill |
+| `labelColor` | `string` | — | Required. Row label |
+| `dividerColor` | `string` | — | Required. Hairline between rows |
+| `chevronColor` | `string` | — | Required. Trailing chevron |
+| `titleColor` | `string` | — | Section title; falls back to `labelColor` when omitted |
+| `radius` | `ButtonRadius` | `"xl"` | Same steps as `Button` |
+| `style` | view style | — | Outer vertical stack |
+
+### Radius
+
+Uses the same Tailwind-style steps as `Button` (`buttonRadiusValue`). Default `"xl"` (12px). See the [Button radius table](./button.md#radius).
+
+### Disabled rows
+
+Set `disabled: true` on an item. The row does not fire `onPress` and uses reduced opacity (same treatment as `Button`).
+
+### Accessibility
+
+Each row uses `accessibilityRole="button"` and `accessibilityLabel` from the item `label`. The chevron is hidden from accessibility APIs.
+
+## Imports
+
+```ts
+import {
+  LinkBlocks,
+  type LinkBlockGroup,
+  type LinkBlockItem,
+  type LinkBlocksProps,
+  useThemeColor,
+} from "@studio-piot/native-ui";
+
+// Or components only:
+import { LinkBlocks } from "@studio-piot/native-ui/components";
+```

package/docs/components/radio-field.md

@@ -0,0 +1,100 @@
+# RadioField — usage
+
+Presentational controlled radio group in a LinkBlocks-style rounded card. Each row shows label (and optional description) on the left and a package-drawn radio mark on the right. Colours default from `ThemeProvider`; pass props only to override. Your app owns form state.
+
+For the design contract, see [RadioField design](../superpowers/specs/2026-09-25-radio-field-design.md).
+
+For `ThemeProvider` and `useThemeColor`, see [theme provider and Button usage](./button.md).
+
+## RadioField
+
+`RadioField` is controlled only (`value` + `onChange`). When colour props are omitted, colours resolve from fixed theme roles (see below). Explicit colour props always win. `ThemeProvider` is required when at least one colour prop is omitted. Full width of the parent is fixed. An empty `options` array renders nothing.
+
+```tsx
+import { RadioField } from "@studio-piot/native-ui";
+import { useState } from "react";
+
+type ThemePreference = "automatic" | "light" | "dark";
+
+const themeOptions = [
+  { value: "automatic" as const, label: "Automatic" },
+  { value: "light" as const, label: "Light" },
+  { value: "dark" as const, label: "Dark" },
+];
+
+export function AppearanceThemePicker() {
+  const [theme, setTheme] = useState<ThemePreference>("automatic");
+
+  return (
+    <RadioField
+      label="Appearance"
+      value={theme}
+      onChange={setTheme}
+      options={themeOptions}
+    />
+  );
+}
+```
+
+Your `ThemeProvider` colour maps must include the default roles listed below (same keys in light and dark). Apps must add **`fieldRadioSelected`** for the selected radio fill; existing Field `field*` roles are reused.
+
+### Colour props (optional overrides)
+
+| Prop | Default theme role | Role |
+|---|---|---|
+| `backgroundColor` | `fieldBackground` | Card fill |
+| `labelColor` | `fieldText` | Option label |
+| `descriptionColor` | `fieldDescription` | Option description |
+| `dividerColor` | `fieldBorder` | Row dividers |
+| `radioColor` | `fieldBorder` | Unselected ring |
+| `selectedColor` | `fieldRadioSelected` | Selected radio fill |
+| `titleColor` | `fieldLabel` | Group label above card |
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `value` | `T \| null` | — | Required. Controlled selection; `null` = none selected |
+| `onChange` | `(value: T) => void` | — | Required |
+| `options` | `RadioOption<T>[]` | — | Required. Empty list → renders nothing |
+| `label` | `string` | — | Optional caption above the card |
+| `radius` | `ButtonRadius` | `"xl"` | Same steps as `Button` |
+| `backgroundColor` | `string` | theme `fieldBackground` | Optional override |
+| `labelColor` | `string` | theme `fieldText` | Optional override |
+| `descriptionColor` | `string` | theme `fieldDescription` | Optional override |
+| `dividerColor` | `string` | theme `fieldBorder` | Optional override |
+| `radioColor` | `string` | theme `fieldBorder` | Optional override |
+| `selectedColor` | `string` | theme `fieldRadioSelected` | Optional override |
+| `titleColor` | `string` | theme `fieldLabel` | Optional override |
+| `style` | view style | — | Outer column |
+
+### RadioOption
+
+| Prop | Type | Notes |
+|---|---|---|
+| `value` | `T` | Stable string id |
+| `label` | `string` | Row title |
+| `description` | `string` | Optional helper under label |
+| `disabled` | `boolean` | Row at 40% opacity; not selectable |
+
+### Layout and radius
+
+Card uses `buttonRadiusValue` (default `"xl"`, 12px). Rows match LinkBlocks density (`minHeight` 52, horizontal padding 16). See the [Button radius table](./button.md#radius).
+
+### Accessibility
+
+The card container uses `accessibilityRole="radiogroup"`. Each row is `accessibilityRole="radio"` with `accessibilityState` including `selected`, `checked` (same as selected; required for Android TalkBack radio semantics), and `disabled`. The drawn radio mark is decorative; the row is the hit target.
+
+## Imports
+
+```ts
+import {
+  RadioField,
+  RADIO_THEME_ROLES,
+  type RadioOption,
+  type RadioFieldProps,
+} from "@studio-piot/native-ui";
+
+// Or components only:
+import { RadioField } from "@studio-piot/native-ui/components";
+```

package/docs/components/select.md

@@ -0,0 +1,59 @@
+# Select — usage
+
+Field-like select trigger that opens a native bottom sheet (`@lodev09/react-native-true-sheet`) of options. Selecting an option updates the value and dismisses the sheet. Grabber, dimmed backdrop, and detents are native.
+
+For `ThemeProvider`, see [theme provider and Button usage](./button.md). Design: [Select design](../superpowers/specs/2026-09-25-select-design.md).
+
+## Peer dependency
+
+Install in the app:
+
+```bash
+npx expo install @lodev09/react-native-true-sheet
+```
+
+Requires New Architecture (Expo SDK 54+ / TrueSheet 3.7+).
+
+## Theme roles
+
+Uses Field roles: `fieldBackground`, `fieldText`, `fieldPlaceholder`, `fieldLabel`, `fieldDescription`, `fieldBorder`, `fieldError`, plus `fieldRadioSelected` for the selected check / emphasis.
+
+## Basic usage
+
+```tsx
+import { Select } from "@studio-piot/native-ui";
+
+<Select
+  label="Type"
+  value={type}
+  onChange={setType}
+  placeholder="Choose a type"
+  options={[
+    { value: "ride", label: "Ride" },
+    { value: "run", label: "Run" },
+    { value: "swim", label: "Swim" },
+  ]}
+/>
+```
+
+## Glass close (app slot)
+
+```tsx
+closeButton={(dismiss) => <FormCloseButton onPress={dismiss} />}
+```
+
+## Detents
+
+Default `detents={[0.25, 0.5, 0.75]}`, opens at `initialDetent={0.5}`. Override via props.
+
+## Imports
+
+```ts
+import {
+  Select,
+  SelectCloseButton,
+  SELECT_THEME_ROLES,
+  type SelectProps,
+  type SelectOption,
+} from "@studio-piot/native-ui";
+```