@krapwoo/ds-viewer 0.1.1 → 0.2.0

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

@@ -0,0 +1,91 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { PillRow } from './PillRow';
+
+export default defineCatalogPage({
+  component: 'PillRow',
+  group: 'Actions',
+  description: 'A horizontally-scrolling row of Pill chips, with an optional trailing icon-only add pill — keeps the selected pill scrolled into view automatically.',
+  whenToUse: 'A scrollable row of selection chips (e.g. saved-place shortcuts) — for a fixed row of action buttons instead, use ButtonGroup.',
+  a11y: 'The row itself carries no accessibility role; each Pill (including the add pill) keeps its own accessibilityLabel/role from the Pill component.',
+  variants: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'few',
+        name: 'Few pills',
+        node: (
+          <PillRow
+            pills={[
+              { id: 'home', label: 'Home', variant: 'selected', iconName: 'home' },
+              { id: 'work', label: 'Work', variant: 'not_selected', iconName: 'briefcase' },
+            ]}
+          />
+        ),
+      },
+      {
+        key: 'many',
+        name: 'Many pills (scrollable)',
+        node: (
+          <PillRow
+            pills={[
+              { id: 'home', label: 'Home', variant: 'not_selected', iconName: 'home' },
+              { id: 'work', label: 'Work', variant: 'selected', iconName: 'briefcase' },
+              { id: 'gym', label: 'Gym', variant: 'not_selected', iconName: 'map' },
+              { id: 'saved', label: 'Saved', variant: 'not_selected', iconName: 'bell' },
+              { id: 'nearby', label: 'Nearby', variant: 'not_selected', iconName: 'pin' },
+              { id: 'recent', label: 'Recent', variant: 'not_selected', iconName: 'clock' },
+            ]}
+          />
+        ),
+      },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'no-add',
+        name: 'No add pill',
+        props: { showAddPill: false },
+        node: (
+          <PillRow
+            showAddPill={false}
+            pills={[
+              { id: 'home', label: 'Home', variant: 'selected', iconName: 'home' },
+              { id: 'work', label: 'Work', variant: 'not_selected', iconName: 'briefcase' },
+            ]}
+          />
+        ),
+      },
+      {
+        key: 'add-selected',
+        name: 'Add pill selected',
+        props: { addSelected: true },
+        node: (
+          <PillRow
+            addSelected
+            pills={[
+              { id: 'home', label: 'Home', variant: 'not_selected', iconName: 'home' },
+              { id: 'work', label: 'Work', variant: 'not_selected', iconName: 'briefcase' },
+            ]}
+          />
+        ),
+      },
+      {
+        key: 'min-width',
+        name: 'Minimum pill width',
+        props: { minPillWidth: 96 },
+        node: (
+          <PillRow
+            minPillWidth={96}
+            pills={[
+              { id: 'home', label: 'Home', variant: 'selected', iconName: 'home' },
+              { id: 'work', label: 'Work', variant: 'not_selected', iconName: 'briefcase' },
+            ]}
+          />
+        ),
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,140 @@
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+import { ScrollView, View, StyleSheet, type LayoutChangeEvent } from 'react-native';
+import { DS_SPACING } from '../../tokens';
+import { Pill } from '../Pill';
+import type { PillRowItem, PillRowProps } from './PillRow.types';
+
+const GAP = DS_SPACING[600];
+
+const DEFAULT_PILLS: NonNullable<PillRowProps['pills']> = [
+  { id: 'home', label: 'Home', variant: 'selected', iconName: 'home' },
+  { id: 'work', label: 'Work', variant: 'not_selected', iconName: 'briefcase' },
+];
+
+/**
+ * A horizontally-scrolling row of Pills with an optional trailing icon-only add pill. Keeps the
+ * selected pill scrolled into view, and resets to the start when the pill set genuinely changes.
+ */
+export function PillRow({
+  pills: pillsProp,
+  showAddPill = true,
+  minPillWidth = 0,
+  onAddPress,
+  addSelected = false,
+  style,
+  trailing,
+}: PillRowProps) {
+  const pills = pillsProp ?? DEFAULT_PILLS;
+  const idsKey = pills.map(p => p.id).join('|');
+
+  const scrollRef = useRef<ScrollView>(null);
+  const scrollXRef = useRef(0);
+  // Laid-out position of each pill (x within the scroll content + width), kept for scroll-into-view.
+  const posRef = useRef<Map<string, { x: number; width: number }>>(new Map());
+  const [viewportW, setViewportW] = useState(0);
+
+  const onPillLayout = (id: string, e: LayoutChangeEvent) => {
+    const { x, width } = e.nativeEvent.layout;
+    posRef.current.set(id, { x, width });
+  };
+
+  // A genuinely different set of pills (not just a selection change within the same set) forgets
+  // wherever the row was scrolled to and starts back at the beginning — otherwise a stale scroll
+  // offset or a stale cached position from the PREVIOUS pill set could carry over onto this one.
+  useEffect(() => {
+    posRef.current.clear();
+    scrollRef.current?.scrollTo({ x: 0, animated: false });
+  }, [idsKey]);
+
+  // Keep the selected pill fully in view. The selected pill is the one with variant 'selected', or the
+  // add pill (tracked under '__add__') when it's selected. Re-runs whenever the selection or the layout
+  // changes; deferred a frame so positions are fresh after a layout change.
+  const selectedId = useMemo(
+    () => (addSelected ? '__add__' : pills.find(p => p.variant === 'selected')?.id),
+    [addSelected, pills],
+  );
+  useEffect(() => {
+    if (!selectedId || viewportW <= 0) return;
+    const raf = requestAnimationFrame(() => {
+      const pos = posRef.current.get(selectedId);
+      if (!pos) return;
+      const left = scrollXRef.current;
+      const right = left + viewportW;
+      if (pos.x < left) {
+        scrollRef.current?.scrollTo({ x: Math.max(0, pos.x - GAP), animated: true });
+      } else if (pos.x + pos.width > right) {
+        scrollRef.current?.scrollTo({ x: pos.x + pos.width - viewportW + GAP, animated: true });
+      }
+    });
+    return () => cancelAnimationFrame(raf);
+  }, [selectedId, viewportW, idsKey]);
+
+  // `minPillWidth` is applied as a floor (`minWidth`) so each pill grows to fit its own label (never
+  // truncates) while short labels still hold the minimum.
+  const pillStyle = minPillWidth > 0 ? { minWidth: minPillWidth } : undefined;
+
+  const renderPill = (pill: PillRowItem) => (
+    <View key={pill.id} onLayout={e => onPillLayout(pill.id, e)}>
+      <Pill
+        label={pill.label}
+        variant={pill.variant}
+        showText={pill.showText}
+        iconName={pill.iconName}
+        iconSize={pill.iconSize}
+        icon={pill.icon}
+        onPress={pill.onPress}
+        disabled={pill.disabled}
+        loading={pill.loading}
+        accessibilityLabel={pill.accessibilityLabel}
+        style={pillStyle}
+      />
+    </View>
+  );
+
+  return (
+    <ScrollView
+      ref={scrollRef}
+      horizontal
+      showsHorizontalScrollIndicator={false}
+      // `style` (the ScrollView's OWN box, not its scrollable content) needs an explicit bound —
+      // without it, react-native-web sizes the scroll viewport to hug its content instead of the
+      // width its parent actually gives it, so it never overflows and never becomes swipable at
+      // all (a wide pill set just spills past the layout silently). `contentContainerStyle` is a
+      // separate thing: the inner row that's *allowed* to be wider than the viewport.
+      style={styles.scrollView}
+      contentContainerStyle={[styles.row, style]}
+      onLayout={e => setViewportW(e.nativeEvent.layout.width)}
+      onScroll={e => {
+        scrollXRef.current = e.nativeEvent.contentOffset.x;
+      }}
+      scrollEventThrottle={16}
+    >
+      {pills.map(renderPill)}
+      {showAddPill && (
+        // Record the add pill's position (under '__add__') so it can be scrolled into view when
+        // selected — tracked separately from `pills` since it's rendered outside that list.
+        <View onLayout={e => onPillLayout('__add__', e)}>
+          <Pill
+            variant={addSelected ? 'selected' : 'not_selected'}
+            showText={false}
+            iconName="pencil"
+            accessibilityLabel="Edit"
+            onPress={onAddPress}
+          />
+        </View>
+      )}
+      {trailing}
+    </ScrollView>
+  );
+}
+
+const styles = StyleSheet.create({
+  scrollView: { width: '100%' },
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: DS_SPACING[600],
+    minHeight: DS_SPACING[2400],
+    paddingVertical: DS_SPACING[200],
+  },
+});

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

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { PillProps } from '../Pill';
+
+export interface PillRowItem extends Omit<PillProps, 'style'> {
+  id: string;
+}
+
+export interface PillRowProps {
+  /** Pills to render — each is a Pill's own props plus an id. Defaults to a two-item Home/Work
+   *  sample. */
+  pills?: PillRowItem[];
+  /** Icon-only add/edit pill at the end of the row. */
+  showAddPill?: boolean;
+  /** Floor for the content pills' width (px). Excludes the icon-only add pill so it stays circular. */
+  minPillWidth?: number;
+  /** Tap handler for the add pill. */
+  onAddPress?: () => void;
+  /** Render the add pill in the selected state. */
+  addSelected?: boolean;
+  style?: StyleProp<ViewStyle>;
+  /** Custom trailing content instead of the add pill. */
+  trailing?: ReactNode;
+}

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

