@startsimpli/ui-native 0.1.1 → 0.1.3

package/src/components/SectionedList.tsx

@@ -0,0 +1,55 @@
+import type { ReactElement } from 'react';
+import { SectionList, Text as RNText, View, type SectionListProps } from 'react-native';
+import { ListControls } from './ListControls';
+import { useServerList } from './useServerList';
+import { useTheme } from './ThemeProvider';
+import type { ServerListProps } from './serverListTypes';
+
+export type SectionedListProps<T, S = { title: string }> = ServerListProps &
+  Pick<SectionListProps<T, S>, 'keyExtractor' | 'renderItem' | 'extraData' | 'contentContainerStyle'> & {
+    sections: ReadonlyArray<S & { data: readonly T[] }>;
+    /** Custom header; defaults to a bold section title. */
+    renderSectionHeader?: (info: { section: S & { data: readonly T[] } }) => ReactElement | null;
+  };
+
+/** Grouped variant of DataList (e.g. to-dos by day). Same server-driven contract: it never regroups or filters rows. */
+export function SectionedList<T, S extends { title: string } = { title: string }>(props: SectionedListProps<T, S>): ReactElement {
+  const { sections, renderItem, keyExtractor, extraData, contentContainerStyle, renderSectionHeader, ListHeaderComponent, testID, search, filters, onFilterChange, onClearFilters, sort } = props;
+  const theme = useTheme();
+  const count = sections.reduce((n, s) => n + s.data.length, 0);
+  const { empty, footer, onEndReached, refreshControl } = useServerList(props, count);
+  const hasControls = !!(search || sort || filters?.length);
+  return (
+    <View style={{ flex: 1 }} testID={testID ? `${testID}-root` : undefined}>
+      {hasControls ? (
+        <View style={{ paddingHorizontal: theme.spacing.lg, paddingTop: theme.spacing.sm }}>
+          <ListControls search={search} filters={filters} onFilterChange={onFilterChange} onClearFilters={onClearFilters} sort={sort} testID={testID} />
+        </View>
+      ) : null}
+      <SectionList
+        testID={testID}
+        sections={sections as any}
+        renderItem={renderItem as any}
+        keyExtractor={keyExtractor}
+        extraData={extraData}
+        stickySectionHeadersEnabled={false}
+        renderSectionHeader={({ section }) =>
+          renderSectionHeader ? renderSectionHeader({ section: section as any }) : (
+            <RNText accessibilityRole="header" style={{ paddingTop: theme.spacing.lg, paddingBottom: theme.spacing.xs, color: theme.colors.mutedForeground, fontSize: theme.fontSizes.sm, fontWeight: '600', textTransform: 'uppercase', backgroundColor: theme.colors.background }}>
+              {(section as any).title}
+            </RNText>
+          )
+        }
+        ListHeaderComponent={ListHeaderComponent ? <>{ListHeaderComponent}</> : undefined}
+        ListEmptyComponent={empty ?? undefined}
+        ListFooterComponent={footer ?? undefined}
+        onEndReached={onEndReached}
+        onEndReachedThreshold={0.5}
+        refreshControl={refreshControl}
+        keyboardShouldPersistTaps="handled"
+        keyboardDismissMode="on-drag"
+        contentContainerStyle={[{ paddingHorizontal: theme.spacing.lg, paddingBottom: theme.spacing.xl, flexGrow: 1 }, contentContainerStyle]}
+      />
+    </View>
+  );
+}

package/src/components/SegmentedControl.tsx

