@lotics/ui 3.6.0 → 4.0.0

package/src/inline_text_input.tsx

@@ -0,0 +1,71 @@
+import { useCallback } from "react";
+import type { NativeSyntheticEvent, TextInputKeyPressEventData } from "react-native";
+import { TextInputField } from "./text_input_field";
+import { InlineEditFrame, useInlineEdit, type InlineEditControls } from "./inline_edit";
+
+export interface InlineTextInputProps {
+  value: string;
+  /** Persist the new value. May be async — the field shows a saving state and
+   *  surfaces a thrown error inline, staying in edit mode so nothing is lost. */
+  onSave: (next: string) => void | Promise<void>;
+  placeholder?: string;
+  /** "blur" (default): clicking away or Enter saves; Escape reverts. "buttons":
+   *  an explicit ✓ saves and ✕ reverts. */
+  controls?: InlineEditControls;
+  disabled?: boolean;
+  accessibilityLabel?: string;
+}
+
+/**
+ * An inline-editable single-line text value: reads as plain text, reveals an
+ * edit affordance on hover, and swaps in-place to a text input on click — at the
+ * same height, so the form never reflows. The preferred control for editing a
+ * value in a dense record / detail surface.
+ */
+export function InlineTextInput(props: InlineTextInputProps) {
+  const { value, onSave, placeholder, controls = "blur", disabled, accessibilityLabel } = props;
+  const edit = useInlineEdit<string>({ value, onSave });
+
+  const onKeyPress = useCallback(
+    (e: NativeSyntheticEvent<TextInputKeyPressEventData>) => {
+      const key = e.nativeEvent.key;
+      if (key === "Escape") edit.cancel();
+      else if (key === "Enter") void edit.commit();
+    },
+    [edit],
+  );
+
+  // Commit on blur (the ergonomic default for moving through a form). In
+  // "buttons" mode the ✓/✕ own the exit, so a stray blur is ignored. The hook's
+  // `active` guard makes the trailing blur after Enter/Escape a no-op.
+  const onBlur = useCallback(() => {
+    if (controls === "buttons") return;
+    void edit.commit();
+  }, [controls, edit]);
+
+  return (
+    <InlineEditFrame
+      editing={edit.editing}
+      display={value}
+      placeholder={placeholder}
+      onBegin={edit.begin}
+      controls={controls}
+      onCommit={() => void edit.commit()}
+      onCancel={edit.cancel}
+      saving={edit.saving}
+      error={edit.error}
+      disabled={disabled}
+      accessibilityLabel={accessibilityLabel}
+    >
+      <TextInputField
+        value={edit.draft}
+        onChangeText={edit.setDraft}
+        onBlur={onBlur}
+        onKeyPress={onKeyPress}
+        autoFocus
+        placeholder={placeholder}
+        accessibilityLabel={accessibilityLabel}
+      />
+    </InlineEditFrame>
+  );
+}

package/src/inline_time_picker.tsx

@@ -0,0 +1,64 @@
+import { useCallback } from "react";
+import type { KeyboardEvent } from "react";
+import { TimePicker } from "./time_picker";
+import { InlineEditFrame, useInlineEdit, type InlineEditControls } from "./inline_edit";
+
+export interface InlineTimePickerProps {
+  /** Canonical 24-hour "HH:mm", "" when empty. */
+  value: string;
+  onSave: (next: string) => void | Promise<void>;
+  placeholder?: string;
+  /** "blur" (default): clicking away or Enter saves; Escape reverts. "buttons":
+   *  an explicit ✓ saves and ✕ reverts. */
+  controls?: InlineEditControls;
+  disabled?: boolean;
+  accessibilityLabel?: string;
+}
+
+/**
+ * An inline-editable time of day — the `InlineTextInput` pattern over
+ * `TimePicker`. The value reads as plain text; clicking swaps in the native time
+ * field at the same height, so the form never reflows.
+ */
+export function InlineTimePicker(props: InlineTimePickerProps) {
+  const { value, onSave, placeholder, controls = "blur", disabled, accessibilityLabel } = props;
+  const edit = useInlineEdit<string>({ 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]);
+
+  return (
+    <InlineEditFrame
+      editing={edit.editing}
+      display={value}
+      placeholder={placeholder}
+      onBegin={edit.begin}
+      controls={controls}
+      onCommit={() => void edit.commit()}
+      onCancel={edit.cancel}
+      saving={edit.saving}
+      error={edit.error}
+      disabled={disabled}
+      accessibilityLabel={accessibilityLabel}
+    >
+      <TimePicker
+        value={edit.draft}
+        onValueChange={edit.setDraft}
+        onBlur={onBlur}
+        onKeyDown={onKeyDown}
+        autoFocus
+        accessibilityLabel={accessibilityLabel}
+      />
+    </InlineEditFrame>
+  );
+}

