@lotics/ui 3.5.0 → 4.0.0

package/src/callout.tsx

@@ -1,3 +1,4 @@
+import { type ReactNode } from "react";
 import { View, StyleSheet } from "react-native";
 import { Text } from "./text";
 import { Icon, type IconName } from "./icon";
@@ -8,12 +9,12 @@ export type CalloutTone = "info" | "success" | "warning" | "error" | "neutral";
 interface CalloutProps {
   /** Sets the accent (icon + tint + border) and the default icon. Default "info". */
   tone?: CalloutTone;
-  /** Optional bold heading above the message. */
-  title?: string;
-  /** The message body — kept in the default text color for legibility on the tint. */
-  message: string;
   /** Override the per-tone default icon (any kit icon), or `null` to drop it. */
   icon?: IconName | null;
+  /** Compose the body with `CalloutTitle`, `CalloutText`, and `CalloutActions`. */
+  children: ReactNode;
+  /** Test id on the container. */
+  testID?: string;
 }
 
 interface ToneStyle {
@@ -23,11 +24,16 @@ interface ToneStyle {
   glyph: IconName;
 }
 
+// Tint surface + SOFT hairline border + deep icon — matches the kit's toned-surface
+// convention (Badge: bg-50 / border-100 / deep accent). A heavier 200 border + 600
+// icon reads as a generic "library alert"; the soft 100 border lets the tint settle
+// into a calm panel with the deep-700 icon carrying the tone. (Neutral keeps a 200
+// border — zinc-100 is invisible on zinc-50.)
 const TONES: Record<CalloutTone, ToneStyle> = {
-  info: { bg: colors.blue[50], border: colors.blue[200], icon: colors.blue[600], glyph: "info" },
-  success: { bg: colors.emerald[50], border: colors.emerald[200], icon: colors.emerald[600], glyph: "circle-check" },
-  warning: { bg: colors.amber[50], border: colors.amber[200], icon: colors.amber[600], glyph: "triangle-alert" },
-  error: { bg: colors.red[50], border: colors.red[200], icon: colors.red[600], glyph: "circle-alert" },
+  info: { bg: colors.blue[50], border: colors.blue[100], icon: colors.blue[700], glyph: "info" },
+  success: { bg: colors.emerald[50], border: colors.emerald[100], icon: colors.emerald[700], glyph: "circle-check" },
+  warning: { bg: colors.amber[50], border: colors.amber[100], icon: colors.amber[700], glyph: "triangle-alert" },
+  error: { bg: colors.red[50], border: colors.red[100], icon: colors.red[700], glyph: "circle-alert" },
   neutral: { bg: colors.zinc[50], border: colors.zinc[200], icon: colors.zinc[500], glyph: "info" },
 };
 
@@ -38,28 +44,54 @@ const TONES: Record<CalloutTone, ToneStyle> = {
  * prompt use `Alert`; for a one-word status use `Badge`. The tone is carried by
  * the icon + tint + border (never color alone — the icon and text stay legible),
  * so it reads on a glance and meets contrast on the light tint.
+ *
+ * COMPOUND — compose the body from the sub-components (like `Card`); this lets a
+ * callout carry rich content and inline actions, not just a string message:
+ *
+ * ```tsx
+ * <Callout tone="warning">
+ *   <CalloutTitle>Phí chưa nhập</CalloutTitle>
+ *   <CalloutText>Nhập trước khi xuất chứng từ, hoặc đặt = 0.</CalloutText>
+ *   <CalloutActions>
+ *     <Button title="Đặt = 0" onPress={fill} />
+ *   </CalloutActions>
+ * </Callout>
+ * ```
  */
-export function Callout({ tone = "info", title, message, icon }: CalloutProps) {
+export function Callout({ tone = "info", icon, children, testID }: CalloutProps) {
   const t = TONES[tone];
   const glyph = icon === null ? null : (icon ?? t.glyph);
   return (
     <View
       accessibilityRole={tone === "error" || tone === "warning" ? "alert" : undefined}
       style={[styles.container, { backgroundColor: t.bg, borderColor: t.border }]}
+      testID={testID}
     >
       {glyph ? <Icon name={glyph} size={18} color={t.icon} /> : null}
-      <View style={styles.body}>
-        {title ? (
-          <Text size="sm" weight="semibold">
-            {title}
-          </Text>
-        ) : null}
-        <Text size="sm">{message}</Text>
-      </View>
+      <View style={styles.body}>{children}</View>
     </View>
   );
 }
 
+/** Bold heading at the top of a `Callout`. */
+export function CalloutTitle({ children }: { children: ReactNode }) {
+  return (
+    <Text size="sm" weight="semibold">
+      {children}
+    </Text>
+  );
+}
+
+/** Message body of a `Callout` — default text color for legibility on the tint. */
+export function CalloutText({ children }: { children: ReactNode }) {
+  return <Text size="sm">{children}</Text>;
+}
+
+/** A row of actions (e.g. buttons) at the foot of a `Callout`. */
+export function CalloutActions({ children }: { children: ReactNode }) {
+  return <View style={styles.actions}>{children}</View>;
+}
+
 export type { CalloutProps };
 
 const styles = StyleSheet.create({
@@ -72,4 +104,5 @@ const styles = StyleSheet.create({
     borderWidth: 1,
   },
   body: { flex: 1, gap: 2, paddingTop: 1 },
+  actions: { flexDirection: "row", flexWrap: "wrap", gap: 8, marginTop: 6 },
 });

package/src/combobox.tsx

@@ -54,6 +54,12 @@ export interface ComboboxProps<T extends string = string, D = unknown> {
   /** Label for the free-entry row (default: `Add "<query>"`). Return null to
    *  suppress it for a given query. */
   customOptionLabel?: (query: string) => string | null;
+  /** Where the free-entry "Create…" row sits relative to the matches. Default
+   *  "bottom" (matches first, create as the fallback). "top" pins it above the
+   *  results for a find-or-create field where the create affordance should stay
+   *  visible; the default keyboard highlight still lands on the first MATCH, so
+   *  Enter on a partial selects the existing record and never creates a duplicate. */
+  customOptionPlacement?: "top" | "bottom";
   /** Shown — under a heading — when the input is focused but empty. */
   recentOptions?: PickerOption<T, D>[];
   loading?: boolean;
@@ -111,6 +117,7 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
     getOptionDescription,
     allowCustom = false,
     customOptionLabel,
+    customOptionPlacement = "bottom",
     recentOptions,
     loading = false,
     searchDebounceMs = 200,
@@ -179,8 +186,9 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
 
   const list = useMemo(() => {
     const base = searching ? filtered : (recentOptions ?? []);
-    return customRow ? [...base, customRow] : base;
-  }, [searching, filtered, recentOptions, customRow]);
+    if (!customRow) return base;
+    return customOptionPlacement === "top" ? [customRow, ...base] : [...base, customRow];
+  }, [searching, filtered, recentOptions, customRow, customOptionPlacement]);
 
   const debouncedSearch = useDebouncedCallback(onSearchChange ?? (() => {}), searchDebounceMs);
 
@@ -235,10 +243,18 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
     onActiveChange: scrollToIndex,
   });
 
+  // Default the keyboard highlight to the first real (non-custom, enabled)
+  // option, so a free-entry "Create…" row — wherever it sits — is never the
+  // Enter target while a match exists (Enter on a partial picks the match, not
+  // a duplicate). Only when the custom row is the sole option does it lead.
   const firstValue = list[0]?.value;
+  const defaultIndex = useMemo(() => {
+    const i = list.findIndex((o) => o.testID !== CUSTOM_VALUE && !o.disabled);
+    return i >= 0 ? i : 0;
+  }, [list]);
   useEffect(() => {
-    setActiveIndex(0);
-  }, [searching, list.length, firstValue, setActiveIndex]);
+    setActiveIndex(defaultIndex);
+  }, [searching, list.length, firstValue, defaultIndex, setActiveIndex]);
 
   const handleChangeText = useCallback(
     (text: string) => {
@@ -390,7 +406,7 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
                         </Text>
                       </View>
                     ) : (
-                      <Text userSelect="none" numberOfLines={1} color={isCustom ? "zinc-500" : undefined}>
+                      <Text userSelect="none" numberOfLines={1} weight={isCustom ? "medium" : undefined}>
                         {label}
                       </Text>
                     );
@@ -401,7 +417,7 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
                       testID={isCustom ? "combobox-custom-option" : `combobox-option-${opt.value}`}
                       role="option"
                       accessibilityLabel={label}
-                      icon={isCustom ? <Icon name="plus" size={16} color={colors.zinc["400"]} /> : undefined}
+                      icon={isCustom ? <Icon name="plus" size={16} color={colors.zinc["600"]} /> : undefined}
                       title={title}
                       focused={i === activeIndex}
                       selected={!multi && !isCustom && single?.value === opt.value}

package/src/form_date_picker.tsx

@@ -5,6 +5,8 @@ export interface FormDatePickerProps
   extends Omit<FormFieldProps, "style">,
     DatePickerProps {}
 
+/** `FormField` wrapping a `DatePicker` — one labeled date field. (Omits `style`; for a grid cell
+ *  use a bare `FormField style={half}` around `DatePicker`.) */
 export function FormDatePicker(props: FormDatePickerProps) {
   const { label, description, optional, optionalLabel, error, ...datePickerProps } = props;
 

package/src/form_picker.tsx

@@ -1,6 +1,7 @@
 import { FormField, FormFieldProps } from "./form_field";
 import { Picker, PickerProps } from "./picker";
 
+/** `FormField` wrapping a `Picker` — one labeled select. */
 export function FormPicker<T extends string, MULTI extends boolean = false>(
   props: PickerProps<T, MULTI> & FormFieldProps,
 ) {

package/src/form_switch.tsx

@@ -7,6 +7,7 @@ import { Spacer } from "./spacer";
 
 export interface FormSwitchProps extends Omit<FormFieldProps, "optional">, SwitchProps {}
 
+/** A labeled on/off toggle — a `Switch` + clickable label + optional `description`/`error`. */
 export function FormSwitch(props: FormSwitchProps) {
   const { label, description, error, value, onChange } = props;
   const labelId = useId();

package/src/form_text_input.tsx

@@ -4,6 +4,8 @@ import { TextInputField } from "./text_input_field";
 
 export interface FormTextInputProps extends Omit<FormFieldProps, "style">, TextInputProps {}
 
+/** `FormField` (label / description / error / optional) wrapping a `TextInputField` — one labeled
+ *  text field. For a 2-col grid cell, prefer a bare `FormField style={half}` around the input. */
 export function FormTextInput(props: FormTextInputProps) {
   const { label, description, optional, error, ...textInputProps } = props;
 

package/src/icon.tsx

@@ -144,6 +144,7 @@ import PanelRightOpen from "lucide-react-native/dist/esm/icons/panel-right-open"
 import Paperclip from "lucide-react-native/dist/esm/icons/paperclip";
 import Pause from "lucide-react-native/dist/esm/icons/pause";
 import Pencil from "lucide-react-native/dist/esm/icons/pencil";
+import Phone from "lucide-react-native/dist/esm/icons/phone";
 import Pin from "lucide-react-native/dist/esm/icons/pin";
 import PinOff from "lucide-react-native/dist/esm/icons/pin-off";
 import Play from "lucide-react-native/dist/esm/icons/play";
@@ -337,6 +338,7 @@ const iconComponents = {
   paperclip: Paperclip,
   pause: Pause,
   pencil: Pencil,
+  phone: Phone,
   pin: Pin,
   "pin-off": PinOff,
   play: Play,

package/src/icon_button.tsx

@@ -9,7 +9,7 @@ interface IconButtonBase {
   ref?: Ref<View>;
   testID?: string;
   icon: IconName;
-  color?: "none" | "secondary" | "white";
+  color?: "none" | "primary" | "secondary" | "white";
   /** `md` (28px, 18px glyph) for toolbars; `sm` (24px, 14px glyph) for
    * inline affordances sitting next to body/sm text — e.g. the ⓘ in a
    * CardHeader. Both keep a 40px touch target via hitSlop. */
@@ -71,7 +71,7 @@ export function IconButton(props: IconButtonProps) {
       <Icon
         size={size === "sm" ? 14 : 18}
         name={icon}
-        color={iconColor || (color === "white" ? colors.white : colors.zinc[700])}
+        color={iconColor || (color === "white" || color === "primary" ? colors.white : colors.zinc[700])}
       />
     </PressableHighlight>
   );
@@ -97,6 +97,9 @@ const styles = StyleSheet.create({
     opacity: 0.3,
   },
   none: {},
+  primary: {
+    backgroundColor: colors.zinc[900],
+  },
   secondary: {
     backgroundColor: colors.zinc[100],
   },

package/src/inline_date_picker.tsx

@@ -0,0 +1,110 @@
+import { useCallback, useRef, useState } from "react";
+import { View } from "react-native";
+import { Icon } from "./icon";
+import { Text } from "./text";
+import { colors } from "./colors";
+import { Popover, PopoverTrigger, PopoverContent } from "./popover";
+import { DatePickerPanel } from "./date_picker";
+import { formatDate } from "./format_date";
+import { ActivityIndicator } from "./activity_indicator";
+import { InlineEditView } from "./inline_edit";
+
+export interface InlineDatePickerProps {
+  /** ISO date (`2026-05-22`) or datetime (`2026-05-22T14:30`). */
+  value: string | null;
+  onSave: (next: string) => void | Promise<void>;
+  /** "date" (default) or "datetime". */
+  format?: "date" | "datetime";
+  placeholder?: string;
+  /** BCP-47 locale for the calendar and the displayed date. */
+  locale?: string;
+  disabled?: boolean;
+  accessibilityLabel?: string;
+}
+
+/**
+ * An inline-editable date / datetime. The value reads as a formatted date;
+ * clicking it floats the calendar (`DatePickerPanel`) in a popover anchored to
+ * the view, so the row never changes height. The selection commits when the
+ * panel closes (immediately for a single date, after time entry for datetime);
+ * dismissing without a change reverts.
+ */
+export function InlineDatePicker(props: InlineDatePickerProps) {
+  const { value, onSave, format = "date", placeholder, locale, disabled, accessibilityLabel } = props;
+  const [open, setOpen] = useState(false);
+  const [draft, setDraft] = useState<string | null>(value);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // The latest panel value, read at close time (the draft state can be stale in
+  // the close handler's closure).
+  const draftRef = useRef<string | null>(value);
+
+  const commit = useCallback(async () => {
+    const next = draftRef.current;
+    if (next === value || !next) return;
+    setSaving(true);
+    setError(null);
+    try {
+      await onSave(next);
+    } catch (e) {
+      setError(e instanceof Error && e.message ? e.message : "Couldn't save. Try again.");
+    } finally {
+      setSaving(false);
+    }
+  }, [value, onSave]);
+
+  const onOpenChange = useCallback(
+    (next: boolean) => {
+      if (next) {
+        draftRef.current = value;
+        setDraft(value);
+        setOpen(true);
+      } else {
+        setOpen(false);
+        void commit();
+      }
+    },
+    [value, commit],
+  );
+
+  const display = formatDate(value, { format, locale, emptyLabel: "" });
+
+  return (
+    <View>
+      <Popover open={open && !disabled} onOpenChange={onOpenChange} side="bottom" align="start">
+        <PopoverTrigger>
+          <InlineEditView
+            display={display}
+            placeholder={placeholder}
+            disabled={disabled}
+            accessibilityLabel={accessibilityLabel}
+            trailing={
+              saving ? (
+                <ActivityIndicator size={16} color={colors.zinc[400]} />
+              ) : (
+                <Icon name="calendar" size={18} color={colors.zinc[400]} />
+              )
+            }
+          />
+        </PopoverTrigger>
+        <PopoverContent>
+          <DatePickerPanel
+            value={draft}
+            onValueChange={(v) => {
+              draftRef.current = v;
+              setDraft(v);
+            }}
+            format={format}
+            locale={locale}
+            onRequestClose={() => setOpen(false)}
+          />
+        </PopoverContent>
+      </Popover>
+      {error ? (
+        <Text size="xs" color="danger" style={{ marginTop: 4 }}>
+          {error}
+        </Text>
+      ) : null}
+    </View>
+  );
+}

package/src/inline_edit.tsx

@@ -0,0 +1,228 @@
+import { useCallback, useRef, useState, type ReactNode, type Ref } from "react";
+import { View, StyleSheet } from "react-native";
+import { Text } from "./text";
+import { IconButton } from "./icon_button";
+import { ActivityIndicator } from "./activity_indicator";
+import { PressableHighlight } from "./pressable_highlight";
+import { colors } from "./colors";
+import { fontFamilyRegular, getInputTextStyle } from "./text_utils";
+
+/** The kit's standard control height (TextInputField, NumberInput, Picker, …).
+ *  The view box matches it — same height, padding, and a 1px transparent border
+ *  — so swapping to the input on click never shifts the layout. */
+export const INLINE_CONTROL_HEIGHT = 40;
+
+export type InlineEditControls = "blur" | "buttons";
+
+/**
+ * Drives an inline-editable field: a view ⇄ edit toggle, a draft buffer, and an
+ * async save with saving/error state. The typed `Inline*` inputs wire their
+ * control's `onBlur`/keydown to `commit()` / `cancel()`. Reuse this hook with
+ * `InlineEditFrame` to make any custom input inline-editable the same way.
+ */
+export function useInlineEdit<T>(opts: {
+  value: T;
+  onSave: (next: T) => void | Promise<void>;
+  /** Equality used to skip a no-op save. Defaults to `===`. */
+  equals?: (a: T, b: T) => boolean;
+}) {
+  const { value, onSave, equals } = opts;
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState<T>(value);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // Synchronous mirror of `editing`. The first exit (commit or cancel) flips it
+  // false; any trailing call — e.g. the blur that fires as Escape unmounts the
+  // input — is then a no-op, so the field commits/cancels exactly once.
+  const active = useRef(false);
+
+  const begin = useCallback(() => {
+    setDraft(value);
+    setError(null);
+    active.current = true;
+    setEditing(true);
+  }, [value]);
+
+  const cancel = useCallback(() => {
+    if (!active.current) return;
+    active.current = false;
+    setEditing(false);
+    setError(null);
+  }, []);
+
+  const commit = useCallback(
+    async (next?: T) => {
+      if (!active.current) return;
+      const candidate = next === undefined ? draft : next;
+      const unchanged = equals ? equals(candidate, value) : candidate === value;
+      if (unchanged) {
+        active.current = false;
+        setEditing(false);
+        return;
+      }
+      active.current = false;
+      setSaving(true);
+      setError(null);
+      try {
+        await onSave(candidate);
+        setEditing(false);
+      } catch (e) {
+        // Stay in edit mode so the entry isn't lost — show the error, re-arm.
+        setError(e instanceof Error && e.message ? e.message : "Couldn't save. Try again.");
+        active.current = true;
+      } finally {
+        setSaving(false);
+      }
+    },
+    [draft, value, onSave, equals],
+  );
+
+  return { editing, draft, setDraft, saving, error, begin, cancel, commit };
+}
+
+interface InlineEditFrameProps {
+  editing: boolean;
+  /** The formatted current value, shown in view mode. Empty → placeholder. */
+  display: string;
+  placeholder?: string;
+  /** Enter edit mode (the view is pressed). */
+  onBegin: () => void;
+  /** The edit-mode control (rendered only while editing). */
+  children: React.ReactNode;
+  /** "blur" (default) commits on blur; "buttons" shows ✓/✕ and blur is inert. */
+  controls?: InlineEditControls;
+  onCommit?: () => void;
+  onCancel?: () => void;
+  saving?: boolean;
+  error?: string | null;
+  disabled?: boolean;
+  /** Accessible name for the view button when there's no enclosing FormField. */
+  accessibilityLabel?: string;
+}
+
+interface InlineEditViewProps {
+  /** The formatted current value. Empty → placeholder. */
+  display: string;
+  placeholder?: string;
+  onPress?: () => void;
+  disabled?: boolean;
+  accessibilityLabel?: string;
+  /** Right-aligned adornment — e.g. a chevron for a select, a spinner while saving. */
+  trailing?: ReactNode;
+  ref?: Ref<View>;
+}
+
+/**
+ * The view-mode box of an inline-editable field: the value as plain text in a
+ * `PressableHighlight` (hover tints it; the pointer cursor signals it's
+ * editable), at the kit's control height with a transparent border — so
+ * swapping to an input, or floating a dropdown above it, never shifts the
+ * layout. Used by `InlineEditFrame`, and as the overlay trigger for the
+ * select/date inline editors (it forwards ref + onPress to a `PopoverTrigger`).
+ */
+export function InlineEditView(props: InlineEditViewProps) {
+  const { display, placeholder, onPress, disabled, accessibilityLabel, trailing, ref } = props;
+  return (
+    <PressableHighlight
+      ref={ref}
+      disabled={disabled}
+      onPress={onPress}
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel}
+      userSelect="none"
+      style={styles.view}
+    >
+      <Text numberOfLines={1} style={[viewTextStyle, display ? null : styles.placeholder]}>
+        {display || placeholder || "—"}
+      </Text>
+      {trailing != null ? trailing : null}
+    </PressableHighlight>
+  );
+}
+
+/**
+ * The shared shell of an inline-editable INPUT (text, number). View mode is an
+ * `InlineEditView`; on press it swaps to the input at the same height — no
+ * layout shift — plus the optional save/cancel controls. Compose it with
+ * `useInlineEdit`. (Overlay-based editors — select, date — use `InlineEditView`
+ * directly as a `Popover` trigger instead.)
+ */
+export function InlineEditFrame(props: InlineEditFrameProps) {
+  const {
+    editing,
+    display,
+    placeholder,
+    onBegin,
+    children,
+    controls = "blur",
+    onCommit,
+    onCancel,
+    saving,
+    error,
+    disabled,
+    accessibilityLabel,
+  } = props;
+
+  if (!editing) {
+    return (
+      <InlineEditView
+        display={display}
+        placeholder={placeholder}
+        onPress={onBegin}
+        disabled={disabled}
+        accessibilityLabel={accessibilityLabel}
+      />
+    );
+  }
+
+  return (
+    <View>
+      <View style={styles.editRow}>
+        <View style={styles.editControl}>
+          {children}
+          {/* The saving spinner floats inside the input's right edge — it must
+              never push or resize the control (no layout shift). */}
+          {saving ? (
+            <View style={styles.savingOverlay} pointerEvents="none">
+              <ActivityIndicator size={16} color={colors.zinc[400]} />
+            </View>
+          ) : null}
+        </View>
+        {controls === "buttons" ? (
+          <View style={styles.buttons}>
+            <IconButton icon="check" color="primary" size="sm" tooltip="Save" onPress={onCommit} disabled={saving} />
+            <IconButton icon="x" color="secondary" size="sm" tooltip="Cancel" onPress={onCancel} disabled={saving} />
+          </View>
+        ) : null}
+      </View>
+      {error ? (
+        <Text size="xs" color="danger" style={styles.error}>
+          {error}
+        </Text>
+      ) : null}
+    </View>
+  );
+}
+
+// The view text reuses the input's own canonical metrics (font, size, spacing)
+// so the value reads identically and occupies the same box in both modes.
+const viewTextStyle = [getInputTextStyle(), { flex: 1, fontFamily: fontFamilyRegular, letterSpacing: -0.4 }];
+
+const styles = StyleSheet.create({
+  view: {
+    minHeight: INLINE_CONTROL_HEIGHT,
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: "transparent",
+    paddingHorizontal: 8,
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 6,
+  },
+  placeholder: { color: colors.zinc[400] },
+  editRow: { flexDirection: "row", alignItems: "flex-start", gap: 6 },
+  editControl: { flex: 1, position: "relative" },
+  savingOverlay: { position: "absolute", right: 8, top: 0, bottom: 0, justifyContent: "center" },
+  buttons: { flexDirection: "row", gap: 6, height: INLINE_CONTROL_HEIGHT, alignItems: "center" },
+  error: { marginTop: 4 },
+});

package/src/inline_number_input.tsx

@@ -0,0 +1,70 @@
+import { useCallback } from "react";
+import type { KeyboardEvent } from "react";
+import { NumberInput } from "./number_input";
+import { InlineEditFrame, useInlineEdit, type InlineEditControls } from "./inline_edit";
+
+export interface InlineNumberInputProps {
+  value: number | null;
+  onSave: (next: number | null) => void | Promise<void>;
+  /** Format the value for view mode (e.g. currency, units). Default: the plain
+   *  number, or empty → placeholder when null. */
+  format?: (value: number | null) => string;
+  placeholder?: string;
+  min?: number;
+  max?: number;
+  controls?: InlineEditControls;
+  disabled?: boolean;
+  accessibilityLabel?: string;
+}
+
+/**
+ * An inline-editable numeric value — the `InlineTextInput` pattern over
+ * `NumberInput`. View mode can format the number (currency, units); edit mode is
+ * the bare numeric field at the same height, so the form never reflows.
+ */
+export function InlineNumberInput(props: InlineNumberInputProps) {
+  const { value, onSave, format, placeholder, min, max, controls = "blur", disabled, accessibilityLabel } = props;
+  const edit = useInlineEdit<number | null>({ value, onSave });
+
+  const onKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLInputElement>) => {
+      if (e.key === "Escape") edit.cancel();
+      else if (e.key === "Enter") void edit.commit();
+    },
+    [edit],
+  );
+
+  const onBlur = useCallback(() => {
+    if (controls === "buttons") return;
+    void edit.commit();
+  }, [controls, edit]);
+
+  const display = format ? format(value) : value == null ? "" : String(value);
+
+  return (
+    <InlineEditFrame
+      editing={edit.editing}
+      display={display}
+      placeholder={placeholder}
+      onBegin={edit.begin}
+      controls={controls}
+      onCommit={() => void edit.commit()}
+      onCancel={edit.cancel}
+      saving={edit.saving}
+      error={edit.error}
+      disabled={disabled}
+      accessibilityLabel={accessibilityLabel}
+    >
+      <NumberInput
+        value={edit.draft}
+        onValueChange={edit.setDraft}
+        onBlur={onBlur}
+        onKeyDown={onKeyDown}
+        autoFocus
+        min={min}
+        max={max}
+        accessibilityLabel={accessibilityLabel}
+      />
+    </InlineEditFrame>
+  );
+}