@krapwoo/ds-viewer 0.1.1 → 0.3.0

package/starter-kit/components/Shimmer/Shimmer.tsx

@@ -0,0 +1,158 @@
+import React, { createContext, useContext, useEffect, useMemo, type ReactNode } from 'react';
+import { View, Animated, Easing, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_RADIUS, DS_SPACING, DS_MOTION_LOOP_DURATION } from '../../tokens';
+import type { ShimmerProps, ShimmerVariant } from './Shimmer.types';
+
+// True for any Shimmer rendered inside a <SkeletonGroup>. When set, individual blocks drop their own
+// "Loading" announcement — the group announces once for the whole skeleton instead (see below).
+const SkeletonGroupContext = createContext(false);
+
+export const SHIMMER_TEXT_HEIGHT = DS_SPACING[800];
+
+// Plain Shimmer blocks pulse between these two values. Translucent black (not an opaque grey) so the
+// shimmer reads correctly as a wash over whatever surface it's placed on — light, dark, or coloured —
+// the same convention DS uses for its other "works on any surface" overlays. Interpolating the colour
+// itself (not a separate `opacity` style) keeps each independent block visually equivalent to a plain
+// alpha wash.
+const PULSE_LOW  = 'rgba(0, 0, 0, 0.02)';
+const PULSE_HIGH = 'rgba(0, 0, 0, 0.05)';
+
+// One pulse cycle, shared by every Shimmer instance.
+const PULSE_CYCLE_MS = DS_MOTION_LOOP_DURATION.pulse;
+
+// A single module-level clock every Shimmer/Breathing instance reads from, instead of each starting
+// its own timer at mount. Two independent per-instance timers would drift out of phase depending on
+// the exact moment each mounted — sharing one clock means any shimmers visible together always pulse
+// in lockstep. `useNativeDriver:false` is required because we interpolate `backgroundColor` (colour
+// interpolation is JS-driven).
+const sharedProgress = new Animated.Value(0);
+let sharedProgressStarted = false;
+function ensureSharedProgressStarted(): void {
+  if (sharedProgressStarted) return;
+  sharedProgressStarted = true;
+  Animated.loop(
+    Animated.timing(sharedProgress, {
+      toValue: 1,
+      duration: PULSE_CYCLE_MS,
+      easing: Easing.linear,
+      useNativeDriver: false,
+    }),
+  ).start();
+}
+
+// ─── Shared animated primitive ────────────────────────────────────────────────
+// A solid block that breathes between `low` and `high` on the shared progress value. Exported so any
+// composite skeleton can reuse the same pulse (and stay in lockstep with plain Shimmers).
+export function Breathing({
+  phase = 0,
+  low = PULSE_LOW,
+  high = PULSE_HIGH,
+  style,
+  accessibilityRole,
+  accessibilityLabel,
+}: {
+  phase?: number;
+  /** Override the pulse's low/high colours. Defaults to the shared translucent pulse. */
+  low?: string;
+  high?: string;
+  style?: StyleProp<ViewStyle>;
+  accessibilityRole?: 'progressbar';
+  accessibilityLabel?: string;
+}) {
+  useEffect(() => {
+    ensureSharedProgressStarted();
+  }, []);
+
+  // (progress + phase) % 1, then a triangle wave: high at 0, low at 0.5, high at 1 — equivalent to the
+  // cosine breathe, driven off the one shared linear clock so all instances stay phase-locked.
+  const backgroundColor = useMemo(
+    () =>
+      Animated.modulo(Animated.add(sharedProgress, phase), 1).interpolate({
+        inputRange: [0, 0.5, 1],
+        outputRange: [high, low, high],
+      }),
+    [phase, low, high],
+  );
+
+  return (
+    <Animated.View
+      style={[style, { backgroundColor }]}
+      accessibilityRole={accessibilityRole}
+      accessibilityLabel={accessibilityLabel}
+    />
+  );
+}
+
+function dimensionsForVariant(
+  variant: ShimmerVariant,
+  width: ShimmerProps['width'],
+  height: ShimmerProps['height'],
+  size: number,
+): ViewStyle {
+  switch (variant) {
+    case 'circle':
+      return { width: size, height: size, borderRadius: DS_RADIUS.round };
+    case 'container':
+      return { width: width ?? '100%', height: height ?? 80, borderRadius: DS_RADIUS.medium };
+    case 'text':
+    default:
+      return { width: width ?? '100%', height: height ?? SHIMMER_TEXT_HEIGHT, borderRadius: DS_RADIUS.small };
+  }
+}
+
+// ─── Shimmer ──────────────────────────────────────────────────────────────────
+/**
+ * A single loading placeholder — see `ShimmerProps.variant` for what each shape stands in for.
+ * A real composite skeleton (e.g. a list row: avatar + a two-line label) is built by stacking
+ * multiple Shimmers of the right variant/count/dimensions, not by inventing one shape to cover
+ * everything — see the "Circle + text" example in the catalog for exactly this composition.
+ */
+export function Shimmer({ variant = 'text', width, height, size = 40, style }: ShimmerProps) {
+  // Inside a <SkeletonGroup>, the group owns the single "Loading" announcement — each block stays
+  // silent so a composite skeleton (avatar + two text lines = 3 blocks) doesn't make a screen
+  // reader read "Loading, Loading, Loading". A standalone Shimmer still announces on its own.
+  const insideGroup = useContext(SkeletonGroupContext);
+  return (
+    <Breathing
+      style={[dimensionsForVariant(variant, width, height, size), style]}
+      accessibilityRole={insideGroup ? undefined : 'progressbar'}
+      accessibilityLabel={insideGroup ? undefined : 'Loading'}
+    />
+  );
+}
+
+// ─── SkeletonGroup ──────────────────────────────────────────────────────────────
+/**
+ * Wraps a composite skeleton (several stacked Shimmers standing in for one real element — e.g. a
+ * list row's avatar + two text lines) so assistive tech announces it as ONE "Loading" region
+ * instead of once per block. Provides {@link SkeletonGroupContext} so every descendant Shimmer drops
+ * its own announcement; the group itself carries the single `progressbar`/busy role. Pass your own
+ * layout via `style` (the group is a plain View, so `flexDirection`/`gap` land where you'd expect) —
+ * it adds no layout of its own.
+ */
+export function SkeletonGroup({
+  label = 'Loading',
+  style,
+  children,
+}: {
+  /** Accessible name for the whole loading region. @default 'Loading' */
+  label?: string;
+  /** Layout for the group (flexDirection, gap, …) — it renders a plain View, so styles land where
+   *  you'd expect. */
+  style?: StyleProp<ViewStyle>;
+  /** The Shimmers making up the skeleton. */
+  children: ReactNode;
+}) {
+  return (
+    <SkeletonGroupContext.Provider value>
+      <View
+        style={style}
+        accessibilityRole="progressbar"
+        accessibilityLabel={label}
+        accessibilityState={{ busy: true }}
+      >
+        {children}
+      </View>
+    </SkeletonGroupContext.Provider>
+  );
+}