@@ -0,0 +1,2 @@
+export { PillRow } from './PillRow';
+export type { PillRowProps, PillRowItem } from './PillRow.types';

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

@@ -0,0 +1,22 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { ProgressDots } from './ProgressDots';
+
+export default defineCatalogPage({
+  component: 'ProgressDots',
+  group: 'Feedback',
+  description: 'A row of dots for a stepped flow; the active dot widens into a pill.',
+  a11y: 'Decorative progress indicator; convey the "step X of Y" position in text for screen readers.',
+  // No `variant` prop exists on ProgressDots — its "Variants" column just shows the one default
+  // look; `active`'s different positions are progress states, covered under "States".
+  variants: {
+    items: [{ key: 'default', name: 'Default', node: <ProgressDots active={1} total={4} /> }],
+  },
+  states: {
+    items: [
+      { key: 'first', name: 'First step', node: <ProgressDots active={0} total={4} /> },
+      { key: 'middle', name: 'Middle step', node: <ProgressDots active={2} total={4} /> },
+      { key: 'last', name: 'Last step', node: <ProgressDots active={3} total={4} /> },
+    ],
+  },
+});

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

@@ -0,0 +1,42 @@
+import React from 'react';
+import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_SPACING } from '../../tokens';
+
+export interface ProgressDotsProps {
+  /** 0-based index of the current step. The active dot widens into a pill. */
+  active: number;
+  /** Total number of steps (dots). */
+  total?: number;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Step progress indicator — a row of dots where the current step is a widened pill.
+ */
+export function ProgressDots({ active, total = 6, style }: ProgressDotsProps) {
+  return (
+    <View
+      style={[styles.row, style]}
+      accessible
+      accessibilityRole="progressbar"
+      accessibilityLabel={`Step ${active + 1} of ${total}`}
+      accessibilityValue={{ min: 1, max: total, now: active + 1 }}
+    >
+      {Array.from({ length: total }).map((_, i) => (
+        <View key={i} style={[styles.dot, i === active && styles.dotActive]} />
+      ))}
+    </View>
+  );
+}
+
+// 7px is intentionally smaller than DS_SPACING[400]=8px — optical correction for small dots.
+const DOT_H = 7;
+const DOT_PILL_W = 20;
+const DOT_RADIUS = 4;
+
+const styles = StyleSheet.create({
+  row: { flexDirection: 'row', justifyContent: 'center', alignItems: 'center', gap: DS_SPACING[200] },
+  dot: { width: DOT_H, height: DOT_H, borderRadius: DOT_RADIUS, backgroundColor: DS_SEMANTIC.border.subtle },
+  // surface.inverse, not text.regular — a dark FILL, not ink (same reasoning as Pill/Toast).
+  dotActive: { width: DOT_PILL_W, borderRadius: DOT_RADIUS, backgroundColor: DS_SEMANTIC.surface.inverse },
+});

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

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

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

@@ -0,0 +1,38 @@
+import React, { useState } from 'react';
+import { View, StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Radio } from './Radio';
+import { DS_SPACING } from '../../tokens';
+
+const styles = StyleSheet.create({
+  radioGroup: { gap: DS_SPACING[600], alignItems: 'flex-start' },
+});
+
+function RadioGroupDemo() {
+  const [value, setValue] = useState('uptown');
+  return (
+    <View style={styles.radioGroup}>
+      <Radio selected={value === 'uptown'} onPress={() => setValue('uptown')} label="Uptown & The Bronx" />
+      <Radio selected={value === 'downtown'} onPress={() => setValue('downtown')} label="Downtown & Brooklyn" />
+    </View>
+  );
+}
+
+export default defineCatalogPage({
+  component: 'Radio',
+  group: 'Controls',
+  specimenSize: 'compact',
+  description: 'A single circular selection control — a filled dot appears in the ring when selected. A group of mutually-exclusive Radios is just multiple instances sharing one selected value in the consumer.',
+  whenToUse: 'One selection from a mutually-exclusive set — checking one should un-check another. For an independent on/off fact, use Checkbox; for a setting that takes effect immediately, use Switch.',
+  a11y: 'Renders a Pressable with accessibilityRole="radio" and accessibilityState.selected; the optional label doubles as its accessibilityLabel.',
+  variants: {
+    items: [{ key: 'default', name: 'Default (tap to select)', node: <RadioGroupDemo /> }],
+  },
+  states: {
+    items: [
+      { key: 'unselected', name: 'Unselected', node: <Radio selected={false} onPress={() => {}} label="Uptown & The Bronx" /> },
+      { key: 'selected', name: 'Selected', node: <Radio selected={true} onPress={() => {}} label="Uptown & The Bronx" /> },
+      { key: 'disabled', name: 'Disabled', node: <Radio selected={true} onPress={() => {}} disabled label="Uptown & The Bronx" /> },
+    ],
+  },
+});

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

@@ -0,0 +1,114 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { Pressable, Text, View, Animated, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_SPACING, DS_RADIUS, DS_TYPOGRAPHY, DS_A11Y_MIN_TOUCH_TARGET, DS_MOTION_DURATION } from '../../tokens';
+import { usePressScale } from './usePressScale';
+
+export interface RadioProps {
+  /** Whether this radio is the selected one. */
+  selected: boolean;
+  /** Tap handler — select this option in the consumer's state. */
+  onPress: () => void;
+  /** Optional inline label rendered to the right of the circle. */
+  label?: string;
+  /** Non-interactive, dimmed. */
+  disabled?: boolean;
+  style?: StyleProp<ViewStyle>;
+}
+
+const CIRCLE_SIZE = 20;
+const DOT_SIZE = 10;
+// Pads the tappable area out to the accessibility minimum without growing the visual circle — same
+// reasoning as Button's own `iconOnlyHitSlop`. Applied on all sides since a no-label Radio's row is
+// exactly CIRCLE_SIZE tall/wide; a labelled row is already wider, where the extra hitSlop is
+// harmless overlap into surrounding whitespace rather than another control.
+const HIT_SLOP = Math.max(0, Math.ceil((DS_A11Y_MIN_TOUCH_TARGET - CIRCLE_SIZE) / 2));
+
+/**
+ * A single circular selection control — a filled dot appears in the ring when selected. A group of
+ * mutually-exclusive Radios is just multiple instances sharing one "selected value" in the consumer
+ * (the same way a native radio group works); this component itself only knows its own selected state.
+ * The circle grows slightly while pressed, for tactile feedback before release, and the dot itself
+ * pops in/out (scale + opacity) rather than snapping — both kept JS-driven (`useNativeDriver: false`)
+ * for the same Fabric-safety reason.
+ */
+export function Radio({ selected, onPress, label, disabled = false, style }: RadioProps) {
+  const { pressScale, onPressIn, onPressOut } = usePressScale(disabled);
+  const dotAnim = useRef(new Animated.Value(selected ? 1 : 0)).current;
+  const [focused, setFocused] = useState(false);
+
+  useEffect(() => {
+    Animated.timing(dotAnim, {
+      toValue: selected ? 1 : 0,
+      duration: DS_MOTION_DURATION.fast,
+      useNativeDriver: false,
+    }).start();
+  }, [selected, dotAnim]);
+
+  return (
+    <Pressable
+      onPress={() => !disabled && onPress()}
+      onPressIn={onPressIn}
+      onPressOut={onPressOut}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+      disabled={disabled}
+      accessibilityRole="radio"
+      accessibilityState={{ selected, disabled }}
+      accessibilityLabel={label}
+      hitSlop={HIT_SLOP}
+      style={[styles.row, disabled && styles.disabled, style]}
+    >
+      <Animated.View style={[styles.circle, selected && styles.circleSelected, { transform: [{ scale: pressScale }] }]}>
+        <Animated.View style={[styles.dot, { opacity: dotAnim, transform: [{ scale: dotAnim }] }]} />
+        {/* 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>
+      {!!label && <Text style={styles.label}>{label}</Text>}
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: DS_SPACING[400],
+  },
+  circle: {
+    width: CIRCLE_SIZE,
+    height: CIRCLE_SIZE,
+    borderRadius: DS_RADIUS.round,
+    borderWidth: 2,
+    borderColor: DS_SEMANTIC.border.dark,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  circleSelected: {
+    borderColor: DS_SEMANTIC.emphasis.info,
+  },
+  dot: {
+    width: DOT_SIZE,
+    height: DOT_SIZE,
+    borderRadius: DS_RADIUS.round,
+    backgroundColor: DS_SEMANTIC.emphasis.info,
+  },
+  label: {
+    ...DS_TYPOGRAPHY.bodyMd,
+    color: DS_SEMANTIC.text.regular,
+  },
+  disabled: {
+    opacity: DS_SEMANTIC.interaction.disabledOpacity,
+  },
+  // 2px air + 2px ring outside the circle; 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/Radio/index.ts

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

package/starter-kit/components/Radio/usePressScale.ts

@@ -0,0 +1,33 @@
+import { useEffect, useRef, useState } from 'react';
+import { Animated } from 'react-native';
+import { DS_MOTION_DURATION } from '../../tokens';
+
+/** How much a control's own touchable grows while pressed. */
+export const PRESS_SCALE = 1.15;
+
+/**
+ * Shared by Radio, Checkbox, and Switch: "grow slightly while pressed, before release" tactile
+ * feedback — the exact same state/animation mechanics were previously copy-pasted verbatim across
+ * all three. `disabled` controls are inert; `onPressIn` won't start the grow for them (a disabled
+ * control has no interaction to give feedback about).
+ */
+export function usePressScale(disabled: boolean) {
+  const [pressed, setPressed] = useState(false);
+  const pressScale = useRef(new Animated.Value(1)).current;
+
+  useEffect(() => {
+    Animated.timing(pressScale, {
+      toValue: pressed ? PRESS_SCALE : 1,
+      // Grow-in at 100ms — deliberately snappier than any duration token (press feedback must feel
+      // instant under the finger); the release settles at the standard fast duration.
+      duration: pressed ? 100 : DS_MOTION_DURATION.fast,
+      useNativeDriver: false,
+    }).start();
+  }, [pressed, pressScale]);
+
+  return {
+    pressScale,
+    onPressIn: () => !disabled && setPressed(true),
+    onPressOut: () => setPressed(false),
+  };
+}

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

@@ -0,0 +1,28 @@
+import React, { useState } from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { SearchField } from './SearchField';
+
+function SearchFieldDemo() {
+  const [value, setValue] = useState('');
+  return <SearchField value={value} onChangeText={setValue} placeholder="Search stations" />;
+}
+
+export default defineCatalogPage({
+  component: 'SearchField',
+  group: 'Inputs',
+  description: 'Single-line search input on the shared field chrome — leading search icon, a border that darkens on focus, and a clear button while active with text.',
+  whenToUse: 'Free-text filtering/searching only — never a named field with a fixed value. For that, use InputField; for a small known set of choices, use Dropdown.',
+  a11y: 'Forwards a ref to the underlying TextInput; all TextInputProps pass through, so pass accessibilityLabel/placeholder as needed.',
+  variants: {
+    itemsFill: true,
+    items: [{ key: 'default', name: 'Default (type to see clear button)', node: <SearchFieldDemo /> }],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      { key: 'empty', name: 'Empty', node: <SearchField value="" onChangeText={() => {}} placeholder="Search stations" /> },
+      { key: 'filled', name: 'With value', node: <SearchField value="Union Sq" onChangeText={() => {}} /> },
+      { key: 'disabled', name: 'Disabled', node: <SearchField value="" onChangeText={() => {}} placeholder="Search stations" disabled /> },
+    ],
+  },
+});

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

@@ -0,0 +1,98 @@
+import React, { forwardRef, useState } from 'react';
+import {
+  TextInput,
+  StyleSheet,
+  Platform,
+  type TextInputProps,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+import { FieldContainer } from '../FieldContainer';
+import { InputClearButton } from '../InputClearButton';
+import { Icon } from '../../icons/Icon.native';
+import type { IconName } from '../../icons';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY, DS_ICON_SIZE } from '../../tokens';
+
+export interface SearchFieldProps extends TextInputProps {
+  /** Leading icon (defaults to the search glyph). */
+  iconName?: IconName;
+  /** Extra layout applied to the field container (e.g. margins). */
+  containerStyle?: StyleProp<ViewStyle>;
+  /** Disabled state — dimmed icon/text (a step past the hint/placeholder tone, so it reads as
+   *  inactive rather than merely empty), non-interactive. Forces the field non-editable regardless
+   *  of `editable`, matching InputField/TextArea. */
+  disabled?: boolean;
+}
+
+/**
+ * Single-line search input on the shared field chrome ({@link FieldContainer}): white fill, medium
+ * radius, a 1px subtle border that **darkens to border.dark on focus**, 56px tall, with a leading search
+ * icon. While the field is active (focused with text) a **clear (×) button** appears on the right and
+ * wipes the input on tap. Forwards a ref to the underlying TextInput; all `TextInputProps` pass through.
+ * Works controlled (`value` + `onChangeText`) or uncontrolled (`defaultValue`). Pick one mode per
+ * mounted instance and stick with it.
+ */
+export const SearchField = forwardRef<TextInput, SearchFieldProps>(function SearchField(
+  { iconName = 'search', containerStyle, style, value, defaultValue, onChangeText, onFocus, onBlur, disabled = false, editable, ...rest },
+  ref,
+) {
+  const isControlled = value !== undefined;
+  const [internal, setInternal] = useState(defaultValue ?? '');
+  const [focused, setFocused] = useState(false);
+  const text = isControlled ? value : internal;
+
+  const change = (t: string) => {
+    if (!isControlled) setInternal(t);
+    onChangeText?.(t);
+  };
+
+  const showClear = !disabled && focused && !!text && text.length > 0;
+
+  return (
+    <FieldContainer focused={focused} disabled={disabled} style={[styles.container, containerStyle]}>
+      <Icon
+        name={iconName}
+        size={DS_ICON_SIZE.sm}
+        color={disabled ? DS_SEMANTIC.text.disabled : focused ? DS_SEMANTIC.text.regular : DS_SEMANTIC.text.muted}
+      />
+      <TextInput
+        ref={ref}
+        style={[styles.input, disabled && styles.inputDisabled, style]}
+        placeholderTextColor={disabled ? DS_SEMANTIC.text.disabled : DS_SEMANTIC.text.muted}
+        value={text}
+        onChangeText={change}
+        onFocus={(e) => { setFocused(true); onFocus?.(e); }}
+        onBlur={(e) => { setFocused(false); onBlur?.(e); }}
+        editable={disabled ? false : editable}
+        {...rest}
+      />
+      {showClear ? <InputClearButton onPress={() => change('')} accessibilityLabel="Clear search" /> : null}
+    </FieldContainer>
+  );
+});
+
+const styles = StyleSheet.create({
+  container: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: DS_SPACING[800],
+    height: DS_SPACING[2800],
+    paddingHorizontal: DS_SPACING[800],
+  },
+  input: {
+    flex: 1,
+    minWidth: 0,
+    // Just the token's size, not the full bodyMd (a TextInput mishandles lineHeight's vertical centering).
+    fontSize: DS_TYPOGRAPHY.bodyMd.fontSize,
+    color: DS_SEMANTIC.text.regular,
+    padding: 0,
+    margin: 0,
+    includeFontPadding: false,
+    ...Platform.select({ android: { textAlignVertical: 'center' as const }, default: {} }),
+  },
+  // A step lighter than the placeholder's muted tone — see DS_SEMANTIC.text.disabled's own doc
+  // comment on why disabled text shouldn't just reuse the hint color.
+  inputDisabled: {
+    color: DS_SEMANTIC.text.disabled,
+  },
+});

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

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