@@ -11,6 +11,8 @@ export interface SegmentedControlProps<T extends string | number> {
   value: T;
   onChange: (value: T) => void;
   style?: StyleProp<ViewStyle>;
+  /** Each option gets testID `${testID}-${value}`. */
+  testID?: string;
 }
 
 /** Mutually-exclusive option selector rendered as a row of Chips. Generic over
@@ -20,11 +22,12 @@ export function SegmentedControl<T extends string | number>({
   value,
   onChange,
   style,
+  testID,
 }: SegmentedControlProps<T>) {
   return (
     <View style={[{ flexDirection: 'row', flexWrap: 'wrap', gap: 8 }, style]}>
       {options.map((o) => (
-        <Chip key={String(o.value)} label={o.label} selected={o.value === value} onPress={() => onChange(o.value)} />
+        <Chip key={String(o.value)} label={o.label} selected={o.value === value} testID={testID ? `${testID}-${o.value}` : undefined} onPress={() => onChange(o.value)} />
       ))}
     </View>
   );

package/src/components/Select.tsx

@@ -0,0 +1,95 @@
+import { useState } from 'react';
+import { Pressable, Text as RNText, View, type StyleProp, type ViewStyle } from 'react-native';
+import { Sheet } from './Sheet';
+import { SearchBar } from './SearchBar';
+import { FormField } from './FormField';
+import { useTheme } from './ThemeProvider';
+import { filterOptions, selectedLabel, type SelectOption } from '../logic/select';
+import { inputStyle } from '../styles';
+
+export type { SelectOption } from '../logic/select';
+
+export interface SelectProps {
+  options: SelectOption[];
+  value: string | null;
+  /** Receives the chosen value, or null when the clear row is picked. */
+  onChange: (value: string | null) => void;
+  label?: string;
+  placeholder?: string;
+  /** Sheet title. Defaults to the label. */
+  title?: string;
+  /** Adds an "all / none" row (e.g. "All projects") that emits null. */
+  clearLabel?: string;
+  /** Shows a search box in the sheet. */
+  searchable?: boolean;
+  error?: string;
+  disabled?: boolean;
+  /** Pill-sized trigger for filter bars. */
+  compact?: boolean;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+/** Picker: a field-style trigger that opens a bottom Sheet of options. */
+export function Select({ options, value, onChange, label, placeholder = 'Select', title, clearLabel, searchable, error, disabled, compact, style, testID }: SelectProps) {
+  const theme = useTheme();
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState('');
+  const current = selectedLabel(options, value);
+  const id = (s: string) => (testID ? `${testID}-${s}` : undefined);
+  const close = () => { setOpen(false); setQuery(''); };
+  const pick = (v: string | null) => { onChange(v); close(); };
+
+  const row = (key: string, text: string, selected: boolean, onPress: () => void, tid?: string, description?: string) => (
+    <Pressable
+      key={key}
+      testID={tid}
+      accessibilityRole="button"
+      accessibilityState={{ selected }}
+      onPress={onPress}
+      style={({ pressed }) => ({ minHeight: 48, flexDirection: 'row', alignItems: 'center', gap: theme.spacing.md, borderBottomWidth: 1, borderBottomColor: theme.colors.border, opacity: pressed ? 0.6 : 1 })}
+    >
+      <View style={{ flex: 1 }}>
+        <RNText style={{ color: theme.colors.foreground, fontSize: theme.fontSizes.base, fontWeight: selected ? '600' : '400' }}>{text}</RNText>
+        {description ? <RNText style={{ color: theme.colors.mutedForeground, fontSize: theme.fontSizes.sm }}>{description}</RNText> : null}
+      </View>
+      {selected ? <RNText style={{ color: theme.colors.primary, fontSize: theme.fontSizes.lg }}>✓</RNText> : null}
+    </Pressable>
+  );
+
+  const shown = filterOptions(options, query);
+  const trigger = (
+    <Pressable
+      testID={testID}
+      accessibilityRole="button"
+      accessibilityLabel={`${label ?? placeholder}: ${current ?? 'none selected'}`}
+      accessibilityState={{ disabled: !!disabled, expanded: open }}
+      disabled={disabled}
+      onPress={() => setOpen(true)}
+      style={({ pressed }) => [
+        compact
+          ? { flexDirection: 'row', alignItems: 'center', gap: 6, paddingHorizontal: theme.spacing.md, paddingVertical: 6, borderRadius: theme.radii.full, borderWidth: 1, borderColor: value != null ? theme.colors.primary : theme.colors.border, backgroundColor: value != null ? theme.colors.primary : 'transparent' }
+          : { ...(inputStyle(theme, { invalid: !!error }) as ViewStyle), flexDirection: 'row', alignItems: 'center', justifyContent: 'space-between' },
+        disabled ? { opacity: 0.5 } : null,
+        pressed ? { opacity: 0.7 } : null,
+      ]}
+    >
+      <RNText numberOfLines={1} style={{ flexShrink: 1, fontSize: compact ? theme.fontSizes.sm : theme.fontSizes.base, color: compact ? (value != null ? theme.colors.primaryForeground : theme.colors.mutedForeground) : current ? theme.colors.foreground : theme.colors.mutedForeground }}>
+        {current ?? (compact && label ? label : placeholder)}
+      </RNText>
+      <RNText style={{ color: compact && value != null ? theme.colors.primaryForeground : theme.colors.mutedForeground }}>▾</RNText>
+    </Pressable>
+  );
+
+  return (
+    <>
+      {compact ? <View style={style}>{trigger}</View> : <FormField label={label} error={error} style={style}>{trigger}</FormField>}
+      <Sheet visible={open} onClose={close} title={title ?? label ?? placeholder} testID={id('sheet')}>
+        {searchable ? <SearchBar testID={id('search-input')} value={query} onChangeText={setQuery} style={{ marginBottom: theme.spacing.sm }} /> : null}
+        {clearLabel ? row('__clear', clearLabel, value == null, () => pick(null), id('clear')) : null}
+        {shown.map((o) => row(o.value, o.label, o.value === value, () => pick(o.value), id(`option-${o.value}`), o.description))}
+        {!shown.length ? <RNText style={{ color: theme.colors.mutedForeground, paddingVertical: theme.spacing.lg }}>No matches</RNText> : null}
+      </Sheet>
+    </>
+  );
+}

