@studio-piot/native-ui 0.1.0

package/docs/superpowers/plans/2026-09-24-field.md

@@ -0,0 +1,583 @@
+# FieldText / FieldTextarea 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 presentational `FieldText` and `FieldTextarea` with shared chrome (label, focus/error border, clear, error text), colour props from the parent, and Button-style radius.
+
+**Architecture:** Shared internal `FieldChrome` owns layout and border/focus/clear/error. Thin `FieldText` / `FieldTextarea` pass multiline vs single-line input options. Pure `resolveFieldBorder` (and `shouldShowFieldClear`) keep focus/error rules testable without a React Native renderer. Replace the app-coupled example files under `src/components/Field/`.
+
+**Tech Stack:** TypeScript, React 19+, React Native, `tsc` → `dist`, Node test runner for pure helpers.
+
+## Global Constraints
+
+- No brand names, palettes, or app role catalogues in the package
+- No icon library dependencies; clear icon is optional `React.ReactNode`
+- Field components do not call `useThemeColor` — colours are required props
+- Controlled only: `value` + `onChangeText` required
+- Width always `100%` of parent; radius reuses `ButtonRadius` (default `"xl"`)
+- Focus: `borderWidth` 1 → 2 with padding compensation; error colour wins over focused colour; double stroke still applies when focused + error
+- Do not invert `editable` (pass through to `TextInput` as given)
+- Spec: `docs/superpowers/specs/2026-09-24-field-design.md`
+- Commit only when the user asks
+
+## File map
+
+| File | Responsibility |
+|---|---|
+| `src/components/Field/types.ts` | Shared props types |
+| `src/components/Field/resolveFieldBorder.ts` | Pure border colour / width / padding |
+| `src/components/Field/resolveFieldBorder.test.ts` | Node tests for border + clear visibility |
+| `src/components/Field/fieldChrome.tsx` | Shared UI chrome (internal) |
+| `src/components/Field/FieldText.tsx` | Single-line public component |
+| `src/components/Field/FieldTextarea.tsx` | Multiline public component |
+| `src/components/Field/index.ts` | Barrel |
+| Delete | `Field.tsx`, `FieldLabel.tsx`, `FieldInput.tsx`, `FieldError.tsx` (example leftovers) |
+| `src/components/index.ts` | Re-export |
+| `src/index.ts` | Public export |
+| `docs/components/field.md` | Usage |
+| `README.md` | Link to usage + design |
+
+---
+
+### Task 1: Types, border helper, FieldChrome, FieldText, FieldTextarea, exports
+
+**Files:**
+- Create: `src/components/Field/types.ts`
+- Create: `src/components/Field/resolveFieldBorder.ts`
+- Create: `src/components/Field/resolveFieldBorder.test.ts`
+- Create: `src/components/Field/fieldChrome.tsx`
+- Create: `src/components/Field/FieldText.tsx`
+- Create: `src/components/Field/FieldTextarea.tsx`
+- Create: `src/components/Field/index.ts`
+- Delete: `src/components/Field/Field.tsx`, `FieldLabel.tsx`, `FieldInput.tsx`, `FieldError.tsx` (and overwrite old example `FieldTextarea.tsx`)
+- Modify: `src/components/index.ts`
+- Modify: `src/index.ts`
+
+**Interfaces:**
+- Consumes: `buttonRadiusValue`, `ButtonRadius` from `../Button/buttonRadius`
+- Produces: `FieldText`, `FieldTextarea`, `FieldTextProps`, `FieldTextareaProps`, `FieldSharedProps`, `resolveFieldBorder`, `shouldShowFieldClear`
+
+- [ ] **Step 1: Write failing border / clear tests**
+
+```ts
+// src/components/Field/resolveFieldBorder.test.ts
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  resolveFieldBorder,
+  shouldShowFieldClear,
+} from "./resolveFieldBorder.ts";
+
+const colors = {
+  borderColor: "#aaa",
+  focusedBorderColor: "#00f",
+  errorColor: "#f00",
+};
+
+describe("resolveFieldBorder", () => {
+  it("resting: width 1 and borderColor", () => {
+    const next = resolveFieldBorder({
+      isFocused: false,
+      hasError: false,
+      ...colors,
+    });
+    assert.equal(next.borderWidth, 1);
+    assert.equal(next.borderColor, "#aaa");
+    assert.equal(next.paddingHorizontal, 14);
+  });
+
+  it("focused without error: width 2, focused colour, padding -1", () => {
+    const next = resolveFieldBorder({
+      isFocused: true,
+      hasError: false,
+      ...colors,
+    });
+    assert.equal(next.borderWidth, 2);
+    assert.equal(next.borderColor, "#00f");
+    assert.equal(next.paddingHorizontal, 13);
+  });
+
+  it("error without focus: width 1, error colour", () => {
+    const next = resolveFieldBorder({
+      isFocused: false,
+      hasError: true,
+      ...colors,
+    });
+    assert.equal(next.borderWidth, 1);
+    assert.equal(next.borderColor, "#f00");
+    assert.equal(next.paddingHorizontal, 14);
+  });
+
+  it("focused + error: width 2, error colour wins", () => {
+    const next = resolveFieldBorder({
+      isFocused: true,
+      hasError: true,
+      ...colors,
+    });
+    assert.equal(next.borderWidth, 2);
+    assert.equal(next.borderColor, "#f00");
+    assert.equal(next.paddingHorizontal, 13);
+  });
+});
+
+describe("shouldShowFieldClear", () => {
+  it("false when value empty", () => {
+    assert.equal(shouldShowFieldClear("", true), false);
+  });
+
+  it("false when no clear icon", () => {
+    assert.equal(shouldShowFieldClear("hi", false), false);
+  });
+
+  it("true when value and clear icon", () => {
+    assert.equal(shouldShowFieldClear("hi", true), true);
+  });
+});
+```
+
+- [ ] **Step 2: Run — expect fail**
+
+```bash
+node --experimental-strip-types --test src/components/Field/resolveFieldBorder.test.ts
+```
+
+Expected: FAIL (module not found).
+
+- [ ] **Step 3: Add types + resolve helpers**
+
+```ts
+// src/components/Field/types.ts
+import type { ReactNode, Ref } from "react";
+import type {
+  StyleProp,
+  TextInputProps,
+  TextStyle,
+  ViewStyle,
+} from "react-native";
+import type { ButtonRadius } from "../Button/buttonRadius";
+
+export type FieldSharedProps = {
+  value: string;
+  onChangeText: (text: string) => void;
+  borderColor: string;
+  focusedBorderColor: string;
+  errorColor: string;
+  textColor: string;
+  labelColor: string;
+  placeholderColor: string;
+  backgroundColor: string;
+  label?: string;
+  error?: string;
+  placeholder?: string;
+  radius?: ButtonRadius;
+  editable?: boolean;
+  clearIcon?: ReactNode;
+  onClear?: () => void;
+  style?: StyleProp<ViewStyle>;
+  inputStyle?: StyleProp<TextStyle>;
+  /** Forwarded to TextInput; do not invert. */
+  secureTextEntry?: boolean;
+  keyboardType?: TextInputProps["keyboardType"];
+  autoCapitalize?: TextInputProps["autoCapitalize"];
+  autoComplete?: TextInputProps["autoComplete"];
+  textContentType?: TextInputProps["textContentType"];
+  onFocus?: TextInputProps["onFocus"];
+  onBlur?: TextInputProps["onBlur"];
+  ref?: Ref<import("react-native").TextInput>;
+};
+
+export type FieldTextProps = FieldSharedProps;
+
+export type FieldTextareaProps = FieldSharedProps & {
+  numberOfLines?: number;
+};
+```
+
+```ts
+// src/components/Field/resolveFieldBorder.ts
+const RESTING_PADDING_HORIZONTAL = 14;
+
+export type ResolveFieldBorderInput = {
+  isFocused: boolean;
+  hasError: boolean;
+  borderColor: string;
+  focusedBorderColor: string;
+  errorColor: string;
+  restingPaddingHorizontal?: number;
+};
+
+export type ResolveFieldBorderResult = {
+  borderColor: string;
+  borderWidth: number;
+  paddingHorizontal: number;
+};
+
+export function resolveFieldBorder(
+  input: ResolveFieldBorderInput,
+): ResolveFieldBorderResult {
+  const resting =
+    input.restingPaddingHorizontal ?? RESTING_PADDING_HORIZONTAL;
+  const borderWidth = input.isFocused ? 2 : 1;
+  const borderColor = input.hasError
+    ? input.errorColor
+    : input.isFocused
+      ? input.focusedBorderColor
+      : input.borderColor;
+  const paddingHorizontal = input.isFocused ? resting - 1 : resting;
+
+  return { borderColor, borderWidth, paddingHorizontal };
+}
+
+export function shouldShowFieldClear(
+  value: string,
+  hasClearIcon: boolean,
+): boolean {
+  return value.length > 0 && hasClearIcon;
+}
+```
+
+- [ ] **Step 4: Run tests — expect pass**
+
+```bash
+node --experimental-strip-types --test src/components/Field/resolveFieldBorder.test.ts
+```
+
+Expected: PASS (all resolve + clear cases).
+
+- [ ] **Step 5: Implement FieldChrome (internal)**
+
+```tsx
+// src/components/Field/fieldChrome.tsx
+import { useState, type ReactNode } from "react";
+import {
+  StyleSheet,
+  Text,
+  TextInput,
+  TouchableOpacity,
+  View,
+  type StyleProp,
+  type TextInputProps,
+  type TextStyle,
+  type ViewStyle,
+} from "react-native";
+import { buttonRadiusValue, type ButtonRadius } from "../Button/buttonRadius";
+import {
+  resolveFieldBorder,
+  shouldShowFieldClear,
+} from "./resolveFieldBorder";
+import type { FieldSharedProps } from "./types";
+
+export type FieldChromeProps = FieldSharedProps & {
+  multiline?: boolean;
+  numberOfLines?: number;
+  minHeight?: number;
+  textAlignVertical?: TextInputProps["textAlignVertical"];
+};
+
+export function FieldChrome({
+  value,
+  onChangeText,
+  borderColor,
+  focusedBorderColor,
+  errorColor,
+  textColor,
+  labelColor,
+  placeholderColor,
+  backgroundColor,
+  label,
+  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 [isFocused, setIsFocused] = useState(false);
+  const hasError = Boolean(error);
+  const showClear = shouldShowFieldClear(value, clearIcon != null);
+  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.error, { color: errorColor }]}>{error}</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,
+  },
+  error: {
+    fontSize: 13,
+  },
+});
+```
+
+- [ ] **Step 6: Implement FieldText and FieldTextarea; barrel; delete leftovers**
+
+```tsx
+// src/components/Field/FieldText.tsx
+import { FieldChrome } from "./fieldChrome";
+import type { FieldTextProps } from "./types";
+
+export function FieldText(props: FieldTextProps) {
+  return <FieldChrome {...props} multiline={false} minHeight={48} />;
+}
+```
+
+```tsx
+// src/components/Field/FieldTextarea.tsx
+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"
+    />
+  );
+}
+```
+
+```ts
+// src/components/Field/index.ts
+export { FieldText } from "./FieldText";
+export { FieldTextarea } from "./FieldTextarea";
+export type { FieldSharedProps, FieldTextProps, FieldTextareaProps } from "./types";
+```
+
+Delete these example files if still present:
+
+- `src/components/Field/Field.tsx`
+- `src/components/Field/FieldLabel.tsx`
+- `src/components/Field/FieldInput.tsx`
+- `src/components/Field/FieldError.tsx`
+
+Update exports:
+
+```ts
+// src/components/index.ts — add alongside existing exports
+export {
+  FieldText,
+  FieldTextarea,
+  type FieldSharedProps,
+  type FieldTextProps,
+  type FieldTextareaProps,
+} from "./Field";
+```
+
+```ts
+// src/index.ts — add alongside existing exports
+export {
+  FieldText,
+  FieldTextarea,
+  type FieldSharedProps,
+  type FieldTextProps,
+  type FieldTextareaProps,
+} from "./components/Field";
+```
+
+- [ ] **Step 7: Run full tests + build**
+
+```bash
+npm test
+npm run build
+```
+
+Expected: all existing tests + new Field tests pass; `dist/components/Field/` emitted with `FieldText`, `FieldTextarea`, helpers; no leftover example modules required by the build.
+
+- [ ] **Step 8: Commit** (only if the user asked)
+
+```bash
+git add src/components/Field src/components/index.ts src/index.ts
+git commit -m "Add FieldText and FieldTextarea with shared chrome."
+```
+
+---
+
+### Task 2: Usage docs and README
+
+**Files:**
+- Create: `docs/components/field.md`
+- Modify: `README.md`
+
+**Interfaces:**
+- Consumes: public API from Task 1
+- Produces: usage doc linked from README
+
+- [ ] **Step 1: Write usage doc**
+
+Create `docs/components/field.md` covering:
+
+- Presentational contract (colours in, no theme lookup inside Field)
+- Example for `FieldText` with label, error, `clearIcon`
+- Example for `FieldTextarea`
+- Colour prop table
+- Focus / error / clear behaviour summary
+- Link to design spec `../superpowers/specs/2026-09-24-field-design.md`
+- Link to theme/Button usage for `useThemeColor`
+
+Use the app example from the design spec as the primary snippet (adapt imports to `@studio-piot/native-ui`).
+
+- [ ] **Step 2: Link from README**
+
+Under Docs, add:
+
+```markdown
+- [Field usage](./docs/components/field.md)
+- [Design: Field](./docs/superpowers/specs/2026-09-24-field-design.md)
+```
+
+- [ ] **Step 3: Commit** (only if the user asked)
+
+```bash
+git add docs/components/field.md README.md
+git commit -m "Document FieldText and FieldTextarea usage."
+```
+
+---
+
+## Self-review (plan vs spec)
+
+| Spec requirement | Task |
+|---|---|
+| FieldText + FieldTextarea single-control API | Task 1 |
+| Shared chrome | Task 1 (`fieldChrome.tsx`) |
+| Required colour props | Task 1 (`types.ts`) |
+| Focus double stroke + padding compensation | Task 1 (`resolveFieldBorder`) |
+| Error under field; error colour; focused+error | Task 1 |
+| Clear when value + clearIcon; onClear default | Task 1 |
+| ButtonRadius default xl | Task 1 |
+| Full width; disabled opacity; editable not inverted | Task 1 |
+| Remove example leftovers | Task 1 |
+| Usage docs + README | Task 2 |
+| No uncontrolled / validation / icon libs | Out of scope (not in tasks) |
+
+No placeholders remaining. Types named consistently: `FieldSharedProps`, `FieldTextProps`, `FieldTextareaProps`, `resolveFieldBorder`, `shouldShowFieldClear`.