@studio-piot/native-ui 0.1.0

package/docs/superpowers/specs/2026-09-25-select-design.md

@@ -0,0 +1,164 @@
+# Select — design
+
+Date: 2026-09-25  
+Package: `@studio-piot/native-ui`  
+Status: approved  
+Apps: Ribe create-activity Type field in the same pass
+
+## Goal
+
+Ship a presentational **Select**: Field-like trigger that opens a native bottom sheet of options (TrueSheet). Highlight the selected option; choosing one updates value and dismisses the sheet. Drag handle, dimmed backdrop, and snap heights feel like system UI (Strava-style grabber). Ribe wires Type of activity to Select with a glass close control.
+
+## Decisions
+
+| Topic | Choice |
+|---|---|
+| API shape | Single `Select`: trigger + internal sheet |
+| Sheet library | `@lodev09/react-native-true-sheet` (native UIKit / Material) |
+| Detents | Default `[0.25, 0.5, 0.75]`; present at `0.5` |
+| Close control | `closeButton` slot; package default plain Cancel; Ribe passes glass |
+| Colours | Field `field*` roles + `fieldRadioSelected` for selected check / emphasis |
+| Trigger | Field-like chrome (label, description, error, chevron, radius) |
+| Options | `{ value, label, disabled? }[]`; scrollable when long |
+| Select behaviour | Tap option → `onChange(value)` + dismiss |
+| Icons / search / grids | Out of scope |
+| Optimum migration | Out of scope this pass (CustomPicker remains until a later PR) |
+| Brand coupling | None in the package |
+
+## Architecture
+
+```
+Select
+  ├── trigger (Field-like Pressable)
+  └── TrueSheet
+        ├── grabber (system)
+        ├── header (title + closeButton)
+        └── scrollable options
+              └── row (label + check when selected)
+```
+
+- Public export: `Select` (+ types). Default close control may be a small internal component (plain Cancel), not required to be public.
+- Controlled only: `value` + `onChange` + `options`.
+- Peer dependency: `@lodev09/react-native-true-sheet` (document in usage docs; matching `devDependency` for types/build).
+
+## Theme roles
+
+| Usage | Theme role |
+|---|---|
+| Trigger / sheet list ground | `fieldBackground` |
+| Trigger value / option label | `fieldText` |
+| Placeholder / chevron | `fieldPlaceholder` |
+| Label above trigger | `fieldLabel` |
+| Description under trigger | `fieldDescription` |
+| Trigger border / dividers | `fieldBorder` |
+| Error border + message | `fieldError` |
+| Selected option emphasis / check | `fieldRadioSelected` |
+
+Optional colour override props follow the Field pattern (explicit prop wins over theme role).
+
+## Props
+
+```ts
+type SelectOption = {
+  value: string;
+  label: string;
+  disabled?: boolean;
+};
+
+type SelectProps = {
+  value: string | null;
+  onChange: (value: string) => void;
+  options: SelectOption[];
+  placeholder?: string;
+  label?: string;
+  description?: string;
+  error?: string;
+  sheetTitle?: string;
+  closeButton?: ReactNode;
+  detents?: number[];
+  initialDetent?: number;
+  radius?: ButtonRadius;
+  editable?: boolean;
+  // optional colour overrides…
+  style?: StyleProp<ViewStyle>;
+};
+```
+
+| Prop | Notes |
+|---|---|
+| `value` | Controlled; `null` / unmatched → show placeholder |
+| `onChange` | Fired with option `value` on row press |
+| `options` | Empty list: trigger still opens an empty sheet (or no-op open — prefer open with empty state text “No options”) |
+| `sheetTitle` | Header title; default `label` or `"Select"` |
+| `closeButton` | Render prop / node for header trailing close; default plain Cancel that dismisses |
+| `detents` | Default `[0.25, 0.5, 0.75]` |
+| `initialDetent` | Default `0.5` (must be one of `detents`) |
+| `radius` | Trigger radius; default `"xl"` |
+| `editable` | `false` → reduced opacity, no open |
+
+## Trigger layout
+
+Aligned with Field:
+
+- Full width; optional label above, description / error below (error replaces description when set)
+- Pressable row: value or placeholder, trailing chevron
+- Resting border `fieldBorder`; error uses `fieldError`
+- Radius via `buttonRadiusValue` (default `"xl"`)
+
+## Sheet behaviour
+
+- Present TrueSheet on trigger press (when `editable`)
+- System grabber; dimmed / fading backdrop (library default)
+- Header: title + `closeButton` (or default Cancel)
+- Scrollable option list; row min height ~52; selected row uses `fieldRadioSelected` for check (and optional label tint)
+- Row press: `onChange` + dismiss
+- Dismiss also via grabber drag / backdrop / close control
+- No search field, no category grids, no leading sport icons in this pass
+
+## Accessibility
+
+- Trigger: `accessibilityRole="button"`, label from `label` / placeholder; announce current value when set
+- Options: `accessibilityRole="button"` (or `menuitem` if we use a menu pattern — prefer button + `accessibilityState.selected`)
+- Close control: button with accessible name “Cancel” / “Close”
+
+## App work (Ribe)
+
+1. `npx expo install @lodev09/react-native-true-sheet` (or pnpm equivalent)
+2. Create-activity: replace Type `FieldText` with `Select`
+   - Options: Ride, Run, Swim, Walk, Hike (values lowercase slug or same as label — pick stable string values e.g. `ride`, `run`, …)
+   - `error` when empty (same validation copy intent as today)
+   - `closeButton` that dismisses the sheet using glass `FormCloseButton` (needs a dismiss callback from Select — either `closeButton` as render prop `(dismiss) => ReactNode` **or** Select clones/passes dismiss via slot convention)
+
+### Close slot + dismiss
+
+Prefer **render prop** so the app can wire glass Cancel correctly:
+
+```ts
+closeButton?: ReactNode | ((dismiss: () => void) => ReactNode);
+```
+
+If `ReactNode` only, the default Cancel works but glass Cancel cannot call dismiss unless Select exposes an imperative API. **Decision: support function form** `(dismiss) => ReactNode`, and also accept a static `ReactNode` for simple cases (static node cannot dismiss unless it uses an internal context — for static nodes, wrap with Pressable only in default Cancel).
+
+Ribe usage:
+
+```tsx
+closeButton={(dismiss) => <FormCloseButton onPress={dismiss} />}
+```
+
+3. Keep Name / Notes as Field; form submit still gated on name (and optionally require type — keep current “type empty → error” UX).
+
+## Out of scope
+
+- Strava “Top Sports” horizontal chips / search
+- Per-option icons
+- Migrating Optimum `CustomPicker` call sites
+- Multi-select
+- Liquid glass Cancel inside the package
+- New `select*` theme roles
+
+## Success criteria
+
+- Package exports `Select` with usage docs and TrueSheet peer documented
+- Sheet: grabber, fade backdrop, detents ¼ / ½ / ¾, open at ½, scrollable options, select-to-dismiss
+- Ribe create-activity Type uses Select + glass close
+- `npm test` / `npm run build` (package) and Ribe `pnpm typecheck` pass

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@studio-piot/native-ui",
+  "version": "0.1.0",
+  "description": "Shared React Native components for Studio Piot apps.",
+  "homepage": "https://github.com/Studio-Piot/studio-native-ui#readme",
+  "bugs": {
+    "url": "https://github.com/Studio-Piot/studio-native-ui/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Studio-Piot/studio-native-ui.git"
+  },
+  "license": "ISC",
+  "author": "Guillaume Piot",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "react-native": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./dist/index.js",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "react-native": "./dist/components/index.js",
+      "import": "./dist/components/index.js",
+      "require": "./dist/components/index.js",
+      "default": "./dist/components/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/*",
+        "./dist/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@lodev09/react-native-true-sheet": ">=3.7.0",
+    "react": ">=19.0.0",
+    "react-native": ">=0.76.0",
+    "react-native-keyboard-controller": ">=1.14.0",
+    "react-native-safe-area-context": ">=4.0.0"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test 'src/**/*.test.ts'",
+    "build": "tsc",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "dev": "tsc --watch",
+    "prepare": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@lodev09/react-native-true-sheet": "3.11.15",
+    "@types/react": "^19.2.2",
+    "react-native": "^0.86.3",
+    "react-native-keyboard-controller": "1.21.9",
+    "react-native-safe-area-context": "~5.7.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/components/Button/Button.tsx