package/src/components/Sheet.tsx

@@ -0,0 +1,41 @@
+import type { ReactNode } from 'react';
+import { Modal, Pressable, ScrollView, Text as RNText, View, useWindowDimensions } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { useTheme } from './ThemeProvider';
+import { sheetBackdropStyle, sheetGrabberStyle, sheetPanelStyle } from '../styles-overlay';
+import { textStyle } from '../styles';
+
+export interface SheetProps {
+  visible: boolean;
+  onClose: () => void;
+  title?: string;
+  children?: ReactNode;
+  /** Fraction of the window height the sheet may fill. Default 0.85. */
+  maxHeightRatio?: number;
+  testID?: string;
+}
+
+/** Bottom sheet over a dimmed backdrop. Tap the backdrop (or swipe back / hardware back) to dismiss. */
+export function Sheet({ visible, onClose, title, children, maxHeightRatio = 0.85, testID }: SheetProps) {
+  const theme = useTheme();
+  const insets = useSafeAreaInsets();
+  const { height } = useWindowDimensions();
+  return (
+    <Modal visible={visible} transparent animationType="slide" onRequestClose={onClose} testID={testID}>
+      <View style={{ flex: 1, justifyContent: 'flex-end' }}>
+        <Pressable
+          testID={testID ? `${testID}-backdrop` : undefined}
+          accessibilityRole="button"
+          accessibilityLabel="Dismiss"
+          onPress={onClose}
+          style={sheetBackdropStyle()}
+        />
+        <View accessibilityViewIsModal style={sheetPanelStyle(theme, height * maxHeightRatio, insets.bottom)}>
+          <View style={sheetGrabberStyle(theme)} />
+          {title ? <RNText accessibilityRole="header" style={[textStyle(theme, 'heading'), { marginBottom: theme.spacing.md }]}>{title}</RNText> : null}
+          <ScrollView keyboardShouldPersistTaps="handled">{children}</ScrollView>
+        </View>
+      </View>
+    </Modal>
+  );
+}

package/src/components/StatusChip.tsx

