@klyftig/mobile-ui 1.0.5 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klyftig/mobile-ui",
-  "version": "1.0.5",
+  "version": "1.2.0",
   "scripts": {
     "pack-install": "npm pack && mv klyftig-ui-*.tgz /tmp/klyftig-ui-local.tgz && cd ../../mobile && npm install /tmp/klyftig-ui-local.tgz"
   },

package/src/components/EmptyState.tsx

@@ -0,0 +1,90 @@
+import React from 'react';
+import { View, Text, StyleSheet, StyleProp, ViewStyle } from 'react-native';
+import { MaterialCommunityIcons as Icon } from '@expo/vector-icons';
+import { useTheme } from '../hooks/useTheme';
+
+/**
+ * Intent of an empty state:
+ * - `empty`   — no content yet, but everything is wired up (default).
+ * - `pending` — feature is set up but waiting on data / connection / opt-in.
+ *               Use this when the screen will fill in once the user takes
+ *               an external step (e.g. connect Health, enable notifications).
+ * - `error`   — something is broken; user may need to retry.
+ */
+export type EmptyStateVariant = 'empty' | 'pending' | 'error';
+
+export interface EmptyStateProps {
+  /** MaterialCommunityIcons name. Defaults vary by variant. */
+  icon?: string;
+  iconSize?: number;
+  iconColor?: string;
+  title: string;
+  description?: string;
+  /** Render an action button (or any node) below the description. */
+  action?: React.ReactNode;
+  variant?: EmptyStateVariant;
+  style?: StyleProp<ViewStyle>;
+}
+
+const VARIANT_DEFAULTS: Record<EmptyStateVariant, { icon: string; tint: string }> = {
+  empty:   { icon: 'inbox-outline',         tint: '#9B9B9B' },
+  pending: { icon: 'progress-clock',        tint: '#2196F3' },
+  error:   { icon: 'alert-circle-outline',  tint: '#F44336' },
+};
+
+/**
+ * Large-icon empty state used on list/feed screens with no data.
+ * Centered in its parent; pass a flex-1 wrapper to vertically center on a full screen.
+ */
+export function EmptyState({
+  icon,
+  iconSize = 64,
+  iconColor,
+  title,
+  description,
+  action,
+  variant = 'empty',
+  style,
+}: EmptyStateProps) {
+  const { colors } = useTheme();
+  const variantDefaults = VARIANT_DEFAULTS[variant];
+  const resolvedIcon = icon ?? variantDefaults.icon;
+  const resolvedIconColor =
+    iconColor ?? (variant === 'empty' ? colors.icon.tertiary : variantDefaults.tint);
+
+  return (
+    <View style={[styles.container, style]}>
+      <Icon name={resolvedIcon as any} size={iconSize} color={resolvedIconColor} />
+      <Text style={[styles.title, { color: colors.text.primary }]}>{title}</Text>
+      {description && (
+        <Text style={[styles.description, { color: colors.text.tertiary }]}>
+          {description}
+        </Text>
+      )}
+      {action && <View style={styles.action}>{action}</View>}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 40,
+  },
+  title: {
+    fontSize: 18,
+    fontWeight: '700',
+    marginTop: 16,
+    marginBottom: 8,
+    textAlign: 'center',
+  },
+  description: {
+    fontSize: 14,
+    fontWeight: '500',
+    textAlign: 'center',
+  },
+  action: {
+    marginTop: 20,
+  },
+});

package/src/components/ErrorState.tsx