package/starter-kit/components/Shimmer/Shimmer.types.ts

@@ -0,0 +1,27 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
+export type ShimmerVariant = 'text' | 'container' | 'circle';
+
+export interface ShimmerProps {
+  /** Which shape this placeholder stands in for:
+   *  - `'text'` (default) — **one line of text**. A real element with 3 lines of text gets 3
+   *    stacked `text` Shimmers, not one tall one — a skeleton should mirror the real line count.
+   *    When stacking 2+ lines, give the last one ~70% of the others' width — real text rarely fills
+   *    every line edge-to-edge, and a shorter final line reads as "this is where the paragraph
+   *    naturally ends," not a loading glitch.
+   *  - `'circle'` — always a circular element (an Avatar, an icon-only Pill/Button, a status dot) —
+   *    never used for anything that isn't actually round in its loaded state.
+   *  - `'container'` — everything else: a Card, a Banner, an image, any non-text/non-circular UI
+   *    element. Its `width`/`height` should match the real element it's replacing (a Card skeleton
+   *    should be Card-shaped, not an arbitrary block), so the skeleton reserves the same layout
+   *    space the loaded content will actually occupy — no jump when it swaps in. */
+  variant?: ShimmerVariant;
+  /** Width (text and container). Defaults to 100%. */
+  width?: number | `${number}%`;
+  /** Height (text and container). Defaults: text 16, container 80 — override to match the real
+   *  element this stands in for. */
+  height?: number;
+  /** Diameter for `circle` variant. Default 40. */
+  size?: number;
+  style?: StyleProp<ViewStyle>;
+}