@@ -0,0 +1,27 @@
+import { Text as RNText, View, type StyleProp, type ViewStyle } from 'react-native';
+import { useTheme } from './ThemeProvider';
+import { badgeStyle, badgeTextStyle } from '../styles';
+import { formatProgress, statusTone } from '../logic/status';
+
+export interface StatusChipProps {
+  /** Domain status, e.g. queued / processing / done / failed. */
+  status: string;
+  /** 0..1. Appends a percent to the label. */
+  progress?: number;
+  /** Overrides the derived label. */
+  label?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+/** Badge that maps a domain status (and optional progress) to a themed variant. */
+export function StatusChip({ status, progress, label, style, testID }: StatusChipProps) {
+  const theme = useTheme();
+  const tone = statusTone(status);
+  const text = `${label ?? tone.label}${progress != null ? ` ${formatProgress(progress)}` : ''}`;
+  return (
+    <View testID={testID} accessible accessibilityLabel={text} style={[badgeStyle(theme, tone.variant), style]}>
+      <RNText style={badgeTextStyle(theme, tone.variant)}>{text}</RNText>
+    </View>
+  );
+}

package/src/components/SwipeRow.tsx

@@ -0,0 +1,85 @@
+import { useMemo, useRef, type ReactNode } from 'react';
+import { Animated, PanResponder, Pressable, Text as RNText, View } from 'react-native';
+import { useTheme } from './ThemeProvider';
+import { swipeActionStyle, swipeActionTextStyle, type SwipeTone } from '../styles-overlay';
+import { clampSwipe, settleSwipe } from '../logic/swipe';
+
+export interface SwipeAction {
+  key: string;
+  label: string;
+  onPress: () => void;
+  tone?: SwipeTone;
+}
+
+export interface SwipeRowProps {
+  /** Trailing actions revealed by swiping left (and exposed to VoiceOver as custom actions). */
+  actions: SwipeAction[];
+  children: ReactNode;
+  /** Width of each action button. Default 84. */
+  actionWidth?: number;
+  /** Start with the actions revealed. */
+  defaultOpen?: boolean;
+  testID?: string;
+}
+
+/** Row that reveals trailing actions (done / delete ...) on a left swipe. Core RN only. */
+export function SwipeRow({ actions, children, actionWidth = 84, defaultOpen = false, testID }: SwipeRowProps) {
+  const theme = useTheme();
+  const total = actionWidth * actions.length;
+  const x = useRef(new Animated.Value(defaultOpen ? -total : 0)).current;
+  const offset = useRef(defaultOpen ? -total : 0);
+  const start = useRef(0);
+
+  const settle = (to: number) => {
+    offset.current = to;
+    Animated.spring(x, { toValue: to, useNativeDriver: true, bounciness: 0 }).start();
+  };
+
+  const pan = useMemo(
+    () =>
+      PanResponder.create({
+        // Horizontal intent only, so vertical list scrolling wins otherwise.
+        onMoveShouldSetPanResponder: (_e, g) => Math.abs(g.dx) > 10 && Math.abs(g.dx) > Math.abs(g.dy) * 1.5,
+        onPanResponderGrant: () => { start.current = offset.current; },
+        onPanResponderMove: (_e, g) => x.setValue(clampSwipe(start.current + g.dx, total)),
+        onPanResponderRelease: (_e, g) => {
+          const at = clampSwipe(start.current + g.dx, total);
+          settle(settleSwipe(at, g.vx, total) === 'open' ? -total : 0);
+        },
+        onPanResponderTerminate: () => settle(offset.current),
+      }),
+    [total], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+
+  const run = (a: SwipeAction) => { settle(0); a.onPress(); };
+
+  return (
+    <View
+      testID={testID}
+      accessibilityActions={actions.map((a) => ({ name: a.key, label: a.label }))}
+      onAccessibilityAction={(e) => {
+        const a = actions.find((x2) => x2.key === e.nativeEvent.actionName);
+        if (a) a.onPress();
+      }}
+      style={{ overflow: 'hidden' }}
+    >
+      <View style={{ position: 'absolute', top: 0, right: 0, bottom: 0, flexDirection: 'row' }}>
+        {actions.map((a) => (
+          <Pressable
+            key={a.key}
+            testID={testID ? `${testID}-action-${a.key}` : undefined}
+            accessibilityRole="button"
+            accessibilityLabel={a.label}
+            onPress={() => run(a)}
+            style={swipeActionStyle(theme, a.tone ?? 'neutral', actionWidth)}
+          >
+            <RNText style={swipeActionTextStyle(theme, a.tone ?? 'neutral')}>{a.label}</RNText>
+          </Pressable>
+        ))}
+      </View>
+      <Animated.View {...pan.panHandlers} style={{ transform: [{ translateX: x }], backgroundColor: theme.colors.background }}>
+        {children}
+      </Animated.View>
+    </View>
+  );
+}

package/src/components/TabBar.tsx

@@ -41,7 +41,7 @@ export function TabBar({ items, activeKey, onChange, style }: TabBarProps) {
             style={tabItemStyle(theme)}
           >
             {item.icon?.({ active, color })}
-            <RNText style={tabLabelStyle(theme, active)}>{item.label}</RNText>
+            <RNText numberOfLines={1} ellipsizeMode="tail" style={tabLabelStyle(theme, active)}>{item.label}</RNText>
           </Pressable>
         );
       })}