package/src/line_chart.tsx

@@ -23,6 +23,10 @@ const defaultFormatNumber = (n: number): string =>
 
 const defaultFormatXLabel = (x: string | number): string => String(x);
 
+/**
+ * The canonical SVG line chart over `points: { x, y }[]` — `formatNumber`/`formatXLabel` for the
+ * axes, `lineColor`, `height`. (No recharts.) For a tiny inline trend use `Sparkline`.
+ */
 export function LineChart(props: LineChartProps) {
   const {
     points: data,

package/src/list_item.tsx

@@ -17,6 +17,11 @@ export interface ListItemProps {
   testID?: string;
 }
 
+/**
+ * A settings / detail ROW — optional `left` (icon/avatar), `title` + `description`, a `right`
+ * control, optional `onPress`/`selected`. For settings lists and detail rows; NOT a data register
+ * row (`PressableRow` / `Table`) and NOT a menu/listbox row (`MenuListItem`).
+ */
 export function ListItem(props: ListItemProps) {
   const { ref, left, title, description, right, onPress, selected, disabled, style, testID } =
     props;

package/src/number_input.tsx

@@ -1,3 +1,4 @@
+import type { KeyboardEvent } from "react";
 import { colors } from "./colors";
 import { fontFamilyRegular, inputTextStyleWeb } from "./text_utils";
 import { useFormField } from "./form_field";
@@ -8,13 +9,21 @@ export interface NumberInputProps {
   min?: number;
   max?: number;
   onBlur?: () => void;
+  /** Web key handler — e.g. an inline editor committing on Enter / reverting on Escape. */
+  onKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;
+  autoFocus?: boolean;
   disabled?: boolean;
   testID?: string;
   accessibilityLabel?: string;
 }
 
+/**
+ * A bare numeric input (`type="number"`, `value: number | null`) for free numeric entry — wrap in
+ * `FormField` for a labeled field. For a small bounded count use `Counter` (− N +); to edit a
+ * number in place on a record use `InlineNumberInput`.
+ */
 export function NumberInput(props: NumberInputProps) {
-  const { value, onValueChange, min, max, disabled, onBlur, testID, accessibilityLabel } = props;
+  const { value, onValueChange, min, max, disabled, onBlur, onKeyDown, autoFocus, testID, accessibilityLabel } = props;
   const binding = useFormField();
   const describedBy = [binding?.descriptionId, binding?.errorId].filter(Boolean).join(" ") || undefined;
 
@@ -35,6 +44,8 @@ export function NumberInput(props: NumberInputProps) {
       type="number"
       disabled={disabled}
       onBlur={onBlur}
+      onKeyDown={onKeyDown}
+      autoFocus={autoFocus}
       style={{
         height: 40,
         paddingLeft: 8,

package/src/page_content.tsx

@@ -16,6 +16,11 @@ interface PageContentProps {
   fullscreen?: boolean;
 }
 
+/**
+ * The page shell — a centered, width-capped column (`size` sm|md|lg) with an optional title band
+ * (`title` + `titleRight` + `description`), `header`/`footer` slots, and `fullscreen`. Wrap a
+ * screen's body for consistent gutters; cards float inside it.
+ */
 export function PageContent(props: PageContentProps) {
   const { children, title, titleRight, description, header, footer, size, fullscreen } = props;
   const screenSize = useScreenSize();

package/src/section_heading.tsx

@@ -1,41 +1,55 @@
-import { View } from "react-native";
-import { Text, HeadingLevel } from "./text";
-import { Icon, IconName } from "./icon";
+import { View, type StyleProp, type ViewStyle } from "react-native";
+import { Text, type HeadingLevel } from "./text";
+import { Icon, type IconName } from "./icon";
+
+// The card-less section header — the bare-canvas sibling of `CardHeader`, built
+// the same compound way. A title (+ optional leading icon / description) on one
+// centered row, with optional actions that sit at the right because the title
+// grows. It owns NO outer margin: spacing comes from the parent's `gap`, so it
+// composes cleanly in a flowed column (a baked-in margin would stack on the gap).
+//
+//   <SectionHeading>
+//     <SectionHeadingTitle description?>Line items</SectionHeadingTitle>
+//     <Button title="Add line" … />            {/* pushed right by the grow */}
+//   </SectionHeading>
 
 export interface SectionHeadingProps {
-  icon?: IconName;
-  title: string;
+  children: React.ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+export function SectionHeading(props: SectionHeadingProps) {
+  return (
+    <View style={[{ flexDirection: "row", alignItems: "center", gap: 12 }, props.style]}>
+      {props.children}
+    </View>
+  );
+}
+
+export interface SectionHeadingTitleProps {
+  children: React.ReactNode;
   description?: string;
-  right?: React.ReactNode;
+  icon?: IconName;
   /** Heading rank. Defaults to 2 — typical for page-level section titles. */
   level?: HeadingLevel;
 }
 
-export function SectionHeading(props: SectionHeadingProps) {
-  const { icon, title, description, right, level = 2 } = props;
-
+/** The title block — grows to push any sibling actions to the right edge. */
+export function SectionHeadingTitle(props: SectionHeadingTitleProps) {
+  const { children, description, icon, level = 2 } = props;
   return (
-    <View
-      style={{
-        flexDirection: "row",
-        alignItems: "center",
-        paddingBottom: 16,
-      }}
-    >
-      <View style={{ flex: 1 }}>
-        <View style={{ flexDirection: "row", alignItems: "center", gap: 4 }}>
-          {icon && <Icon name={icon} size={18} />}
-          <Text level={level} weight="medium" size="md">
-            {title}
-          </Text>
-        </View>
-        {!!description && (
-          <Text color="zinc-500" size="sm">
-            {description}
-          </Text>
-        )}
+    <View style={{ flex: 1, gap: 2 }}>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
+        {icon ? <Icon name={icon} size={18} /> : null}
+        <Text level={level} weight="medium" size="md">
+          {children}
+        </Text>
       </View>
-      {right}
+      {description ? (
+        <Text color="zinc-500" size="sm">
+          {description}
+        </Text>
+      ) : null}
     </View>
   );
 }

package/src/tag_input.tsx

@@ -0,0 +1,202 @@
+import { useMemo, useRef, useState } from "react";
+import { Pressable, ScrollView, StyleSheet, View, type StyleProp, type ViewStyle } from "react-native";
+import { colors } from "./colors";
+import { Text } from "./text";
+import { Icon } from "./icon";
+import { TextInputField } from "./text_input_field";
+import { MenuButton } from "./menu_button";
+import { Popover, PopoverContent } from "./popover";
+
+export interface TagOption {
+  value: string;
+  label: string;
+}
+
+export interface TagInputProps {
+  /** Selected tags. */
+  value: TagOption[];
+  /** The suggestible set. */
+  options: TagOption[];
+  onChange: (next: TagOption[]) => void;
+  /** Offer a "Create …" row when the query matches no option. Default false. */
+  allowCreate?: boolean;
+  placeholder?: string;
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Multi-select tag field. The CONTROL is a bordered box of removable chips plus
+ * an Add affordance; the typing/searching/creating happens in a POPOVER (a
+ * searchable, checkable list + an optional create row) — never an inline token
+ * input squeezed among the chips. So the field always reads as a clean container
+ * that matches its border, instead of a text box fighting the chips. Distinct
+ * from `Combobox multi` (a search field whose selection renders as in-input chips):
+ * reach for `TagInput` when the field's resting state should be a tidy chip box.
+ */
+export function TagInput(props: TagInputProps) {
+  const { value, options, onChange, allowCreate = false, placeholder = "Add tags", accessibilityLabel, style } = props;
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const anchorRef = useRef<View>(null);
+
+  const selected = useMemo(() => new Set(value.map((t) => t.value)), [value]);
+
+  const filtered = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    return q ? options.filter((o) => o.label.toLowerCase().includes(q)) : options;
+  }, [options, query]);
+
+  const exact = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    return q.length > 0 && [...options, ...value].some((o) => o.label.toLowerCase() === q);
+  }, [options, value, query]);
+
+  const showCreate = allowCreate && query.trim().length > 0 && !exact;
+
+  const toggle = (o: TagOption) =>
+    onChange(selected.has(o.value) ? value.filter((t) => t.value !== o.value) : [...value, o]);
+
+  const create = () => {
+    const label = query.trim();
+    if (!label) return;
+    const v = label.toLowerCase().replaceAll(" ", "_");
+    if (!selected.has(v)) onChange([...value, { value: v, label }]);
+    setQuery("");
+  };
+
+  return (
+    <>
+      <View ref={anchorRef} style={[styles.box, style]} accessibilityLabel={accessibilityLabel}>
+        {value.map((t) => (
+          <View key={t.value} style={styles.chip}>
+            <Text size="sm">{t.label}</Text>
+            <Pressable
+              onPress={() => onChange(value.filter((x) => x.value !== t.value))}
+              accessibilityRole="button"
+              accessibilityLabel={`Remove ${t.label}`}
+              style={styles.chipRemove}
+              hitSlop={6}
+            >
+              <Icon name="x" size={12} color={colors.zinc[500]} />
+            </Pressable>
+          </View>
+        ))}
+        <Pressable
+          onPress={() => setOpen(true)}
+          accessibilityRole="button"
+          accessibilityLabel={accessibilityLabel ?? "Add tag"}
+          style={styles.add}
+        >
+          <Icon name="plus" size={14} color={colors.zinc[500]} />
+          <Text size="sm" color="muted">
+            {value.length === 0 ? placeholder : "Add"}
+          </Text>
+        </Pressable>
+      </View>
+
+      <Popover
+        open={open}
+        onOpenChange={(o) => {
+          setOpen(o);
+          if (!o) setQuery("");
+        }}
+        triggerRef={anchorRef}
+        side="bottom"
+        align="start"
+        offset={4}
+        inheritTriggerWidth
+      >
+        <PopoverContent>
+          <View style={styles.menu}>
+            <TextInputField
+              value={query}
+              onChangeText={setQuery}
+              icon="search"
+              placeholder={allowCreate ? "Search or create…" : "Search…"}
+              autoFocus
+              autoCapitalize="none"
+              autoCorrect={false}
+              onKeyPress={(e: { nativeEvent: { key: string }; preventDefault: () => void }) => {
+                if (e.nativeEvent.key === "Enter") {
+                  e.preventDefault();
+                  if (showCreate) create();
+                  else if (filtered.length === 1) toggle(filtered[0]);
+                }
+              }}
+            />
+            <ScrollView style={styles.list} keyboardShouldPersistTaps="handled">
+              {filtered.map((o) => (
+                <MenuButton
+                  key={o.value}
+                  title={o.label}
+                  right={selected.has(o.value) ? <Icon name="check" size={16} color={colors.zinc[900]} /> : undefined}
+                  onPress={() => toggle(o)}
+                />
+              ))}
+              {showCreate ? <MenuButton title={`Create “${query.trim()}”`} icon="plus" onPress={create} /> : null}
+              {filtered.length === 0 && !showCreate ? (
+                <View style={styles.empty}>
+                  <Text size="sm" color="muted">
+                    No tags found
+                  </Text>
+                </View>
+              ) : null}
+            </ScrollView>
+          </View>
+        </PopoverContent>
+      </Popover>
+    </>
+  );
+}
+
+const styles = StyleSheet.create({
+  box: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    alignItems: "center",
+    gap: 6,
+    minHeight: 40,
+    paddingHorizontal: 6,
+    paddingVertical: 5,
+    borderWidth: 1,
+    borderColor: colors.border,
+    borderRadius: 8,
+    backgroundColor: colors.background,
+  },
+  chip: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 4,
+    paddingLeft: 8,
+    paddingRight: 4,
+    paddingVertical: 3,
+    borderRadius: 6,
+    backgroundColor: colors.zinc[100],
+  },
+  chipRemove: {
+    padding: 2,
+    borderRadius: 4,
+    cursor: "pointer",
+  },
+  add: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 4,
+    paddingHorizontal: 6,
+    paddingVertical: 4,
+    cursor: "pointer",
+  },
+  menu: {
+    gap: 6,
+    padding: 6,
+    minWidth: 240,
+  },
+  list: {
+    maxHeight: 240,
+  },
+  empty: {
+    paddingVertical: 12,
+    alignItems: "center",
+  },
+});

package/src/time_picker.tsx

@@ -1,12 +1,19 @@
+import type { KeyboardEvent } from "react";
 import { colors } from "@lotics/ui/colors";
 import { fontFamilyRegular, inputTextStyleWeb } from "@lotics/ui/text_utils";
 export interface TimePickerProps {
   value?: string;
   onValueChange: (value: string) => void;
+  onBlur?: () => void;
+  /** Web key handler — e.g. an inline editor committing on Enter / reverting on Escape. */
+  onKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;
+  autoFocus?: boolean;
+  disabled?: boolean;
+  accessibilityLabel?: string;
 }
 
 export function TimePicker(props: TimePickerProps) {
-  const { value, onValueChange } = props;
+  const { value, onValueChange, onBlur, onKeyDown, autoFocus, disabled, accessibilityLabel } = props;
 
   return (
     <input
@@ -15,10 +22,15 @@ export function TimePicker(props: TimePickerProps) {
         onValueChange(e.target.value);
       }}
       type="time"
+      onBlur={onBlur}
+      onKeyDown={onKeyDown}
+      autoFocus={autoFocus}
+      disabled={disabled}
+      aria-label={accessibilityLabel}
       style={{
         height: 40,
-        paddingLeft: 12,
-        paddingRight: 12,
+        paddingLeft: 8,
+        paddingRight: 8,
         borderRadius: 8,
         borderWidth: 1,
         borderStyle: "solid",

package/src/tooltip.tsx

@@ -189,6 +189,9 @@ export function useTooltip(options?: string | UseTooltipOptions) {
   const text = typeof options === "string" ? options : options?.text;
   const side = typeof options === "string" ? "top" : (options?.side ?? "top");
   const offset = typeof options === "string" ? undefined : options?.offset;
+  // True while THIS instance owns the visible tooltip — so the unmount cleanup
+  // only dismisses a tooltip it actually opened.
+  const shown = useRef(false);
 
   const showFor = useCallback(
     (target: unknown) => {
@@ -200,10 +203,23 @@ export function useTooltip(options?: string | UseTooltipOptions) {
       if (!(target instanceof HTMLElement)) return;
       const rect = target.getBoundingClientRect();
       context.show(text, rect, side, offset);
+      shown.current = true;
     },
     [text, context, side, offset],
   );
 
+  // Dismiss on unmount. An element hovered/focused when it disappears — a button
+  // that commits and re-renders away — never fires mouseLeave/blur, so its
+  // tooltip would otherwise orphan on screen.
+  useEffect(() => {
+    return () => {
+      if (shown.current) {
+        shown.current = false;
+        context?.hide();
+      }
+    };
+  }, [context]);
+
   const onMouseEnter = useCallback(
     (e: { currentTarget: unknown }) => {
       showFor(e.currentTarget);
@@ -213,11 +229,13 @@ export function useTooltip(options?: string | UseTooltipOptions) {
 
   const onMouseLeave = useCallback(() => {
     if (!context) return;
+    shown.current = false;
     context.hide();
   }, [context]);
 
   const onMouseDown = useCallback(() => {
     if (!context) return;
+    shown.current = false;
     context.hide();
   }, [context]);
 
@@ -238,6 +256,7 @@ export function useTooltip(options?: string | UseTooltipOptions) {
 
   const onBlur = useCallback(() => {
     if (!context) return;
+    shown.current = false;
     context.hide();
   }, [context]);