@startsimpli/ui-native 0.1.0 → 0.1.2

package/src/__tests__/logic-list.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { resolveListState, createLoadMoreGuard, createDebouncer, summarizeFilters } from '../logic/listState';
+
+describe('resolveListState', () => {
+  it('loading only when nothing is shown yet', () => {
+    expect(resolveListState({ itemCount: 0, loading: true })).toBe('loading');
+    expect(resolveListState({ itemCount: 5, loading: true })).toBe('content');
+  });
+  it('refreshing an empty list is not the skeleton', () => {
+    expect(resolveListState({ itemCount: 0, loading: true, refreshing: true })).toBe('empty');
+  });
+  it('error wins over empty but not over content', () => {
+    expect(resolveListState({ itemCount: 0, error: 'boom' })).toBe('error');
+    expect(resolveListState({ itemCount: 2, error: 'boom' })).toBe('content');
+  });
+  it('empty with an active query/filter is noResults', () => {
+    expect(resolveListState({ itemCount: 0, hasActiveQuery: true })).toBe('noResults');
+    expect(resolveListState({ itemCount: 0 })).toBe('empty');
+  });
+});
+
+describe('createLoadMoreGuard', () => {
+  const ok = { hasMore: true, loading: false, loadingMore: false, error: false };
+  it('allows one fetch per data length (no duplicate pages)', () => {
+    const g = createLoadMoreGuard();
+    expect(g.tryStart(ok, 20)).toBe(true);
+    expect(g.tryStart(ok, 20)).toBe(false);
+    expect(g.tryStart(ok, 20)).toBe(false);
+    expect(g.tryStart(ok, 40)).toBe(true);
+  });
+  it('refuses when no more, loading, loadingMore or error', () => {
+    const g = createLoadMoreGuard();
+    expect(g.tryStart({ ...ok, hasMore: false }, 1)).toBe(false);
+    expect(g.tryStart({ ...ok, loading: true }, 2)).toBe(false);
+    expect(g.tryStart({ ...ok, loadingMore: true }, 3)).toBe(false);
+    expect(g.tryStart({ ...ok, error: true }, 4)).toBe(false);
+  });
+  it('refused attempts do not burn the token', () => {
+    const g = createLoadMoreGuard();
+    g.tryStart({ ...ok, loadingMore: true }, 20);
+    expect(g.tryStart(ok, 20)).toBe(true);
+  });
+  it('reset allows retrying the same length (refresh / retry / new query)', () => {
+    const g = createLoadMoreGuard();
+    g.tryStart(ok, 20);
+    g.reset();
+    expect(g.tryStart(ok, 20)).toBe(true);
+  });
+});
+
+describe('createDebouncer', () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+  it('fires once with the last value after the quiet period', () => {
+    const fn = vi.fn();
+    const d = createDebouncer(fn, 300);
+    d.call('a'); vi.advanceTimersByTime(200);
+    d.call('ab'); vi.advanceTimersByTime(299);
+    expect(fn).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(1);
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenCalledWith('ab');
+  });
+  it('flush fires immediately, cancel drops', () => {
+    const fn = vi.fn();
+    const d = createDebouncer(fn, 300);
+    d.call('x'); d.flush();
+    expect(fn).toHaveBeenCalledWith('x');
+    d.call('y'); d.cancel(); vi.advanceTimersByTime(1000);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('summarizeFilters', () => {
+  const groups = [
+    { key: 'project', label: 'Project', options: [{ value: 'p1', label: 'Alpha' }], value: 'p1' },
+    { key: 'status', label: 'Status', options: [{ value: 'open', label: 'Open' }], value: null },
+  ];
+  it('lists only active groups with option labels', () => {
+    expect(summarizeFilters(groups)).toEqual({ count: 1, labels: ['Project: Alpha'] });
+  });
+  it('counts a search query', () => {
+    expect(summarizeFilters(groups, 'milk')).toEqual({ count: 2, labels: ['Project: Alpha', '"milk"'] });
+  });
+  it('empty when nothing active', () => {
+    expect(summarizeFilters([groups[1]], '  ')).toEqual({ count: 0, labels: [] });
+  });
+});

package/src/__tests__/logic-markdown.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { parseMarkdown, parseInline } from '../logic/markdown';
+
+describe('parseInline', () => {
+  it('plain text', () => expect(parseInline('hi')).toEqual([{ type: 'text', text: 'hi' }]));
+  it('bold, italic, code', () => {
+    expect(parseInline('a **b** *c* `d`')).toEqual([
+      { type: 'text', text: 'a ' },
+      { type: 'bold', children: [{ type: 'text', text: 'b' }] },
+      { type: 'text', text: ' ' },
+      { type: 'italic', children: [{ type: 'text', text: 'c' }] },
+      { type: 'text', text: ' ' },
+      { type: 'code', text: 'd' },
+    ]);
+  });
+  it('links keep http(s)/mailto/tel only', () => {
+    expect(parseInline('[x](https://a.com)')).toEqual([{ type: 'link', href: 'https://a.com', children: [{ type: 'text', text: 'x' }] }]);
+    expect(parseInline('[x](javascript:alert(1))')).toEqual([{ type: 'text', text: 'x' }]);
+  });
+  it('unclosed markers stay literal', () => expect(parseInline('a **b')).toEqual([{ type: 'text', text: 'a **b' }]));
+  it('bold with nested italic', () => {
+    expect(parseInline('**a *b***')).toEqual([{ type: 'bold', children: [{ type: 'text', text: 'a ' }, { type: 'italic', children: [{ type: 'text', text: 'b' }] }] }]);
+  });
+});
+
+describe('parseMarkdown', () => {
+  it('headings, paragraphs, bullets, numbered, quote, rule, code', () => {
+    const src = ['# T', '', 'para one', 'still one', '', '- a', '* b **x**', '', '1. one', '2. two', '', '> q', '', '---', '', '```', 'code **raw**', '```'].join('\n');
+    const b = parseMarkdown(src);
+    expect(b.map((x) => x.type)).toEqual(['heading', 'paragraph', 'bullets', 'numbered', 'quote', 'rule', 'code']);
+    expect(b[0]).toMatchObject({ type: 'heading', level: 1 });
+    expect(b[1]).toEqual({ type: 'paragraph', inlines: [{ type: 'text', text: 'para one\nstill one' }] });
+    expect((b[2] as any).items).toHaveLength(2);
+    expect(b[6]).toEqual({ type: 'code', text: 'code **raw**' });
+  });
+  it('heading levels clamp to 3', () => expect(parseMarkdown('#### deep')[0]).toMatchObject({ type: 'heading', level: 3 }));
+  it('empty / whitespace gives no blocks', () => expect(parseMarkdown('  \n\n')).toEqual([]));
+  it('unterminated code fence consumes the rest', () => expect(parseMarkdown('```\na\nb')).toEqual([{ type: 'code', text: 'a\nb' }]));
+});

package/src/__tests__/logic-misc.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest';
+import { clampSwipe, settleSwipe } from '../logic/swipe';
+import { createToastStore } from '../logic/toast';
+import { canSend } from '../logic/chat';
+import { statusTone, formatProgress } from '../logic/status';
+import { filterOptions, selectedLabel } from '../logic/select';
+
+describe('swipe', () => {
+  it('clamps between -actionsWidth (open) and 0', () => {
+    expect(clampSwipe(-300, 160)).toBe(-160);
+    expect(clampSwipe(40, 160)).toBe(0);
+    expect(clampSwipe(-50, 160)).toBe(-50);
+  });
+  it('settles open past half or on a fast left fling, closed otherwise', () => {
+    expect(settleSwipe(-90, 0, 160)).toBe('open');
+    expect(settleSwipe(-30, -0.8, 160)).toBe('open');
+    expect(settleSwipe(-90, 0.8, 160)).toBe('closed');
+    expect(settleSwipe(-30, 0, 160)).toBe('closed');
+  });
+});
+
+describe('toast store', () => {
+  it('show/dismiss/clear notify subscribers', () => {
+    let n = 0;
+    const s = createToastStore();
+    s.subscribe(() => { n++; });
+    const a = s.show('Saved');
+    const b = s.show('Oops', { tone: 'error', durationMs: 0 });
+    expect(s.getToasts().map((t) => [t.id, t.message, t.tone])).toEqual([[a, 'Saved', 'info'], [b, 'Oops', 'error']]);
+    expect(s.getToasts()[0].durationMs).toBe(3000);
+    s.dismiss(a);
+    expect(s.getToasts()).toHaveLength(1);
+    s.clear();
+    expect(s.getToasts()).toEqual([]);
+    expect(n).toBe(4);
+  });
+  it('unsubscribe stops notifications; dismissing unknown id is a no-op', () => {
+    let n = 0;
+    const s = createToastStore();
+    const off = s.subscribe(() => { n++; });
+    off();
+    s.show('x'); s.dismiss('nope');
+    expect(n).toBe(0);
+  });
+});
+
+describe('canSend', () => {
+  it('needs non-blank text and not already sending', () => {
+    expect(canSend('hi', false)).toBe(true);
+    expect(canSend('  \n', false)).toBe(false);
+    expect(canSend('hi', true)).toBe(false);
+    expect(canSend('', false)).toBe(false);
+  });
+});
+
+describe('status', () => {
+  it('maps domain statuses onto badge variants', () => {
+    expect(statusTone('queued')).toEqual({ variant: 'secondary', label: 'Queued' });
+    expect(statusTone('processing').variant).toBe('default');
+    expect(statusTone('Transcribing').variant).toBe('default');
+    expect(statusTone('done')).toEqual({ variant: 'success', label: 'Done' });
+    expect(statusTone('ready').variant).toBe('success');
+    expect(statusTone('failed')).toEqual({ variant: 'destructive', label: 'Failed' });
+    expect(statusTone('partial').variant).toBe('warning');
+    expect(statusTone('weird_thing')).toEqual({ variant: 'outline', label: 'Weird thing' });
+  });
+  it('formats progress as a clamped percent', () => {
+    expect(formatProgress(0.4)).toBe('40%');
+    expect(formatProgress(2)).toBe('100%');
+    expect(formatProgress(-1)).toBe('0%');
+    expect(formatProgress(Number.NaN)).toBe('0%');
+  });
+});
+
+describe('select', () => {
+  const opts = [{ value: 'a', label: 'Alpha', description: 'first' }, { value: 'b', label: 'Beta' }];
+  it('filters by label/description, case-insensitive', () => {
+    expect(filterOptions(opts, 'ALP')).toEqual([opts[0]]);
+    expect(filterOptions(opts, 'first')).toEqual([opts[0]]);
+    expect(filterOptions(opts, '  ')).toEqual(opts);
+  });
+  it('selectedLabel falls back to null', () => {
+    expect(selectedLabel(opts, 'b')).toBe('Beta');
+    expect(selectedLabel(opts, null)).toBeNull();
+    expect(selectedLabel(opts, 'zzz')).toBeNull();
+  });
+});

package/src/__tests__/styles-overlay.test.ts

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+import { errorTextColor, toastStyle, swipeActionStyle } from '../styles-overlay';
+import { lightTheme, darkTheme } from '../theme';
+
+describe('styles-overlay', () => {
+  it('error text is the token in light and a brighter red in dark', () => {
+    expect(errorTextColor(lightTheme)).toBe(lightTheme.colors.destructive);
+    expect(errorTextColor(darkTheme)).not.toBe(darkTheme.colors.destructive);
+  });
+  it('toast and swipe actions follow the tone tokens', () => {
+    expect(toastStyle(lightTheme, 'success').backgroundColor).toBe(lightTheme.colors.success);
+    expect(swipeActionStyle(darkTheme, 'destructive', 80)).toMatchObject({ width: 80, backgroundColor: darkTheme.colors.destructive });
+  });
+});

package/src/components/ChatComposer.tsx

@@ -0,0 +1,65 @@
+import { useState } from 'react';
+import { KeyboardAvoidingView, Platform, Pressable, Text as RNText, View, type StyleProp, type ViewStyle } from 'react-native';
+import { Input } from './Input';
+import { useTheme } from './ThemeProvider';
+import { composerStyle, sendButtonStyle, sendGlyphStyle } from '../styles-chat';
+import { canSend } from '../logic/chat';
+
+export interface ChatComposerProps {
+  onSend: (text: string) => void;
+  /** Controlled value. Omit to let the composer own (and clear) its text. */
+  value?: string;
+  onChangeText?: (text: string) => void;
+  placeholder?: string;
+  /** Disables sending while an answer is in flight. */
+  sending?: boolean;
+  /** Extra offset for headers above the keyboard-avoiding view. */
+  keyboardVerticalOffset?: number;
+  /** Bottom safe-area padding (home indicator). */
+  bottomInset?: number;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+/** Keyboard-avoiding message input with a send button. Trims text on send. */
+export function ChatComposer({ onSend, value, onChangeText, placeholder = 'Message', sending = false, keyboardVerticalOffset = 0, bottomInset = 0, style, testID }: ChatComposerProps) {
+  const theme = useTheme();
+  const [own, setOwn] = useState('');
+  const controlled = value !== undefined;
+  const text = controlled ? value : own;
+  const enabled = canSend(text, sending);
+  const id = (s: string) => (testID ? `${testID}-${s}` : undefined);
+
+  const submit = () => {
+    if (!enabled) return;
+    onSend(text.trim());
+    if (!controlled) setOwn('');
+  };
+
+  return (
+    <KeyboardAvoidingView behavior={Platform.OS === 'ios' ? 'padding' : undefined} keyboardVerticalOffset={keyboardVerticalOffset}>
+      <View style={[composerStyle(theme), { paddingBottom: bottomInset + theme.spacing.sm }, style]}>
+        <Input
+          testID={id('input')}
+          value={text}
+          onChangeText={(t) => { if (!controlled) setOwn(t); onChangeText?.(t); }}
+          placeholder={placeholder}
+          accessibilityLabel={placeholder}
+          multiline
+          style={{ flex: 1, maxHeight: 120, borderRadius: theme.radii.xl }}
+        />
+        <Pressable
+          testID={id('send')}
+          accessibilityRole="button"
+          accessibilityLabel="Send message"
+          accessibilityState={{ disabled: !enabled }}
+          disabled={!enabled}
+          onPress={submit}
+          style={sendButtonStyle(theme, enabled)}
+        >
+          <RNText style={sendGlyphStyle(theme, enabled)}>↑</RNText>
+        </Pressable>
+      </View>
+    </KeyboardAvoidingView>
+  );
+}

package/src/components/Chip.tsx

@@ -7,17 +7,21 @@ export interface ChipProps {
   selected?: boolean;
   onPress?: () => void;
   style?: StyleProp<ViewStyle>;
+  testID?: string;
+  accessibilityLabel?: string;
 }
 
 /** Selectable filter pill. Filled with the primary color when selected,
  *  outlined otherwise. Compose a row of these for a filter bar. */
-export function Chip({ label, selected = false, onPress, style }: ChipProps) {
+export function Chip({ label, selected = false, onPress, style, testID, accessibilityLabel }: ChipProps) {
   const theme = useTheme();
   return (
     <Pressable
       accessibilityRole="button"
       accessibilityState={{ selected }}
       onPress={onPress}
+      testID={testID}
+      accessibilityLabel={accessibilityLabel}
       style={({ pressed }) => [chipStyle(theme, selected), pressed ? { opacity: 0.7 } : null, style]}
     >
       <RNText style={chipTextStyle(theme, selected)}>{label}</RNText>

package/src/components/DataList.tsx

@@ -0,0 +1,52 @@
+import type { ReactElement } from 'react';
+import { FlatList, View, type FlatListProps, type ListRenderItem } from 'react-native';
+import { ListControls } from './ListControls';
+import { useServerList } from './useServerList';
+import { useTheme } from './ThemeProvider';
+import type { ServerListProps } from './serverListTypes';
+
+export type DataListProps<T> = ServerListProps &
+  Pick<FlatListProps<T>, 'keyExtractor' | 'extraData' | 'ItemSeparatorComponent' | 'contentContainerStyle'> & {
+    data: readonly T[];
+    renderItem: ListRenderItem<T>;
+  };
+
+/**
+ * List for server-driven data: debounced search, sort + filter controls with an
+ * active-filter summary, pull-to-refresh, infinite scroll with a hasMore /
+ * loadingMore footer, and distinct loading / empty / no-results / error states.
+ * It renders exactly the rows it is given: filtering, sorting and paging are the
+ * server's job, reported through the callbacks.
+ */
+export function DataList<T>(props: DataListProps<T>): ReactElement {
+  const { data, renderItem, keyExtractor, extraData, ItemSeparatorComponent, contentContainerStyle, ListHeaderComponent, testID, search, filters, onFilterChange, onClearFilters, sort } = props;
+  const theme = useTheme();
+  const { empty, footer, onEndReached, refreshControl } = useServerList(props, data.length);
+  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}
+      <FlatList
+        testID={testID}
+        data={data}
+        renderItem={renderItem}
+        keyExtractor={keyExtractor}
+        extraData={extraData}
+        ItemSeparatorComponent={ItemSeparatorComponent}
+        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/EmptyState.tsx

@@ -14,6 +14,9 @@ export interface EmptyStateProps {
   onAction?: () => void;
   /** Layout overrides (e.g. margins), merged after the base style. */
   style?: StyleProp<ViewStyle>;
+  testID?: string;
+  /** testID for the action button. */
+  actionTestID?: string;
 }
 
 /**
@@ -22,10 +25,11 @@ export interface EmptyStateProps {
  * 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) {
+export function EmptyState({ icon, title, description, actionLabel, onAction, style, testID, actionTestID }: EmptyStateProps) {
   const theme = useTheme();
   return (
     <View
+      testID={testID}
       style={[
         {
           alignItems: 'center',
@@ -55,6 +59,7 @@ export function EmptyState({ icon, title, description, actionLabel, onAction, st
           title={actionLabel}
           variant="primary"
           onPress={onAction}
+          testID={actionTestID}
           style={{ marginTop: theme.spacing.sm, alignSelf: 'stretch' }}
         />
       ) : null}

package/src/components/FormField.tsx

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react';
+import { Text as RNText, View, type StyleProp, type ViewStyle } from 'react-native';
+import { Label } from './Label';
+import { useTheme } from './ThemeProvider';
+import { errorTextColor } from '../styles-overlay';
+
+export interface FormFieldProps {
+  label?: string;
+  required?: boolean;
+  hint?: string;
+  /** When set, replaces the hint and is announced as an alert. */
+  error?: string;
+  /** Right-aligned text under the control, e.g. a character counter. */
+  footerRight?: string;
+  children: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+/** Label + control + hint/error wrapper for any input. */
+export function FormField({ label, required, hint, error, footerRight, children, style }: FormFieldProps) {
+  const theme = useTheme();
+  return (
+    <View style={[{ gap: theme.spacing.xs }, style]}>
+      {label ? <Label>{label}{required ? <RNText style={{ color: theme.colors.destructive }}> *</RNText> : null}</Label> : null}
+      {children}
+      {error || hint || footerRight ? (
+        <View style={{ flexDirection: 'row', justifyContent: 'space-between', gap: theme.spacing.sm }}>
+          {error ? (
+            <RNText accessibilityRole="alert" style={{ flex: 1, color: errorTextColor(theme), fontSize: theme.fontSizes.xs }}>{error}</RNText>
+          ) : (
+            <RNText style={{ flex: 1, color: theme.colors.mutedForeground, fontSize: theme.fontSizes.xs }}>{hint ?? ''}</RNText>
+          )}
+          {footerRight ? <RNText style={{ color: theme.colors.mutedForeground, fontSize: theme.fontSizes.xs }}>{footerRight}</RNText> : null}
+        </View>
+      ) : null}
+    </View>
+  );
+}

package/src/components/Header.tsx

@@ -0,0 +1,46 @@
+import 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 { headerStyle } from '../styles-overlay';
+import { textStyle } from '../styles';
+
+export interface HeaderProps {
+  title: string;
+  subtitle?: string;
+  /** Shows a back button when set. */
+  onBack?: () => void;
+  backLabel?: string;
+  /** Node pinned right, e.g. an action Button. */
+  trailing?: ReactNode;
+  /** Pad for the status bar / notch. Default false (Screen already does). */
+  safeArea?: boolean;
+  testID?: string;
+}
+
+/** Stack-screen header: back button, title/subtitle, trailing actions. */
+export function Header({ title, subtitle, onBack, backLabel = 'Back', trailing, safeArea = false, testID }: HeaderProps) {
+  const theme = useTheme();
+  const insets = useSafeAreaInsets();
+  return (
+    <View testID={testID} style={headerStyle(theme, safeArea ? insets.top : 0)}>
+      {onBack ? (
+        <Pressable
+          testID={testID ? `${testID}-back` : undefined}
+          accessibilityRole="button"
+          accessibilityLabel={backLabel}
+          hitSlop={8}
+          onPress={onBack}
+          style={{ width: 44, height: 44, marginLeft: -theme.spacing.sm, alignItems: 'center', justifyContent: 'center' }}
+        >
+          <RNText style={{ color: theme.colors.primary, fontSize: 32, lineHeight: 34 }}>‹</RNText>
+        </Pressable>
+      ) : null}
+      <View style={{ flex: 1 }}>
+        <RNText accessibilityRole="header" numberOfLines={1} style={[textStyle(theme, 'heading'), { fontSize: theme.fontSizes.lg }]}>{title}</RNText>
+        {subtitle ? <RNText numberOfLines={1} style={textStyle(theme, 'caption')}>{subtitle}</RNText> : null}
+      </View>
+      {trailing ? <View style={{ flexDirection: 'row', alignItems: 'center', gap: theme.spacing.sm }}>{trailing}</View> : null}
+    </View>
+  );
+}

package/src/components/ListControls.tsx

@@ -0,0 +1,85 @@
+import { useEffect, useRef } from 'react';
+import { Pressable, ScrollView, Text as RNText, View } from 'react-native';
+import { Chip } from './Chip';
+import { SearchBar } from './SearchBar';
+import { SegmentedControl } from './SegmentedControl';
+import { Select } from './Select';
+import { useTheme } from './ThemeProvider';
+import { createDebouncer, summarizeFilters } from '../logic/listState';
+import type { ServerListProps } from './serverListTypes';
+
+type Props = Pick<ServerListProps, 'search' | 'filters' | 'onFilterChange' | 'onClearFilters' | 'sort' | 'testID'>;
+
+/** Search, sort, filter chips and the active-filter summary shared by the server lists. */
+export function ListControls({ search, filters = [], onFilterChange, onClearFilters, sort, testID }: Props) {
+  const theme = useTheme();
+  const id = (s: string) => (testID ? `${testID}-${s}` : undefined);
+  const latest = useRef(search);
+  latest.current = search;
+  const debouncer = useRef(createDebouncer<string>((t) => latest.current?.onSearch(t), search?.debounceMs ?? 300)).current;
+  useEffect(() => () => debouncer.cancel(), [debouncer]);
+
+  const summary = summarizeFilters(filters, search?.value ?? '');
+
+  return (
+    <View style={{ gap: theme.spacing.sm, paddingBottom: theme.spacing.sm }}>
+      {search ? (
+        <SearchBar
+          testID={id('search')}
+          value={search.value}
+          placeholder={search.placeholder}
+          onChangeText={(t) => { search.onChange(t); debouncer.call(t); }}
+          onSubmit={(t) => { debouncer.cancel(); search.onSearch(t); }}
+          onClear={() => debouncer.flush()}
+        />
+      ) : null}
+      {sort ? <SegmentedControl testID={id('sort')} options={sort.options} value={sort.value} onChange={sort.onChange} /> : null}
+      {filters.length ? (
+        <ScrollView horizontal showsHorizontalScrollIndicator={false} keyboardShouldPersistTaps="handled" contentContainerStyle={{ gap: theme.spacing.sm, alignItems: 'center' }}>
+          {filters.map((g) =>
+            g.display === 'select' ? (
+              <Select
+                key={g.key}
+                compact
+                testID={id(`filter-${g.key}`)}
+                label={g.label}
+                options={g.options}
+                value={g.value}
+                clearLabel={`All ${g.label.toLowerCase()}`}
+                onChange={(v) => onFilterChange?.(g.key, v)}
+              />
+            ) : (
+              g.options.map((o) => {
+                const active = g.value === o.value;
+                return (
+                  <Chip
+                    key={`${g.key}:${o.value}`}
+                    testID={id(`filter-${g.key}-${o.value}`)}
+                    label={o.label}
+                    selected={active}
+                    accessibilityLabel={`${g.label}: ${o.label}`}
+                    onPress={() => onFilterChange?.(g.key, active ? null : o.value)}
+                  />
+                );
+              })
+            ),
+          )}
+        </ScrollView>
+      ) : null}
+      {summary.count > 0 && onClearFilters ? (
+        <View style={{ flexDirection: 'row', alignItems: 'center', gap: theme.spacing.sm }}>
+          <RNText numberOfLines={2} style={{ flex: 1, color: theme.colors.mutedForeground, fontSize: theme.fontSizes.xs }}>{summary.labels.join(' · ')}</RNText>
+          <Pressable
+            testID={id('clear-filters')}
+            accessibilityRole="button"
+            accessibilityLabel={`Clear ${summary.count} filter${summary.count === 1 ? '' : 's'}`}
+            hitSlop={8}
+            onPress={onClearFilters}
+          >
+            <RNText style={{ color: theme.colors.primary, fontSize: theme.fontSizes.sm, fontWeight: '600' }}>Clear</RNText>
+          </Pressable>
+        </View>
+      ) : null}
+    </View>
+  );
+}