package/src/components/TextArea.tsx

@@ -0,0 +1,38 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import { Input, type InputProps } from './Input';
+import { FormField } from './FormField';
+
+export interface TextAreaProps extends Omit<InputProps, 'multiline' | 'invalid'> {
+  label?: string;
+  hint?: string;
+  error?: string;
+  required?: boolean;
+  /** Visible lines at rest. Default 4. */
+  rows?: number;
+  containerStyle?: StyleProp<ViewStyle>;
+}
+
+/** Multiline Input wrapped in a FormField (label, hint, error, optional char counter with maxLength). */
+export function TextArea({ label, hint, error, required, rows = 4, containerStyle, style, maxLength, value, accessibilityLabel, ...rest }: TextAreaProps) {
+  return (
+    <FormField
+      label={label}
+      hint={hint}
+      error={error}
+      required={required}
+      style={containerStyle}
+      footerRight={maxLength ? `${(value ?? '').length}/${maxLength}` : undefined}
+    >
+      <Input
+        multiline
+        textAlignVertical="top"
+        value={value}
+        maxLength={maxLength}
+        invalid={!!error}
+        accessibilityLabel={accessibilityLabel ?? label}
+        style={[{ minHeight: rows * 22 + 16 }, style]}
+        {...rest}
+      />
+    </FormField>
+  );
+}

package/src/components/Toast.tsx

@@ -0,0 +1,61 @@
+import { createContext, useContext, useEffect, useMemo, useRef, useSyncExternalStore, type ReactNode } from 'react';
+import { Pressable, Text as RNText, View } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { useTheme } from './ThemeProvider';
+import { toastStyle, toastTextStyle } from '../styles-overlay';
+import { createToastStore, type ToastItem, type ToastOptions } from '../logic/toast';
+
+export type { ToastOptions, ToastTone } from '../logic/toast';
+
+export interface ToastApi {
+  show: (message: string, options?: ToastOptions) => string;
+  dismiss: (id: string) => void;
+  clear: () => void;
+}
+
+const ToastContext = createContext<ToastApi | null>(null);
+
+function ToastView({ toast, onDismiss }: { toast: ToastItem; onDismiss: (id: string) => void }) {
+  const theme = useTheme();
+  useEffect(() => {
+    if (toast.durationMs <= 0) return;
+    const t = setTimeout(() => onDismiss(toast.id), toast.durationMs);
+    return () => clearTimeout(t);
+  }, [toast.id, toast.durationMs, onDismiss]);
+  return (
+    <Pressable
+      testID={`toast-${toast.tone}`}
+      accessibilityRole="alert"
+      accessibilityLiveRegion="polite"
+      accessibilityLabel={toast.message}
+      accessibilityHint="Tap to dismiss"
+      onPress={() => onDismiss(toast.id)}
+      style={toastStyle(theme, toast.tone)}
+    >
+      <RNText style={toastTextStyle(theme, toast.tone)}>{toast.message}</RNText>
+    </Pressable>
+  );
+}
+
+/** Mount once near the root (inside ThemeProvider). Renders toasts at the top of the screen. */
+export function ToastProvider({ children }: { children: ReactNode }) {
+  const theme = useTheme();
+  const insets = useSafeAreaInsets();
+  const store = useRef(createToastStore()).current;
+  const toasts = useSyncExternalStore(store.subscribe, store.getToasts, store.getToasts);
+  const api = useMemo<ToastApi>(() => ({ show: store.show, dismiss: store.dismiss, clear: store.clear }), [store]);
+  return (
+    <ToastContext.Provider value={api}>
+      {children}
+      <View pointerEvents="box-none" style={{ position: 'absolute', top: insets.top + theme.spacing.sm, left: theme.spacing.lg, right: theme.spacing.lg, gap: theme.spacing.sm }}>
+        {toasts.map((t) => <ToastView key={t.id} toast={t} onDismiss={store.dismiss} />)}
+      </View>
+    </ToastContext.Provider>
+  );
+}
+
+export function useToast(): ToastApi {
+  const ctx = useContext(ToastContext);
+  if (!ctx) throw new Error('useToast must be used inside a <ToastProvider>');
+  return ctx;
+}