package/starter-kit/components/Shimmer/SkeletonGroup.catalog.tsx

@@ -0,0 +1,39 @@
+import React from 'react';
+import { View, StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Shimmer, SkeletonGroup } from './Shimmer';
+import { DS_SPACING } from '../../tokens';
+
+const styles = StyleSheet.create({
+  shimmerLines: { flex: 1, gap: DS_SPACING[400] },
+  previewRow: { flexDirection: 'row', alignItems: 'center', gap: DS_SPACING[600] },
+});
+
+export default defineCatalogPage({
+  component: 'SkeletonGroup',
+  group: 'Sub-Parts',
+  description: 'An accessibility wrapper for a composite skeleton — several Shimmers standing in for one real element (e.g. a list row: an avatar + a two-line label). It announces the whole thing as one "Loading" region and silences the individual blocks, so a screen reader says "Loading" once instead of once per Shimmer. Adds no layout of its own — pass your own flexDirection/gap via style.',
+  whenToUse: 'Wrap 2+ Shimmers that together stand in for one element. A single lone Shimmer already announces on its own and needs no wrapper.',
+  a11y: 'Carries accessibilityRole="progressbar" + accessibilityLabel (default "Loading") + accessibilityState={{ busy: true }} for the whole region; provides a context that makes every descendant Shimmer drop its own announcement. Net effect: one "Loading" announcement per skeleton, not one per block.',
+  // No visual variants/states — it's a transparent a11y wrapper. The one example shows the
+  // composite it wraps; Props + Accessibility document its contract.
+  hide: { states: true },
+  variants: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'composite',
+        name: 'Wrapping a composite skeleton',
+        node: (
+          <SkeletonGroup style={styles.previewRow}>
+            <Shimmer variant="circle" size={40} />
+            <View style={styles.shimmerLines}>
+              <Shimmer variant="text" width={160} />
+              <Shimmer variant="text" width={112} />
+            </View>
+          </SkeletonGroup>
+        ),
+      },
+    ],
+  },
+});

package/starter-kit/components/Shimmer/index.ts

@@ -0,0 +1,2 @@
+export { Shimmer, SkeletonGroup, Breathing, SHIMMER_TEXT_HEIGHT } from './Shimmer';
+export type { ShimmerProps, ShimmerVariant } from './Shimmer.types';

package/starter-kit/components/Surface/Surface.catalog.tsx

@@ -0,0 +1,44 @@
+import React from 'react';
+import { Text, StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Surface } from './Surface';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../../tokens';
+
+const styles = StyleSheet.create({
+  surfaceDemo: { height: 96, justifyContent: 'center', alignItems: 'center', padding: DS_SPACING[800] },
+  surfaceText: { ...DS_TYPOGRAPHY.bodyMd, color: DS_SEMANTIC.text.regular },
+});
+
+export default defineCatalogPage({
+  component: 'Surface',
+  group: 'Surfaces',
+  description:
+    "Declares \"this subtree's background is tone\" — renders a plain View filled with the matching token (surface.white or surface.main) and provides that tone to descendants via context, so a tone-aware component inside (e.g. FieldContainer/InputField) can automatically pick a fill that contrasts with it instead of assuming white.",
+  whenToUse:
+    "Wrap a screen (or any region) wherever its background isn't the default white — a page with a muted/grey background, for instance — so anything inside that needs to contrast with its background picks the right fill automatically.",
+  variants: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'white',
+        name: 'White',
+        props: { tone: 'white' },
+        node: (
+          <Surface tone="white" style={styles.surfaceDemo}>
+            <Text style={styles.surfaceText}>surface.white</Text>
+          </Surface>
+        ),
+      },
+      {
+        key: 'muted',
+        name: 'Muted',
+        props: { tone: 'muted' },
+        node: (
+          <Surface tone="muted" style={styles.surfaceDemo}>
+            <Text style={styles.surfaceText}>surface.main</Text>
+          </Surface>
+        ),
+      },
+    ],
+  },
+});

