@startsimpli/ui-native 0.0.0-stage → 0.1.1

package/src/components/DonutLegend.tsx

@@ -0,0 +1,49 @@
+import { type ReactNode } from 'react';
+import { View } from 'react-native';
+import { DonutChart } from './DonutChart';
+import { Text } from './Text';
+
+export interface DonutLegendItem {
+  label: string;
+  /** Segment magnitude. */
+  value: number;
+  color: string;
+  /** Optional secondary line under the label. */
+  caption?: string;
+  /** Right-aligned content (formatted value, badge, sparkline…). */
+  trailing?: ReactNode;
+}
+
+export interface DonutLegendProps {
+  items: DonutLegendItem[];
+  size?: number;
+  thickness?: number;
+  /** Content rendered in the donut hole. */
+  center?: ReactNode;
+  /** Gap between the donut and the legend. */
+  gap?: number;
+}
+
+/** Donut chart beside a colored-dot legend. The common "breakdown" block
+ *  (revenue by source, fans by platform, …). */
+export function DonutLegend({ items, size = 130, thickness = 16, center, gap = 16 }: DonutLegendProps) {
+  return (
+    <View style={{ flexDirection: 'row', alignItems: 'center', gap }}>
+      <DonutChart size={size} thickness={thickness} segments={items.map((i) => ({ value: i.value, color: i.color }))}>
+        {center}
+      </DonutChart>
+      <View style={{ flex: 1, gap: 10 }}>
+        {items.map((it, idx) => (
+          <View key={`${it.label}-${idx}`} style={{ flexDirection: 'row', alignItems: 'center', gap: 8 }}>
+            <View style={{ width: 8, height: 8, borderRadius: 4, backgroundColor: it.color }} />
+            <View style={{ flex: 1 }}>
+              <Text variant="muted">{it.label}</Text>
+              {it.caption ? <Text variant="caption">{it.caption}</Text> : null}
+            </View>
+            {it.trailing ? <View>{it.trailing}</View> : null}
+          </View>
+        ))}
+      </View>
+    </View>
+  );
+}

package/src/components/DualRangeControl.tsx