package/src/components/serverListTypes.ts

@@ -0,0 +1,53 @@
+import type { ReactNode } from 'react';
+import type { FilterGroup } from '../logic/listState';
+
+export type { FilterGroup, FilterOption } from '../logic/listState';
+
+export interface ListSearch {
+  /** Controlled text shown in the field. */
+  value: string;
+  /** Fires on every keystroke (update your input state here). */
+  onChange: (text: string) => void;
+  /** Fires debounced, and immediately on submit / clear. Run the server query here. */
+  onSearch: (text: string) => void;
+  debounceMs?: number;
+  placeholder?: string;
+}
+
+export interface ListSort {
+  value: string;
+  options: Array<{ value: string; label: string }>;
+  onChange: (value: string) => void;
+}
+
+/**
+ * Props shared by DataList and SectionedList. Everything is server-driven: the
+ * list never filters, sorts or slices rows itself, it only reports what the user
+ * asked for and renders what it is given.
+ */
+export interface ServerListProps {
+  loading?: boolean;
+  refreshing?: boolean;
+  onRefresh?: () => void;
+  /** Error message. With no rows it is the full-screen error; with rows it is the paging footer error. */
+  error?: string | null;
+  onRetry?: () => void;
+  hasMore?: boolean;
+  loadingMore?: boolean;
+  /** Called at most once per loaded length when the end is reached. */
+  onLoadMore?: () => void;
+  search?: ListSearch;
+  filters?: FilterGroup[];
+  /** value null clears that group. */
+  onFilterChange?: (key: string, value: string | null) => void;
+  /** Clears search text and every filter. Shown in the summary and the no-results state. */
+  onClearFilters?: () => void;
+  sort?: ListSort;
+  emptyTitle?: string;
+  emptyDescription?: string;
+  noResultsTitle?: string;
+  noResultsDescription?: string;
+  /** Rendered above the rows inside the scroll area. */
+  ListHeaderComponent?: ReactNode;
+  testID?: string;
+}

package/src/components/useServerList.tsx

