@krapwoo/ds-viewer 0.1.0 → 0.2.0

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

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

@@ -0,0 +1,61 @@
+import React, { useState } from 'react';
+import { View, StyleSheet } from 'react-native';
+import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
+import { Button } from '../Button';
+import { Toast } from './Toast';
+import { DS_SPACING } from '../../tokens';
+
+const styles = StyleSheet.create({
+  // Toast demo — floats the toast near the top of the PhoneFrame, the same way a real screen would
+  // position it (Toast itself renders no absolute overlay; that's always the call site's job).
+  toastDemoOverlay: { position: 'absolute', top: DS_SPACING[800], left: DS_SPACING[600], right: DS_SPACING[600] },
+});
+
+// Drives Toast's `visible` prop directly (rather than the usual mount/unmount-the-whole-component
+// pattern) so this demo actually exercises the slide-in-from-top/fade animation, not just the two
+// static end states.
+function ToastDemo() {
+  const [visible, setVisible] = useState(true);
+  return (
+    <PhoneFrame>
+      <Button label={visible ? 'Hide toast' : 'Show toast'} onPress={() => setVisible((v) => !v)} />
+      <View style={styles.toastDemoOverlay} pointerEvents="box-none">
+        <Toast message="Trip saved" variant="success" visible={visible} />
+      </View>
+    </PhoneFrame>
+  );
+}
+
+export default defineCatalogPage({
+  component: 'Toast',
+  group: 'Feedback',
+  description: 'A transient confirmation bar. Without a variant it renders the dark surface with inverse text; a variant shifts to a pastel status color.',
+  whenToUse: "Transient and self-contained, floating over the screen, expected to go away on its own or via its own action. For a persistent, in-flow message about a standing condition, use Banner.",
+  a11y: 'Rendered with accessibilityRole="alert" so screen readers announce it when it appears.',
+  variants: {
+    itemsFill: true,
+    items: [
+      { key: 'base', name: 'Base (no variant)', node: <Toast message="Changes saved" /> },
+      { key: 'success', name: 'Success', props: { variant: 'success' }, node: <Toast message="Trip saved" variant="success" /> },
+      { key: 'informational', name: 'Informational', props: { variant: 'informational' }, node: <Toast message="New app version available" variant="informational" /> },
+      { key: 'warning', name: 'Warning', props: { variant: 'warning' }, node: <Toast message="Signal delays reported" variant="warning" /> },
+      { key: 'negative', name: 'Negative', props: { variant: 'negative' }, node: <Toast message="Failed to save trip" variant="negative" /> },
+      { key: 'neutral', name: 'Neutral', props: { variant: 'neutral' }, node: <Toast message="3 new updates" variant="neutral" /> },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'action',
+        name: 'With action',
+        node: <Toast message="Trip removed" action={{ label: 'Undo', onPress: () => {} }} />,
+      },
+      {
+        key: 'visible-toggle',
+        name: 'Slide-in animation (toggle)',
+        node: <ToastDemo />,
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,144 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { View, Text, Animated, Easing, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_SPACING, DS_RADIUS, DS_TYPOGRAPHY, DS_FONT_WEIGHT, DS_SHADOW, DS_ICON_SIZE, DS_MOTION_DURATION, DS_MOTION_EASING } from '../../tokens';
+import { Icon } from '../../icons/Icon.native';
+import { Button } from '../Button';
+import type { IconName } from '../../icons';
+
+// Generously bigger than any real toast's rendered height, so the slide-in always starts fully
+// above the visible area regardless of message length — no onLayout measurement needed (unlike
+// Banner's collapse, this only needs "off-screen" vs "resting", not the real height).
+const ENTER_FROM_Y = -100;
+
+export type ToastVariant = 'success' | 'informational' | 'warning' | 'negative' | 'neutral';
+
+// Same light tinted fill + saturated foreground pairing as Banner/Badge, so a variant toast reads as
+// the same colour identity as the badge/banner of that status.
+const VARIANT_CONFIG: Record<ToastVariant, { bg: string; fg: string; icon: IconName }> = {
+  success:       { bg: DS_SEMANTIC.shade.positive, fg: DS_SEMANTIC.emphasis.positive, icon: 'circle-check'  },
+  informational: { bg: DS_SEMANTIC.shade.info,     fg: DS_SEMANTIC.emphasis.info,     icon: 'info'          },
+  warning:       { bg: DS_SEMANTIC.shade.warning,  fg: DS_SEMANTIC.emphasis.warning,  icon: 'triangle-alert'},
+  negative:      { bg: DS_SEMANTIC.shade.negative, fg: DS_SEMANTIC.emphasis.negative, icon: 'circle-slash'  },
+  neutral:       { bg: DS_SEMANTIC.shade.neutral,  fg: DS_SEMANTIC.emphasis.neutral,  icon: 'info-circle'   },
+};
+
+export interface ToastProps {
+  /** Toast text. */
+  message: string;
+  /** Whether the toast is mounted and shown — animates in by sliding down from above (+ fading in)
+   *  when it becomes true, and slides back out the same way when it becomes false. @default true
+   *  (renders already in its resting position, no animation — for call sites that mount/unmount the
+   *  whole Toast themselves rather than toggling this prop). */
+  visible?: boolean;
+  /** When set, applies one of the semantic colour schemes (bg + default icon). */
+  variant?: ToastVariant;
+  /** Override the icon. Defaults to the variant's icon, or `circle-check` for the base style. */
+  iconName?: IconName;
+  /** Override the icon colour. Defaults to the variant's emphasis colour for variant toasts, white (matching the text) for base. */
+  iconColor?: string;
+  /** Optional trailing action — e.g. "Undo". Colour-matched to the toast's own text/icon colour
+   *  (whichever that resolves to for the active variant), not a separate fixed accent. */
+  action?: { label: string; onPress: () => void };
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * A transient confirmation bar. Without `variant`, renders the default dark surface with inverse text.
+ * With `variant`, the background shifts to the same light tinted fill Banner/Badge use for that
+ * status, with the matching saturated emphasis colour for text/icon — not white. Slides in from
+ * above (+ fades in) when `visible` turns true, and reverses on the way out — the same
+ * measure-free, JS-driven (`useNativeDriver: false`, so it's visible in the web preview too, not
+ * just on native) enter/exit pattern Dialog/BottomSheet use for their own show/hide.
+ */
+export function Toast({ message, visible = true, variant, iconName, iconColor, action, style }: ToastProps) {
+  const [mounted, setMounted] = useState(visible);
+  const progress = useRef(new Animated.Value(visible ? 1 : 0)).current;
+
+  useEffect(() => {
+    if (visible) setMounted(true);
+    const duration = visible ? DS_MOTION_DURATION.base : DS_MOTION_DURATION.fast;
+    Animated.timing(progress, {
+      toValue: visible ? 1 : 0,
+      duration,
+      // `decelerate` — a toast entering the screen, per DS_MOTION_EASING_USE.
+      easing: Easing.bezier(...DS_MOTION_EASING.decelerate),
+      useNativeDriver: false,
+    }).start();
+    // A plain timer (not the animation's own `.start()` callback) drives the unmount-after-exit —
+    // `finished` can come back false (or the callback can simply not fire) when this Animated.Value
+    // is fighting for frames alongside other continuously-looping JS-driven animations elsewhere on
+    // the same screen (Loading, Shimmer), which left Toast permanently stuck invisible-but-mounted
+    // in exactly that scenario. A timer matching the animation's own duration is deterministic
+    // regardless of what the Animated internals do.
+    let hideTimer: ReturnType<typeof setTimeout> | undefined;
+    if (!visible) hideTimer = setTimeout(() => setMounted(false), duration);
+    return () => {
+      if (hideTimer != null) clearTimeout(hideTimer);
+    };
+  }, [visible, progress]);
+
+  if (!mounted) return null;
+
+  const cfg = variant ? VARIANT_CONFIG[variant] : null;
+  const resolvedIcon = iconName ?? cfg?.icon ?? 'circle-check';
+  // Message, icon (by default), and the action label all share this colour, so the whole bar reads
+  // as one consistent colour identity regardless of variant.
+  const resolvedTextColor = cfg ? cfg.fg : DS_SEMANTIC.text.inverse;
+  const resolvedIconColor = iconColor ?? resolvedTextColor;
+
+  const translateY = progress.interpolate({ inputRange: [0, 1], outputRange: [ENTER_FROM_Y, 0] });
+
+  return (
+    <Animated.View
+      style={[styles.toast, cfg && { backgroundColor: cfg.bg }, { opacity: progress, transform: [{ translateY }] }, style]}
+      accessibilityRole="alert"
+    >
+      <Icon name={resolvedIcon} size={DS_ICON_SIZE.sm} color={resolvedIconColor} />
+      <Text style={[styles.text, { color: resolvedTextColor }]} numberOfLines={2}>{message}</Text>
+      {action && (
+        <>
+          {/* A plain vertical rule tinted to resolvedTextColor at reduced opacity — not the shared
+              Divider component, which is a fixed subtle-black horizontal line meant for light
+              surfaces; Toast's own background can be dark (base) or a light tint (variant), so the
+              divider has to adapt to whichever text colour is active instead. */}
+          <View style={[styles.divider, { backgroundColor: resolvedTextColor }]} />
+          {/* Always ghost + label-only — Toast's action is a quiet inline affordance, never a second
+              visual weight competing with the message. Ghost's own padding is already 0, so it sits
+              flush like the rest of the row; textStyle overrides ghost's fixed label colour with
+              resolvedTextColor so the action still colour-matches this toast's own variant. */}
+          <Button variant="ghost" size="small" label={action.label} onPress={action.onPress} textStyle={{ color: resolvedTextColor }} />
+        </>
+      )}
+    </Animated.View>
+  );
+}
+
+const styles = StyleSheet.create({
+  toast: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: DS_SPACING[300],
+    // surface.inverse, not text.regular — the base toast is a dark inverse PANEL; using the ink
+    // token here would silently recolor it if a rebrand ever splits ink from dark surfaces.
+    backgroundColor: DS_SEMANTIC.surface.inverse,
+    borderRadius: DS_RADIUS.medium,
+    paddingVertical: DS_SPACING[800],
+    paddingHorizontal: DS_SPACING[600],
+    borderWidth: 2,
+    borderColor: 'transparent',
+    ...DS_SHADOW.card,
+  },
+  text: {
+    flex: 1,
+    ...DS_TYPOGRAPHY.bodySm,
+    fontWeight: DS_FONT_WEIGHT.medium,
+  },
+  divider: {
+    width: 1,
+    height: 20,
+    opacity: 0.3,
+    // Extra space on top of the row's own `gap` — the divider reads as a rule between two distinct
+    // regions (message vs. action), so it gets more breathing room than the icon-to-label gap does.
+    marginHorizontal: DS_SPACING[200],
+  },
+});

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

@@ -0,0 +1,2 @@
+export { Toast } from './Toast';
+export type { ToastProps, ToastVariant } from './Toast';

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

@@ -0,0 +1,121 @@
+import React, { useState } from 'react';
+import { View, StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Button } from '../Button';
+import { Tooltip } from './Tooltip';
+
+const styles = StyleSheet.create({
+  // Tooltip demos — the bubble is an absolutely-positioned overlay above/below the trigger, sized
+  // relative to the trigger's own tiny box, not this box. A fixed-height box with the trigger
+  // centred inside gives the bubble equal clearance whichever direction it points, so stacked items
+  // (States/Configurations renders 5 of these one after another) don't crowd or overlap each other.
+  tooltipDemoBox: { height: 80, alignItems: 'center', justifyContent: 'center' },
+});
+
+function TooltipDemo() {
+  const [visible, setVisible] = useState(true);
+  return (
+    <Tooltip visible={visible} label="Tap to add a stop">
+      <Button
+        variant="ghost"
+        size="medium"
+        showIcon
+        showLabel={false}
+        iconName="add"
+        accessibilityLabel="Add stop"
+        onPress={() => setVisible((v) => !v)}
+      />
+    </Tooltip>
+  );
+}
+
+export default defineCatalogPage({
+  component: 'Tooltip',
+  group: 'Overlays',
+  description: 'A small floating label anchored above or below its wrapped trigger. Fully controlled — drive `visible` from the trigger\'s own onLongPress/onPressIn, since mobile has no hover.',
+  a11y: 'The bubble is a plain, non-interactive View; the trigger you wrap it around carries its own accessibility.',
+  variants: {
+    items: [
+      {
+        key: 'default',
+        name: 'Default (tap to toggle)',
+        props: { placement: 'top', align: 'center' },
+        node: (
+          <View style={styles.tooltipDemoBox}>
+            <TooltipDemo />
+          </View>
+        ),
+      },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'bottom',
+        name: 'Placement: bottom',
+        props: { placement: 'bottom' },
+        node: (
+          <View style={styles.tooltipDemoBox}>
+            <Tooltip visible label="Tap to add a stop" placement="bottom">
+              <Button variant="ghost" size="medium" showIcon showLabel={false} iconName="add" accessibilityLabel="Add stop" onPress={() => {}} />
+            </Tooltip>
+          </View>
+        ),
+      },
+      {
+        // The arrow always attaches to whichever bubble edge faces the trigger — so a
+        // placement="bottom" bubble (sitting below the trigger) has its arrow on its own TOP
+        // edge, not its bottom. Naming/labels below describe the arrow's actual visual corner on
+        // the bubble, not the `placement` value, since that's what a reader looking at the
+        // rendered example actually sees.
+        key: 'top-left',
+        name: 'Top-left arrow',
+        props: { placement: 'bottom', align: 'left' },
+        node: (
+          <View style={styles.tooltipDemoBox}>
+            <Tooltip visible label="Top left" placement="bottom" align="left">
+              <Button variant="ghost" size="medium" showIcon showLabel={false} iconName="add" accessibilityLabel="Add stop" onPress={() => {}} />
+            </Tooltip>
+          </View>
+        ),
+      },
+      {
+        key: 'top-right',
+        name: 'Top-right arrow',
+        props: { placement: 'bottom', align: 'right' },
+        node: (
+          <View style={styles.tooltipDemoBox}>
+            <Tooltip visible label="Top right" placement="bottom" align="right">
+              <Button variant="ghost" size="medium" showIcon showLabel={false} iconName="add" accessibilityLabel="Add stop" onPress={() => {}} />
+            </Tooltip>
+          </View>
+        ),
+      },
+      {
+        key: 'bottom-left',
+        name: 'Bottom-left arrow',
+        props: { placement: 'top', align: 'left' },
+        node: (
+          <View style={styles.tooltipDemoBox}>
+            <Tooltip visible label="Bottom left" placement="top" align="left">
+              <Button variant="ghost" size="medium" showIcon showLabel={false} iconName="add" accessibilityLabel="Add stop" onPress={() => {}} />
+            </Tooltip>
+          </View>
+        ),
+      },
+      {
+        key: 'bottom-right',
+        name: 'Bottom-right arrow',
+        props: { placement: 'top', align: 'right' },
+        node: (
+          <View style={styles.tooltipDemoBox}>
+            <Tooltip visible label="Bottom right" placement="top" align="right">
+              <Button variant="ghost" size="medium" showIcon showLabel={false} iconName="add" accessibilityLabel="Add stop" onPress={() => {}} />
+            </Tooltip>
+          </View>
+        ),
+      },
+    ],
+  },
+});