@lotics/ui 4.1.0 → 4.3.0

package/src/assisted_field.tsx

@@ -0,0 +1,93 @@
+import { StyleSheet, View } from "react-native";
+import { solid, tint } from "./colors";
+import { Text } from "./text";
+import { Icon } from "./icon";
+import { IconButton } from "./icon_button";
+import { LinkButton } from "./link_button";
+import { Confidence, type ConfidenceLevel } from "./confidence";
+
+export interface AssistedFieldProps {
+  label: string;
+  /** The current value — an AI estimate until confirmed, or the final value. */
+  value: string;
+  /** Unit suffix shown after the value (mm, cm, kg). */
+  unit?: string;
+  confidence?: ConfidenceLevel;
+  confidenceScore?: number;
+  /** True while the value is still an unconfirmed AI estimate — it reads
+   *  amber-tinted with a Confidence chip and a Confirm action (visible
+   *  provenance). Confirm or override flips it to a plain confirmed value. */
+  estimated?: boolean;
+  onConfirm?: () => void;
+  /** Override — the host swaps in its own inline input to edit the value. */
+  onEdit?: () => void;
+}
+
+/**
+ * A form value the AI pre-filled — shown as a tinted ESTIMATE the human
+ * confirms (→ plain, checked) or overrides, never silently committed. The
+ * provenance is always visible: an estimate looks different from a value a
+ * person stood behind. Pair with `Confidence`; for a whole extracted record,
+ * stack several and add one "Confirm all" at the form level.
+ */
+export function AssistedField(props: AssistedFieldProps) {
+  const { label, value, unit, estimated, confidence, confidenceScore, onConfirm, onEdit } = props;
+  const display = unit ? `${value} ${unit}` : value;
+  return (
+    <View style={styles.row}>
+      <Text size="sm" color="muted" style={styles.label}>
+        {label}
+      </Text>
+      <View style={styles.valueCol}>
+        <View style={styles.valueRow}>
+          {estimated ? (
+            <View style={styles.estimatePill}>
+              <Icon name="sparkles" size={11} color={solid("violet")} />
+              <Text size="sm" weight="medium" tabular>
+                {display}
+              </Text>
+            </View>
+          ) : (
+            <View style={styles.confirmedRow}>
+              <Text size="sm" weight="medium" tabular>
+                {display}
+              </Text>
+              <Icon name="circle-check" size={13} color={solid("emerald")} />
+            </View>
+          )}
+          {onEdit ? (
+            <IconButton icon="square-pen" size="sm" color="none" accessibilityLabel={`Edit ${label}`} onPress={onEdit} />
+          ) : null}
+        </View>
+        {estimated ? (
+          <View style={styles.estimateMeta}>
+            {confidence != null || confidenceScore != null ? (
+              <Confidence level={confidence} score={confidenceScore} />
+            ) : null}
+            {onConfirm ? <LinkButton title="Confirm" onPress={onConfirm} /> : null}
+          </View>
+        ) : null}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: { flexDirection: "row", alignItems: "flex-start", gap: 16, paddingVertical: 8 },
+  label: { width: 132, paddingTop: 6 },
+  valueCol: { flex: 1, gap: 6, alignItems: "flex-end" },
+  valueRow: { flexDirection: "row", alignItems: "center", gap: 6 },
+  estimatePill: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 6,
+    paddingHorizontal: 10,
+    paddingVertical: 5,
+    borderRadius: 8,
+    backgroundColor: tint("amber", 0.12),
+    borderWidth: 1,
+    borderColor: tint("amber", 0.35),
+  },
+  confirmedRow: { flexDirection: "row", alignItems: "center", gap: 6, paddingVertical: 5 },
+  estimateMeta: { flexDirection: "row", alignItems: "center", gap: 10 },
+});

package/src/change_review.tsx