@@ -0,0 +1,58 @@
+import { useEffect, useRef, type ReactElement } from 'react';
+import { RefreshControl, Text as RNText, View } from 'react-native';
+import { Button } from './Button';
+import { EmptyState } from './EmptyState';
+import { SkeletonList } from './SkeletonList';
+import { Spinner } from './Spinner';
+import { useTheme } from './ThemeProvider';
+import { errorTextColor } from '../styles-overlay';
+import { createLoadMoreGuard, resolveListState, summarizeFilters } from '../logic/listState';
+import type { ServerListProps } from './serverListTypes';
+
+/** Behaviour shared by DataList and SectionedList: state views, the paging guard, footer and refresh control. */
+export function useServerList(p: ServerListProps, itemCount: number) {
+  const theme = useTheme();
+  const guard = useRef(createLoadMoreGuard()).current;
+  const id = (s: string) => (p.testID ? `${p.testID}-${s}` : undefined);
+  const summary = summarizeFilters(p.filters ?? [], p.search?.value ?? '');
+  const signature = `${summary.labels.join('|')}#${p.sort?.value ?? ''}`;
+
+  // A new query, refresh or initial load starts a new paging sequence.
+  useEffect(() => { guard.reset(); }, [guard, signature, p.loading, p.refreshing]);
+
+  const state = resolveListState({ itemCount, loading: p.loading, refreshing: p.refreshing, error: p.error, hasActiveQuery: summary.count > 0 });
+  const retry = () => { guard.reset(); p.onRetry?.(); };
+
+  let empty: ReactElement | null = null;
+  if (state === 'loading') {
+    empty = <View testID={id('loading')} style={{ paddingTop: theme.spacing.sm }}><SkeletonList count={4} height={64} /></View>;
+  } else if (state === 'error') {
+    empty = <EmptyState testID={id('error')} icon="⚠️" title="Something went wrong" description={p.error ?? undefined} actionLabel={p.onRetry ? 'Retry' : undefined} onAction={retry} actionTestID={id('retry')} />;
+  } else if (state === 'noResults') {
+    empty = <EmptyState testID={id('no-results')} icon="🔍" title={p.noResultsTitle ?? 'No results'} description={p.noResultsDescription ?? 'Try a different search or clear the filters.'} actionLabel={p.onClearFilters ? 'Clear filters' : undefined} onAction={p.onClearFilters} actionTestID={id('empty-clear')} />;
+  } else if (state === 'empty') {
+    empty = <EmptyState testID={id('empty')} title={p.emptyTitle ?? 'Nothing here yet'} description={p.emptyDescription} />;
+  }
+
+  let footer: ReactElement | null = null;
+  if (state === 'content') {
+    if (p.error) {
+      footer = (
+        <View testID={id('footer-error')} style={{ alignItems: 'center', gap: theme.spacing.sm, paddingVertical: theme.spacing.lg }}>
+          <RNText accessibilityRole="alert" style={{ color: errorTextColor(theme), fontSize: theme.fontSizes.sm }}>{p.error}</RNText>
+          {p.onRetry ? <Button testID={id('footer-retry')} title="Retry" variant="outline" size="sm" onPress={retry} /> : null}
+        </View>
+      );
+    } else if (p.loadingMore) {
+      footer = <View testID={id('footer-loading')} style={{ paddingVertical: theme.spacing.lg }}><Spinner /></View>;
+    }
+  }
+
+  const onEndReached = () => {
+    if (guard.tryStart({ hasMore: !!p.hasMore, loading: !!p.loading, loadingMore: !!p.loadingMore, error: !!p.error }, itemCount)) p.onLoadMore?.();
+  };
+
+  const refreshControl = p.onRefresh ? <RefreshControl refreshing={!!p.refreshing} onRefresh={p.onRefresh} tintColor={theme.colors.mutedForeground} /> : undefined;
+
+  return { empty, footer, onEndReached, refreshControl, state };
+}

package/src/index.ts

@@ -62,3 +62,23 @@ export { GradientBox, type GradientBoxProps } from './components/GradientBox';
 export { HeroBanner, type HeroBannerProps } from './components/HeroBanner';
 export { AccentProvider, useAccent } from './components/AccentContext';
 export { DataTable, type DataTableProps, type DataColumn, type DataRow } from './components/DataTable';
