@studio-piot/native-ui 0.1.0

package/docs/superpowers/plans/2026-09-24-theme-provider-button.md

@@ -0,0 +1,493 @@
+# Theme provider and Button 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 project-agnostic `ThemeProvider` / `useThemeColor` / `useColorScheme` API and a presentational `Button` that takes colours as props, with Tailwind-style radius steps and full-width layout.
+
+**Architecture:** Apps pass `{ light, dark }` colour maps into `ThemeProvider`. Pure helpers resolve scheme and roles. `Button` never looks up theme roles — callers pass `backgroundColor` and `labelColor`. Package layout styles stay colour-free.
+
+**Tech Stack:** TypeScript, React 19+, React Native 0.76+, `tsc` build to `dist`, Node test runner for pure helpers.
+
+## Global Constraints
+
+- No brand names, palettes, or app-specific role catalogues in the package
+- Peer deps only: `react` >= 19, `react-native` >= 0.76; no new runtime dependencies
+- Button width is always `"100%"` of its parent (not a prop)
+- Button colours come only from props (`backgroundColor`, `labelColor`)
+- Radius values: `none` | `sm` | `md` | `lg` | `xl` | `2xl` | `3xl` | `full` (default `xl`)
+- Disabled / loading: opacity (e.g. `0.4`), same colours
+- Spec: `docs/superpowers/specs/2026-09-24-theme-provider-button-design.md`
+- Usage doc: `docs/components/button.md` (keep in sync if API drifts)
+- Commit only when the user asks
+- Remove `drafts/` WIP button leftovers once the real `Button` exists
+
+## File map
+
+| File | Responsibility |
+|---|---|
+| `src/theme/types.ts` | `ThemeColors`, provider value types |
+| `src/theme/resolveColorScheme.ts` | Pure `string \| null \| undefined` → `"light" \| "dark"` |
+| `src/theme/resolveColorScheme.test.ts` | Node tests for scheme helper |
+| `src/theme/ThemeProvider.tsx` | Context + provider |
+| `src/theme/useColorScheme.ts` | Hook wrapping RN + `resolveColorScheme` |
+| `src/theme/useThemeColor.ts` | Role → colour with overrides |
+| `src/theme/index.ts` | Theme barrel |
+| `src/components/buttonRadius.ts` | Radius name → number map + type |
+| `src/components/buttonRadius.test.ts` | Node tests for radius map |
+| `src/components/Button.tsx` | Button component |
+| `src/components/index.ts` | Export `Button` |
+| `src/index.ts` | Public entry |
+| `tsconfig.json` | Ensure RN types resolve (`moduleResolution: "bundler"`) |
+| `package.json` | `test` script; include `docs` in `files` if publishing docs |
+| Delete `drafts/` | Remove parked WIP |
+
+---
+
+### Task 1: Theme scheme helper + provider + hooks
+
+**Files:**
+- Create: `src/theme/types.ts`
+- Create: `src/theme/resolveColorScheme.ts`
+- Create: `src/theme/resolveColorScheme.test.ts`
+- Create: `src/theme/ThemeProvider.tsx`
+- Create: `src/theme/useColorScheme.ts`
+- Create: `src/theme/useThemeColor.ts`
+- Create: `src/theme/index.ts`
+- Modify: `package.json` (add `"test": "node --experimental-strip-types --test src/**/*.test.ts"`)
+- Modify: `tsconfig.json` (`moduleResolution`: `"bundler"`, keep emit)
+
+**Interfaces:**
+- Produces:
+  - `resolveColorScheme(scheme: string | null | undefined): "light" | "dark"`
+  - `ThemeColors = Record<string, string>`
+  - `ThemeProvider({ colors: { light: T; dark: T }, children })`
+  - `useColorScheme(): "light" | "dark"`
+  - `useThemeColor(colorName: string, overrides?: { light?: string; dark?: string }): string`
+
+- [ ] **Step 1: Write failing scheme tests**
+
+```ts
+// src/theme/resolveColorScheme.test.ts
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { resolveColorScheme } from "./resolveColorScheme.ts";
+
+describe("resolveColorScheme", () => {
+  it("returns dark only for dark", () => {
+    assert.equal(resolveColorScheme("dark"), "dark");
+  });
+
+  it("treats everything else as light", () => {
+    assert.equal(resolveColorScheme("light"), "light");
+    assert.equal(resolveColorScheme(null), "light");
+    assert.equal(resolveColorScheme(undefined), "light");
+    assert.equal(resolveColorScheme("unspecified"), "light");
+  });
+});
+```
+
+- [ ] **Step 2: Run tests — expect fail**
+
+```bash
+node --experimental-strip-types --test src/theme/resolveColorScheme.test.ts
+```
+
+Expected: FAIL (module not found).
+
+- [ ] **Step 3: Implement scheme helper**
+
+```ts
+// src/theme/resolveColorScheme.ts
+export function resolveColorScheme(
+  scheme: string | null | undefined,
+): "light" | "dark" {
+  return scheme === "dark" ? "dark" : "light";
+}
+```
+
+- [ ] **Step 4: Re-run tests — expect pass**
+
+```bash
+node --experimental-strip-types --test src/theme/resolveColorScheme.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Add theme types + provider + hooks**
+
+```ts
+// src/theme/types.ts
+export type ThemeColors = Record<string, string>;
+
+export type ThemeContextValue = {
+  colors: { light: ThemeColors; dark: ThemeColors };
+};
+```
+
+```tsx
+// src/theme/ThemeProvider.tsx
+import { createContext, createElement, type ReactNode } from "react";
+import type { ThemeColors, ThemeContextValue } from "./types";
+
+export const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+export function ThemeProvider({
+  colors,
+  children,
+}: {
+  colors: { light: ThemeColors; dark: ThemeColors };
+  children: ReactNode;
+}) {
+  return createElement(
+    ThemeContext.Provider,
+    { value: { colors } },
+    children,
+  );
+}
+```
+
+```ts
+// src/theme/useColorScheme.ts
+import { useContext } from "react";
+import { useColorScheme as useSystemColorScheme } from "react-native";
+import { resolveColorScheme } from "./resolveColorScheme";
+import { ThemeContext } from "./ThemeProvider";
+
+export function useColorScheme(): "light" | "dark" {
+  if (!useContext(ThemeContext)) {
+    throw new Error("useColorScheme must be used within ThemeProvider");
+  }
+  return resolveColorScheme(useSystemColorScheme());
+}
+```
+
+```ts
+// src/theme/useThemeColor.ts
+import { useContext } from "react";
+import { ThemeContext } from "./ThemeProvider";
+import { useColorScheme } from "./useColorScheme";
+
+export function useThemeColor(
+  colorName: string,
+  overrides?: { light?: string; dark?: string },
+): string {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) {
+    throw new Error("useThemeColor must be used within ThemeProvider");
+  }
+  const scheme = useColorScheme();
+  const override = overrides?.[scheme];
+  if (override != null) {
+    return override;
+  }
+  const value = ctx.colors[scheme][colorName];
+  if (value == null) {
+    throw new Error(`Unknown theme colour "${colorName}" for scheme "${scheme}"`);
+  }
+  return value;
+}
+```
+
+```ts
+// src/theme/index.ts
+export type { ThemeColors, ThemeContextValue } from "./types";
+export { ThemeProvider } from "./ThemeProvider";
+export { useColorScheme } from "./useColorScheme";
+export { useThemeColor } from "./useThemeColor";
+export { resolveColorScheme } from "./resolveColorScheme";
+```
+
+- [ ] **Step 6: Fix `tsconfig.json` + add test script; build**
+
+Set `"moduleResolution": "bundler"` (keep `commonjs` module emit if that is what Metro consumers expect today, or keep current emit settings except resolution). Add `react-native` to `devDependencies` so `tsc` can resolve types during package builds:
+
+```bash
+npm install --save-dev react-native@0.86.3
+```
+
+```json
+"scripts": {
+  "test": "node --experimental-strip-types --test 'src/**/*.test.ts'"
+}
+```
+
+```bash
+npm test && npm run build
+```
+
+Expected: tests pass; `dist/theme/*` emitted.
+
+---
+
+### Task 2: Button radius map + Button component
+
+**Files:**
+- Create: `src/components/buttonRadius.ts`
+- Create: `src/components/buttonRadius.test.ts`
+- Create: `src/components/Button.tsx`
+- Modify: `src/components/index.ts`
+- Delete: `drafts/` (entire folder)
+- Delete: any leftover `src/components/button.tsx` if present
+
+**Interfaces:**
+- Consumes: React Native primitives only (no theme hooks inside Button)
+- Produces:
+  - `ButtonRadius` type and `buttonRadiusValue(radius: ButtonRadius): number`
+  - `Button` props per spec (`label`, `onPress`, `backgroundColor`, `labelColor`, `disabled?`, `loading?`, `variant?`, `radius?`, `style?`, `labelStyle?`)
+
+- [ ] **Step 1: Write failing radius tests**
+
+```ts
+// src/components/buttonRadius.test.ts
+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);
+  });
+});
+```
+
+- [ ] **Step 2: Run — expect fail; then implement map**
+
+```ts
+// src/components/buttonRadius.ts
+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];
+}
+```
+
+```bash
+node --experimental-strip-types --test src/components/buttonRadius.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Implement `Button.tsx`**
+
+```tsx
+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
+      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",
+  },
+});
+```
+
+- [ ] **Step 4: Export from barrels and public entry**
+
+```ts
+// src/components/index.ts
+export { Button, type ButtonProps } from "./Button";
+export { buttonRadiusValue, type ButtonRadius } from "./buttonRadius";
+```
+
+```ts
+// src/index.ts
+export const version = "0.1.0";
+
+export * from "./theme";
+export { Button, type ButtonProps } from "./components/Button";
+export {
+  buttonRadiusValue,
+  type ButtonRadius,
+} from "./components/buttonRadius";
+export * as components from "./components";
+```
+
+Remove `drafts/` and any dead lowercase `button.tsx`.
+
+- [ ] **Step 5: Build + test**
+
+```bash
+npm test && npm run build
+```
+
+Expected: all tests pass; `dist/components/Button.js` and theme files exist; package entry exports `Button`, `ThemeProvider`, `useThemeColor`.
+
+---
+
+### Task 3: Docs + package metadata sync
+
+**Files:**
+- Verify: `docs/components/button.md` matches the implemented API
+- Modify: `README.md` — link usage + design; drop outdated Ribe/`link:` notes; show `file:` / npm install generically
+- Modify: `package.json` `files` to include `docs`
+- Modify: design spec status line to `approved`
+
+- [ ] **Step 1: Update README**
+
+Replace the Local development / Ribe-specific section with generic install + docs links:
+
+```md
+## Docs
+
+- [Theme provider and Button usage](./docs/components/button.md)
+- [Design: theme provider and Button](./docs/superpowers/specs/2026-09-24-theme-provider-button-design.md)
+```
+
+Keep install, publish, license. Example import should show `Button` + `ThemeProvider`.
+
+- [ ] **Step 2: Confirm usage doc**
+
+Skim `docs/components/button.md` against Task 2 props. Fix any drift (radius table, prop names).
+
+- [ ] **Step 3: Mark design approved + include docs in publish**
+
+In the design spec header: `Status: approved`.
+
+In `package.json`:
+
+```json
+"files": ["dist", "src", "docs", "README.md", "LICENSE"]
+```
+
+- [ ] **Step 4: Final verify**
+
+```bash
+npm test && npm run build && npm pack --dry-run
+```
+
+Expected: docs appear in the tarball listing; build clean.
+
+---
+
+## Spec coverage
+
+| Spec requirement | Task |
+|---|---|
+| ThemeProvider + context | 1 |
+| useColorScheme / resolveColorScheme | 1 |
+| useThemeColor + overrides + missing role error | 1 |
+| Button colour props, variants, loading/disabled opacity | 2 |
+| Full width | 2 |
+| Tailwind radius scale + default `xl` | 2 |
+| Exports / barrels | 2 |
+| Usage documentation | 3 (and pre-written `docs/components/button.md`) |
+| No brand coupling | Global + all tasks |
+
+## Self-review
+
+- No TBD / placeholder steps
+- Types aligned: `ButtonRadius`, `ButtonProps`, `ThemeColors`
+- Consumer app wiring (Ribe `ThemeProvider` mount) is out of scope per spec — not in this plan