package/starter-kit/components/Surface/Surface.tsx

@@ -0,0 +1,45 @@
+import React, { createContext, useContext, type ReactNode } from 'react';
+import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC } from '../../tokens';
+
+export type SurfaceTone = 'white' | 'muted';
+
+// Defaults to 'white' — a screen with no explicit <Surface> ancestor is assumed to sit on a white
+// background, the common case (matches e.g. Card's own default fill).
+const SurfaceToneContext = createContext<SurfaceTone>('white');
+
+/** What background tone the nearest ancestor `<Surface>` declared (or 'white' if there isn't one).
+ *  Components that need to contrast with whatever's actually behind them — FieldContainer/
+ *  InputField today — read this instead of assuming one fixed background. */
+export function useSurfaceTone(): SurfaceTone {
+  return useContext(SurfaceToneContext);
+}
+
+export interface SurfaceProps {
+  /** Which background this surface renders. Descendants read this via `useSurfaceTone()` to
+   *  automatically pick a fill that contrasts with it (e.g. a field goes white on a muted page,
+   *  recessed on a white one) instead of needing to be told individually. */
+  tone: SurfaceTone;
+  style?: StyleProp<ViewStyle>;
+  children?: ReactNode;
+}
+
+/**
+ * Declares "this subtree's background is `tone`" — renders a plain View filled with the matching
+ * token (`surface.white` or `surface.main`) and provides that tone to descendants via context.
+ * Wrap a screen (or any region) in this wherever its background isn't the default white — a page
+ * with a muted/grey background, for instance — so anything inside that needs to contrast with its
+ * background picks the right fill automatically rather than assuming white.
+ */
+export function Surface({ tone, style, children }: SurfaceProps) {
+  return (
+    <SurfaceToneContext.Provider value={tone}>
+      <View style={[tone === 'white' ? styles.white : styles.muted, style]}>{children}</View>
+    </SurfaceToneContext.Provider>
+  );
+}
+
+const styles = StyleSheet.create({
+  white: { backgroundColor: DS_SEMANTIC.surface.white },
+  muted: { backgroundColor: DS_SEMANTIC.surface.main },
+});

package/starter-kit/components/Surface/index.ts

@@ -0,0 +1,2 @@
+export { Surface, useSurfaceTone } from './Surface';
+export type { SurfaceProps, SurfaceTone } from './Surface';

package/starter-kit/components/Switch/Switch.catalog.tsx

