@krapwoo/ds-viewer 0.1.0 → 0.2.0

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';

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

@@ -0,0 +1,72 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { SectionHeader } from './SectionHeader';
+
+export default defineCatalogPage({
+  component: 'SectionHeader',
+  group: 'Layout',
+  description: 'An uppercase muted section label with an optional inline icon and a right-aligned ghost button.',
+  whenToUse: "A label above a group of related rows within a screen (e.g. above a List) — for the screen's own top bar, use TopNav.",
+  a11y: 'Title renders as plain Text — no heading role. A tappable labelIcon (onPress set) becomes accessibilityRole="button" with accessibilityLabel falling back to the section\'s own title; a non-interactive labelIcon has no accessibility node of its own. The trailing button is a real Button, so it carries Button\'s own accessibility for free.',
+  variants: {
+    itemsFill: true,
+    items: [
+      { key: 'title-only', name: 'Title only', node: <SectionHeader title="Nearby stations" /> },
+      {
+        key: 'with-icon',
+        name: 'With icon',
+        node: <SectionHeader title="Trip details" labelIcon={{ name: 'info-circle', accessibilityLabel: 'About trip details' }} />,
+      },
+      {
+        key: 'with-button',
+        name: 'With trailing button',
+        node: <SectionHeader title="Saved places" trailingButtonLabel="See all" onTrailingButtonPress={() => {}} />,
+      },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'tappable-icon',
+        name: 'Tappable icon',
+        node: (
+          <SectionHeader
+            title="Delays"
+            labelIcon={{ name: 'info-circle', onPress: () => {}, accessibilityLabel: 'What causes delays' }}
+          />
+        ),
+      },
+      {
+        key: 'icon-and-button',
+        name: 'Icon + trailing button',
+        // This instance demonstrates the 'trailing' (default) icon position — tagged so
+        // checkCompleteness sees both enum values covered, not just the 'leading' one below.
+        props: { trailingButtonIconPosition: 'trailing' },
+        node: (
+          <SectionHeader
+            title="Alerts"
+            labelIcon={{ name: 'bell' }}
+            trailingButtonLabel="Manage"
+            trailingButtonIconName="chevron-right"
+            onTrailingButtonPress={() => {}}
+          />
+        ),
+      },
+      {
+        key: 'leading-icon-position',
+        name: 'Trailing button, leading icon',
+        props: { trailingButtonIconPosition: 'leading' },
+        node: (
+          <SectionHeader
+            title="Saved places"
+            trailingButtonLabel="Add"
+            trailingButtonIconName="add"
+            trailingButtonIconPosition="leading"
+            onTrailingButtonPress={() => {}}
+          />
+        ),
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,139 @@
+import React, { useState } from 'react';
+import {
+  View,
+  Text,
+  Pressable,
+  StyleSheet,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY, DS_FONT_WEIGHT, DS_RADIUS } from '../../tokens';
+import { Icon } from '../../icons/Icon.native';
+import type { IconName } from '../../icons';
+import { Button } from '../Button';
+
+// Bumped up from the global 2px default — at this icon's small 16px render size, a default-weight
+// stroke reads noticeably thinner than the bold (semibold, uppercase) label text it sits beside;
+// this brings its visual weight in line with that text, the same reasoning Checkbox's own
+// thicker check icon uses for a small glyph that needs to read clearly next to bold UI.
+const LABEL_ICON_STROKE_WIDTH = 2.5;
+
+export interface SectionHeaderLabelIcon {
+  name: IconName;
+  /** Render size in points. Defaults to 16 — matching the trailing button's own small-size icon
+   *  (Button's `small` SIZE_TOKENS) and the row's own 16px line-height, so the row reads at a
+   *  consistent height whether the label icon or the trailing button is the one present. */
+  size?: number;
+  /** When provided the icon is wrapped in a Pressable; omit for a non-interactive decoration. */
+  onPress?: () => void;
+  accessibilityLabel?: string;
+}
+
+export interface SectionHeaderProps {
+  /** Section label text. */
+  title: string;
+  /**
+   * Icon shown right after the title text with a 4 px gap.
+   * Pass `onPress` to make it tappable (e.g. info); omit for a static decoration (e.g. pin).
+   */
+  labelIcon?: SectionHeaderLabelIcon;
+  /** Label for a right-aligned ghost button. */
+  trailingButtonLabel?: string;
+  /** Icon to show on the trailing button. */
+  trailingButtonIconName?: IconName;
+  /** Whether the icon appears before or after the button label (default: 'trailing'). */
+  trailingButtonIconPosition?: 'leading' | 'trailing';
+  /** Called when the trailing button is pressed. */
+  onTrailingButtonPress?: () => void;
+  style?: StyleProp<ViewStyle>;
+}
+
+/** An uppercase muted section label with an optional inline icon and a right-aligned ghost button. */
+export function SectionHeader({
+  title,
+  labelIcon,
+  trailingButtonLabel,
+  trailingButtonIconName,
+  trailingButtonIconPosition = 'trailing',
+  onTrailingButtonPress,
+  style,
+}: SectionHeaderProps) {
+  const [iconFocused, setIconFocused] = useState(false);
+  const iconEl = labelIcon ? (
+    labelIcon.onPress ? (
+      <Pressable
+        onPress={labelIcon.onPress}
+        onFocus={() => setIconFocused(true)}
+        onBlur={() => setIconFocused(false)}
+        // Pads the ~16px icon out to the 44pt touch-target minimum.
+        hitSlop={14}
+        accessibilityRole="button"
+        accessibilityLabel={labelIcon.accessibilityLabel ?? title}
+        // Keyboard focus shows the same highlight as a press (same policy as ListItem/SegmentedToggle).
+        style={({ pressed }) => [styles.labelIconPressable, (pressed || iconFocused) && styles.labelIconPressed]}
+      >
+        <Icon name={labelIcon.name} size={labelIcon.size ?? 16} color={DS_SEMANTIC.text.muted} strokeWidth={LABEL_ICON_STROKE_WIDTH} />
+      </Pressable>
+    ) : (
+      <Icon name={labelIcon.name} size={labelIcon.size ?? 16} color={DS_SEMANTIC.text.muted} strokeWidth={LABEL_ICON_STROKE_WIDTH} />
+    )
+  ) : null;
+
+  return (
+    <View style={[styles.container, style]}>
+      <View style={styles.left}>
+        <View style={styles.titleGroup}>
+          <Text style={styles.title} numberOfLines={1}>
+            {title}
+          </Text>
+          {iconEl}
+        </View>
+      </View>
+      {trailingButtonLabel ? (
+        <Button
+          label={trailingButtonLabel}
+          variant="ghost"
+          size="small"
+          showIcon={!!trailingButtonIconName}
+          iconName={trailingButtonIconName}
+          iconPosition={trailingButtonIconPosition}
+          onPress={onTrailingButtonPress}
+        />
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    width: '100%',
+  },
+  left: {
+    flex: 1,
+    flexDirection: 'row',
+    alignItems: 'center',
+  },
+  titleGroup: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: DS_SPACING[200],
+  },
+  title: {
+    fontSize: DS_TYPOGRAPHY.labelXs.fontSize,
+    fontWeight: DS_FONT_WEIGHT.semibold,
+    color: DS_SEMANTIC.text.muted,
+    textTransform: 'uppercase',
+    // Match the tallest trailing control (16px small button icon / labelIcon) so the row height is
+    // constant whether or not a button/icon is present — otherwise toggling them changes the header
+    // height and shifts the content beneath it.
+    lineHeight: 16,
+  },
+  labelIconPressable: {
+    borderRadius: DS_RADIUS.round,
+  },
+  labelIconPressed: {
+    backgroundColor: DS_SEMANTIC.interaction.pressed,
+  },
+});

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

@@ -0,0 +1,2 @@
+export { SectionHeader } from './SectionHeader';
+export type { SectionHeaderProps, SectionHeaderLabelIcon } from './SectionHeader';

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

@@ -0,0 +1,31 @@
+import React, { useState } from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { SegmentedToggle } from './SegmentedToggle';
+
+function SegmentedToggleDemo() {
+  const [value, setValue] = useState('map');
+  return (
+    <SegmentedToggle
+      value={value}
+      onChange={setValue}
+      options={[
+        { value: 'map', label: 'Map', iconName: 'map' },
+        { value: 'list', label: 'List', iconName: 'menu' },
+        { value: 'saved', label: 'Saved', iconName: 'bell', badge: 3 },
+        // Label-only segment (no iconName) — the layout every other option's icon would otherwise hide.
+        { value: 'settings', label: 'Settings' },
+      ]}
+    />
+  );
+}
+
+export default defineCatalogPage({
+  component: 'SegmentedToggle',
+  group: 'Selection',
+  // Phone width plus a small phone, where long labels truncate.
+  previewWidths: [402, 320],
+  description: 'A row of mutually-exclusive options on a recessed track, with a white thumb that slides to the selected segment. Two or more options.',
+  whenToUse: 'A filled, heavier-weight control for a primary, prominent choice on the screen. For quieter secondary navigation, use UnderlineTabs.',
+  a11y: 'The row is accessibilityRole="tablist"; each segment is a "tab" with accessibilityState.selected reflecting the current value.',
+  render: () => <SegmentedToggleDemo />,
+});