@lotics/ui 2.4.1 → 2.5.0

package/src/progress_bar.tsx

@@ -1,4 +1,4 @@
-import { View, StyleSheet } from "react-native";
+import { View, StyleSheet, type ViewStyle } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
 
@@ -7,15 +7,28 @@ export type ProgressBarFormat = "percentage" | "fraction" | "none";
 export interface ProgressBarProps {
   value: number;
   max: number;
+  /** What this bar measures ("Đã nhận", "Tiến độ giao") — the xs muted
+   * uppercase eyebrow above the bar. Omit inside a band that already names
+   * it. */
+  title?: string;
+  /** Caption above-right of the bar: `percentage` → "50%", `fraction` →
+   * "1.250 / 2.500 · 50%". */
   format?: ProgressBarFormat;
   color?: string;
   completeColor?: string;
 }
 
+/**
+ * Continuous value-vs-max meter. Shares the labeled-meter anatomy with
+ * `StepProgress`/`StackedProgressBar`: optional title eyebrow left, derived
+ * caption right, 8px track below. Countable stages → `StepProgress`;
+ * weighted composition → `StackedProgressBar`.
+ */
 export function ProgressBar(props: ProgressBarProps) {
   const {
     value,
     max,
+    title,
     format = "percentage",
     color = colors.blue["500"],
     completeColor = colors.green["500"],
@@ -24,26 +37,34 @@ export function ProgressBar(props: ProgressBarProps) {
   const percentage = Math.min(100, Math.max(0, (value / max) * 100));
   const isComplete = percentage >= 100;
 
-  const label =
+  const caption =
     format === "fraction"
-      ? `${value} / ${max}`
+      ? `${value.toLocaleString("vi-VN")} / ${max.toLocaleString("vi-VN")} · ${Math.round(percentage)}%`
       : format === "percentage"
         ? `${Math.round(percentage)}%`
         : null;
 
   return (
     <View style={styles.container}>
-      {label !== null && (
+      {title || caption ? (
         <View style={styles.header}>
-          <Text size="sm" color="muted">
-            {label}
-          </Text>
+          {title ? (
+            <Text size="xs" color="muted" transform="uppercase">
+              {title}
+            </Text>
+          ) : null}
+          <View style={styles.spacer} />
+          {caption ? (
+            <Text size="xs" color="muted" tabular>
+              {caption}
+            </Text>
+          ) : null}
         </View>
-      )}
-      <View style={styles.barBackground}>
+      ) : null}
+      <View style={styles.track}>
         <View
           style={[
-            styles.barFill,
+            styles.fill,
             {
               width: `${percentage}%`,
               backgroundColor: isComplete ? completeColor : color,
@@ -61,16 +82,25 @@ const styles = StyleSheet.create({
   },
   header: {
     flexDirection: "row",
-    justifyContent: "flex-end",
+    alignItems: "baseline",
+    gap: 12,
   },
-  barBackground: {
-    height: 8,
-    borderRadius: 4,
-    backgroundColor: colors.gray["100"],
+  spacer: {
+    flex: 1,
+  },
+  // 10px — substantial enough to read as a meter, not a hairline.
+  track: {
+    height: 10,
+    borderRadius: 5,
+    backgroundColor: colors.zinc["100"],
     overflow: "hidden",
+    // Hairline inner edge — the track reads as a groove, not a gray strip.
+    ...({ boxShadow: "inset 0 0 0 1px rgba(38,38,38,0.04)" } as ViewStyle),
   },
-  barFill: {
+  fill: {
     height: "100%",
-    borderRadius: 4,
+    borderRadius: 5,
+    // Progress that snaps is dead; progress that moves is alive.
+    ...({ transition: "width 200ms ease-out, background-color 200ms ease-out" } as ViewStyle),
   },
 });

package/src/radio_picker.tsx

@@ -22,10 +22,15 @@ export interface RadioPickerProps<T extends string | number | symbol> {
   options: RadioPickerOption<T>[];
   value: T;
   onValueChange: (value: T) => void;
+  /** "column" (default) stacks full-width rows — right when options carry
+   *  descriptions. "row" wraps compact options inline — right for short,
+   *  description-less choices (a quick-entry form), where a six-option
+   *  column would push the rest of the form below the fold. */
+  direction?: "column" | "row";
 }
 
 export function RadioPicker<T extends string | number | symbol>(props: RadioPickerProps<T>) {
-  const { accessibilityLabel, options, value, onValueChange } = props;
+  const { accessibilityLabel, options, value, onValueChange, direction = "column" } = props;
   const itemRefs = useRef<Array<View | null>>([]);
 
   // Roving tabindex: arrow keys move focus between options and select, matching
@@ -65,7 +70,11 @@ export function RadioPicker<T extends string | number | symbol>(props: RadioPick
   const tabStopIndex = selectedIndex === -1 ? 0 : selectedIndex;
 
   return (
-    <View accessibilityRole="radiogroup" accessibilityLabel={accessibilityLabel}>
+    <View
+      accessibilityRole="radiogroup"
+      accessibilityLabel={accessibilityLabel}
+      style={direction === "row" ? { flexDirection: "row", flexWrap: "wrap", gap: 4 } : undefined}
+    >
       {options.map((option, index) => (
         <RadioOption
           ref={(node: View | null) => {
@@ -76,6 +85,7 @@ export function RadioPicker<T extends string | number | symbol>(props: RadioPick
           value={option.value}
           description={option.description}
           testID={option.testID}
+          compact={direction === "row"}
           selected={value === option.value}
           isTabStop={index === tabStopIndex}
           onSelect={() => onValueChange(option.value)}
@@ -89,13 +99,14 @@ export function RadioPicker<T extends string | number | symbol>(props: RadioPick
 function RadioOption<T extends string | number | symbol>(
   props: RadioPickerOption<T> & {
     ref: (node: View | null) => void;
+    compact: boolean;
     selected: boolean;
     isTabStop: boolean;
     onSelect: () => void;
     onKeyDown: (event: { key: string; preventDefault?: () => void }) => void;
   },
 ) {
-  const { ref, label, description, selected, isTabStop, onSelect, value, testID, onKeyDown } = props;
+  const { ref, label, description, compact, selected, isTabStop, onSelect, value, testID, onKeyDown } = props;
 
   const handlePress = useCallback(() => {
     onSelect();
@@ -108,9 +119,9 @@ function RadioOption<T extends string | number | symbol>(
       style={{
         flexDirection: "row",
         alignItems: "center",
-        padding: 12,
+        padding: compact ? 8 : 12,
         borderRadius: 8,
-        gap: 16,
+        gap: compact ? 8 : 16,
       }}
       onPress={handlePress}
       accessibilityRole="radio"
@@ -122,8 +133,8 @@ function RadioOption<T extends string | number | symbol>(
     >
       <View
         style={{
-          width: 28,
-          height: 28,
+          width: compact ? 20 : 28,
+          height: compact ? 20 : 28,
           borderRadius: 999,
           borderWidth: 1,
           borderColor: colors.border,
@@ -132,10 +143,10 @@ function RadioOption<T extends string | number | symbol>(
           alignItems: "center",
         }}
       >
-        {selected && <Icon name="check" color={getTextColor("inverted")} />}
+        {selected && <Icon name="check" size={compact ? 14 : 24} color={getTextColor("inverted")} />}
       </View>
       <View>
-        <Text>{label}</Text>
+        <Text size={compact ? "sm" : undefined}>{label}</Text>
         {!!description && <Text color="muted">{description}</Text>}
       </View>
     </PressableHighlight>

package/src/range_slider.tsx

@@ -0,0 +1,185 @@
+import { useRef, useState } from "react";
+import { StyleSheet, View, type GestureResponderEvent, type LayoutChangeEvent, type ViewStyle } from "react-native";
+import { Text } from "./text";
+import { colors } from "./colors";
+
+const THUMB = 20;
+const R = THUMB / 2;
+
+export interface RangeSliderProps {
+  min: number;
+  max: number;
+  step?: number;
+  /** The controlled [low, high] selection. */
+  value: [number, number];
+  onValueChange: (value: [number, number]) => void;
+  /** Render the edge labels (money, units). Default: the bare number. */
+  format?: (value: number) => string;
+  /** Filled-track / thumb accent. Default the neutral ink. */
+  color?: string;
+  /** Base name — the thumbs announce "{label} minimum" / "{label} maximum". */
+  accessibilityLabel: string;
+}
+
+type Thumb = "low" | "high";
+
+/**
+ * A short human summary of a range selection for a `FilterPill` preview —
+ * "5tr–10tr", or "≥ 5tr" / "≤ 10tr" when one end sits at its bound, and
+ * `undefined` at the full range (no active filter). Mirrors `columnFilterSummary`.
+ */
+export function rangeSummary(
+  value: [number, number],
+  format: (n: number) => string = String,
+  bounds?: [number, number],
+): string | undefined {
+  const [low, high] = value;
+  if (!bounds) return `${format(low)}–${format(high)}`;
+  const atMin = low <= bounds[0];
+  const atMax = high >= bounds[1];
+  if (atMin && atMax) return undefined;
+  if (atMin) return `≤ ${format(high)}`;
+  if (atMax) return `≥ ${format(low)}`;
+  return `${format(low)}–${format(high)}`;
+}
+
+/**
+ * A dual-thumb range slider — drag either end to bound a continuous number
+ * (a price range, an amount, a weight). Drag works on web and native (the RN
+ * Responder system), and each thumb is a keyboard-operable ARIA slider
+ * (arrow keys step it, clamped against the other). For a small discrete count
+ * use `Counter`; for a single free value use `NumberInput`.
+ */
+export function RangeSlider(props: RangeSliderProps) {
+  const { min, max, step = 1, value, onValueChange, format, color = colors.zinc[900], accessibilityLabel } = props;
+  const [low, high] = value;
+  const [width, setWidth] = useState(0);
+  const [dragging, setDragging] = useState<Thumb | null>(null);
+  const active = useRef<Thumb | null>(null);
+
+  const fmt = (n: number) => (format ? format(n) : String(n));
+  const span = max - min || 1;
+  const usable = Math.max(0, width - THUMB); // the track inset by a thumb radius at each end
+  const pct = (v: number) => (v - min) / span;
+  const x = (v: number) => pct(v) * usable; // thumb box left, in px — never crosses the edge
+
+  const snap = (raw: number) => {
+    const stepped = Math.round((raw - min) / step) * step + min;
+    return Math.min(max, Math.max(min, stepped));
+  };
+
+  // A thumb never crosses the other — low stays ≤ high.
+  const setThumb = (thumb: Thumb, v: number) => {
+    if (thumb === "low") onValueChange([Math.min(v, high), high]);
+    else onValueChange([low, Math.max(v, low)]);
+  };
+
+  // locationX is relative to the track; the usable range maps [R, width−R] → [0,1].
+  const fromX = (thumb: Thumb, locationX: number) =>
+    setThumb(thumb, snap(min + Math.min(1, Math.max(0, (locationX - R) / (usable || 1))) * span));
+
+  const closerThumb = (locationX: number): Thumb => {
+    const f = Math.min(1, Math.max(0, (locationX - R) / (usable || 1)));
+    const v = min + f * span;
+    return Math.abs(v - low) <= Math.abs(v - high) ? "low" : "high";
+  };
+
+  const onLayout = (e: LayoutChangeEvent) => setWidth(e.nativeEvent.layout.width);
+
+  // The track is the responder; grant picks the nearer thumb. We refuse
+  // termination so a parent ScrollView can't steal the drag on a vertical wobble.
+  const responder = {
+    onStartShouldSetResponder: () => true,
+    onMoveShouldSetResponder: () => true,
+    onResponderTerminationRequest: () => false,
+    onResponderGrant: (e: GestureResponderEvent) => {
+      const t = closerThumb(e.nativeEvent.locationX);
+      active.current = t;
+      setDragging(t);
+      fromX(t, e.nativeEvent.locationX);
+    },
+    onResponderMove: (e: GestureResponderEvent) => {
+      if (active.current) fromX(active.current, e.nativeEvent.locationX);
+    },
+    onResponderRelease: () => { active.current = null; setDragging(null); },
+    onResponderTerminate: () => { active.current = null; setDragging(null); },
+  };
+
+  // Web keyboard handler, forwarded by react-native-web (cast like the mouse
+  // handlers elsewhere — RN's View types don't declare it).
+  const keyProps = (thumb: Thumb) =>
+    ({
+      onKeyDown: (e: { key: string; preventDefault: () => void }) => {
+        const d = e.key === "ArrowRight" || e.key === "ArrowUp" ? step : e.key === "ArrowLeft" || e.key === "ArrowDown" ? -step : 0;
+        if (d === 0) return;
+        e.preventDefault();
+        setThumb(thumb, snap((thumb === "low" ? low : high) + d));
+      },
+    }) as object;
+
+  return (
+    <View style={styles.container}>
+      <View style={styles.labels}>
+        <Text size="sm" color="muted" tabular>{fmt(low)}</Text>
+        <Text size="sm" color="muted" tabular>{fmt(high)}</Text>
+      </View>
+      <View style={styles.trackArea} onLayout={onLayout} {...responder}>
+        <View style={styles.trackBg} />
+        <View style={[styles.trackFill, { left: x(low) + R, width: Math.max(0, x(high) - x(low)), backgroundColor: color }]} />
+        {(["low", "high"] as const).map((thumb) => {
+          const v = thumb === "low" ? low : high;
+          return (
+            <View
+              key={thumb}
+              accessibilityRole="adjustable"
+              accessibilityLabel={`${accessibilityLabel} ${thumb === "low" ? "minimum" : "maximum"}`}
+              accessibilityValue={{ min, max, now: v }}
+              focusable
+              style={[styles.thumb, { left: x(v), borderColor: color }, dragging === thumb && styles.thumbActive]}
+              {...keyProps(thumb)}
+            />
+          );
+        })}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { gap: 10, minWidth: 240 },
+  labels: { flexDirection: "row", justifyContent: "space-between" },
+  trackArea: {
+    height: 28,
+    justifyContent: "center",
+    ...({ cursor: "pointer", touchAction: "none" } as ViewStyle),
+  },
+  trackBg: {
+    position: "absolute",
+    left: R,
+    right: R,
+    top: 11,
+    height: 6,
+    borderRadius: 999,
+    backgroundColor: colors.zinc[200],
+  },
+  trackFill: {
+    position: "absolute",
+    top: 11,
+    height: 6,
+    borderRadius: 999,
+  },
+  thumb: {
+    position: "absolute",
+    top: 4,
+    width: THUMB,
+    height: THUMB,
+    borderRadius: 999,
+    backgroundColor: colors.white,
+    borderWidth: 2,
+    ...({ cursor: "pointer", boxShadow: "0 1px 3px rgba(38,38,38,0.18)" } as ViewStyle),
+  },
+  thumbActive: {
+    // a soft halo while dragging — no size change, so the thumb never shifts
+    ...({ boxShadow: "0 1px 3px rgba(38,38,38,0.18), 0 0 0 6px rgba(38,38,38,0.10)" } as ViewStyle),
+  },
+});

package/src/remainder_meter.tsx

@@ -0,0 +1,48 @@
+import { StyleSheet, View, type DimensionValue } from "react-native";
+import { colors, solid } from "./colors";
+import { Text } from "./text";
+
+export interface RemainderMeterProps {
+  /** The source amount being distributed — the payment, the available stock. */
+  total: number;
+  /** How much has been allocated across the targets so far. */
+  allocated: number;
+  /** Format amounts (money / units). Defaults to a plain locale string. */
+  format?: (n: number) => string;
+}
+
+/**
+ * The heart of an allocation — how much of a SOURCE has been distributed and
+ * how much is left. Three states the operator reads at a glance: UNDER (a
+ * remainder still to place), EXACT (fully applied — green), OVER (over-allocated
+ * — red, the commit is blocked). Pair with `AllocationRow`s that split the source
+ * down until this reads zero. Reused by cash application, stock allocation, cost
+ * distribution, budgeting.
+ */
+export function RemainderMeter(props: RemainderMeterProps) {
+  const { total, allocated, format = (n) => n.toLocaleString() } = props;
+  const remainder = total - allocated;
+  const state = remainder > 0 ? "under" : remainder < 0 ? "over" : "exact";
+  const pct: DimensionValue = `${total <= 0 ? 0 : Math.min(100, (allocated / total) * 100)}%`;
+  const barColor = state === "over" ? solid("red") : state === "exact" ? solid("emerald") : solid("blue");
+  const right =
+    state === "exact" ? "Fully applied" : state === "over" ? `Over by ${format(-remainder)}` : `${format(remainder)} unapplied`;
+  return (
+    <View style={{ gap: 8 }}>
+      <View style={{ flexDirection: "row", alignItems: "baseline", gap: 8 }}>
+        <Text size="sm" color="muted" style={{ flex: 1 }}>{`${format(allocated)} of ${format(total)} applied`}</Text>
+        <Text size="sm" weight="medium" tabular color={state === "over" ? "danger" : state === "exact" ? "success" : "default"}>
+          {right}
+        </Text>
+      </View>
+      <View style={styles.track}>
+        <View style={[styles.fill, { width: pct, backgroundColor: barColor }]} />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  track: { height: 8, borderRadius: 999, backgroundColor: colors.zinc[200], overflow: "hidden" },
+  fill: { height: "100%", borderRadius: 999 },
+});

package/src/ring_gauge.tsx

@@ -11,7 +11,7 @@ export interface RingGaugeProps {
   caption?: string;
   /** Diameter in px. Default 128. */
   size?: number;
-  /** Ring stroke width in px. Default 12. */
+  /** Ring stroke width in px. Default 14 — thinner reads weak. */
   thickness?: number;
   /** Arc color. Default teal accent. */
   color?: string;
@@ -29,7 +29,7 @@ export interface RingGaugeProps {
  * (`rotate(-90)`) and grows clockwise via `strokeDasharray`.
  */
 export function RingGauge(props: RingGaugeProps) {
-  const { value, label, caption, size = 140, thickness = 10, color = colors.teal[600] } = props;
+  const { value, label, caption, size = 140, thickness = 14, color = colors.teal[600] } = props;
   const clamped = Math.max(0, Math.min(100, value));
   const center = size / 2;
   const radius = (size - thickness) / 2;
@@ -40,7 +40,7 @@ export function RingGauge(props: RingGaugeProps) {
     <View style={{ alignItems: "center", gap: 12 }}>
       <View style={{ width: size, height: size, alignItems: "center", justifyContent: "center" }}>
         <svg width={size} height={size} viewBox={`0 0 ${size} ${size}`} style={{ position: "absolute" }}>
-          <circle cx={center} cy={center} r={radius} fill="none" stroke={colors.zinc[200]} strokeWidth={thickness} />
+          <circle cx={center} cy={center} r={radius} fill="none" stroke={colors.zinc[100]} strokeWidth={thickness} />
           <circle
             cx={center}
             cy={center}
@@ -58,11 +58,11 @@ export function RingGauge(props: RingGaugeProps) {
         </Text>
       </View>
       <View style={{ alignItems: "center", gap: 2 }}>
-        <Text size="sm" weight="medium">
+        <Text size="md" weight="semibold">
           {label}
         </Text>
         {caption ? (
-          <Text size="xs" color="muted">
+          <Text size="sm" color="muted">
             {caption}
           </Text>
         ) : null}

package/src/scan_field.tsx

@@ -0,0 +1,58 @@
+import { StyleSheet, View } from "react-native";
+import { colors, solid } from "./colors";
+import { Text } from "./text";
+import { TextInputField } from "./text_input_field";
+
+export type ScanStatus = "idle" | "match" | "mismatch";
+
+export interface ScanFieldProps {
+  value: string;
+  onChangeText: (text: string) => void;
+  placeholder?: string;
+  /** Verify state — drives the border colour, the leading glyph, and the inline
+   *  message. Stays "idle" until the consumer compares the scan to the expected
+   *  code and reports the result. */
+  status?: ScanStatus;
+  /** Inline confirmation shown when `status` is "match". */
+  matchHint?: string;
+  /** Inline correction shown when `status` is "mismatch". */
+  mismatchHint?: string;
+  /** Fired on Enter — a scan gun sends a return after the code, so this is the
+   *  "scanned" signal (also a manual submit). */
+  onScan?: () => void;
+  accessibilityLabel?: string;
+}
+
+/**
+ * The scan/verify input for operations work — scan (or type) a code to confirm
+ * you're at the right bin, on the right item, handling the right tote. Unlike a
+ * plain field it carries a VERIFY state: the border, the leading glyph, and an
+ * inline message go green on a match and red on a mismatch, giving the operator a
+ * go / no-go before they act. Reused across pick / pack / receive / count / ship.
+ */
+export function ScanField(props: ScanFieldProps) {
+  const { value, onChangeText, placeholder, status = "idle", matchHint, mismatchHint, onScan, accessibilityLabel } = props;
+  const borderColor = status === "match" ? solid("emerald") : status === "mismatch" ? solid("red") : colors.zinc[300];
+  return (
+    <View style={{ gap: 6 }}>
+      <TextInputField
+        value={value}
+        onChangeText={onChangeText}
+        onSubmitEditing={onScan}
+        placeholder={placeholder}
+        icon={status === "match" ? "circle-check" : "scan"}
+        accessibilityLabel={accessibilityLabel}
+        style={[styles.field, { borderColor }]}
+      />
+      {status === "match" && matchHint ? <Text size="xs" color="success">{matchHint}</Text> : null}
+      {status === "mismatch" && mismatchHint ? <Text size="xs" color="danger">{mismatchHint}</Text> : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  field: {
+    borderRadius: 10,
+    backgroundColor: colors.white,
+  },
+});

package/src/search_input.tsx

@@ -8,6 +8,7 @@ import {
   View,
   type ViewStyle,
 } from "react-native";
+import { colors } from "./colors";
 import { TextInputField } from "./text_input_field";
 
 type SearchInputProps = Omit<
@@ -55,7 +56,18 @@ export function SearchInput(props: SearchInputProps) {
 }
 
 const styles = StyleSheet.create({
+  // Search reads as a view-control by SHAPE (rounded pill + the leading
+  // search glyph). White fill pops against the zinc-50 canvas where most
+  // toolbars live; a zinc-300 border (one step up from the form-input
+  // hairline) keeps it defined on white cards too, where the fill alone
+  // would vanish. 40px (TextInputField default) — the system control height
+  // every band aligns to.
   pill: {
     borderRadius: 999,
+    backgroundColor: colors.white,
+    // A thin 1px resting border (TextInputField's default width) — emphasis on
+    // interaction comes from the input's own focus outline, so the pill stays
+    // quiet at rest. zinc-300 keeps it defined on white cards.
+    borderColor: colors.zinc[300],
   },
 });

package/src/sort_header.tsx

@@ -0,0 +1,102 @@
+import { StyleSheet, type ViewStyle } from "react-native";
+import { Text } from "./text";
+import { Icon } from "./icon";
+import { colors } from "./colors";
+import { PressableHighlight } from "./pressable_highlight";
+
+export type SortDir = "asc" | "desc";
+export interface SortState {
+  key: string;
+  dir: SortDir;
+}
+
+/**
+ * Cycle a SINGLE-column sort on press: none → asc → desc → none (the third
+ * toggle clears it). The parent holds one `SortState | null`.
+ */
+export function cycleSort(current: SortState | null, key: string): SortState | null {
+  if (current?.key !== key) return { key, dir: "asc" };
+  if (current.dir === "asc") return { key, dir: "desc" };
+  return null;
+}
+
+/**
+ * Order a COPY of `items` by the active column. `getValue` maps (item, key) to a
+ * comparable (lowercase strings for case-insensitive order). Returns `items`
+ * unchanged when nothing is sorted.
+ */
+export function sortBy<T>(
+  items: T[],
+  sort: SortState | null,
+  getValue: (item: T, key: string) => string | number,
+): T[] {
+  if (!sort) return items;
+  const dir = sort.dir === "asc" ? 1 : -1;
+  return [...items].sort((a, b) => {
+    const va = getValue(a, sort.key);
+    const vb = getValue(b, sort.key);
+    return va < vb ? -dir : va > vb ? dir : 0;
+  });
+}
+
+export interface SortHeaderProps {
+  label: string;
+  sortKey: string;
+  sort: SortState | null;
+  onSort: (key: string) => void;
+  /** Right-align for numeric columns — the arrow then sits LEFT of the label. */
+  align?: "left" | "right";
+  style?: ViewStyle;
+}
+
+/**
+ * A sortable column header — the eyebrow label's pressable sibling. Press
+ * cycles a single-column sort (none → asc → desc → none) via `cycleSort`,
+ * showing a direction chevron when active; the parent orders rows with `sortBy`.
+ * One sort at a time. The hover wash bleeds (negative margin) so the label stays
+ * flush with the column content beneath it.
+ */
+export function SortHeader(props: SortHeaderProps) {
+  const { label, sortKey, sort, onSort, align = "left", style } = props;
+  const active = sort?.key === sortKey;
+  const arrow = active ? (sort.dir === "asc" ? "chevron-up" : "chevron-down") : undefined;
+  const dirText = active ? (sort.dir === "asc" ? ", ascending" : ", descending") : "";
+
+  return (
+    <PressableHighlight
+      accessibilityRole="button"
+      accessibilityLabel={`Sort by ${label}${dirText}`}
+      onPress={() => onSort(sortKey)}
+      style={[styles.header, align === "right" ? styles.right : null, style]}
+    >
+      {align === "right" && arrow ? <Icon name={arrow} size={12} color={colors.zinc[500]} /> : null}
+      <Text
+        size="xs"
+        color={active ? "default" : "muted"}
+        weight={active ? "medium" : "regular"}
+        transform="uppercase"
+        numberOfLines={1}
+      >
+        {label}
+      </Text>
+      {align === "left" && arrow ? <Icon name={arrow} size={12} color={colors.zinc[500]} /> : null}
+    </PressableHighlight>
+  );
+}
+
+const styles = StyleSheet.create({
+  // Negative margin so the wash bleeds while the label stays flush with the
+  // column content below (same idea as LinkButton).
+  header: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 4,
+    paddingVertical: 4,
+    paddingHorizontal: 6,
+    marginHorizontal: -6,
+    borderRadius: 6,
+  },
+  right: {
+    justifyContent: "flex-end",
+  },
+});