@@ -0,0 +1,33 @@
+import React, { useState } from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Switch } from './Switch';
+
+function SwitchDemo() {
+  const [value, setValue] = useState(true);
+  return <Switch value={value} onValueChange={setValue} accessibilityLabel="Notifications" />;
+}
+
+function SwitchLabelDemo() {
+  const [value, setValue] = useState(true);
+  return <Switch value={value} onValueChange={setValue} label="Notifications" />;
+}
+
+export default defineCatalogPage({
+  component: 'Switch',
+  group: 'Controls',
+  specimenSize: 'compact',
+  description: 'A boolean on/off toggle. The thumb slides and the track crossfades colour, sharing SegmentedToggle/UnderlineTabs\' own slide-animation hook for a consistent motion feel.',
+  whenToUse: 'A setting that takes effect immediately, no separate save step. For recording a fact a future action (like a form submit) will act on, use Checkbox; for one-of-many exclusive selection, use Radio.',
+  a11y: 'Renders a Pressable with accessibilityRole="switch" and accessibilityState.checked — pass accessibilityLabel to say what it controls.',
+  variants: {
+    items: [{ key: 'default', name: 'Default (tap to toggle)', node: <SwitchDemo /> }],
+  },
+  states: {
+    items: [
+      { key: 'off', name: 'Off', node: <Switch value={false} onValueChange={() => {}} accessibilityLabel="Notifications" /> },
+      { key: 'on', name: 'On', node: <Switch value={true} onValueChange={() => {}} accessibilityLabel="Notifications" /> },
+      { key: 'label', name: 'With label', props: { label: true }, node: <SwitchLabelDemo /> },
+      { key: 'disabled', name: 'Disabled', node: <Switch value={true} onValueChange={() => {}} disabled accessibilityLabel="Notifications" /> },
+    ],
+  },
+});

package/starter-kit/components/Switch/Switch.tsx