@@ -0,0 +1,31 @@
+import { View, type StyleProp, type ViewStyle } from 'react-native';
+import { Text } from './Text';
+import { SegmentedControl, type SegmentedOption } from './SegmentedControl';
+
+export interface DualRangeControlProps<T extends string | number> {
+  /** Comparison baselines, e.g. previous period / same period last year / none. */
+  options: SegmentedOption<T>[];
+  value: T;
+  onChange: (value: T) => void;
+  /** Leading label, e.g. "Compare to". */
+  label?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+/** Period-comparison selector: pick what the current range is measured against
+ *  (the period math lives in @startsimpli/utils). A labeled SegmentedControl —
+ *  generic over the baseline value type. */
+export function DualRangeControl<T extends string | number>({
+  options,
+  value,
+  onChange,
+  label,
+  style,
+}: DualRangeControlProps<T>) {
+  return (
+    <View style={[{ gap: 6 }, style]}>
+      {label ? <Text variant="muted">{label}</Text> : null}
+      <SegmentedControl options={options} value={value} onChange={onChange} />
+    </View>
+  );
+}

package/src/components/EmptyState.tsx

@@ -0,0 +1,63 @@
+import type { ReactNode } from 'react';
+import { View, type StyleProp, type ViewStyle } from 'react-native';
+import { Text } from './Text';
+import { Button } from './Button';
+import { useTheme } from './ThemeProvider';
+
+export interface EmptyStateProps {
+  /** Large glyph above the title — an emoji string or a node (e.g. an icon). */
+  icon?: ReactNode;
+  title: string;
+  description?: string;
+  /** Optional primary action. Both label and handler must be set to render it. */
+  actionLabel?: string;
+  onAction?: () => void;
+  /** Layout overrides (e.g. margins), merged after the base style. */
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Centered zero-data / first-run placeholder: optional glyph, a title, an
+ * optional description, and an optional primary action. Use it instead of
+ * leaving a screen blank (or showing a bare table header) when there's nothing
+ * to display yet.
+ */
+export function EmptyState({ icon, title, description, actionLabel, onAction, style }: EmptyStateProps) {
+  const theme = useTheme();
+  return (
+    <View
+      style={[
+        {
+          alignItems: 'center',
+          justifyContent: 'center',
+          paddingVertical: theme.spacing['2xl'],
+          paddingHorizontal: theme.spacing.xl,
+          gap: theme.spacing.sm,
+        },
+        style,
+      ]}
+    >
+      {icon != null
+        ? typeof icon === 'string'
+          ? <Text style={{ fontSize: 40, lineHeight: 48 }}>{icon}</Text>
+          : icon
+        : null}
+      <Text variant="heading" style={{ textAlign: 'center' }}>
+        {title}
+      </Text>
+      {description ? (
+        <Text variant="muted" style={{ textAlign: 'center' }}>
+          {description}
+        </Text>
+      ) : null}
+      {actionLabel && onAction ? (
+        <Button
+          title={actionLabel}
+          variant="primary"
+          onPress={onAction}
+          style={{ marginTop: theme.spacing.sm, alignSelf: 'stretch' }}
+        />
+      ) : null}
+    </View>
+  );
+}

package/src/components/ErrorBoundary.tsx

@@ -0,0 +1,52 @@
+import { Component, type ReactNode } from 'react';
+import { View } from 'react-native';
+import { Screen } from './Screen';
+import { Text } from './Text';
+import { Alert } from './Alert';
+import { Button } from './Button';
+
+export interface ErrorBoundaryProps {
+  children: ReactNode;
+  /** Custom fallback; receives a `reset` to clear the error and re-render. */
+  fallback?: (reset: () => void, error: Error) => ReactNode;
+  /** Side-effect on catch (logging/telemetry). */
+  onError?: (error: Error) => void;
+}
+
+interface State {
+  error: Error | null;
+}
+
+/** Catches render errors in its subtree and shows a fallback instead of an
+ *  unmounted (blank) tree. Must be a class component (React error boundary). */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
+  state: State = { error: null };
+
+  static getDerivedStateFromError(error: Error): State {
+    return { error };
+  }
+
+  componentDidCatch(error: Error) {
+    this.props.onError?.(error);
+  }
+
+  reset = () => this.setState({ error: null });
+
+  render() {
+    const { error } = this.state;
+    if (error) {
+      if (this.props.fallback) return this.props.fallback(this.reset, error);
+      return (
+        <Screen>
+          <View style={{ flex: 1, justifyContent: 'center', gap: 16 }}>
+            <Alert title="Something went wrong" variant="destructive">
+              An unexpected error occurred.
+            </Alert>
+            <Button title="Try again" variant="primary" onPress={this.reset} />
+          </View>
+        </Screen>
+      );
+    }
+    return this.props.children;
+  }
+}

package/src/components/Flag.tsx

@@ -0,0 +1,26 @@
+import { Image, type StyleProp, type ImageStyle } from 'react-native';
+
+export interface FlagProps {
+  /** ISO 3166-1 alpha-2 country code (e.g. 'EG'), case-insensitive. */
+  code: string;
+  /** Flag width in px; height follows the standard 4:3 ratio. */
+  size?: number;
+  style?: StyleProp<ImageStyle>;
+}
+
+/**
+ * A real country-flag image. Emoji flags ("🇪🇬") fall back to tofu boxes on any
+ * platform without a regional-indicator emoji font (most browsers/OSs outside
+ * Apple), so UI uses this instead. Sourced from the flagcdn image CDN by code.
+ */
+export function Flag({ code, size = 20, style }: FlagProps) {
+  const cc = code.trim().toLowerCase();
+  const height = Math.round((size * 3) / 4);
+  return (
+    <Image
+      accessibilityLabel={code.toUpperCase()}
+      source={{ uri: `https://flagcdn.com/w80/${cc}.png` }}
+      style={[{ width: size, height, borderRadius: 2 }, style]}
+    />
+  );
+}

package/src/components/GradientBox.tsx

@@ -0,0 +1,48 @@
+import { type ReactNode } from 'react';
+import { View, type StyleProp, type ViewStyle } from 'react-native';
+import Svg, { Defs, LinearGradient, Stop, Rect } from 'react-native-svg';
+import { useTheme } from './ThemeProvider';
+
+export interface GradientBoxProps {
+  /** Two or more gradient colors, top-left to bottom-right by default. */
+  colors: string[];
+  /** Gradient direction as fractional coords. Defaults to a 140°-ish diagonal. */
+  start?: { x: number; y: number };
+  end?: { x: number; y: number };
+  borderRadius?: number;
+  style?: StyleProp<ViewStyle>;
+  children?: ReactNode;
+}
+
+let gradSeq = 0;
+
+/** A box whose background is a linear gradient (via react-native-svg), with
+ *  children rendered on top. Generic — heroes, banners, callouts. */
+export function GradientBox({
+  colors,
+  start = { x: 0, y: 0 },
+  end = { x: 1, y: 1 },
+  borderRadius,
+  style,
+  children,
+}: GradientBoxProps) {
+  const theme = useTheme();
+  const id = `grad${gradSeq++}`;
+  const radius = borderRadius ?? theme.radii.lg;
+  const stops = colors.length >= 2 ? colors : [colors[0] ?? theme.colors.primary, colors[0] ?? theme.colors.primary];
+  return (
+    <View style={[{ borderRadius: radius, overflow: 'hidden' }, style]}>
+      <Svg width="100%" height="100%" style={{ position: 'absolute' }}>
+        <Defs>
+          <LinearGradient id={id} x1={start.x} y1={start.y} x2={end.x} y2={end.y}>
+            {stops.map((c, i) => (
+              <Stop key={i} offset={stops.length === 1 ? 0 : i / (stops.length - 1)} stopColor={c} />
+            ))}
+          </LinearGradient>
+        </Defs>
+        <Rect x={0} y={0} width="100%" height="100%" fill={`url(#${id})`} />
+      </Svg>
+      {children}
+    </View>
+  );
+}

package/src/components/HeroBanner.tsx

@@ -0,0 +1,160 @@
+/**
+ * Full-bleed gradient hero region. Composes GradientBox with sensible defaults
+ * for a screen-top hero: rounded corners, generous padding, optional accent
+ * overlay. If `colors` is omitted, derives a 2-stop gradient from the current
+ * accent → deep slate, giving each screen the artist-immersive feel.
+ *
+ * Optional `backdrop` lays an image (e.g. an artist portrait) UNDER the
+ * gradient with low opacity, so the screen reads as "the artist's page".
+ *
+ * Generic — any app can use this for hero sections; the accent comes from
+ * AccentContext, so the colour rotates per the screen's context.
+ */
+import { type ReactNode } from 'react';
+import {
+  Image,
+  View,
+  type ImageSourcePropType,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+import { GradientBox } from './GradientBox';
+import { useTheme } from './ThemeProvider';
+import { useAccent } from './AccentContext';
+
+export interface HeroBannerProps {
+  /** Override the auto-derived gradient. Two or more colours. */
+  colors?: string[];
+  /** Override accent (otherwise pulled from AccentContext). */
+  accent?: string;
+  /**
+   * Optional image laid behind / over the gradient.
+   * - mode 'photo' (default): image is the visual, darkened-bottom overlay so
+   *   text stays legible (Apple-Music album-page hero).
+   * - mode 'tint':            accent gradient is the visual, image overlays at
+   *   low opacity to add texture (data-forward heroes).
+   */
+  backdrop?: ImageSourcePropType;
+  /** How to layer the backdrop. Defaults to 'photo'. */
+  backdropMode?: 'photo' | 'tint';
+  /** Backdrop opacity (0–1). Defaults: photo=0.85, tint=0.22. */
+  backdropOpacity?: number;
+  /** Container style. Margins, padding, borderRadius overrides land here. */
+  style?: StyleProp<ViewStyle>;
+  /** Inner content (numbers, labels). */
+  children?: ReactNode;
+}
+
+export function HeroBanner({
+  colors,
+  accent,
+  backdrop,
+  backdropMode = 'photo',
+  backdropOpacity,
+  style,
+  children,
+}: HeroBannerProps) {
+  const theme = useTheme();
+  const fallbackAccent = useAccent();
+  const stops = colors ?? [accent ?? fallbackAccent, theme.colors.background];
+  const opacity = backdropOpacity ?? (backdropMode === 'tint' ? 0.22 : 0.85);
+
+  // Tint mode: accent gradient is the visual; portrait sits over it at low
+  // opacity for texture. Children render on top of both.
+  if (backdrop && backdropMode === 'tint') {
+    return (
+      <View
+        style={[
+          { borderRadius: theme.radii.lg, overflow: 'hidden' },
+          style,
+        ]}
+      >
+        <View style={{ position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 }}>
+          <GradientBox
+            colors={stops}
+            start={{ x: 0, y: 0 }}
+            end={{ x: 1, y: 1 }}
+            style={{ width: '100%', height: '100%' }}
+          />
+        </View>
+        <View
+          pointerEvents="none"
+          style={{ position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 }}
+        >
+          <Image
+            source={backdrop}
+            style={{ width: '100%', height: '100%', opacity }}
+            resizeMode="cover"
+          />
+        </View>
+        <View
+          style={{
+            paddingVertical: theme.spacing.xl,
+            paddingHorizontal: theme.spacing.lg,
+            gap: theme.spacing.xs,
+          }}
+        >
+          {children}
+        </View>
+      </View>
+    );
+  }
+
+  // If a backdrop is provided we need a clipping wrapper so the image
+  // (absolute-positioned beneath the gradient layer) is rounded to the same
+  // borderRadius as the gradient. Otherwise the GradientBox draws directly.
+  if (backdrop) {
+    // Photo mode: artist photo at full size + a vertical darkening overlay so
+    // text on top stays legible. Accent isn't in the gradient here — the
+    // image itself is the visual.
+    return (
+      <View
+        style={[
+          {
+            borderRadius: theme.radii.lg,
+            overflow: 'hidden',
+            backgroundColor: theme.colors.background,
+          },
+          style,
+        ]}
+      >
+        <Image
+          source={backdrop}
+          style={{ position: 'absolute', top: 0, left: 0, right: 0, bottom: 0, opacity }}
+          resizeMode="cover"
+        />
+        <GradientBox
+          colors={['#00000000', '#000000B3']}
+          start={{ x: 0, y: 0 }}
+          end={{ x: 0, y: 1 }}
+          style={{
+            paddingVertical: theme.spacing.xl,
+            paddingHorizontal: theme.spacing.lg,
+            gap: theme.spacing.xs,
+          }}
+        >
+          {children}
+        </GradientBox>
+      </View>
+    );
+  }
+
+  return (
+    <GradientBox
+      colors={stops}
+      start={{ x: 0, y: 0 }}
+      end={{ x: 1, y: 1 }}
+      borderRadius={theme.radii.lg}
+      style={[
+        {
+          paddingVertical: theme.spacing.xl,
+          paddingHorizontal: theme.spacing.lg,
+          gap: theme.spacing.xs,
+        },
+        style,
+      ]}
+    >
+      {children}
+    </GradientBox>
+  );
+}

package/src/components/Input.tsx

@@ -0,0 +1,33 @@
+import { useState } from 'react';
+import { TextInput, type TextInputProps } from 'react-native';
+import { useTheme } from './ThemeProvider';
+import { inputStyle } from '../styles';
+
+export interface InputProps extends TextInputProps {
+  invalid?: boolean;
+}
+
+/** Themed single-line text field. Mirrors @startsimpli/ui input. */
+export function Input({ invalid = false, style, onFocus, onBlur, ...rest }: InputProps) {
+  const theme = useTheme();
+  const [focused, setFocused] = useState(false);
+  return (
+    <TextInput
+      placeholderTextColor={theme.colors.mutedForeground}
+      style={[
+        inputStyle(theme, { invalid }),
+        focused ? { borderColor: theme.colors.ring } : null,
+        style,
+      ]}
+      onFocus={(e) => {
+        setFocused(true);
+        onFocus?.(e);
+      }}
+      onBlur={(e) => {
+        setFocused(false);
+        onBlur?.(e);
+      }}
+      {...rest}
+    />
+  );
+}

package/src/components/Label.tsx

@@ -0,0 +1,9 @@
+import { Text as RNText, type TextProps } from 'react-native';
+import { useTheme } from './ThemeProvider';
+import { labelStyle } from '../styles';
+
+/** Form field label. */
+export function Label({ style, ...rest }: TextProps) {
+  const theme = useTheme();
+  return <RNText style={[labelStyle(theme), style]} {...rest} />;
+}

package/src/components/ListRow.tsx

@@ -0,0 +1,44 @@
+import { type ReactNode } from 'react';
+import { View, Pressable, Text as RNText, type StyleProp, type ViewStyle } from 'react-native';
+import { useTheme } from './ThemeProvider';
+import { listRowStyle, listRowTitleStyle, listRowSubtitleStyle } from '../styles';
+
+export interface ListRowProps {
+  title: string;
+  subtitle?: string;
+  /** Leading node, e.g. an Avatar or icon. */
+  leading?: ReactNode;
+  /** Trailing node, e.g. a value, Badge, or chevron. */
+  trailing?: ReactNode;
+  /** When set, the row becomes a pressable. */
+  onPress?: () => void;
+  style?: StyleProp<ViewStyle>;
+}
+
+/** Leading · (title / subtitle) · trailing row. Pressable when `onPress` is set. */
+export function ListRow({ title, subtitle, leading, trailing, onPress, style }: ListRowProps) {
+  const theme = useTheme();
+  const content = (
+    <>
+      {leading ? <View>{leading}</View> : null}
+      <View style={{ flex: 1 }}>
+        <RNText style={listRowTitleStyle(theme)}>{title}</RNText>
+        {subtitle ? <RNText style={listRowSubtitleStyle(theme)}>{subtitle}</RNText> : null}
+      </View>
+      {trailing ? <View>{trailing}</View> : null}
+    </>
+  );
+
+  if (onPress) {
+    return (
+      <Pressable
+        accessibilityRole="button"
+        onPress={onPress}
+        style={({ pressed }) => [listRowStyle(theme), pressed ? { opacity: 0.6 } : null, style]}
+      >
+        {content}
+      </Pressable>
+    );
+  }
+  return <View style={[listRowStyle(theme), style]}>{content}</View>;
+}

package/src/components/MetricRow.tsx

@@ -0,0 +1,48 @@
+import { type ReactNode } from 'react';
+import { View, Pressable, Text as RNText, type StyleProp, type ViewStyle } from 'react-native';
+import { useTheme } from './ThemeProvider';
+import { Sparkline } from './Sparkline';
+import { listRowStyle, listRowTitleStyle, listRowSubtitleStyle } from '../styles';
+
+export interface MetricRowProps {
+  /** Leading node (logo / avatar / icon). */
+  leading?: ReactNode;
+  title: string;
+  subtitle?: string;
+  /** Optional inline trend sparkline between subtitle and trailing. */
+  trend?: number[];
+  trendColor?: string;
+  /** Trailing node (delta badge, value column, chevron…). */
+  trailing?: ReactNode;
+  onPress?: () => void;
+  style?: StyleProp<ViewStyle>;
+}
+
+/** Leading · (title/subtitle) · sparkline · trailing row — a ListRow augmented
+ *  with an inline trend. Pressable when `onPress` is set. */
+export function MetricRow({ leading, title, subtitle, trend, trendColor, trailing, onPress, style }: MetricRowProps) {
+  const theme = useTheme();
+  const content = (
+    <>
+      {leading ? <View>{leading}</View> : null}
+      <View style={{ flex: 1 }}>
+        <RNText style={listRowTitleStyle(theme)}>{title}</RNText>
+        {subtitle ? <RNText style={listRowSubtitleStyle(theme)}>{subtitle}</RNText> : null}
+      </View>
+      {trend && trend.length > 0 ? <Sparkline data={trend} color={trendColor} width={54} height={22} /> : null}
+      {trailing ? <View>{trailing}</View> : null}
+    </>
+  );
+  if (onPress) {
+    return (
+      <Pressable
+        accessibilityRole="button"
+        onPress={onPress}
+        style={({ pressed }) => [listRowStyle(theme), pressed ? { opacity: 0.6 } : null, style]}
+      >
+        {content}
+      </Pressable>
+    );
+  }
+  return <View style={[listRowStyle(theme), style]}>{content}</View>;
+}

package/src/components/MultiLineLegend.tsx

@@ -0,0 +1,30 @@
+import { View, type StyleProp, type ViewStyle } from 'react-native';
+import { Text } from './Text';
+
+export interface MultiLineLegendItem {
+  label: string;
+  color: string;
+  /** Optional right-aligned pre-formatted value (e.g. "1.2M"). */
+  value?: string;
+}
+
+export interface MultiLineLegendProps {
+  items: MultiLineLegendItem[];
+  style?: StyleProp<ViewStyle>;
+}
+
+/** Color-swatch legend for multi-series line charts (CompareChart). The swatch
+ *  is a short line — signalling a series, not a donut slice. Wraps to fit. */
+export function MultiLineLegend({ items, style }: MultiLineLegendProps) {
+  return (
+    <View style={[{ flexDirection: 'row', flexWrap: 'wrap', gap: 14 }, style]}>
+      {items.map((it, i) => (
+        <View key={`${it.label}-${i}`} style={{ flexDirection: 'row', alignItems: 'center', gap: 6 }}>
+          <View style={{ width: 14, height: 3, borderRadius: 2, backgroundColor: it.color }} />
+          <Text variant="muted">{it.label}</Text>
+          {it.value ? <Text variant="caption">{it.value}</Text> : null}
+        </View>
+      ))}
+    </View>
+  );
+}

package/src/components/Progress.tsx

@@ -0,0 +1,18 @@
+import { View } from 'react-native';
+import { useTheme } from './ThemeProvider';
+import { progressTrackStyle, progressFillStyle } from '../styles';
+
+export interface ProgressProps {
+  /** 0–100. */
+  value: number;
+}
+
+/** Determinate progress bar. */
+export function Progress({ value }: ProgressProps) {
+  const theme = useTheme();
+  return (
+    <View style={progressTrackStyle(theme)} accessibilityRole="progressbar" accessibilityValue={{ now: value, min: 0, max: 100 }}>
+      <View style={progressFillStyle(theme, value)} />
+    </View>
+  );
+}

package/src/components/Screen.tsx

@@ -0,0 +1,38 @@
+import { ScrollView, View, type ViewProps, type ViewStyle } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { useTheme } from './ThemeProvider';
+
+export interface ScreenProps extends ViewProps {
+  /** Wrap content in a ScrollView (for screens taller than the viewport). */
+  scroll?: boolean;
+  contentContainerStyle?: ViewStyle;
+}
+
+/**
+ * Full-bleed page surface: theme background, standard padding, and safe-area
+ * insets so content clears the status bar / notch and home indicator.
+ */
+export function Screen({ scroll = false, style, contentContainerStyle, children, ...rest }: ScreenProps) {
+  const theme = useTheme();
+  const insets = useSafeAreaInsets();
+
+  const padding: ViewStyle = {
+    paddingTop: insets.top + theme.spacing.sm,
+    paddingBottom: insets.bottom + theme.spacing.sm,
+    paddingHorizontal: theme.spacing.lg,
+  };
+
+  if (scroll) {
+    return (
+      <View style={[{ flex: 1, backgroundColor: theme.colors.background }, style]} {...rest}>
+        <ScrollView contentContainerStyle={[padding, contentContainerStyle]}>{children}</ScrollView>
+      </View>
+    );
+  }
+
+  return (
+    <View style={[{ flex: 1, backgroundColor: theme.colors.background }, padding, style]} {...rest}>
+      {children}
+    </View>
+  );
+}