@@ -0,0 +1,81 @@
+import React from 'react';
+import {
+  View,
+  Text,
+  TouchableOpacity,
+  StyleSheet,
+  StyleProp,
+  ViewStyle,
+} from 'react-native';
+import { useTheme } from '../hooks/useTheme';
+
+export interface ErrorStateProps {
+  title?: string;
+  description?: string;
+  retryLabel?: string;
+  onRetry?: () => void;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Centered error view with optional retry button.
+ * Use inside a flex-1 wrapper to vertically center on a full screen.
+ */
+export function ErrorState({
+  title = 'Something went wrong',
+  description,
+  retryLabel = 'Try Again',
+  onRetry,
+  style,
+}: ErrorStateProps) {
+  const { colors } = useTheme();
+  return (
+    <View style={[styles.container, style]}>
+      <Text style={[styles.title, { color: colors.text.primary }]}>{title}</Text>
+      {description && (
+        <Text style={[styles.description, { color: colors.text.secondary }]}>
+          {description}
+        </Text>
+      )}
+      {onRetry && (
+        <TouchableOpacity
+          onPress={onRetry}
+          accessibilityRole="button"
+          accessibilityLabel={retryLabel}
+          style={[styles.retryButton, { backgroundColor: colors.text.primary }]}
+        >
+          <Text style={styles.retryText}>{retryLabel}</Text>
+        </TouchableOpacity>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 40,
+  },
+  title: {
+    fontSize: 18,
+    fontWeight: '700',
+    marginBottom: 8,
+    textAlign: 'center',
+  },
+  description: {
+    fontSize: 14,
+    textAlign: 'center',
+    marginBottom: 20,
+  },
+  retryButton: {
+    paddingHorizontal: 24,
+    paddingVertical: 10,
+    borderRadius: 10,
+  },
+  retryText: {
+    color: '#FFFFFF',
+    fontWeight: '600',
+    fontSize: 14,
+  },
+});

package/src/components/FAB.tsx

@@ -19,6 +19,37 @@ interface FABAction {
   color?: string;
 }
 
+/**
+ * Floating action button with two operating modes:
+ *
+ * 1. **Toggle-menu (default).** With just `actions`, tapping the FAB animates a
+ *    vertical column of sub-buttons up from the FAB, each with a label pill.
+ *    Tap an action to dismiss the menu and run it.
+ *
+ * 2. **Single-action override.** Pass `overrideIcon` and `overrideOnPress` to
+ *    swap the FAB into a one-tap shortcut. Used by the chat dock: when the
+ *    chat input gains focus, the host swaps the FAB icon to `"camera"` and
+ *    `overrideOnPress` opens the camera directly — bypassing the menu.
+ *    `actions` are ignored in this mode.
+ *
+ * @example
+ * // Toggle-menu mode
+ * <FAB
+ *   actions={[
+ *     { icon: 'camera', label: 'Snap food', onPress: openCamera },
+ *     { icon: 'silverware-fork-knife', label: 'Suggest recipe', onPress: openRecipes },
+ *     { icon: 'message-text', label: 'Chat', onPress: openChat },
+ *   ]}
+ * />
+ *
+ * @example
+ * // Single-action override (chat input focused)
+ * <FAB
+ *   actions={[]}
+ *   overrideIcon="camera"
+ *   overrideOnPress={openCamera}
+ * />
+ */
 interface FABProps {
   actions: FABAction[];
   /** Override main button icon (e.g. 'camera' when input is focused) */

package/src/components/LoadingState.tsx

@@ -0,0 +1,45 @@
+import React from 'react';
+import { View, Text, ActivityIndicator, StyleSheet, StyleProp, ViewStyle } from 'react-native';
+import { useTheme } from '../hooks/useTheme';
+
+export interface LoadingStateProps {
+  message?: string;
+  size?: 'small' | 'large';
+  color?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Centered ActivityIndicator + optional message. Default uses the brand text color.
+ */
+export function LoadingState({
+  message,
+  size = 'large',
+  color,
+  style,
+}: LoadingStateProps) {
+  const { colors } = useTheme();
+  const resolvedColor = color ?? colors.text.primary;
+  return (
+    <View style={[styles.container, style]}>
+      <ActivityIndicator size={size} color={resolvedColor} />
+      {message && (
+        <Text style={[styles.message, { color: colors.text.secondary }]}>{message}</Text>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 40,
+  },
+  message: {
+    fontSize: 14,
+    fontWeight: '500',
+    marginTop: 12,
+    textAlign: 'center',
+  },
+});

package/src/components/ProgressCard.tsx

@@ -0,0 +1,227 @@
+import React from 'react';
+import {
+  View,
+  Text,
+  StyleSheet,
+  TouchableOpacity,
+  StyleProp,
+  ViewStyle,
+} from 'react-native';
+import { MaterialCommunityIcons as Icon } from '@expo/vector-icons';
+import { useTheme } from '../hooks/useTheme';
+import { CircularProgress } from './progress/CircularProgress';
+
+export interface ProgressCardProps {
+  /** Bottom label, e.g. "Protein". */
+  label: string;
+  /** Primary value text (already formatted), e.g. "151.8" or "1428". */
+  value: string;
+  /** Optional unit appended to value, e.g. "g" or "cal". */
+  unit?: string;
+  /** MaterialCommunityIcons name shown above the value (compact mode only). */
+  icon?: string;
+  /** Optional emoji shown next to label (e.g. "🍗" for protein). */
+  emoji?: string;
+  /** Current progress numerator. If omitted, no ring is rendered. */
+  current?: number;
+  /** Progress denominator. */
+  target?: number;
+  /** Ring stroke color (defaults to text.primary). */
+  color?: string;
+  /**
+   * `compact` — 3-up macro tile (Home today). Stacked: ring on top, label below.
+   * `wide`    — 2-up daily-goal tile (Profile). Ring on left, text on right.
+   */
+  size?: 'compact' | 'wide';
+  onPress?: () => void;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Stat tile with optional progress ring. Use `size="compact"` for the row of
+ * macro tiles on Home, `size="wide"` for the daily-goals 2x2 grid on Profile.
+ */
+export const ProgressCard: React.FC<ProgressCardProps> = ({
+  label,
+  value,
+  unit,
+  icon,
+  emoji,
+  current,
+  target,
+  color,
+  size = 'compact',
+  onPress,
+  style,
+}) => {
+  const { colors } = useTheme();
+  const showRing = typeof current === 'number' && typeof target === 'number' && target > 0;
+  const ringColor = color ?? colors.text.primary;
+
+  const Wrapper: any = onPress ? TouchableOpacity : View;
+  const wrapperProps = onPress
+    ? { onPress, activeOpacity: 0.85, accessibilityRole: 'button' as const }
+    : {};
+
+  if (size === 'wide') {
+    return (
+      <Wrapper
+        {...wrapperProps}
+        style={[
+          styles.card,
+          styles.wideCard,
+          { backgroundColor: colors.background.card, borderColor: colors.border.light },
+          style,
+        ]}
+      >
+        {showRing ? (
+          <CircularProgress
+            size={48}
+            strokeWidth={5}
+            current={current!}
+            target={target!}
+            color={ringColor}
+            hideText
+          />
+        ) : icon ? (
+          <View style={[styles.iconBubble, { backgroundColor: colors.background.secondary }]}>
+            <Icon name={icon as any} size={22} color={ringColor} />
+          </View>
+        ) : null}
+        <View style={styles.wideText}>
+          <Text style={[styles.wideLabel, { color: colors.text.tertiary }]} numberOfLines={1}>
+            {emoji ? `${emoji} ` : ''}
+            {label}
+          </Text>
+          <Text style={[styles.wideValue, { color: colors.text.primary }]} numberOfLines={1}>
+            {value}
+            {unit ? <Text style={styles.wideUnit}> {unit}</Text> : null}
+          </Text>
+        </View>
+      </Wrapper>
+    );
+  }
+
+  // compact
+  return (
+    <Wrapper
+      {...wrapperProps}
+      style={[
+        styles.card,
+        styles.compactCard,
+        { backgroundColor: colors.background.card, borderColor: colors.border.light },
+        style,
+      ]}
+    >
+      <View style={styles.compactRingWrap}>
+        {showRing ? (
+          <CircularProgress
+            size={56}
+            strokeWidth={6}
+            current={current!}
+            target={target!}
+            color={ringColor}
+            hideText
+          />
+        ) : (
+          <View style={[styles.iconBubble, { backgroundColor: colors.background.secondary }]}>
+            {icon ? <Icon name={icon as any} size={22} color={ringColor} /> : null}
+          </View>
+        )}
+        {emoji ? (
+          <View style={styles.compactEmojiWrap}>
+            <Text style={styles.compactEmoji}>{emoji}</Text>
+          </View>
+        ) : null}
+      </View>
+      <Text style={[styles.compactValue, { color: colors.text.primary }]} numberOfLines={1}>
+        {value}
+        {unit ? <Text style={styles.compactUnit}>{unit}</Text> : null}
+      </Text>
+      <Text style={[styles.compactLabel, { color: colors.text.tertiary }]} numberOfLines={1}>
+        {label}
+      </Text>
+    </Wrapper>
+  );
+};
+
+const styles = StyleSheet.create({
+  card: {
+    borderRadius: 20,
+    borderWidth: 1,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.06,
+    shadowRadius: 8,
+    elevation: 3,
+  },
+  compactCard: {
+    flex: 1,
+    paddingVertical: 16,
+    paddingHorizontal: 12,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  compactRingWrap: {
+    width: 56,
+    height: 56,
+    alignItems: 'center',
+    justifyContent: 'center',
+    marginBottom: 10,
+  },
+  compactEmojiWrap: {
+    position: 'absolute',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  compactEmoji: {
+    fontSize: 22,
+  },
+  compactValue: {
+    fontSize: 18,
+    fontWeight: '800',
+  },
+  compactUnit: {
+    fontSize: 12,
+    fontWeight: '600',
+  },
+  compactLabel: {
+    fontSize: 12,
+    fontWeight: '600',
+    marginTop: 2,
+    textTransform: 'uppercase',
+    letterSpacing: 0.4,
+  },
+  wideCard: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingVertical: 16,
+    paddingHorizontal: 16,
+    gap: 14,
+  },
+  iconBubble: {
+    width: 48,
+    height: 48,
+    borderRadius: 24,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  wideText: {
+    flex: 1,
+  },
+  wideLabel: {
+    fontSize: 12,
+    fontWeight: '600',
+    textTransform: 'uppercase',
+    letterSpacing: 0.4,
+    marginBottom: 4,
+  },
+  wideValue: {
+    fontSize: 22,
+    fontWeight: '800',
+  },
+  wideUnit: {
+    fontSize: 14,
+    fontWeight: '600',
+  },
+});

package/src/components/RadioOption.tsx

@@ -0,0 +1,190 @@
+import React, { createContext, useContext } from 'react';
+import {
+  TouchableOpacity,
+  View,
+  Text,
+  StyleSheet,
+  StyleProp,
+  ViewStyle,
+  TextStyle,
+} from 'react-native';
+import { useTheme } from '../hooks/useTheme';
+
+type RadioGroupContextValue<T> = {
+  value: T | undefined;
+  onChange: (value: T) => void;
+};
+
+const RadioGroupContext = createContext<RadioGroupContextValue<unknown> | null>(null);
+
+export interface RadioGroupProps<T> {
+  value: T | undefined;
+  onChange: (value: T) => void;
+  children: React.ReactNode;
+  style?: StyleProp<ViewStyle>;
+  accessibilityLabel?: string;
+}
+
+export function RadioGroup<T>({ value, onChange, children, style, accessibilityLabel }: RadioGroupProps<T>) {
+  return (
+    <RadioGroupContext.Provider value={{ value, onChange: onChange as (v: unknown) => void }}>
+      <View
+        accessibilityRole="radiogroup"
+        accessibilityLabel={accessibilityLabel}
+        style={style}
+      >
+        {children}
+      </View>
+    </RadioGroupContext.Provider>
+  );
+}
+
+export interface RadioOptionProps<T = string> {
+  /** The value this option represents — used for selection matching when inside a RadioGroup. */
+  value?: T;
+  /** Explicit selected flag. Ignored if rendered inside a RadioGroup with a matching `value`. */
+  selected?: boolean;
+  /** Callback when the option is tapped. Ignored if rendered inside a RadioGroup (the group's onChange fires). */
+  onPress?: () => void;
+  /** Primary label text. Either `label` or `children` is required. */
+  label?: string;
+  /** Secondary description text shown under the label. */
+  description?: string;
+  /** Render custom content to the right of the radio circle instead of label/description. */
+  children?: React.ReactNode;
+  /** `"sm"` for a compact inline row (gender pickers); `"md"` for a card-style row (activity level). */
+  variant?: 'sm' | 'md';
+  style?: StyleProp<ViewStyle>;
+  labelStyle?: StyleProp<TextStyle>;
+  disabled?: boolean;
+}
+
+/**
+ * A tap-anywhere radio row: the circle is purely visual (pointerEvents: none)
+ * and the entire row is a single TouchableOpacity. Safe inside ScrollViews
+ * and dialogs — no competing gesture responders.
+ *
+ * Use inside <RadioGroup value={x} onChange={setX}> for controlled selection,
+ * or pass `selected` + `onPress` directly for standalone use.
+ */
+export function RadioOption<T = string>({
+  value,
+  selected,
+  onPress,
+  label,
+  description,
+  children,
+  variant = 'sm',
+  style,
+  labelStyle,
+  disabled = false,
+}: RadioOptionProps<T>) {
+  const { colors } = useTheme();
+  const group = useContext(RadioGroupContext) as RadioGroupContextValue<T> | null;
+
+  const isSelected = group && value !== undefined ? group.value === value : !!selected;
+  const handlePress = () => {
+    if (disabled) return;
+    if (group && value !== undefined) {
+      group.onChange(value);
+    } else {
+      onPress?.();
+    }
+  };
+
+  const isCard = variant === 'md';
+  const ringColor = isSelected ? colors.text.primary : colors.text.tertiary;
+
+  return (
+    <TouchableOpacity
+      onPress={handlePress}
+      disabled={disabled}
+      activeOpacity={0.7}
+      accessibilityRole="radio"
+      accessibilityState={{ selected: isSelected, disabled }}
+      accessibilityLabel={label}
+      style={[
+        isCard ? styles.cardRow : styles.inlineRow,
+        disabled && styles.disabled,
+        style,
+      ]}
+    >
+      {/* Radio circle — fully non-interactive; outer TouchableOpacity handles taps. */}
+      <View pointerEvents="none" style={[styles.ring, { borderColor: ringColor }]}>
+        {isSelected && <View style={[styles.dot, { backgroundColor: colors.text.primary }]} />}
+      </View>
+
+      {children ?? (
+        <View style={styles.textContainer}>
+          {label && (
+            <Text
+              style={[
+                isCard ? styles.cardLabel : styles.inlineLabel,
+                { color: colors.text.primary },
+                labelStyle,
+              ]}
+            >
+              {label}
+            </Text>
+          )}
+          {description && (
+            <Text style={[styles.description, { color: colors.text.secondary }]}>
+              {description}
+            </Text>
+          )}
+        </View>
+      )}
+    </TouchableOpacity>
+  );
+}
+
+const styles = StyleSheet.create({
+  inlineRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingVertical: 6,
+    paddingHorizontal: 4,
+  },
+  cardRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    backgroundColor: 'rgba(255,255,255,0.3)',
+    borderRadius: 12,
+    padding: 12,
+    borderWidth: 1,
+    borderColor: 'rgba(255,255,255,0.4)',
+  },
+  ring: {
+    width: 20,
+    height: 20,
+    borderRadius: 10,
+    borderWidth: 2,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  dot: {
+    width: 10,
+    height: 10,
+    borderRadius: 5,
+  },
+  textContainer: {
+    flex: 1,
+    marginLeft: 12,
+  },
+  inlineLabel: {
+    fontSize: 15,
+    fontWeight: '500',
+  },
+  cardLabel: {
+    fontSize: 15,
+    fontWeight: '600',
+    marginBottom: 2,
+  },
+  description: {
+    fontSize: 13,
+    fontWeight: '500',
+  },
+  disabled: {
+    opacity: 0.5,
+  },
+});

package/src/components/RecipeRow.tsx

@@ -0,0 +1,261 @@
+import React, { useState } from 'react';
+import {
+  View,
+  Text,
+  Image,
+  TouchableOpacity,
+  StyleSheet,
+  Animated,
+  ImageSourcePropType,
+  StyleProp,
+  ViewStyle,
+} from 'react-native';
+import { LinearGradient } from 'expo-linear-gradient';
+import { MaterialCommunityIcons as Icon } from '@expo/vector-icons';
+import { useTheme } from '../hooks/useTheme';
+
+export interface RecipeRowProps {
+  title: string;
+  /** Short tag rendered under the title, e.g. "Lunch · 25 min". */
+  tag?: string;
+  /** Image source. Pass a string URL or a require(...) source. */
+  thumbnail?: ImageSourcePropType | string;
+  /** Emoji rendered on a colored gradient when no thumbnail is provided. */
+  fallbackEmoji?: string;
+  kcal: number;
+  protein: number;
+  carbs: number;
+  fat: number;
+  /** Render a "BEST" pill next to the title. */
+  bestMatch?: boolean;
+  /**
+   * `navigate` (default) — chevron-right; tapping the row fires onPress.
+   * `expand` — chevron-down/up; row expands inline to show `expandedContent`.
+   */
+  mode?: 'navigate' | 'expand';
+  expandedContent?: React.ReactNode;
+  onPress?: () => void;
+  style?: StyleProp<ViewStyle>;
+}
+
+const FALLBACK_GRADIENTS: Array<readonly [string, string]> = [
+  ['#FFE0B2', '#FFB74D'],
+  ['#C8E6C9', '#81C784'],
+  ['#BBDEFB', '#64B5F6'],
+  ['#F8BBD0', '#F06292'],
+  ['#D1C4E9', '#9575CD'],
+];
+
+function pickGradient(seed: string): readonly [string, string] {
+  let h = 0;
+  for (let i = 0; i < seed.length; i++) h = (h * 31 + seed.charCodeAt(i)) >>> 0;
+  return FALLBACK_GRADIENTS[h % FALLBACK_GRADIENTS.length];
+}
+
+/**
+ * One recipe in a list. Renders a thumbnail, title (+optional BEST pill),
+ * a tag line, and macros in a compact row.
+ */
+export const RecipeRow: React.FC<RecipeRowProps> = ({
+  title,
+  tag,
+  thumbnail,
+  fallbackEmoji = '🍽️',
+  kcal,
+  protein,
+  carbs,
+  fat,
+  bestMatch,
+  mode = 'navigate',
+  expandedContent,
+  onPress,
+  style,
+}) => {
+  const { colors } = useTheme();
+  const [expanded, setExpanded] = useState(false);
+  const rotation = React.useRef(new Animated.Value(0)).current;
+
+  const handlePress = () => {
+    if (mode === 'expand') {
+      const toValue = expanded ? 0 : 1;
+      Animated.timing(rotation, {
+        toValue,
+        duration: 180,
+        useNativeDriver: true,
+      }).start();
+      setExpanded(!expanded);
+    } else {
+      onPress?.();
+    }
+  };
+
+  const rotate = rotation.interpolate({
+    inputRange: [0, 1],
+    outputRange: ['0deg', '180deg'],
+  });
+
+  const chevronName = mode === 'expand' ? 'chevron-down' : 'chevron-right';
+  const gradient = pickGradient(title);
+
+  const thumbSrc =
+    typeof thumbnail === 'string' ? { uri: thumbnail } : thumbnail;
+
+  return (
+    <View
+      style={[
+        styles.card,
+        { backgroundColor: colors.background.card, borderColor: colors.border.light },
+        style,
+      ]}
+    >
+      <TouchableOpacity
+        activeOpacity={0.85}
+        onPress={handlePress}
+        accessibilityRole="button"
+        accessibilityLabel={title}
+        accessibilityState={mode === 'expand' ? { expanded } : undefined}
+        style={styles.row}
+      >
+        <View style={styles.thumb}>
+          {thumbSrc ? (
+            <Image source={thumbSrc} style={styles.thumbImage} />
+          ) : (
+            <LinearGradient colors={gradient} style={styles.thumbImage}>
+              <Text style={styles.thumbEmoji}>{fallbackEmoji}</Text>
+            </LinearGradient>
+          )}
+        </View>
+
+        <View style={styles.body}>
+          <View style={styles.titleRow}>
+            <Text style={[styles.title, { color: colors.text.primary }]} numberOfLines={1}>
+              {title}
+            </Text>
+            {bestMatch && (
+              <View style={[styles.bestPill, { backgroundColor: colors.text.primary }]}>
+                <Text style={styles.bestText}>BEST</Text>
+              </View>
+            )}
+          </View>
+          {tag ? (
+            <Text style={[styles.tag, { color: colors.text.tertiary }]} numberOfLines={1}>
+              {tag}
+            </Text>
+          ) : null}
+          <View style={styles.macros}>
+            <Macro label={`${Math.round(kcal)} cal`} color={colors.text.primary} />
+            <MacroDot color={colors.macro.protein} />
+            <Macro label={`${Math.round(protein)}g`} color={colors.text.secondary} />
+            <MacroDot color={colors.macro.carbs} />
+            <Macro label={`${Math.round(carbs)}g`} color={colors.text.secondary} />
+            <MacroDot color={colors.macro.fat} />
+            <Macro label={`${Math.round(fat)}g`} color={colors.text.secondary} />
+          </View>
+        </View>
+
+        <Animated.View style={{ transform: [{ rotate }] }}>
+          <Icon name={chevronName as any} size={22} color={colors.icon.tertiary} />
+        </Animated.View>
+      </TouchableOpacity>
+
+      {mode === 'expand' && expanded && expandedContent ? (
+        <View style={[styles.expanded, { borderTopColor: colors.border.light }]}>
+          {expandedContent}
+        </View>
+      ) : null}
+    </View>
+  );
+};
+
+const Macro: React.FC<{ label: string; color: string }> = ({ label, color }) => (
+  <Text style={[styles.macroText, { color }]}>{label}</Text>
+);
+
+const MacroDot: React.FC<{ color: string }> = ({ color }) => (
+  <View style={[styles.dot, { backgroundColor: color }]} />
+);
+
+const styles = StyleSheet.create({
+  card: {
+    borderRadius: 18,
+    borderWidth: 1,
+    overflow: 'hidden',
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.06,
+    shadowRadius: 8,
+    elevation: 2,
+  },
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    padding: 12,
+    gap: 12,
+  },
+  thumb: {
+    width: 60,
+    height: 60,
+    borderRadius: 14,
+    overflow: 'hidden',
+    backgroundColor: '#F0EFEA',
+  },
+  thumbImage: {
+    width: '100%',
+    height: '100%',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  thumbEmoji: {
+    fontSize: 30,
+  },
+  body: {
+    flex: 1,
+  },
+  titleRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 8,
+  },
+  title: {
+    fontSize: 15,
+    fontWeight: '700',
+    flexShrink: 1,
+  },
+  bestPill: {
+    paddingHorizontal: 6,
+    paddingVertical: 2,
+    borderRadius: 4,
+  },
+  bestText: {
+    color: '#FFFFFF',
+    fontSize: 10,
+    fontWeight: '800',
+    letterSpacing: 0.5,
+  },
+  tag: {
+    fontSize: 12,
+    fontWeight: '500',
+    marginTop: 2,
+  },
+  macros: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 6,
+    marginTop: 6,
+    flexWrap: 'wrap',
+  },
+  macroText: {
+    fontSize: 12,
+    fontWeight: '600',
+  },
+  dot: {
+    width: 4,
+    height: 4,
+    borderRadius: 2,
+  },
+  expanded: {
+    paddingHorizontal: 12,
+    paddingVertical: 12,
+    borderTopWidth: 1,
+  },
+});

package/src/components/ScreenHeader.tsx

@@ -0,0 +1,107 @@
+import React from 'react';
+import { View, Text, TouchableOpacity, StyleSheet, StyleProp, ViewStyle } from 'react-native';
+import { MaterialCommunityIcons as Icon } from '@expo/vector-icons';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { useTheme } from '../hooks/useTheme';
+
+export interface ScreenHeaderProps {
+  title: string;
+  subtitle?: string;
+  /** Left icon name (MaterialCommunityIcons). Defaults to "home-outline". */
+  leftIcon?: string;
+  /** Accessibility label for the left button. Defaults to "Go to Dashboard". */
+  leftAccessibilityLabel?: string;
+  onLeftPress?: () => void;
+  /** Right-side content (optional action, e.g. a settings button). Reserves space for symmetry when absent. */
+  right?: React.ReactNode;
+  /** Render below the title row — e.g. a tab bar or period toggle that should stay pinned with the header. */
+  below?: React.ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Fixed-position screen header matching the Kaelo glass design system.
+ * Renders safe-area top inset + home icon + centered title/subtitle + optional right slot.
+ * Place as a sibling of (not inside) your ScrollView so it stays pinned while body scrolls.
+ */
+export function ScreenHeader({
+  title,
+  subtitle,
+  leftIcon = 'home-outline',
+  leftAccessibilityLabel = 'Go to Dashboard',
+  onLeftPress,
+  right,
+  below,
+  style,
+}: ScreenHeaderProps) {
+  const insets = useSafeAreaInsets();
+  const { colors } = useTheme();
+
+  return (
+    <View style={[styles.container, { paddingTop: insets.top + 16 }, style]}>
+      <View style={styles.row}>
+        <View style={styles.side}>
+          {onLeftPress && (
+            <TouchableOpacity
+              onPress={onLeftPress}
+              accessibilityLabel={leftAccessibilityLabel}
+              accessibilityRole="button"
+              hitSlop={8}
+            >
+              <Icon name={leftIcon as any} size={26} color={colors.icon.primary} />
+            </TouchableOpacity>
+          )}
+        </View>
+        <View style={styles.center}>
+          <Text
+            style={[styles.title, { color: colors.text.primary }]}
+            numberOfLines={1}
+          >
+            {title}
+          </Text>
+          {subtitle && (
+            <Text
+              style={[styles.subtitle, { color: colors.text.tertiary }]}
+              numberOfLines={1}
+            >
+              {subtitle}
+            </Text>
+          )}
+        </View>
+        <View style={styles.side}>{right}</View>
+      </View>
+      {below}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    paddingHorizontal: 20,
+    paddingBottom: 8,
+  },
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    marginBottom: 8,
+  },
+  side: {
+    width: 40,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  center: {
+    flex: 1,
+    alignItems: 'center',
+  },
+  title: {
+    fontSize: 22,
+    fontWeight: '700',
+    textAlign: 'center',
+  },
+  subtitle: {
+    fontSize: 13,
+    fontWeight: '500',
+    marginTop: 2,
+  },
+});

package/src/components/SectionHeader.tsx

@@ -0,0 +1,32 @@
+import React from 'react';
+import { Text, StyleSheet, StyleProp, TextStyle } from 'react-native';
+import { useTheme } from '../hooks/useTheme';
+
+export interface SectionHeaderProps {
+  children: React.ReactNode;
+  style?: StyleProp<TextStyle>;
+}
+
+/**
+ * Small uppercase section label used above lists of settings or cards.
+ * Matches the existing Profile / LogFood section headers.
+ */
+export function SectionHeader({ children, style }: SectionHeaderProps) {
+  const { colors } = useTheme();
+  return (
+    <Text style={[styles.title, { color: colors.text.secondary }, style]}>
+      {children}
+    </Text>
+  );
+}
+
+const styles = StyleSheet.create({
+  title: {
+    fontSize: 13,
+    fontWeight: '700',
+    marginBottom: 12,
+    marginLeft: 4,
+    textTransform: 'uppercase',
+    letterSpacing: 1,
+  },
+});

package/src/components/SegmentedToggle.tsx

@@ -0,0 +1,158 @@
+import React from 'react';
+import {
+  View,
+  Text,
+  TouchableOpacity,
+  StyleSheet,
+  StyleProp,
+  ViewStyle,
+} from 'react-native';
+import { useTheme } from '../hooks/useTheme';
+
+export interface SegmentedToggleOption<T extends string> {
+  value: T;
+  label: string;
+  accessibilityLabel?: string;
+  /** Render at 40% opacity and ignore taps. */
+  disabled?: boolean;
+}
+
+export interface SegmentedToggleProps<T extends string> {
+  options: SegmentedToggleOption<T>[];
+  value: T;
+  onChange: (value: T) => void;
+  /**
+   * `pill` — rounded pill row with white active background (primary tabs, e.g. Insights/History).
+   * `chip` — subtle inset variant for filter rows.
+   * `underline` — no container background; active tab has a 2px bar underneath. Best for secondary toggles (e.g. Week/Month).
+   */
+  variant?: 'pill' | 'chip' | 'underline';
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Horizontal toggle used for Week/Month, Insights/History, etc.
+ * Replaces the ad-hoc tabBar/periodToggle rows in ProgressScreen and InsightsScreen.
+ */
+export function SegmentedToggle<T extends string>({
+  options,
+  value,
+  onChange,
+  variant = 'pill',
+  style,
+}: SegmentedToggleProps<T>) {
+  const { colors } = useTheme();
+  const isChip = variant === 'chip';
+  const isUnderline = variant === 'underline';
+
+  const containerBg = isUnderline
+    ? 'transparent'
+    : isChip
+      ? colors.glass.backgroundLight
+      : '#F0EFEA';
+  const activeBg = isChip ? colors.glass.backgroundHeavy : '#FFFFFF';
+
+  return (
+    <View
+      accessibilityRole="tablist"
+      style={[
+        styles.container,
+        { backgroundColor: containerBg },
+        isChip && styles.containerChip,
+        isUnderline && styles.containerUnderline,
+        style,
+      ]}
+    >
+      {options.map((opt) => {
+        const active = opt.value === value;
+        const disabled = !!opt.disabled;
+        return (
+          <TouchableOpacity
+            key={opt.value}
+            disabled={disabled}
+            onPress={() => onChange(opt.value)}
+            accessibilityRole="tab"
+            accessibilityLabel={opt.accessibilityLabel ?? opt.label}
+            accessibilityState={{ selected: active, disabled }}
+            style={[
+              styles.segment,
+              isUnderline && styles.segmentUnderline,
+              !isUnderline && active && { backgroundColor: activeBg },
+              !isUnderline && active && styles.segmentActiveShadow,
+              disabled && styles.segmentDisabled,
+            ]}
+          >
+            <Text
+              style={[
+                styles.label,
+                {
+                  color: active ? colors.text.primary : colors.text.tertiary,
+                },
+                isUnderline && styles.labelUnderline,
+              ]}
+            >
+              {opt.label}
+            </Text>
+            {isUnderline && active && (
+              <View
+                style={[styles.underlineBar, { backgroundColor: colors.text.primary }]}
+              />
+            )}
+          </TouchableOpacity>
+        );
+      })}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flexDirection: 'row',
+    borderRadius: 12,
+    padding: 4,
+  },
+  containerChip: {
+    borderRadius: 10,
+  },
+  containerUnderline: {
+    borderRadius: 0,
+    padding: 0,
+  },
+  segment: {
+    flex: 1,
+    paddingVertical: 10,
+    alignItems: 'center',
+    borderRadius: 10,
+  },
+  segmentUnderline: {
+    paddingVertical: 8,
+    borderRadius: 0,
+  },
+  segmentActiveShadow: {
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 1 },
+    shadowOpacity: 0.06,
+    shadowRadius: 3,
+    elevation: 1,
+  },
+  segmentDisabled: {
+    opacity: 0.4,
+  },
+  label: {
+    fontSize: 14,
+    fontWeight: '600',
+  },
+  labelUnderline: {
+    fontSize: 13,
+    fontWeight: '700',
+    letterSpacing: 0.2,
+  },
+  underlineBar: {
+    position: 'absolute',
+    bottom: 0,
+    left: '20%',
+    right: '20%',
+    height: 2,
+    borderRadius: 2,
+  },
+});

package/src/components/progress/CircularProgress.tsx

@@ -5,6 +5,16 @@ import { useTheme } from '../../hooks/useTheme';
 
 const AnimatedCircle = Animated.createAnimatedComponent(Circle);
 
+/**
+ * Display mode for the center text:
+ * - `consumed`  → shows `current` (e.g. "747") with `/ target` underneath.
+ * - `remaining` → shows `max(0, target - current)` (e.g. "681 cal left").
+ * - `percent`   → shows "NN%".
+ *
+ * `mode` supersedes the legacy `showPercentage` / `showRemaining` booleans.
+ */
+export type CircularProgressMode = 'consumed' | 'remaining' | 'percent';
+
 interface CircularProgressProps {
   size?: number;
   strokeWidth?: number;
@@ -13,7 +23,10 @@ interface CircularProgressProps {
   color?: string;
   label?: string;
   unit?: string;
+  mode?: CircularProgressMode;
+  /** @deprecated Use `mode="percent"`. */
   showPercentage?: boolean;
+  /** @deprecated Use `mode="remaining"`. */
   showRemaining?: boolean;
   subtitle?: string;
   valueSize?: number;
@@ -29,6 +42,7 @@ export const CircularProgress: React.FC<CircularProgressProps> = ({
   color,
   label,
   unit = '',
+  mode,
   showPercentage = false,
   showRemaining = false,
   subtitle,
@@ -40,6 +54,15 @@ export const CircularProgress: React.FC<CircularProgressProps> = ({
   const styles = createStyles(colors);
   const resolvedColor = color ?? colors.text.primary;
 
+  if (__DEV__ && mode && (showPercentage || showRemaining)) {
+    console.warn(
+      '[CircularProgress] `mode` is set; ignoring deprecated `showPercentage` / `showRemaining`.',
+    );
+  }
+  const resolvedMode: CircularProgressMode =
+    mode ??
+    (showPercentage ? 'percent' : showRemaining ? 'remaining' : 'consumed');
+
   const animatedValue = useRef(new Animated.Value(0)).current;
   const circleRef = useRef<any>(null);
 
@@ -101,14 +124,22 @@ export const CircularProgress: React.FC<CircularProgressProps> = ({
         <View style={styles.textContainer}>
           {label && <Text style={styles.label}>{label}</Text>}
           <Text style={[styles.value, valueSize ? { fontSize: valueSize } : undefined]}>
-            {showRemaining ? Math.max(0, Math.round(target - current)) : Math.round(current)}
-            {unit && <Text style={[styles.unit, valueSize ? { fontSize: valueSize * 0.58 } : undefined]}>{unit}</Text>}
+            {resolvedMode === 'percent'
+              ? `${Math.round(percentage)}`
+              : resolvedMode === 'remaining'
+                ? Math.max(0, Math.round(target - current))
+                : Math.round(current)}
+            {(resolvedMode === 'percent' ? '%' : unit) && (
+              <Text style={[styles.unit, valueSize ? { fontSize: valueSize * 0.58 } : undefined]}>
+                {resolvedMode === 'percent' ? '%' : unit}
+              </Text>
+            )}
           </Text>
           {subtitle ? (
             <Text style={[styles.subtitle, subtitleSize ? { fontSize: subtitleSize } : undefined]}>{subtitle}</Text>
-          ) : target > 0 ? (
+          ) : target > 0 && resolvedMode === 'consumed' ? (
             <Text style={styles.target}>
-              {showPercentage ? `${Math.round(percentage)}%` : `/ ${Math.round(target)}${unit}`}
+              / {Math.round(target)}{unit}
             </Text>
           ) : null}
         </View>

package/src/components/progress/MacroBar.tsx

@@ -59,7 +59,14 @@ export const MacroBar: React.FC<MacroBarProps> = ({
           </Animated.View>
         </View>
         {percentage > 0 && (
-          <Text style={styles.percentage}>{Math.round(percentage)}%</Text>
+          <Text
+            style={[
+              styles.percentage,
+              percentage >= 85 && styles.percentageOnFill,
+            ]}
+          >
+            {Math.round(percentage)}%
+          </Text>
         )}
       </View>
     </View>
@@ -116,4 +123,7 @@ const createStyles = (colors: any) => StyleSheet.create({
     textAlignVertical: 'center',
     lineHeight: 28,
   },
+  percentageOnFill: {
+    color: '#FFFFFF',
+  },
 });

package/src/index.ts

@@ -22,8 +22,27 @@ export { GlassHeaderBackground } from './components/GlassHeaderBackground';
 export { GlassInput } from './components/GlassInput';
 export { GlassListItem } from './components/GlassList';
 export { GlassStatsCard, GlassMacroCard, GlassNutrientRow } from './components/GlassStats';
+export { RadioOption, RadioGroup } from './components/RadioOption';
+export type { RadioOptionProps, RadioGroupProps } from './components/RadioOption';
+export { ScreenHeader } from './components/ScreenHeader';
+export type { ScreenHeaderProps } from './components/ScreenHeader';
+export { SectionHeader } from './components/SectionHeader';
+export type { SectionHeaderProps } from './components/SectionHeader';
+export { SegmentedToggle } from './components/SegmentedToggle';
+export type { SegmentedToggleProps, SegmentedToggleOption } from './components/SegmentedToggle';
+export { EmptyState } from './components/EmptyState';
+export type { EmptyStateProps, EmptyStateVariant } from './components/EmptyState';
+export { ProgressCard } from './components/ProgressCard';
+export type { ProgressCardProps } from './components/ProgressCard';
+export { RecipeRow } from './components/RecipeRow';
+export type { RecipeRowProps } from './components/RecipeRow';
+export { ErrorState } from './components/ErrorState';
+export type { ErrorStateProps } from './components/ErrorState';
+export { LoadingState } from './components/LoadingState';
+export type { LoadingStateProps } from './components/LoadingState';
 
 // Progress
 export { CircularProgress } from './components/progress/CircularProgress';
+export type { CircularProgressMode } from './components/progress/CircularProgress';
 export { CArcProgress } from './components/progress/CArcProgress';
 export { MacroBar } from './components/progress/MacroBar';