@@ -0,0 +1,129 @@
+import React, { useState } from 'react';
+import { Pressable, Text, View, Animated, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_SPACING, DS_RADIUS, DS_SHADOW, DS_TYPOGRAPHY, DS_A11Y_MIN_TOUCH_TARGET } from '../../tokens';
+import { useSlideAnim } from '../SegmentedToggle/useSlideAnim';
+import { usePressScale } from '../Radio/usePressScale';
+
+export interface SwitchProps {
+  /** Whether the switch is on. */
+  value: boolean;
+  /** Called with the new value on tap. */
+  onValueChange: (value: boolean) => void;
+  /** Optional inline label rendered to the left of the track, at the same bodyMd size/weight
+   *  Checkbox/Radio use for their own labels — tapping it toggles the switch too. */
+  label?: string;
+  /** Non-interactive, dimmed. */
+  disabled?: boolean;
+  /** Accessible name. Defaults to `label` when set — pass this separately only when the switch
+   *  needs a different (or the only) spoken name, e.g. no visible label at all. */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+const TRACK_WIDTH = 51;
+const TRACK_HEIGHT = 31;
+// Sized so (TRACK_HEIGHT - THUMB_SIZE) / 2 lands on 4 — the same total inset SegmentedToggle's own
+// thumb gets (its TRACK_PADDING + THUMB_INSET, both DS_SPACING[100]) — so the two sliding controls'
+// thumbs read with the same amount of breathing room around them.
+const THUMB_SIZE = 23;
+// Horizontal inset for the thumb's off/on positions — matched to the vertical gap the track's own
+// `justifyContent: 'center'` already gives it ((TRACK_HEIGHT - THUMB_SIZE) / 2 = 4), so the padding
+// around the thumb reads as an even ring on every side, not tighter left/right than top/bottom.
+const THUMB_INSET = (TRACK_HEIGHT - THUMB_SIZE) / 2;
+// Pads the tappable area vertically out to the accessibility minimum — same reasoning as Button's
+// own `iconOnlyHitSlop`. TRACK_WIDTH (51) already clears the minimum horizontally, so only the
+// vertical sides need it.
+const HIT_SLOP = {
+  top: Math.ceil((DS_A11Y_MIN_TOUCH_TARGET - TRACK_HEIGHT) / 2),
+  bottom: Math.ceil((DS_A11Y_MIN_TOUCH_TARGET - TRACK_HEIGHT) / 2),
+};
+
+/**
+ * A boolean on/off toggle. The thumb slides between its two resting positions and the track fades
+ * between its off/on colours together, driven by the same shared slide animation SegmentedToggle and
+ * UnderlineTabs use (JS-driven here, since the track colour crossfade needs it) for a consistent
+ * motion feel across the DS's sliding controls. The thumb also grows slightly while pressed, for
+ * tactile feedback before release. Kept on the same JS-driven pipeline as the slide/colour (not
+ * `useNativeDriver: true`) — mixing native- and JS-driven animations on the same Animated.View's
+ * transform is unreliable in RN, and this component's slide already has to be JS-driven anyway.
+ */
+export function Switch({ value, onValueChange, label, disabled = false, accessibilityLabel, style }: SwitchProps) {
+  const anim = useSlideAnim(value ? 1 : 0, false);
+  const { pressScale, onPressIn, onPressOut } = usePressScale(disabled);
+  const [focused, setFocused] = useState(false);
+
+  const trackColor = anim.interpolate({
+    inputRange: [0, 1],
+    outputRange: [DS_SEMANTIC.surface.recessed, DS_SEMANTIC.emphasis.positive],
+  });
+  const thumbX = anim.interpolate({
+    inputRange: [0, 1],
+    outputRange: [THUMB_INSET, TRACK_WIDTH - THUMB_SIZE - THUMB_INSET],
+  });
+
+  return (
+    <Pressable
+      onPress={() => !disabled && onValueChange(!value)}
+      onPressIn={onPressIn}
+      onPressOut={onPressOut}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+      disabled={disabled}
+      accessibilityRole="switch"
+      accessibilityState={{ checked: value, disabled }}
+      accessibilityLabel={accessibilityLabel ?? label}
+      hitSlop={HIT_SLOP}
+      style={[styles.row, disabled && styles.disabled, style]}
+    >
+      {/* Label sits before the track (unlike Checkbox/Radio's control-then-label) — matches the
+          near-universal settings-row convention (description left, toggle right), while still
+          sharing their bodyMd label typography. */}
+      {!!label && <Text style={styles.label}>{label}</Text>}
+      <Animated.View style={[styles.track, { backgroundColor: trackColor }]}>
+        <Animated.View style={[styles.thumb, { transform: [{ translateX: thumbX }, { scale: pressScale }] }]} />
+        {/* Keyboard-focus ring — same interaction.focused treatment Button/Pill use; a zero-layout
+            absolute overlay so focusing never shifts layout. */}
+        {focused && !disabled && <View pointerEvents="none" style={styles.focusRing} />}
+      </Animated.View>
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: DS_SPACING[400],
+  },
+  label: {
+    ...DS_TYPOGRAPHY.bodyMd,
+    color: DS_SEMANTIC.text.regular,
+  },
+  track: {
+    width: TRACK_WIDTH,
+    height: TRACK_HEIGHT,
+    borderRadius: DS_RADIUS.round,
+    justifyContent: 'center',
+  },
+  thumb: {
+    width: THUMB_SIZE,
+    height: THUMB_SIZE,
+    borderRadius: DS_RADIUS.round,
+    backgroundColor: DS_SEMANTIC.surface.white,
+    ...DS_SHADOW.resting,
+  },
+  disabled: {
+    opacity: DS_SEMANTIC.interaction.disabledOpacity,
+  },
+  // 2px air + 2px ring outside the track; fully round to stay concentric.
+  focusRing: {
+    position: 'absolute',
+    top: -4,
+    bottom: -4,
+    left: -4,
+    right: -4,
+    borderWidth: 2,
+    borderColor: DS_SEMANTIC.interaction.focused,
+    borderRadius: DS_RADIUS.round,
+  },
+});

package/starter-kit/components/Switch/index.ts

@@ -0,0 +1,2 @@
+export { Switch } from './Switch';
+export type { SwitchProps } from './Switch';

package/starter-kit/components/TextArea/TextArea.catalog.tsx

@@ -0,0 +1,29 @@
+import React, { useState } from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { TextArea } from './TextArea';
+
+function TextAreaDemo() {
+  const [value, setValue] = useState('');
+  return <TextArea value={value} onChangeText={setValue} placeholder="Describe the issue…" />;
+}
+
+export default defineCatalogPage({
+  component: 'TextArea',
+  group: 'Inputs',
+  description: 'A multi-line input that grows with its content from a minimum height.',
+  a11y: 'A multiline TextInput; pass accessibilityLabel via inputProps when there is no visible label beside it.',
+  variants: {
+    itemsFill: true,
+    items: [{ key: 'default', name: 'Default', node: <TextAreaDemo /> }],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'disabled',
+        name: 'Disabled',
+        node: <TextArea value="This report has already been submitted." onChangeText={() => {}} editable={false} />,
+      },
+    ],
+  },
+});