@@ -0,0 +1,97 @@
+import {
+  ActivityIndicator,
+  StyleSheet,
+  Text,
+  TouchableOpacity,
+  type StyleProp,
+  type TextStyle,
+  type ViewStyle,
+} from "react-native";
+import { buttonRadiusValue, type ButtonRadius } from "./buttonRadius";
+
+export type ButtonProps = {
+  label: string;
+  onPress: () => void;
+  backgroundColor: string;
+  labelColor: string;
+  disabled?: boolean;
+  loading?: boolean;
+  variant?: "filled" | "outline";
+  radius?: ButtonRadius;
+  style?: StyleProp<ViewStyle>;
+  labelStyle?: StyleProp<TextStyle>;
+};
+
+export function Button({
+  label,
+  onPress,
+  backgroundColor,
+  labelColor,
+  disabled = false,
+  loading = false,
+  variant = "filled",
+  radius = "xl",
+  style,
+  labelStyle,
+}: ButtonProps) {
+  const blocked = disabled || loading;
+  const isOutline = variant === "outline";
+  const borderRadius = buttonRadiusValue(radius);
+
+  return (
+    <TouchableOpacity
+      accessibilityLabel={label}
+      accessibilityRole="button"
+      accessibilityState={{ disabled: blocked, busy: loading }}
+      activeOpacity={0.75}
+      disabled={blocked}
+      onPress={onPress}
+      style={[
+        styles.shell,
+        { borderRadius },
+        isOutline
+          ? {
+              backgroundColor: "transparent",
+              borderWidth: 1,
+              borderColor: backgroundColor,
+            }
+          : { backgroundColor },
+        blocked && styles.blocked,
+        style,
+      ]}
+    >
+      {loading ? (
+        <ActivityIndicator
+          color={isOutline ? backgroundColor : labelColor}
+          size="small"
+        />
+      ) : (
+        <Text
+          style={[
+            styles.label,
+            { color: isOutline ? backgroundColor : labelColor },
+            labelStyle,
+          ]}
+        >
+          {label}
+        </Text>
+      )}
+    </TouchableOpacity>
+  );
+}
+
+const styles = StyleSheet.create({
+  shell: {
+    width: "100%",
+    minHeight: 52,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  blocked: {
+    opacity: 0.4,
+  },
+  label: {
+    fontSize: 17,
+    fontWeight: "600",
+  },
+});

package/src/components/Button/buttonRadius.test.ts

@@ -0,0 +1,16 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { buttonRadiusValue } from "./buttonRadius.ts";
+
+describe("buttonRadiusValue", () => {
+  it("maps Tailwind-style steps", () => {
+    assert.equal(buttonRadiusValue("none"), 0);
+    assert.equal(buttonRadiusValue("sm"), 2);
+    assert.equal(buttonRadiusValue("md"), 6);
+    assert.equal(buttonRadiusValue("lg"), 8);
+    assert.equal(buttonRadiusValue("xl"), 12);
+    assert.equal(buttonRadiusValue("2xl"), 16);
+    assert.equal(buttonRadiusValue("3xl"), 24);
+    assert.equal(buttonRadiusValue("full"), 999);
+  });
+});

package/src/components/Button/buttonRadius.ts

@@ -0,0 +1,24 @@
+export type ButtonRadius =
+  | "none"
+  | "sm"
+  | "md"
+  | "lg"
+  | "xl"
+  | "2xl"
+  | "3xl"
+  | "full";
+
+const RADIUS: Record<ButtonRadius, number> = {
+  none: 0,
+  sm: 2,
+  md: 6,
+  lg: 8,
+  xl: 12,
+  "2xl": 16,
+  "3xl": 24,
+  full: 999,
+};
+
+export function buttonRadiusValue(radius: ButtonRadius): number {
+  return RADIUS[radius];
+}

package/src/components/Button/index.ts

@@ -0,0 +1,2 @@
+export { Button, type ButtonProps } from "./Button";
+export { buttonRadiusValue, type ButtonRadius } from "./buttonRadius";

package/src/components/Field/FieldText.tsx

@@ -0,0 +1,6 @@
+import { FieldChrome } from "./fieldChrome";
+import type { FieldTextProps } from "./types";
+
+export function FieldText(props: FieldTextProps) {
+  return <FieldChrome {...props} multiline={false} minHeight={48} />;
+}

package/src/components/Field/FieldTextarea.tsx

@@ -0,0 +1,18 @@
+import { FieldChrome } from "./fieldChrome";
+import type { FieldTextareaProps } from "./types";
+
+export function FieldTextarea({
+  numberOfLines = 4,
+  ...props
+}: FieldTextareaProps) {
+  const minHeight = Math.max(100, numberOfLines * 24);
+  return (
+    <FieldChrome
+      {...props}
+      multiline
+      numberOfLines={numberOfLines}
+      minHeight={minHeight}
+      textAlignVertical="top"
+    />
+  );
+}

package/src/components/Field/fieldChrome.tsx

@@ -0,0 +1,219 @@
+import { useState } from "react";
+import {
+  StyleSheet,
+  Text,
+  TextInput,
+  TouchableOpacity,
+  View,
+  type TextInputProps,
+} from "react-native";
+import { buttonRadiusValue } from "../Button/buttonRadius";
+import { FIELD_THEME_ROLES } from "./fieldThemeRoles";
+import {
+  resolveFieldBorder,
+  shouldShowFieldClear,
+} from "./resolveFieldBorder";
+import type { FieldSharedProps } from "./types";
+import { useResolvedFieldColor } from "./useResolvedFieldColor";
+
+export type FieldChromeProps = FieldSharedProps & {
+  multiline?: boolean;
+  numberOfLines?: number;
+  minHeight?: number;
+  textAlignVertical?: TextInputProps["textAlignVertical"];
+};
+
+export function FieldChrome({
+  value,
+  onChangeText,
+  borderColor: borderColorProp,
+  focusedBorderColor: focusedBorderColorProp,
+  errorColor: errorColorProp,
+  textColor: textColorProp,
+  labelColor: labelColorProp,
+  placeholderColor: placeholderColorProp,
+  backgroundColor: backgroundColorProp,
+  label,
+  description,
+  error,
+  placeholder,
+  radius = "xl",
+  editable = true,
+  clearIcon,
+  onClear,
+  style,
+  inputStyle,
+  multiline = false,
+  numberOfLines,
+  minHeight = 48,
+  textAlignVertical,
+  secureTextEntry,
+  keyboardType,
+  autoCapitalize,
+  autoComplete,
+  textContentType,
+  onFocus,
+  onBlur,
+  ref,
+}: FieldChromeProps) {
+  const borderColor = useResolvedFieldColor(
+    borderColorProp,
+    FIELD_THEME_ROLES.borderColor,
+  );
+  const focusedBorderColor = useResolvedFieldColor(
+    focusedBorderColorProp,
+    FIELD_THEME_ROLES.focusedBorderColor,
+  );
+  const errorColor = useResolvedFieldColor(
+    errorColorProp,
+    FIELD_THEME_ROLES.errorColor,
+  );
+  const textColor = useResolvedFieldColor(
+    textColorProp,
+    FIELD_THEME_ROLES.textColor,
+  );
+  const labelColor = useResolvedFieldColor(
+    labelColorProp,
+    FIELD_THEME_ROLES.labelColor,
+  );
+  const placeholderColor = useResolvedFieldColor(
+    placeholderColorProp,
+    FIELD_THEME_ROLES.placeholderColor,
+  );
+  const backgroundColor = useResolvedFieldColor(
+    backgroundColorProp,
+    FIELD_THEME_ROLES.backgroundColor,
+  );
+  const descriptionColor = useResolvedFieldColor(
+    undefined,
+    FIELD_THEME_ROLES.descriptionColor,
+  );
+
+  const [isFocused, setIsFocused] = useState(false);
+  const hasError = Boolean(error);
+  const showClear = shouldShowFieldClear(value, clearIcon != null, editable);
+  const border = resolveFieldBorder({
+    isFocused,
+    hasError,
+    borderColor,
+    focusedBorderColor,
+    errorColor,
+  });
+  const borderRadius = buttonRadiusValue(radius);
+
+  const handleClear = () => {
+    if (onClear) onClear();
+    else onChangeText("");
+  };
+
+  return (
+    <View style={[styles.column, !editable && styles.blocked, style]}>
+      {label ? (
+        <Text style={[styles.label, { color: labelColor }]}>{label}</Text>
+      ) : null}
+      <View style={styles.inputWrapper}>
+        <TextInput
+          ref={ref}
+          value={value}
+          onChangeText={onChangeText}
+          placeholder={placeholder}
+          placeholderTextColor={placeholderColor}
+          editable={editable}
+          multiline={multiline}
+          numberOfLines={numberOfLines}
+          textAlignVertical={textAlignVertical}
+          secureTextEntry={secureTextEntry}
+          keyboardType={keyboardType}
+          autoCapitalize={autoCapitalize}
+          autoComplete={autoComplete}
+          textContentType={textContentType}
+          accessibilityLabel={label}
+          accessibilityState={{ disabled: !editable }}
+          onFocus={(e) => {
+            setIsFocused(true);
+            onFocus?.(e);
+          }}
+          onBlur={(e) => {
+            setIsFocused(false);
+            onBlur?.(e);
+          }}
+          style={[
+            styles.input,
+            {
+              minHeight,
+              color: textColor,
+              backgroundColor,
+              borderRadius,
+              borderColor: border.borderColor,
+              borderWidth: border.borderWidth,
+              paddingHorizontal: border.paddingHorizontal,
+              paddingRight: showClear
+                ? border.paddingHorizontal + 28
+                : border.paddingHorizontal,
+            },
+            multiline && styles.multiline,
+            inputStyle,
+          ]}
+        />
+        {showClear ? (
+          <TouchableOpacity
+            accessibilityLabel="Clear"
+            accessibilityRole="button"
+            hitSlop={{ top: 10, bottom: 10, left: 10, right: 10 }}
+            onPress={handleClear}
+            style={styles.clearButton}
+          >
+            {clearIcon}
+          </TouchableOpacity>
+        ) : null}
+      </View>
+      {error ? (
+        <Text style={[styles.helper, { color: errorColor }]}>{error}</Text>
+      ) : description ? (
+        <Text style={[styles.helper, { color: descriptionColor }]}>
+          {description}
+        </Text>
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  column: {
+    width: "100%",
+    gap: 6,
+  },
+  blocked: {
+    opacity: 0.4,
+  },
+  label: {
+    fontSize: 13,
+    fontWeight: "600",
+  },
+  inputWrapper: {
+    position: "relative",
+    width: "100%",
+    justifyContent: "center",
+  },
+  input: {
+    width: "100%",
+    paddingVertical: 12,
+    fontSize: 17,
+  },
+  multiline: {
+    paddingTop: 16,
+    paddingBottom: 16,
+  },
+  clearButton: {
+    position: "absolute",
+    right: 8,
+    top: 0,
+    bottom: 0,
+    justifyContent: "center",
+    alignItems: "center",
+    zIndex: 2,
+  },
+  helper: {
+    fontSize: 13,
+  },
+});

package/src/components/Field/fieldThemeRoles.ts

@@ -0,0 +1,13 @@
+/** Theme roles Field uses when colour props are omitted. */
+export const FIELD_THEME_ROLES = {
+  borderColor: "fieldBorder",
+  focusedBorderColor: "fieldFocusedBorder",
+  errorColor: "fieldError",
+  textColor: "fieldText",
+  labelColor: "fieldLabel",
+  placeholderColor: "fieldPlaceholder",
+  backgroundColor: "fieldBackground",
+  descriptionColor: "fieldDescription",
+} as const;
+
+export type FieldThemeColorProp = keyof typeof FIELD_THEME_ROLES;

package/src/components/Field/index.ts

@@ -0,0 +1,5 @@
+export { FieldText } from "./FieldText";
+export { FieldTextarea } from "./FieldTextarea";
+export { FIELD_THEME_ROLES } from "./fieldThemeRoles";
+export type { FieldThemeColorProp } from "./fieldThemeRoles";
+export type { FieldSharedProps, FieldTextProps, FieldTextareaProps } from "./types";