@studio-piot/native-ui 0.1.0

package/docs/superpowers/plans/2026-09-25-radio-field.md

@@ -0,0 +1,516 @@
+# RadioField Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship a controlled `RadioField` (LinkBlocks-style card, Field colours + `fieldRadioSelected`) and migrate Ribe Appearance to it.
+
+**Architecture:** One public `RadioField` component resolves theme colours like Field, renders a rounded card of option rows (label + optional description left, `RadioMark` right). Pure helpers stay unit-tested without an RN renderer. Ribe adds `fieldRadioSelected` and swaps Appearance’s checkmark list for `RadioField`.
+
+**Tech Stack:** TypeScript, React 19+, React Native, `tsc` → `dist`, Node `--test` for pure helpers; Ribe Expo Router + existing `ThemeProvider` / `Colors`.
+
+## Global Constraints
+
+- Spec: `docs/superpowers/specs/2026-09-25-radio-field-design.md`
+- No brand names or palettes in the package
+- Controlled only: `value` + `onChange` + `options` required
+- Theme defaults from Field roles + new `fieldRadioSelected`; optional colour props override
+- Layout metrics match LinkBlocks (row minHeight 52, pad H 16, radius default `"xl"`)
+- No multi-group RadioBlocks, icons, multi-select, or liquid-glass radios
+- Commit only when the user asks (unless they explicitly request commits in the execution session)
+
+## File map
+
+| File | Responsibility |
+|---|---|
+| `src/components/RadioField/radioThemeRoles.ts` | Role map for defaults |
+| `src/components/RadioField/types.ts` | `RadioOption`, `RadioFieldProps` |
+| `src/components/RadioField/RadioMark.tsx` | Selected / unselected circle |
+| `src/components/RadioField/RadioField.tsx` | Card + rows |
+| `src/components/RadioField/index.ts` | Barrel |
+| `src/components/RadioField/radioThemeRoles.test.ts` | Role map assertions |
+| `src/components/index.ts` / `src/index.ts` | Public exports |
+| `docs/components/radio-field.md` | Usage |
+| `README.md` | Link to usage + design |
+| Ribe `src/config/colors.ts` (+ test) | `fieldRadioSelected` |
+| Ribe `src/app/(app)/(tabs)/profile/appearance.tsx` | Use `RadioField` |
+
+---
+
+### Task 1: RadioField package component, tests, docs, exports
+
+**Files:**
+- Create: `src/components/RadioField/radioThemeRoles.ts`
+- Create: `src/components/RadioField/radioThemeRoles.test.ts`
+- Create: `src/components/RadioField/types.ts`
+- Create: `src/components/RadioField/RadioMark.tsx`
+- Create: `src/components/RadioField/RadioField.tsx`
+- Create: `src/components/RadioField/index.ts`
+- Create: `docs/components/radio-field.md`
+- Modify: `src/components/index.ts`
+- Modify: `src/index.ts`
+- Modify: `README.md`
+
+**Interfaces:**
+- Consumes: `buttonRadiusValue`, `ButtonRadius` from `../Button/buttonRadius`; `useResolvedFieldColor` from `../Field/useResolvedFieldColor` (same resolve path as Field)
+- Produces: `RadioField`, `RADIO_THEME_ROLES`, `RadioOption`, `RadioFieldProps`
+
+- [ ] **Step 1: Write failing role-map test**
+
+```ts
+// src/components/RadioField/radioThemeRoles.test.ts
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { RADIO_THEME_ROLES } from "./radioThemeRoles.ts";
+
+describe("RADIO_THEME_ROLES", () => {
+  it("maps colour props to Field roles plus fieldRadioSelected", () => {
+    assert.equal(RADIO_THEME_ROLES.backgroundColor, "fieldBackground");
+    assert.equal(RADIO_THEME_ROLES.labelColor, "fieldText");
+    assert.equal(RADIO_THEME_ROLES.descriptionColor, "fieldDescription");
+    assert.equal(RADIO_THEME_ROLES.dividerColor, "fieldBorder");
+    assert.equal(RADIO_THEME_ROLES.radioColor, "fieldBorder");
+    assert.equal(RADIO_THEME_ROLES.selectedColor, "fieldRadioSelected");
+    assert.equal(RADIO_THEME_ROLES.titleColor, "fieldLabel");
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd libraries/@studio-piot/studio-native-ui && node --experimental-strip-types --test src/components/RadioField/radioThemeRoles.test.ts`
+
+Expected: FAIL (module not found)
+
+- [ ] **Step 3: Add roles, types, RadioMark, RadioField**
+
+```ts
+// src/components/RadioField/radioThemeRoles.ts
+export const RADIO_THEME_ROLES = {
+  backgroundColor: "fieldBackground",
+  labelColor: "fieldText",
+  descriptionColor: "fieldDescription",
+  dividerColor: "fieldBorder",
+  radioColor: "fieldBorder",
+  selectedColor: "fieldRadioSelected",
+  titleColor: "fieldLabel",
+} as const;
+
+export type RadioThemeColorProp = keyof typeof RADIO_THEME_ROLES;
+```
+
+```ts
+// src/components/RadioField/types.ts
+import type { StyleProp, ViewStyle } from "react-native";
+import type { ButtonRadius } from "../Button/buttonRadius";
+
+export type RadioOption<T extends string = string> = {
+  value: T;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+};
+
+export type RadioFieldProps<T extends string = string> = {
+  value: T | null;
+  onChange: (value: T) => void;
+  options: RadioOption<T>[];
+  label?: string;
+  radius?: ButtonRadius;
+  backgroundColor?: string;
+  labelColor?: string;
+  descriptionColor?: string;
+  dividerColor?: string;
+  radioColor?: string;
+  selectedColor?: string;
+  titleColor?: string;
+  style?: StyleProp<ViewStyle>;
+};
+```
+
+```tsx
+// src/components/RadioField/RadioMark.tsx
+import { StyleSheet, View } from "react-native";
+
+const SIZE = 22;
+const DOT = 8;
+
+export function RadioMark({
+  selected,
+  radioColor,
+  selectedColor,
+  holeColor,
+}: {
+  selected: boolean;
+  radioColor: string;
+  selectedColor: string;
+  holeColor: string;
+}) {
+  if (selected) {
+    return (
+      <View
+        accessibilityElementsHidden
+        importantForAccessibility="no"
+        style={[
+          styles.outer,
+          { backgroundColor: selectedColor, borderColor: selectedColor },
+        ]}
+      >
+        <View style={[styles.dot, { backgroundColor: holeColor }]} />
+      </View>
+    );
+  }
+  return (
+    <View
+      accessibilityElementsHidden
+      importantForAccessibility="no"
+      style={[styles.outer, { borderColor: radioColor }]}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  outer: {
+    width: SIZE,
+    height: SIZE,
+    borderRadius: SIZE / 2,
+    borderWidth: 2,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  dot: {
+    width: DOT,
+    height: DOT,
+    borderRadius: DOT / 2,
+  },
+});
+```
+
+```tsx
+// src/components/RadioField/RadioField.tsx
+import {
+  StyleSheet,
+  Text,
+  TouchableOpacity,
+  View,
+} from "react-native";
+import { buttonRadiusValue } from "../Button/buttonRadius";
+import { useResolvedFieldColor } from "../Field/useResolvedFieldColor";
+import { RadioMark } from "./RadioMark";
+import { RADIO_THEME_ROLES } from "./radioThemeRoles";
+import type { RadioFieldProps } from "./types";
+
+const ROW_PAD_H = 16;
+
+export function RadioField<T extends string = string>({
+  value,
+  onChange,
+  options,
+  label,
+  radius = "xl",
+  backgroundColor: backgroundColorProp,
+  labelColor: labelColorProp,
+  descriptionColor: descriptionColorProp,
+  dividerColor: dividerColorProp,
+  radioColor: radioColorProp,
+  selectedColor: selectedColorProp,
+  titleColor: titleColorProp,
+  style,
+}: RadioFieldProps<T>) {
+  const backgroundColor = useResolvedFieldColor(
+    backgroundColorProp,
+    RADIO_THEME_ROLES.backgroundColor,
+  );
+  const labelColor = useResolvedFieldColor(
+    labelColorProp,
+    RADIO_THEME_ROLES.labelColor,
+  );
+  const descriptionColor = useResolvedFieldColor(
+    descriptionColorProp,
+    RADIO_THEME_ROLES.descriptionColor,
+  );
+  const dividerColor = useResolvedFieldColor(
+    dividerColorProp,
+    RADIO_THEME_ROLES.dividerColor,
+  );
+  const radioColor = useResolvedFieldColor(
+    radioColorProp,
+    RADIO_THEME_ROLES.radioColor,
+  );
+  const selectedColor = useResolvedFieldColor(
+    selectedColorProp,
+    RADIO_THEME_ROLES.selectedColor,
+  );
+  const titleColor = useResolvedFieldColor(
+    titleColorProp,
+    RADIO_THEME_ROLES.titleColor,
+  );
+  const borderRadius = buttonRadiusValue(radius);
+
+  if (options.length === 0) {
+    return null;
+  }
+
+  return (
+    <View style={[styles.group, style]}>
+      {label ? (
+        <Text style={[styles.title, { color: titleColor }]}>{label}</Text>
+      ) : null}
+      <View
+        accessibilityRole="radiogroup"
+        style={[
+          styles.surface,
+          { backgroundColor, borderRadius },
+        ]}
+      >
+        {options.map((option, index) => {
+          const selected = value === option.value;
+          return (
+            <View key={option.value}>
+              {index > 0 ? (
+                <View
+                  style={[styles.divider, { backgroundColor: dividerColor }]}
+                />
+              ) : null}
+              <TouchableOpacity
+                accessibilityLabel={
+                  option.description
+                    ? `${option.label}. ${option.description}`
+                    : option.label
+                }
+                accessibilityRole="radio"
+                accessibilityState={{
+                  selected,
+                  disabled: !!option.disabled,
+                }}
+                activeOpacity={0.75}
+                disabled={option.disabled}
+                onPress={() => onChange(option.value)}
+                style={[styles.row, option.disabled && styles.blocked]}
+              >
+                <View style={styles.textCol}>
+                  <Text style={[styles.label, { color: labelColor }]}>
+                    {option.label}
+                  </Text>
+                  {option.description ? (
+                    <Text
+                      style={[styles.description, { color: descriptionColor }]}
+                    >
+                      {option.description}
+                    </Text>
+                  ) : null}
+                </View>
+                <RadioMark
+                  holeColor={backgroundColor}
+                  radioColor={radioColor}
+                  selected={selected}
+                  selectedColor={selectedColor}
+                />
+              </TouchableOpacity>
+            </View>
+          );
+        })}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  group: {
+    width: "100%",
+    gap: 8,
+  },
+  title: {
+    fontSize: 13,
+    fontWeight: "600",
+    paddingHorizontal: 4,
+  },
+  surface: {
+    width: "100%",
+    overflow: "hidden",
+  },
+  row: {
+    minHeight: 52,
+    paddingHorizontal: ROW_PAD_H,
+    paddingVertical: 10,
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 12,
+  },
+  blocked: {
+    opacity: 0.4,
+  },
+  textCol: {
+    flex: 1,
+    gap: 2,
+  },
+  label: {
+    fontSize: 17,
+  },
+  description: {
+    fontSize: 13,
+  },
+  divider: {
+    height: StyleSheet.hairlineWidth,
+  },
+});
+```
+
+```ts
+// src/components/RadioField/index.ts
+export { RadioField } from "./RadioField";
+export { RADIO_THEME_ROLES, type RadioThemeColorProp } from "./radioThemeRoles";
+export type { RadioOption, RadioFieldProps } from "./types";
+```
+
+Wire exports in `src/components/index.ts` and `src/index.ts` the same way as Field/Form.
+
+- [ ] **Step 4: Run role test + full package tests and build**
+
+Run:
+
+```bash
+cd libraries/@studio-piot/studio-native-ui
+npm test
+npm run build
+```
+
+Expected: all tests pass; `tsc` succeeds; `dist/components/RadioField/` present.
+
+- [ ] **Step 5: Write usage docs and README links**
+
+Create `docs/components/radio-field.md` covering: peer ThemeProvider, required theme roles (including `fieldRadioSelected`), props table, Appearance-style example with `value` / `onChange` / `options`.
+
+Add to `README.md` Docs list:
+
+- `[RadioField usage](./docs/components/radio-field.md)`
+- `[Design: RadioField](./docs/superpowers/specs/2026-09-25-radio-field-design.md)`
+
+- [ ] **Step 6: Commit** (only if the user asked to commit)
+
+```bash
+git add src/components/RadioField src/components/index.ts src/index.ts docs/components/radio-field.md README.md
+git commit -m "Add RadioField with Field theme roles and selected mark."
+```
+
+---
+
+### Task 2: Ribe theme role + Appearance migration
+
+**Files:**
+- Modify: `projects/ribe/ribe-mobile-app/src/config/colors.ts`
+- Modify: `projects/ribe/ribe-mobile-app/src/config/colors.test.ts`
+- Modify: `projects/ribe/ribe-mobile-app/src/app/(app)/(tabs)/profile/appearance.tsx`
+
+**Interfaces:**
+- Consumes: `RadioField` from `@studio-piot/native-ui`; existing `useColorSchemePreference`, `ColorSchemePreference`
+- Produces: Appearance screen driven by `RadioField`; `Colors.*.fieldRadioSelected`
+
+- [ ] **Step 1: Add `fieldRadioSelected` to colours + test**
+
+In `ThemeColors` and both maps:
+
+```ts
+fieldRadioSelected: string;
+// light:
+fieldRadioSelected: charcoal, // or palette.neutral[900]
+// dark:
+fieldRadioSelected: stone, // or palette.neutral[100]
+```
+
+Update `colors.test.ts` `deepEqual` objects to include the new key with the exact hex (read `charcoal` / `stone` constants — currently `#22201D` / `#EDE7DE`).
+
+Run: `cd projects/ribe/ribe-mobile-app && pnpm exec node --experimental-strip-types --test src/config/colors.test.ts`
+
+Expected: PASS after both file and test updated together.
+
+- [ ] **Step 2: Replace Appearance list with RadioField**
+
+```tsx
+import { styles } from "@/config/styles";
+import {
+  useColorSchemePreference,
+  type ColorSchemePreference,
+} from "@/hooks/useThemeColor";
+import { RadioField } from "@studio-piot/native-ui";
+import { ScrollView } from "react-native";
+
+const OPTIONS: {
+  value: ColorSchemePreference;
+  label: string;
+  description?: string;
+}[] = [
+  {
+    value: "automatic",
+    label: "Automatic",
+    description: "Match the appearance settings on your device.",
+  },
+  { value: "light", label: "Light" },
+  { value: "dark", label: "Dark" },
+];
+
+export default function AppearanceScreen() {
+  const { preference, setPreference } = useColorSchemePreference();
+  // keep parseColorSchemePreference / openedAs behaviour from the current file
+  const current = preference || openedAs;
+
+  return (
+    <ScrollView
+      contentContainerStyle={styles.content}
+      contentInsetAdjustmentBehavior="automatic"
+      style={[styles.screen, { backgroundColor: /* useThemeColor("background") */ }]}
+    >
+      <RadioField
+        onChange={setPreference}
+        options={OPTIONS}
+        value={current}
+      />
+    </ScrollView>
+  );
+}
+```
+
+Preserve existing preference / search-param resolution from the current `appearance.tsx`. Drop the checkmark `Pressable` list and the summary “Automatic” line above it (the radio card is the UI). Ensure `ThemeProvider` already wraps the app (it does).
+
+After editing, run package link if needed:
+
+```bash
+cd projects/ribe/ribe-mobile-app
+pnpm install
+pnpm typecheck
+```
+
+Expected: `tsc --noEmit` passes.
+
+- [ ] **Step 3: Manual check**
+
+- Open Profile → Appearance; three rows in one rounded card; Automatic selected by default when preference is automatic; tap Light/Dark updates scheme and selected radio.
+- Light/dark maps: selected fill uses `fieldRadioSelected`; unselected rings use `fieldBorder`.
+
+- [ ] **Step 4: Commit** (only if the user asked)
+
+```bash
+# in ribe-mobile-app
+git add src/config/colors.ts src/config/colors.test.ts src/app/(app)/(tabs)/profile/appearance.tsx
+git commit -m "Use RadioField on Appearance and add fieldRadioSelected."
+```
+
+---
+
+## Spec coverage check
+
+| Spec item | Task |
+|---|---|
+| Single controlled group API | Task 1 |
+| LinkBlocks card layout + metrics | Task 1 |
+| Field roles + `fieldRadioSelected` | Task 1 roles + Task 2 colours |
+| RadioMark Views | Task 1 |
+| a11y radiogroup / radio | Task 1 |
+| Docs / exports | Task 1 |
+| Ribe Appearance migration | Task 2 |
+| Out of scope (multi-group, icons, …) | Not implemented |
+
+## Placeholder / consistency scan
+
+- No TBD / “similar to Task N” leftovers
+- Role names match the spec table
+- Props match the approved design (`value: T | null`, `onChange`, `options`, optional `label`)

package/docs/superpowers/plans/2026-09-25-select.md

@@ -0,0 +1,22 @@
+# Select Implementation Plan
+
+> **For agentic workers:** Inline execution in session; checkboxes track progress.
+
+**Goal:** Ship `Select` (Field-like trigger + TrueSheet options) and wire Ribe create-activity Type.
+
+**Architecture:** Controlled `Select` presents `@lodev09/react-native-true-sheet` at detents `[0.25, 0.5, 0.75]` (open index for `0.5`). `closeButton` accepts `ReactNode | ((dismiss) => ReactNode)`. Field theme roles + `fieldRadioSelected` for selected check.
+
+**Tech Stack:** TypeScript, RN, TrueSheet peer, Expo Ribe.
+
+## Global Constraints
+
+- Spec: `docs/superpowers/specs/2026-09-25-select-design.md`
+- Peer `@lodev09/react-native-true-sheet` (v3.x for Expo 57)
+- No brand in package; no search/icons/grids
+
+## Tasks
+
+1. [x] Package Select + peers + docs + exports + unit test for detent index helper
+2. [x] Ribe: install TrueSheet, create-activity Type → Select + glass close
+
+---