package/starter-kit/components/TextArea/TextArea.tsx

@@ -0,0 +1,99 @@
+import React, { useCallback, useState } from 'react';
+import {
+  TextInput,
+  StyleSheet,
+  type StyleProp,
+  type ViewStyle,
+  type TextInputProps,
+} from 'react-native';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../../tokens';
+import { FieldContainer } from '../FieldContainer';
+
+export interface TextAreaProps {
+  /** Current text. */
+  value: string;
+  /** Change handler. */
+  onChangeText: (text: string) => void;
+  /** Shown when empty. */
+  placeholder?: string;
+  /** Min height of the field before it grows with content (default 96). */
+  minHeight?: number;
+  editable?: boolean;
+  autoFocus?: boolean;
+  inputRef?: React.Ref<TextInput>;
+  style?: StyleProp<ViewStyle>;
+  /** Extra TextInput props (e.g. maxLength, accessibilityLabel, onFocus). */
+  inputProps?: Omit<
+    TextInputProps,
+    'value' | 'onChangeText' | 'placeholder' | 'editable' | 'multiline' | 'autoFocus'
+  >;
+}
+
+/**
+ * A multiline free-text field — built on {@link FieldContainer} (white surface, medium radius, border
+ * that darkens on focus) with top-aligned text that grows from `minHeight`. For single-line labelled
+ * rows use {@link InputField} — both share the same FieldContainer chrome.
+ */
+export function TextArea({
+  value,
+  onChangeText,
+  placeholder,
+  minHeight = 96,
+  editable = true,
+  autoFocus = false,
+  inputRef,
+  style,
+  inputProps,
+}: TextAreaProps) {
+  const [focused, setFocused] = useState(false);
+
+  const handleFocus = useCallback(
+    (e: Parameters<NonNullable<TextInputProps['onFocus']>>[0]) => {
+      setFocused(true);
+      inputProps?.onFocus?.(e);
+    },
+    [inputProps],
+  );
+  const handleBlur = useCallback(
+    (e: Parameters<NonNullable<TextInputProps['onBlur']>>[0]) => {
+      setFocused(false);
+      inputProps?.onBlur?.(e);
+    },
+    [inputProps],
+  );
+
+  return (
+    <FieldContainer focused={focused} disabled={!editable} style={style}>
+      <TextInput
+        {...inputProps}
+        ref={inputRef}
+        style={[styles.input, { minHeight }, !editable && styles.inputDisabled]}
+        value={value}
+        onChangeText={onChangeText}
+        placeholder={placeholder}
+        placeholderTextColor={editable ? DS_SEMANTIC.text.muted : DS_SEMANTIC.text.disabled}
+        editable={editable}
+        autoFocus={autoFocus}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        multiline
+        textAlignVertical="top"
+      />
+    </FieldContainer>
+  );
+}
+
+const styles = StyleSheet.create({
+  // The chrome (surface/border/radius) lives on FieldContainer; the input owns the text style + padding
+  // so a tap anywhere over the padded area still focuses it.
+  input: {
+    ...DS_TYPOGRAPHY.bodySm,
+    color: DS_SEMANTIC.text.regular,
+    padding: DS_SPACING[400],
+  },
+  // A step lighter than the hint tone so a non-editable area reads as inactive, not just filled —
+  // same convention as InputField/SearchField (see DS_SEMANTIC.text.disabled's own doc comment).
+  inputDisabled: {
+    color: DS_SEMANTIC.text.disabled,
+  },
+});

package/starter-kit/components/TextArea/index.ts

@@ -0,0 +1,2 @@
+export { TextArea } from './TextArea';
+export type { TextAreaProps } from './TextArea';