@@ -0,0 +1,166 @@
+import { StyleSheet, View } from "react-native";
+import { colors, solid, tint } from "./colors";
+import { Text } from "./text";
+import { Icon } from "./icon";
+import { Button } from "./button";
+import { IconButton } from "./icon_button";
+import { LinkButton } from "./link_button";
+
+export type ChangeReviewItemStatus = "pending" | "accepted" | "rejected";
+
+export interface ChangeReviewItem {
+  /** What changed — a field/parameter name. */
+  label: string;
+  /** Prior value. Omit for a newly-added value (renders as just the new value). */
+  before?: string;
+  /** Proposed value. */
+  after: string;
+  /** Per-item decision — only meaningful in the 1-by-1 mode (when the host
+   *  passes `onAcceptItem`/`onRejectItem`). */
+  status?: ChangeReviewItemStatus;
+}
+
+export interface ChangeReviewProps {
+  changes: ChangeReviewItem[];
+  /** The instruction that produced the edit ("make it 5 mm taller"). */
+  summary?: string;
+  onApply?: () => void;
+  onDiscard?: () => void;
+  applyLabel?: string;
+  /** Once resolved the card settles to a quiet outcome line (no actions). */
+  status?: "open" | "applied" | "discarded";
+  /** Providing either flips the card into 1-BY-1 mode: each change row gets its
+   *  own ✓/✕ and reflects `item.status`; the footer counts the accepted set and
+   *  Apply commits only those. The "review the agent's suggested edits one by
+   *  one" pattern. Omit both for whole-set apply/discard. */
+  onAcceptItem?: (index: number) => void;
+  onRejectItem?: (index: number) => void;
+}
+
+/**
+ * An agent-proposed edit to existing state, shown as a before→after diff the
+ * human reviews before it lands — never auto-applied. Two modes: whole-set
+ * (apply / discard the lot) or, when the host passes `onAcceptItem`/
+ * `onRejectItem`, 1-BY-1 — each suggested change accepted or rejected on its
+ * own, the footer applying only the accepted set. Where `Suggestion` proposes
+ * a NEW value, this reviews CHANGES to existing ones.
+ */
+export function ChangeReview(props: ChangeReviewProps) {
+  const status = props.status ?? "open";
+  const perItem = props.onAcceptItem != null || props.onRejectItem != null;
+  const accepted = props.changes.filter((c) => c.status === "accepted").length;
+
+  return (
+    <View style={[styles.card, status !== "open" ? styles.resolved : null]}>
+      {props.summary ? (
+        <View style={styles.summary}>
+          <Icon name="sparkles" size={13} color={solid("violet")} />
+          <Text size="sm" weight="medium" style={{ flex: 1 }}>
+            {props.summary}
+          </Text>
+        </View>
+      ) : null}
+
+      <View style={styles.changes}>
+        {props.changes.map((c, i) => {
+          const rejected = c.status === "rejected";
+          const ok = c.status === "accepted";
+          return (
+            <View key={`${c.label}-${i}`} style={styles.change}>
+              <Text size="xs" color="muted" transform="uppercase" style={styles.changeLabel}>
+                {c.label}
+              </Text>
+              <View style={styles.diff}>
+                {c.before != null ? (
+                  <>
+                    <Text size="sm" color="muted" tabular style={styles.before}>
+                      {c.before}
+                    </Text>
+                    <Icon name="arrow-right" size={13} color={colors.zinc[400]} />
+                  </>
+                ) : null}
+                <Text size="sm" weight="medium" tabular color={rejected ? "muted" : "default"} style={rejected ? styles.before : undefined}>
+                  {c.after}
+                </Text>
+              </View>
+              {perItem && status === "open" ? (
+                <View style={styles.itemControls}>
+                  <IconButton
+                    icon="check"
+                    size="sm"
+                    color="none"
+                    iconColor={ok ? solid("emerald") : colors.zinc[400]}
+                    accessibilityLabel={`Accept — ${c.label}`}
+                    onPress={() => props.onAcceptItem?.(i)}
+                  />
+                  <IconButton
+                    icon="x"
+                    size="sm"
+                    color="none"
+                    iconColor={rejected ? solid("red") : colors.zinc[400]}
+                    accessibilityLabel={`Reject — ${c.label}`}
+                    onPress={() => props.onRejectItem?.(i)}
+                  />
+                </View>
+              ) : null}
+            </View>
+          );
+        })}
+      </View>
+
+      {status !== "open" ? (
+        <View style={styles.outcome}>
+          <Icon
+            name={status === "applied" ? "circle-check" : "rotate-ccw"}
+            size={14}
+            color={status === "applied" ? solid("emerald") : colors.zinc[400]}
+          />
+          <Text size="xs" color="muted">
+            {status === "applied" ? "Applied" : "Discarded"}
+          </Text>
+        </View>
+      ) : (
+        <View style={styles.footer}>
+          <View style={{ flex: 1 }}>
+            {perItem ? (
+              <Text size="xs" color="muted">
+                {accepted} of {props.changes.length} accepted
+              </Text>
+            ) : null}
+          </View>
+          {props.onDiscard ? <LinkButton title={perItem ? "Reject all" : "Discard"} onPress={props.onDiscard} /> : null}
+          {props.onApply ? (
+            <Button
+              title={props.applyLabel ?? (perItem ? "Apply accepted" : "Apply")}
+              color="primary"
+              shape="rounded"
+              disabled={perItem && accepted === 0}
+              onPress={props.onApply}
+            />
+          ) : null}
+        </View>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  card: {
+    borderWidth: 1,
+    borderColor: tint("violet", 0.35),
+    backgroundColor: colors.white,
+    borderRadius: 12,
+    padding: 14,
+    gap: 12,
+  },
+  resolved: { borderColor: colors.border, backgroundColor: colors.zinc[50] },
+  summary: { flexDirection: "row", alignItems: "center", gap: 8 },
+  changes: { gap: 8 },
+  change: { flexDirection: "row", alignItems: "center", gap: 12 },
+  changeLabel: { width: 120 },
+  diff: { flexDirection: "row", alignItems: "center", gap: 8, flex: 1 },
+  before: { textDecorationLine: "line-through" },
+  itemControls: { flexDirection: "row", alignItems: "center", gap: 2 },
+  outcome: { flexDirection: "row", alignItems: "center", gap: 6 },
+  footer: { flexDirection: "row", alignItems: "center", gap: 8 },
+});

package/src/chip_group.tsx

@@ -3,17 +3,19 @@ import { Text } from "./text";
 import { PressableHighlight } from "./pressable_highlight";
 import { pillSurfaceStyle } from "./control_surface";
 
-// Exclusive filter chips — the view-control sibling of the form-input
-// selectors. Picking between the one-of-N controls:
-//   - ChipGroup: a SMALL, HOT filter set (≤ ~10 short options) the user flips
-//     between constantly — every option stays visible, switching is one tap,
-//     the row wraps on narrow widths. Reads as "narrow this view".
-//   - Picker: many options or tight space — compact, but hides the set behind
-//     a click. Reads as "choose a value".
-//   - RadioPicker: a form input that SETS data on a record (radio circles
-//     signal "this writes"), not a view filter.
-// Chips carry quiet zinc styling: bordered white at rest, dark fill when
-// active — color stays reserved for status semantics and primary actions.
+// One-of-N chips: every option visible, one tap to switch, the row wraps on
+// narrow widths. Quiet zinc styling — bordered white at rest, dark fill when
+// active (color stays reserved for status + primary actions). Two jobs, one
+// control:
+//   - a SMALL, HOT FILTER the user flips between constantly ("narrow this
+//     view") — model the unfiltered state as an explicit option (e.g. "All").
+//   - a small REQUIRED single-select in a form / composer (a call outcome, a
+//     1–N grade) — pills keep every choice in view and entry to one tap; an
+//     empty initial value (nothing chosen yet) is fine here.
+// Reach for `Picker` when options are many or space is tight (it hides the set
+// behind a click); for `RadioPicker` when the radio-circle "this writes"
+// affordance suits a denser form. It's affordance + density, not
+// filter-vs-write — the same ChipGroup serves both.
 
 export interface ChipOption<T extends string = string> {
   label: string;
@@ -29,8 +31,9 @@ export interface ChipGroupProps<T extends string = string> {
    */
   accessibilityLabel: string;
   options: ChipOption<T>[];
-  /** The active option — exactly one; include an explicit "all" option for
-   *  the unfiltered state rather than modelling it as no selection. */
+  /** The active option. As a FILTER, model the unfiltered state as an explicit
+   *  option (e.g. "All"); as a FORM selector, an empty value (nothing chosen
+   *  yet) is valid. */
   value: T;
   onValueChange: (value: T) => void;
 }

package/src/clarify.tsx

@@ -0,0 +1,68 @@
+import { StyleSheet, View } from "react-native";
+import { colors, solid, tint } from "./colors";
+import { Text } from "./text";
+import { Icon } from "./icon";
+import { Button } from "./button";
+
+export interface ClarifyOption {
+  label: string;
+  value: string;
+}
+
+export interface ClarifyProps {
+  /** The agent's question — what it needs settled to proceed. */
+  question: string;
+  options: ClarifyOption[];
+  onAnswer: (value: string) => void;
+  /** Once answered, the card settles showing the chosen reply (pass the option
+   *  label). */
+  answer?: string;
+}
+
+/**
+ * The agent asks BACK — a question with quick-reply options the human picks
+ * before the run continues. Human-in-the-loop input: when the agent is unsure,
+ * it clarifies instead of guessing wrong. The run pauses on this; `onAnswer`
+ * resumes it. Pair with `AgentRun` / `AgentProgress`.
+ */
+export function Clarify(props: ClarifyProps) {
+  const answered = props.answer != null;
+  return (
+    <View style={styles.card}>
+      <View style={styles.header}>
+        <Icon name="message-circle-question-mark" size={15} color={solid("violet")} />
+        <Text size="sm" weight="medium" style={{ flex: 1 }}>
+          {props.question}
+        </Text>
+      </View>
+      {answered ? (
+        <View style={styles.answered}>
+          <Icon name="circle-check" size={14} color={solid("emerald")} />
+          <Text size="sm" color="muted">
+            {props.answer}
+          </Text>
+        </View>
+      ) : (
+        <View style={styles.options}>
+          {props.options.map((o) => (
+            <Button key={o.value} title={o.label} color="secondary" shape="rounded" onPress={() => props.onAnswer(o.value)} />
+          ))}
+        </View>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  card: {
+    borderWidth: 1,
+    borderColor: tint("violet", 0.35),
+    backgroundColor: colors.white,
+    borderRadius: 12,
+    padding: 14,
+    gap: 12,
+  },
+  header: { flexDirection: "row", alignItems: "flex-start", gap: 8 },
+  options: { flexDirection: "row", flexWrap: "wrap", gap: 8 },
+  answered: { flexDirection: "row", alignItems: "center", gap: 6 },
+});

package/src/colors.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { isColorName, asColorName } from "./colors";
+
+describe("isColorName", () => {
+  it("accepts palette family names", () => {
+    expect(isColorName("blue")).toBe(true);
+    expect(isColorName("emerald")).toBe(true);
+    expect(isColorName("zinc")).toBe(true);
+  });
+
+  it("rejects role keys and scalar colors (not selectable families)", () => {
+    expect(isColorName("border")).toBe(false);
+    expect(isColorName("border_shadow")).toBe(false);
+    expect(isColorName("background")).toBe(false);
+    expect(isColorName("shadow")).toBe(false);
+    expect(isColorName("black")).toBe(false);
+    expect(isColorName("white")).toBe(false);
+  });
+
+  it("rejects unknown tokens and non-strings", () => {
+    expect(isColorName("chartreuse")).toBe(false);
+    expect(isColorName("")).toBe(false);
+    expect(isColorName(undefined)).toBe(false);
+    expect(isColorName(null)).toBe(false);
+    expect(isColorName(42)).toBe(false);
+  });
+});
+
+describe("asColorName", () => {
+  it("passes a valid family through", () => {
+    expect(asColorName("purple")).toBe("purple");
+  });
+
+  it("degrades an unknown/absent token to the neutral default", () => {
+    // The graceful-degradation contract: a select option whose color token this
+    // build doesn't recognize, or none at all, renders neutral rather than break.
+    expect(asColorName("chartreuse")).toBe("zinc");
+    expect(asColorName(undefined)).toBe("zinc");
+    expect(asColorName(null)).toBe("zinc");
+  });
+
+  it("honors a custom fallback", () => {
+    expect(asColorName(undefined, "slate")).toBe("slate");
+  });
+});

package/src/colors.ts

@@ -359,3 +359,28 @@ export function ramp(name: ColorName, count: number): string[] {
     return scale[RAMP_STOPS[idx]];
   });
 }
+
+/**
+ * Is `value` a usable {@link ColorName} — a palette FAMILY, not a role key
+ * (`border`/`background`/…) and not `black`/`white`? A family resolves to a
+ * shade object; the role/scalar keys resolve to a string, so "value is an
+ * object" is the test (no name list to keep in sync).
+ */
+export function isColorName(value: unknown): value is ColorName {
+  return (
+    typeof value === "string" &&
+    value in colors &&
+    typeof (colors as Record<string, unknown>)[value] === "object"
+  );
+}
+
+/**
+ * Coerce an arbitrary color token to a {@link ColorName}, falling back to a
+ * neutral. The single graceful-degradation point for stored option/status
+ * colors: a select option's `color` may be a token a newer table config
+ * introduced that this UI build predates, or absent entirely — either way a
+ * component renders a neutral badge instead of breaking. Used by `OptionBadge`.
+ */
+export function asColorName(value: unknown, fallback: ColorName = "zinc"): ColorName {
+  return isColorName(value) ? value : fallback;
+}

package/src/confidence.tsx

@@ -0,0 +1,31 @@
+import { Badge } from "./badge";
+import type { ColorName } from "./colors";
+
+export type ConfidenceLevel = "high" | "medium" | "low";
+
+export interface ConfidenceProps {
+  /** Pass a level directly, or a 0–1 `score` (≥0.8 high · ≥0.5 medium · else low). */
+  level?: ConfidenceLevel;
+  score?: number;
+}
+
+const LABEL: Record<ConfidenceLevel, string> = { high: "High", medium: "Medium", low: "Low" };
+// low is zinc (unsure, NOT an error — an error is a different signal); high
+// emerald, medium amber. One family per level, weights derive from the name.
+const COLOR: Record<ConfidenceLevel, ColorName> = { high: "emerald", medium: "amber", low: "zinc" };
+
+export function levelFromScore(score: number): ConfidenceLevel {
+  if (score >= 0.8) return "high";
+  if (score >= 0.5) return "medium";
+  return "low";
+}
+
+/**
+ * How sure the AI is — a calibrated high/medium/low chip on the kit's `Badge`
+ * (dot variant). The human weights an AI proposal or estimate by it before
+ * accepting. Pair with `Suggestion` and `AssistedField`.
+ */
+export function Confidence(props: ConfidenceProps) {
+  const level = props.level ?? (props.score != null ? levelFromScore(props.score) : "medium");
+  return <Badge variant="dot" color={COLOR[level]} label={LABEL[level]} />;
+}

package/src/file_dropzone.tsx

@@ -20,8 +20,9 @@ export interface FileDropzoneProps {
   hint?: string;
   /** Main line while a drag hovers the zone ("Thả để tải lên"). */
   dropLabel?: string;
-  /** Zone height — size it to the surface (compact 120 in a form field,
-   * 200+ as a screen's main affordance). Default 160. */
+  /** Minimum zone height — it grows to fit the icon + labels + padding, so a
+   * small value never crops the content. Size it to the surface (compact ~120 in
+   * a form field, 200+ as a screen's main affordance). Default 160. */
   height?: number;
   disabled?: boolean;
   accessibilityLabel?: string;
@@ -127,7 +128,7 @@ export function FileDropzone(props: FileDropzoneProps) {
       onHoverOut={() => setHovered(false)}
       style={[
         styles.zone,
-        { height },
+        { minHeight: height },
         hovered && !dragging ? styles.zoneHovered : null,
         dragging ? styles.zoneDragging : null,
         disabled ? styles.zoneDisabled : null,
@@ -160,6 +161,7 @@ const styles = StyleSheet.create({
     borderColor: colors.zinc[300],
     backgroundColor: colors.zinc[50],
     paddingHorizontal: 20,
+    paddingVertical: 16,
   },
   zoneHovered: {
     borderColor: colors.zinc[400],

package/src/inline_edit.tsx

@@ -102,8 +102,10 @@ interface InlineEditFrameProps {
 }
 
 interface InlineEditViewProps {
-  /** The formatted current value. Empty → placeholder. */
-  display: string;
+  /** The current value: a formatted string (empty → placeholder), or a node
+   *  rendered as-is — e.g. a `MemberChip` / `OptionBadge` for a rich resting
+   *  value. A node takes the flex slot; the trailing adornment still right-aligns. */
+  display: string | ReactNode;
   placeholder?: string;
   onPress?: () => void;
   disabled?: boolean;
@@ -136,9 +138,13 @@ export function InlineEditView(props: InlineEditViewProps) {
       userSelect="none"
       style={[styles.view, active && styles.viewActive]}
     >
-      <Text numberOfLines={1} style={[viewTextStyle, display ? null : styles.placeholder]}>
-        {display || placeholder || "—"}
-      </Text>
+      {typeof display === "string" ? (
+        <Text numberOfLines={1} style={[viewTextStyle, display ? null : styles.placeholder]}>
+          {display || placeholder || "—"}
+        </Text>
+      ) : (
+        <View style={styles.viewNode}>{display}</View>
+      )}
       {trailing != null ? trailing : null}
     </PressableHighlight>
   );
@@ -230,6 +236,7 @@ const styles = StyleSheet.create({
     boxShadow: ACTIVE_RING,
   },
   placeholder: { color: colors.zinc[400] },
+  viewNode: { flex: 1, minWidth: 0 },
   editRow: { flexDirection: "row", alignItems: "flex-start", gap: 6 },
   editControl: { flex: 1, position: "relative" },
   savingOverlay: { position: "absolute", right: 8, top: 0, bottom: 0, justifyContent: "center" },

package/src/inline_member_select.tsx

@@ -0,0 +1,62 @@
+import { useCallback, useMemo } from "react";
+import { InlineSelect } from "./inline_select";
+import { MemberChip } from "./member_chip";
+import type { MemberSelectMember } from "./member_select";
+import type { PickerOption } from "./picker";
+
+interface InlineMemberSelectProps {
+  /** The candidate roster — an app feeds `useMembers()`, the product any
+   *  directory. Each member carries its own avatar (`image`), so the resting
+   *  chip and every option render with no side lookup. */
+  members: MemberSelectMember[];
+  /** The currently-assigned member id, or `null` when unassigned. A value not
+   *  in `members` (a removed/deactivated member) reads as empty → placeholder. */
+  value: string | null;
+  /** Commit a new assignment (the picked member id). Throwing surfaces the
+   *  inline error and reverts, like every inline editor. */
+  onSave: (memberId: string) => void | Promise<void>;
+  placeholder?: string;
+  disabled?: boolean;
+  accessibilityLabel?: string;
+}
+
+/**
+ * Edit a `select_member` field in place: the assigned member shows as a
+ * {@link MemberChip} (avatar + name) at the kit's control height; clicking it
+ * floats a member picker (every option a `MemberChip`) and picking commits — no
+ * layout shift. The inline-edit twin of {@link MemberSelect} (use that in a
+ * form); built on {@link InlineSelect}. PURE: pass the candidate `members` (an
+ * app feeds `useMembers`); this fetches nothing.
+ *
+ * ```tsx
+ * const { members } = useMembers();
+ * <InlineMemberSelect members={members} value={row.assignee} onSave={saveAssignee} />
+ * ```
+ */
+export function InlineMemberSelect(props: InlineMemberSelectProps) {
+  const { members, ...inline } = props;
+
+  const byId = useMemo(() => new Map(members.map((m) => [m.id, m])), [members]);
+  const options = useMemo<PickerOption<string>[]>(
+    () => members.map((m) => ({ value: m.id, label: m.name || m.email || m.id })),
+    [members],
+  );
+
+  const renderMember = useCallback(
+    (option: PickerOption<string>) => {
+      const member = byId.get(option.value);
+      if (!member) return null;
+      return <MemberChip name={member.name || member.email} image={member.image} />;
+    },
+    [byId],
+  );
+
+  return (
+    <InlineSelect<string>
+      options={options}
+      renderOptionContent={renderMember}
+      renderValue={renderMember}
+      {...inline}
+    />
+  );
+}

package/src/inline_select.tsx

@@ -16,6 +16,10 @@ export interface InlineSelectProps<T extends string> {
   /** Custom option content in the dropdown (icon + label, two-line, a badge…).
    *  Omit for a plain label list — both render through the same `PickerMenu`. */
   renderOptionContent?: (option: PickerOption<T>) => React.ReactNode;
+  /** Render the SELECTED value in the resting view as a node (an avatar chip, a
+   *  colored badge) instead of its plain label. Falls back to the label when
+   *  omitted; the empty state always shows the placeholder. */
+  renderValue?: (selected: PickerOption<T>) => React.ReactNode;
   placeholder?: string;
   disabled?: boolean;
   accessibilityLabel?: string;
@@ -29,7 +33,7 @@ export interface InlineSelectProps<T extends string> {
  * standard and custom-rendered pickers are both supported here.
  */
 export function InlineSelect<T extends string>(props: InlineSelectProps<T>) {
-  const { value, onSave, options, renderOptionContent, placeholder, disabled, accessibilityLabel } = props;
+  const { value, onSave, options, renderOptionContent, renderValue, placeholder, disabled, accessibilityLabel } = props;
   const [open, setOpen] = useState(false);
   const [saving, setSaving] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -58,7 +62,7 @@ export function InlineSelect<T extends string>(props: InlineSelectProps<T>) {
       <Popover open={open && !disabled} onOpenChange={setOpen} side="bottom" align="start" inheritTriggerWidth>
         <PopoverTrigger>
           <InlineEditView
-            display={selected?.label ?? ""}
+            display={selected ? (renderValue ? renderValue(selected) : (selected.label ?? "")) : ""}
             placeholder={placeholder}
             disabled={disabled}
             active={open && !disabled}