@krapwoo/ds-viewer 0.1.1 → 0.3.0

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>
+        ),
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,195 @@
+import React, { useEffect, useRef, useState, type ReactNode } from 'react';
+import { View, Text, StyleSheet, useWindowDimensions, type LayoutChangeEvent, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_SPACING, DS_RADIUS, DS_SHADOW, DS_TYPOGRAPHY } from '../../tokens';
+
+export interface TooltipProps {
+  /** Whether the bubble is shown. Fully controlled — drive this from the wrapped trigger's own
+   *  onLongPress/onPressIn, since mobile has no hover. */
+  visible: boolean;
+  /** The tooltip text. */
+  label: string;
+  /** Which side of the trigger the bubble appears on. @default 'top' */
+  placement?: 'top' | 'bottom';
+  /** Which edge of the trigger the bubble prefers to anchor to horizontally: `'center'` (default)
+   *  centers the bubble on the trigger; `'left'`/`'right'` aligns the bubble's respective edge with
+   *  the trigger's — useful when the trigger sits near a screen edge and a centered bubble would
+   *  extend past it. This is only a *preference*: the bubble is always clamped to stay fully within
+   *  the screen regardless, and the arrow is always computed to point at the trigger's true center,
+   *  never a decorative fixed corner offset. */
+  align?: 'left' | 'center' | 'right';
+  /** The trigger content the bubble is anchored to. */
+  children: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+const GAP = DS_SPACING[200];
+const MIN_WIDTH = 60;
+const MAX_WIDTH_RATIO = 0.8;
+const ARROW_SIZE = 6;
+// How close the bubble (and the arrow within it) may come to the screen's own edge.
+const EDGE_MARGIN = DS_SPACING[400];
+// For align='left'/'right': how far the bubble extends *past* the trigger's own edge, instead of
+// aligning flush with it. This gives the arrow (still always computed from the trigger's true
+// center — see below) breathing room from the bubble's rounded corner by shifting the bubble
+// itself, never by clamping the arrow away from accuracy the way a min-inset-on-the-arrow approach
+// would (that approach was tried and reverted: it silently mis-pointed the arrow for any trigger
+// narrower than the inset).
+const EDGE_OVERHANG = DS_SPACING[400];
+// Same colour as the bubble's own background, referenced directly (not via a resolved variable)
+// since — unlike Toast — Tooltip has only the one dark surface, no variant/light-background mode.
+// surface.inverse, not text.regular — it's a dark PANEL fill, not ink (same reasoning as Toast).
+const BUBBLE_COLOR = DS_SEMANTIC.surface.inverse;
+
+/**
+ * A small floating label anchored above or below its wrapped trigger, with a small triangular arrow
+ * pointing back at it. Measures the trigger's real position (`measureInWindow`, since a plain
+ * onLayout only gives a position relative to the trigger's own parent, not the screen) and the
+ * bubble's own rendered width (onLayout), then computes the bubble's horizontal offset itself
+ * instead of just flexbox-centering it — this is what makes it possible to (a) clamp the bubble so
+ * it never runs past the screen's left/right edge and (b) always place the arrow at the trigger's
+ * true horizontal center, even when the bubble itself had to shift away from `align`'s preferred
+ * position to stay on screen. No `numberOfLines` cap on the label — it wraps to however many lines
+ * it needs rather than truncating; `maxWidth` (80% of the screen width, via `useWindowDimensions` so
+ * it tracks rotation/resize) is what keeps a long label from ever running edge-to-edge. The arrow is
+ * the classic CSS border-triangle trick (a zero-size box with one transparent-adjacent border side
+ * coloured in) — RN's View supports per-side border colours, so this needs no SVG.
+ */
+export function Tooltip({ visible, label, placement = 'top', align = 'center', children, style }: TooltipProps) {
+  const { width: windowWidth } = useWindowDimensions();
+  const maxWidth = Math.round(windowWidth * MAX_WIDTH_RATIO);
+
+  const wrapRef = useRef<View>(null);
+  const [trigger, setTrigger] = useState<{ x: number; width: number } | null>(null);
+  const [bubbleWidth, setBubbleWidth] = useState(0);
+
+  // Re-measures whenever the bubble becomes visible or the window is resized — the trigger's own
+  // on-screen position can only be read once it (and any layout change causing it) has settled.
+  useEffect(() => {
+    if (!visible) return undefined;
+    const raf = requestAnimationFrame(() => {
+      wrapRef.current?.measureInWindow((x, _y, width) => setTrigger({ x, width }));
+    });
+    return () => cancelAnimationFrame(raf);
+  }, [visible, windowWidth]);
+
+  // Falls back to plain flex-centering (the old behavior) for the one frame before the trigger/
+  // bubble have been measured, so there's no flash of an unpositioned bubble at 0,0.
+  let bubbleOffsetStyle: ViewStyle = styles.bubbleWrapCentered;
+  let arrowLeft: number | null = null;
+
+  if (trigger && bubbleWidth > 0) {
+    const triggerCenterAbs = trigger.x + trigger.width / 2;
+    const idealLeftAbs =
+      align === 'left'
+        ? trigger.x - EDGE_OVERHANG
+        : align === 'right'
+          ? trigger.x + trigger.width + EDGE_OVERHANG - bubbleWidth
+          : triggerCenterAbs - bubbleWidth / 2;
+    const minLeftAbs = EDGE_MARGIN;
+    const maxLeftAbs = windowWidth - bubbleWidth - EDGE_MARGIN;
+    // maxLeftAbs can be < minLeftAbs for a bubble wider than the screen minus margins — clamp the
+    // clamp range itself so a too-wide bubble still lands at minLeftAbs instead of NaN/garbage.
+    const clampedLeftAbs = Math.min(Math.max(idealLeftAbs, minLeftAbs), Math.max(maxLeftAbs, minLeftAbs));
+    bubbleOffsetStyle = { alignSelf: 'flex-start', marginLeft: clampedLeftAbs - trigger.x };
+    // Always derived from the trigger's real position — never clamped/overridden — so the arrow is
+    // guaranteed accurate regardless of how far the bubble above just shifted for `align` or screen
+    // clamping. EDGE_OVERHANG (baked into idealLeftAbs) is what gives it breathing room from the
+    // bubble's corner; this line doesn't need its own inset logic on top of that.
+    arrowLeft = Math.min(Math.max(triggerCenterAbs - clampedLeftAbs, 0), bubbleWidth);
+  }
+
+  return (
+    <View style={styles.wrap} ref={wrapRef}>
+      {children}
+      {visible && (
+        <View pointerEvents="none" style={[styles.overlay, placement === 'top' ? styles.overlayTop : styles.overlayBottom]}>
+          <View style={[styles.bubbleWrap, bubbleOffsetStyle]}>
+            <View
+              style={[styles.bubble, { maxWidth }, style]}
+              onLayout={(e: LayoutChangeEvent) => setBubbleWidth(e.nativeEvent.layout.width)}
+              // Announce the hint when it appears — without this, a screen-reader user gets no
+              // signal the tooltip exists unless they stumble onto it by swiping.
+              accessibilityLiveRegion="polite"
+            >
+              <Text style={styles.label}>{label}</Text>
+            </View>
+            <View
+              style={[
+                styles.arrow,
+                placement === 'top' ? styles.arrowTop : styles.arrowBottom,
+                arrowLeft != null ? { left: arrowLeft, marginLeft: -ARROW_SIZE } : styles.arrowCenter,
+              ]}
+            />
+          </View>
+        </View>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  // Shrinks to the trigger's own content width, so the overlay below (left:0/right:0) matches it —
+  // without this, a Tooltip inside a wider flex row would stretch and mis-centre the bubble.
+  wrap: { alignSelf: 'flex-start' },
+  overlay: { position: 'absolute', left: 0, right: 0, zIndex: 10 },
+  overlayTop: { bottom: '100%', marginBottom: GAP },
+  overlayBottom: { top: '100%', marginTop: GAP },
+  // Shrink-wraps to `bubble`'s own real width (the only in-flow child; `arrow` is absolutely
+  // positioned so it doesn't affect this) — the shared positioning context the computed
+  // `marginLeft`/arrow offsets above are both relative to.
+  bubbleWrap: { alignItems: 'center' },
+  // Pre-measurement fallback only — matches the old always-centered look.
+  bubbleWrapCentered: { alignSelf: 'center' },
+  bubble: {
+    // Flexbox's implicit `min-width: auto` would otherwise let this shrink down to its longest
+    // single word (collapsing "Tap to add a stop" into a tall, narrow, multi-line sliver) since it's
+    // a flex child of `overlay`, a column container whose own width matches the (often much
+    // narrower) trigger — `flexShrink: 0` alone doesn't stop that on web; `width: 'max-content'`
+    // (a web-only CSS value, harmlessly ignored by RN's own layout engine on native, where this
+    // shrink-to-longest-word quirk doesn't occur) forces the natural single-line width instead.
+    flexShrink: 0,
+    width: 'max-content' as unknown as number,
+    minWidth: MIN_WIDTH,
+    backgroundColor: BUBBLE_COLOR,
+    borderRadius: DS_RADIUS.small,
+    paddingHorizontal: DS_SPACING[400],
+    paddingVertical: DS_SPACING[200],
+    ...DS_SHADOW.card,
+  },
+  label: {
+    ...DS_TYPOGRAPHY.bodyXs,
+    color: DS_SEMANTIC.text.inverse,
+    textAlign: 'center',
+    // The actual node that was collapsing to its min-content (longest word) width — `flexShrink: 0`
+    // on `bubble` alone wasn't enough, since this Text is itself a shrinkable flex child one level in.
+    flexShrink: 0,
+  },
+  // A zero-size box with only one border side coloured in draws as a triangle — the classic CSS
+  // trick, which RN's per-side border-color/width props support natively too. Horizontal position
+  // is applied separately above (a computed `left`, or `arrowCenter` before the first measurement).
+  arrow: {
+    position: 'absolute',
+    width: 0,
+    height: 0,
+    borderLeftWidth: ARROW_SIZE,
+    borderRightWidth: ARROW_SIZE,
+    borderLeftColor: 'transparent',
+    borderRightColor: 'transparent',
+  },
+  arrowCenter: { left: '50%', marginLeft: -ARROW_SIZE },
+  // Bubble sits above the trigger (placement="top") — the arrow hangs off the bubble's bottom edge,
+  // pointing down at the trigger below it. `bottom: 0` on the overlay-relative arrow lines its own
+  // top edge up with the bubble's bottom edge exactly, since the bubble itself sits flush at the
+  // overlay's bottom (overlayTop's `marginBottom: GAP` already reserves the gap between the two).
+  arrowTop: {
+    bottom: -ARROW_SIZE,
+    borderTopWidth: ARROW_SIZE,
+    borderTopColor: BUBBLE_COLOR,
+  },
+  // Mirror of the above — bubble sits below the trigger, arrow hangs off its top edge pointing up.
+  arrowBottom: {
+    top: -ARROW_SIZE,
+    borderBottomWidth: ARROW_SIZE,
+    borderBottomColor: BUBBLE_COLOR,
+  },
+});

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

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

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

@@ -0,0 +1,71 @@
+import React from 'react';
+import { Text, StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Button } from '../Button';
+import { TopNav } from './TopNav';
+import { DS_SEMANTIC, DS_TYPOGRAPHY } from '../../tokens';
+
+const styles = StyleSheet.create({
+  cardTitle: { ...DS_TYPOGRAPHY.labelMd, color: DS_SEMANTIC.text.regular },
+});
+
+export default defineCatalogPage({
+  component: 'TopNav',
+  group: 'Navigation',
+  description: 'A screen\'s top bar — fixed-width leading/trailing slots flanking a centered title (or custom center content). Slots reserve their layout space even when empty, so the title stays centered no matter which sides are populated.',
+  a11y: 'The title renders with accessibilityRole="header". Slot content (typically icon-only Buttons) carries its own accessibilityLabel.',
+  // No `variant` prop exists on TopNav — its "Variants" column just shows the one default look,
+  // with both slots populated; the individual slot combinations live under "States".
+  variants: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'default',
+        name: 'Default',
+        node: (
+          <TopNav
+            title="Trip planner"
+            leading={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="chevron-left" accessibilityLabel="Back" onPress={() => {}} />}
+            trailing={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="search" accessibilityLabel="Search" onPress={() => {}} />}
+          />
+        ),
+      },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      { key: 'title-only', name: 'Title only', node: <TopNav title="Settings" /> },
+      {
+        key: 'leading-only',
+        name: 'Leading only',
+        node: (
+          <TopNav
+            title="Trip details"
+            leading={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="chevron-left" accessibilityLabel="Back" onPress={() => {}} />}
+          />
+        ),
+      },
+      {
+        key: 'trailing-only',
+        name: 'Trailing only',
+        node: (
+          <TopNav
+            title="Saved trips"
+            trailing={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="add" accessibilityLabel="Add" onPress={() => {}} />}
+          />
+        ),
+      },
+      {
+        key: 'custom-center',
+        name: 'Custom center',
+        node: (
+          <TopNav
+            leading={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="clear" accessibilityLabel="Close" onPress={() => {}} />}
+            center={<Text style={styles.cardTitle}>Custom center content</Text>}
+          />
+        ),
+      },
+    ],
+  },
+});