@studio-piot/native-ui 0.1.0

package/docs/superpowers/plans/2026-09-24-link-blocks.md

@@ -0,0 +1,414 @@
+# LinkBlocks 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 presentational `LinkBlocks` component driven by a config of titled groups and tappable rows (optional icon, label, chevron), with colour props from the parent.
+
+**Architecture:** Same pattern as `Button`: package owns layout; parent passes colours and `onPress`. Reuse `buttonRadiusValue` for surface radius. Pure helper filters empty groups for testability without a React Native renderer.
+
+**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 Expo Router, Linking, or icon library dependencies
+- Navigation is `onPress` per item only
+- Icons are optional `React.ReactNode`
+- Colours are props: `surfaceColor`, `labelColor`, `dividerColor`, `chevronColor`, optional `titleColor`
+- Width always `100%` of parent; radius reuses `ButtonRadius` (default `"xl"`)
+- Empty `items` groups are skipped (no surface, no title)
+- Spec: `docs/superpowers/specs/2026-09-24-link-blocks-design.md`
+- Commit only when the user asks
+
+## File map
+
+| File | Responsibility |
+|---|---|
+| `src/components/LinkBlocks/types.ts` | `LinkBlockItem`, `LinkBlockGroup`, `LinkBlocksProps` |
+| `src/components/LinkBlocks/filterGroups.ts` | Pure filter: drop groups with no items |
+| `src/components/LinkBlocks/filterGroups.test.ts` | Node tests |
+| `src/components/LinkBlocks/LinkBlocks.tsx` | UI |
+| `src/components/LinkBlocks/index.ts` | Barrel |
+| `src/components/index.ts` | Re-export |
+| `src/index.ts` | Public export |
+| `docs/components/link-blocks.md` | Usage |
+| `README.md` | Link to usage + design |
+
+---
+
+### Task 1: LinkBlocks types, filter helper, and component
+
+**Files:**
+- Create: `src/components/LinkBlocks/types.ts`
+- Create: `src/components/LinkBlocks/filterGroups.ts`
+- Create: `src/components/LinkBlocks/filterGroups.test.ts`
+- Create: `src/components/LinkBlocks/LinkBlocks.tsx`
+- Create: `src/components/LinkBlocks/index.ts`
+- Modify: `src/components/index.ts`
+- Modify: `src/index.ts`
+
+**Interfaces:**
+- Consumes: `buttonRadiusValue`, `ButtonRadius` from `../Button/buttonRadius`
+- Produces: `LinkBlocks`, `LinkBlocksProps`, `LinkBlockItem`, `LinkBlockGroup`, `filterLinkBlockGroups`
+
+- [ ] **Step 1: Write failing filter tests**
+
+```ts
+// src/components/LinkBlocks/filterGroups.test.ts
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { filterLinkBlockGroups } from "./filterGroups.ts";
+import type { LinkBlockGroup } from "./types.ts";
+
+describe("filterLinkBlockGroups", () => {
+  it("drops groups with empty items", () => {
+    const blocks: LinkBlockGroup[] = [
+      { key: "a", title: "A", items: [] },
+      {
+        key: "b",
+        items: [{ key: "1", label: "One", onPress: () => undefined }],
+      },
+    ];
+    const next = filterLinkBlockGroups(blocks);
+    assert.equal(next.length, 1);
+    assert.equal(next[0]?.key, "b");
+  });
+
+  it("keeps titled and untitled non-empty groups in order", () => {
+    const blocks: LinkBlockGroup[] = [
+      {
+        key: "t",
+        title: "Settings",
+        items: [{ key: "1", label: "One", onPress: () => undefined }],
+      },
+      {
+        key: "u",
+        items: [{ key: "2", label: "Two", onPress: () => undefined }],
+      },
+    ];
+    assert.deepEqual(
+      filterLinkBlockGroups(blocks).map((g) => g.key),
+      ["t", "u"],
+    );
+  });
+});
+```
+
+- [ ] **Step 2: Run — expect fail**
+
+```bash
+node --experimental-strip-types --test src/components/LinkBlocks/filterGroups.test.ts
+```
+
+Expected: FAIL (module not found).
+
+- [ ] **Step 3: Add types + filter**
+
+```ts
+// src/components/LinkBlocks/types.ts
+import type { ReactNode } from "react";
+import type { StyleProp, ViewStyle } from "react-native";
+import type { ButtonRadius } from "../Button/buttonRadius";
+
+export type LinkBlockItem = {
+  key: string;
+  label: string;
+  onPress: () => void;
+  icon?: ReactNode;
+  disabled?: boolean;
+};
+
+export type LinkBlockGroup = {
+  key: string;
+  title?: string;
+  items: LinkBlockItem[];
+};
+
+export type LinkBlocksProps = {
+  blocks: LinkBlockGroup[];
+  surfaceColor: string;
+  labelColor: string;
+  dividerColor: string;
+  chevronColor: string;
+  titleColor?: string;
+  radius?: ButtonRadius;
+  style?: StyleProp<ViewStyle>;
+};
+```
+
+```ts
+// src/components/LinkBlocks/filterGroups.ts
+import type { LinkBlockGroup } from "./types";
+
+export function filterLinkBlockGroups(
+  blocks: LinkBlockGroup[],
+): LinkBlockGroup[] {
+  return blocks.filter((group) => group.items.length > 0);
+}
+```
+
+- [ ] **Step 4: Re-run filter tests — expect pass**
+
+```bash
+node --experimental-strip-types --test src/components/LinkBlocks/filterGroups.test.ts
+```
+
+- [ ] **Step 5: Implement `LinkBlocks.tsx`**
+
+```tsx
+import {
+  StyleSheet,
+  Text,
+  TouchableOpacity,
+  View,
+} from "react-native";
+import { buttonRadiusValue } from "../Button/buttonRadius";
+import { filterLinkBlockGroups } from "./filterGroups";
+import type { LinkBlockGroup, LinkBlocksProps } from "./types";
+
+const ICON_SLOT = 28;
+const ROW_PAD_H = 16;
+
+export function LinkBlocks({
+  blocks,
+  surfaceColor,
+  labelColor,
+  dividerColor,
+  chevronColor,
+  titleColor,
+  radius = "xl",
+  style,
+}: LinkBlocksProps) {
+  const visible = filterLinkBlockGroups(blocks);
+  const borderRadius = buttonRadiusValue(radius);
+  const resolvedTitleColor = titleColor ?? labelColor;
+
+  return (
+    <View style={[styles.stack, style]}>
+      {visible.map((group) => (
+        <Group
+          key={group.key}
+          group={group}
+          surfaceColor={surfaceColor}
+          labelColor={labelColor}
+          dividerColor={dividerColor}
+          chevronColor={chevronColor}
+          titleColor={resolvedTitleColor}
+          borderRadius={borderRadius}
+        />
+      ))}
+    </View>
+  );
+}
+
+function Group({
+  group,
+  surfaceColor,
+  labelColor,
+  dividerColor,
+  chevronColor,
+  titleColor,
+  borderRadius,
+}: {
+  group: LinkBlockGroup;
+  surfaceColor: string;
+  labelColor: string;
+  dividerColor: string;
+  chevronColor: string;
+  titleColor: string;
+  borderRadius: number;
+}) {
+  const showIconSlot = group.items.some((item) => item.icon != null);
+  const dividerInset = ROW_PAD_H + (showIconSlot ? ICON_SLOT + 12 : 0);
+
+  return (
+    <View style={styles.group}>
+      {group.title ? (
+        <Text style={[styles.title, { color: titleColor }]}>{group.title}</Text>
+      ) : null}
+      <View
+        style={[
+          styles.surface,
+          { backgroundColor: surfaceColor, borderRadius },
+        ]}
+      >
+        {group.items.map((item, index) => (
+          <View key={item.key}>
+            {index > 0 ? (
+              <View
+                style={[
+                  styles.divider,
+                  {
+                    backgroundColor: dividerColor,
+                    marginLeft: dividerInset,
+                  },
+                ]}
+              />
+            ) : null}
+            <TouchableOpacity
+              accessibilityRole="button"
+              accessibilityState={{ disabled: !!item.disabled }}
+              activeOpacity={0.75}
+              disabled={item.disabled}
+              onPress={item.onPress}
+              style={[styles.row, item.disabled && styles.blocked]}
+            >
+              {showIconSlot ? (
+                <View style={styles.iconSlot}>{item.icon ?? null}</View>
+              ) : null}
+              <Text style={[styles.label, { color: labelColor, flex: 1 }]}>
+                {item.label}
+              </Text>
+              <Text
+                accessibilityElementsHidden
+                importantForAccessibility="no"
+                style={[styles.chevron, { color: chevronColor }]}
+              >
+                ›
+              </Text>
+            </TouchableOpacity>
+          </View>
+        ))}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  stack: {
+    width: "100%",
+    gap: 16,
+  },
+  group: {
+    width: "100%",
+    gap: 8,
+  },
+  title: {
+    fontSize: 13,
+    fontWeight: "600",
+    paddingHorizontal: 4,
+  },
+  surface: {
+    width: "100%",
+    overflow: "hidden",
+  },
+  row: {
+    minHeight: 52,
+    paddingHorizontal: ROW_PAD_H,
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 12,
+  },
+  blocked: {
+    opacity: 0.4,
+  },
+  iconSlot: {
+    width: ICON_SLOT,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  label: {
+    fontSize: 17,
+  },
+  chevron: {
+    fontSize: 22,
+    fontWeight: "300",
+    lineHeight: 24,
+  },
+  divider: {
+    height: StyleSheet.hairlineWidth,
+  },
+});
+```
+
+- [ ] **Step 6: Export from barrels**
+
+```ts
+// src/components/LinkBlocks/index.ts
+export { LinkBlocks } from "./LinkBlocks";
+export type {
+  LinkBlockGroup,
+  LinkBlockItem,
+  LinkBlocksProps,
+} from "./types";
+export { filterLinkBlockGroups } from "./filterGroups";
+```
+
+```ts
+// src/components/index.ts
+export {
+  Button,
+  type ButtonProps,
+  buttonRadiusValue,
+  type ButtonRadius,
+} from "./Button";
+export {
+  LinkBlocks,
+  filterLinkBlockGroups,
+  type LinkBlockGroup,
+  type LinkBlockItem,
+  type LinkBlocksProps,
+} from "./LinkBlocks";
+```
+
+```ts
+// src/index.ts — add alongside Button exports:
+export {
+  LinkBlocks,
+  filterLinkBlockGroups,
+  type LinkBlockGroup,
+  type LinkBlockItem,
+  type LinkBlocksProps,
+} from "./components/LinkBlocks";
+```
+
+- [ ] **Step 7: Verify**
+
+```bash
+npm test && npm run build
+```
+
+Expected: all existing tests plus filter suite pass; `dist/components/LinkBlocks/` emitted.
+
+---
+
+### Task 2: Usage docs and README
+
+**Files:**
+- Create: `docs/components/link-blocks.md`
+- Modify: `README.md` (Docs section)
+- Confirm: design spec status is `approved`
+
+- [ ] **Step 1: Write usage doc** covering props table, data shape, colour wiring with `useThemeColor`, example with `onPress` + optional icon `ReactNode`. Link to the design spec.
+
+- [ ] **Step 2: README** — add:
+  - [LinkBlocks usage](./docs/components/link-blocks.md)
+  - [Design: LinkBlocks](./docs/superpowers/specs/2026-09-24-link-blocks-design.md)
+
+- [ ] **Step 3: Final verify**
+
+```bash
+npm test && npm run build && npm pack --dry-run
+```
+
+Expected: docs appear in tarball; build clean.
+
+---
+
+## Spec coverage
+
+| Spec requirement | Task |
+|---|---|
+| Config `blocks` / item / group types | 1 |
+| Colour props + title fallback | 1 |
+| Skip empty groups | 1 |
+| Title outside surface, rows, chevron, dividers, radius, disabled opacity | 1 |
+| Exports | 1 |
+| Usage doc + README | 2 |
+| No router / brand / icon deps | Global |
+
+## Self-review
+
+- No TBD placeholders
+- Types align with spec (`LinkBlockItem`, `LinkBlockGroup`, `LinkBlocksProps`)
+- Ribe Profile migration remains out of scope