+
+// Tandem-screen primitives: rich text, overlays, forms, server-driven lists, chat
+export { Markdown, type MarkdownProps } from './components/Markdown';
+export { parseMarkdown, parseInline, type Block as MarkdownBlock, type Inline as MarkdownInline } from './logic/markdown';
+export { Sheet, type SheetProps } from './components/Sheet';
+export { Select, type SelectProps, type SelectOption } from './components/Select';
+export { FormField, type FormFieldProps } from './components/FormField';
+export { TextArea, type TextAreaProps } from './components/TextArea';
+export { SearchBar, type SearchBarProps } from './components/SearchBar';
+export { Header, type HeaderProps } from './components/Header';
+export { StatusChip, type StatusChipProps } from './components/StatusChip';
+export { statusTone, formatProgress } from './logic/status';
+export { SwipeRow, type SwipeRowProps, type SwipeAction } from './components/SwipeRow';
+export { ToastProvider, useToast, type ToastApi, type ToastOptions, type ToastTone } from './components/Toast';
+export { MessageBubble, type MessageBubbleProps } from './components/MessageBubble';
+export { ChatComposer, type ChatComposerProps } from './components/ChatComposer';
+export { DataList, type DataListProps } from './components/DataList';
+export { SectionedList, type SectionedListProps } from './components/SectionedList';
+export type { ServerListProps, ListSearch, ListSort, FilterGroup, FilterOption } from './components/serverListTypes';
+export { resolveListState, createLoadMoreGuard, createDebouncer, summarizeFilters, type ListViewState } from './logic/listState';

package/src/logic/chat.ts

@@ -0,0 +1,3 @@
+export function canSend(text: string, sending: boolean): boolean {
+  return !sending && text.trim().length > 0;
+}

package/src/logic/listState.ts

@@ -0,0 +1,77 @@
+/** Pure state logic for server-driven lists. Nothing here ever sees the full
+ *  dataset: search, filter, sort and paging all belong to the server. */
+
+export type ListViewState = 'loading' | 'error' | 'noResults' | 'empty' | 'content';
+
+export interface ListStateInput {
+  itemCount: number;
+  loading?: boolean;
+  refreshing?: boolean;
+  error?: unknown;
+  /** True when a search query or filter is applied (empty then means "no results"). */
+  hasActiveQuery?: boolean;
+}
+
+export function resolveListState(i: ListStateInput): ListViewState {
+  if (i.itemCount > 0) return 'content';
+  if (i.error) return 'error';
+  if (i.loading && !i.refreshing) return 'loading';
+  return i.hasActiveQuery ? 'noResults' : 'empty';
+}
+
+export interface LoadMoreState {
+  hasMore: boolean;
+  loading: boolean;
+  loadingMore: boolean;
+  error: boolean;
+}
+
+/** Stops onEndReached (which fires repeatedly) from requesting the same page
+ *  twice: one request per data length until the data grows or reset() is called. */
+export function createLoadMoreGuard() {
+  let lastToken: number | null = null;
+  return {
+    tryStart(s: LoadMoreState, token: number): boolean {
+      if (!s.hasMore || s.loading || s.loadingMore || s.error) return false;
+      if (lastToken === token) return false;
+      lastToken = token;
+      return true;
+    },
+    reset() { lastToken = null; },
+  };
+}
+
+export function createDebouncer<T>(fn: (v: T) => void, ms: number) {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let pending: { v: T } | null = null;
+  const clear = () => { if (timer) clearTimeout(timer); timer = null; };
+  const fire = () => { clear(); if (pending) { const { v } = pending; pending = null; fn(v); } };
+  return {
+    call(v: T) { pending = { v }; clear(); timer = setTimeout(fire, ms); },
+    flush: fire,
+    cancel() { clear(); pending = null; },
+  };
+}
+
+export interface FilterOption { value: string; label: string }
+export interface FilterGroup {
+  key: string;
+  label: string;
+  options: FilterOption[];
+  /** Selected option value, or null when the filter is off. */
+  value: string | null;
+  /** 'chips' (default) for few options, 'select' opens a Sheet picker. */
+  display?: 'chips' | 'select';
+}
+
+export function summarizeFilters(groups: FilterGroup[], query = ''): { count: number; labels: string[] } {
+  const labels: string[] = [];
+  for (const g of groups) {
+    if (g.value == null) continue;
+    const opt = g.options.find((o) => o.value === g.value);
+    labels.push(`${g.label}: ${opt?.label ?? g.value}`);
+  }
+  const q = query.trim();
+  if (q) labels.push(`"${q}"`);
+  return { count: labels.length, labels };
+}