@lotics/ui 3.6.0 → 4.1.0

package/src/inline_select.tsx

@@ -0,0 +1,92 @@
+import { useCallback, 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 { PickerMenu } from "./picker_menu";
+import type { PickerOption } from "./picker";
+import { ActivityIndicator } from "./activity_indicator";
+import { InlineEditView } from "./inline_edit";
+
+export interface InlineSelectProps<T extends string> {
+  value: T | null;
+  onSave: (next: T) => void | Promise<void>;
+  options: PickerOption<T>[];
+  /** 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;
+  placeholder?: string;
+  disabled?: boolean;
+  accessibilityLabel?: string;
+}
+
+/**
+ * An inline-editable single-select. The value reads as plain text; clicking it
+ * floats the option list (a `PickerMenu`) in a popover anchored to the view, so
+ * the row never changes height. Picking commits; dismissing reverts. Pass
+ * `renderOptionContent` for rich options, or omit it for a plain list — the
+ * 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 [open, setOpen] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const selected = options.find((o) => o.value === value);
+
+  const pick = useCallback(
+    async (next: T) => {
+      setOpen(false);
+      if (next === value) 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],
+  );
+
+  return (
+    <View>
+      <Popover open={open && !disabled} onOpenChange={setOpen} side="bottom" align="start" inheritTriggerWidth>
+        <PopoverTrigger>
+          <InlineEditView
+            display={selected?.label ?? ""}
+            placeholder={placeholder}
+            disabled={disabled}
+            active={open && !disabled}
+            accessibilityLabel={accessibilityLabel}
+            trailing={
+              saving ? (
+                <ActivityIndicator size={16} color={colors.zinc[400]} />
+              ) : (
+                <Icon name="chevron-down" size={18} color={colors.zinc[400]} />
+              )
+            }
+          />
+        </PopoverTrigger>
+        <PopoverContent>
+          <PickerMenu
+            options={options}
+            value={value}
+            onValueChange={(next) => void pick(next)}
+            onRequestClose={() => setOpen(false)}
+            renderOptionContent={renderOptionContent}
+          />
+        </PopoverContent>
+      </Popover>
+      {error ? (
+        <Text size="xs" color="danger" style={{ marginTop: 4 }}>
+          {error}
+        </Text>
+      ) : null}
+    </View>
+  );
+}

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/link.tsx

@@ -0,0 +1,32 @@
+import { type ReactNode } from "react";
+import { Pressable } from "react-native";
+import { Text, type TextSize } from "./text";
+import { colors } from "./colors";
+
+export interface LinkProps {
+  children: ReactNode;
+  /** Opening the link is the consumer's job (a URL via the app SDK's openExternal,
+   *  an in-app route, …) — Link is pure presentation + the press target. */
+  onPress: () => void;
+  size?: TextSize;
+  accessibilityLabel?: string;
+  testID?: string;
+}
+
+/**
+ * An EXTERNAL hyperlink — underline + blue, the universal "this opens somewhere
+ * else" signal (a document URL, a record, an invoice). The deliberate counterpart
+ * to `LinkButton`: `LinkButton` is a QUIET IN-APP ACTION (a ghost button — "Clear",
+ * "Show more") and intentionally NOT underlined; `Link` is a link OUT and IS
+ * underlined-blue so it reads as a destination, not an action. The consumer wires
+ * `onPress` to its opener.
+ */
+export function Link({ children, onPress, size = "sm", accessibilityLabel, testID }: LinkProps) {
+  return (
+    <Pressable onPress={onPress} accessibilityRole="link" accessibilityLabel={accessibilityLabel} testID={testID}>
+      <Text size={size} decoration="underline" style={{ color: colors.blue[600] }}>
+        {children}
+      </Text>
+    </Pressable>
+  );
+}

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/picker.tsx

@@ -2,6 +2,7 @@ import { Picker as RNPicker } from "@react-native-picker/picker";
 import { StyleSheet, View, Pressable, StyleProp, ViewStyle, TextStyle } from "react-native";
 import { useState, useCallback, useMemo, useEffect, useRef } from "react";
 import { colors } from "./colors";
+import { ACTIVE_RING } from "./control_surface";
 import { Text } from "./text";
 import { fontFamilyRegular, getInputTextStyle } from "./text_utils";
 import { Icon } from "./icon";
@@ -328,7 +329,9 @@ const styles = StyleSheet.create({
     height: 40,
   },
   opened: {
-    borderColor: colors.zinc["900"],
+    // Mouse-opened, so no `:focus-visible` — wear the same 2px zinc ring a
+    // focused input gets, over the unchanged 1px border (not a lone 1px edge).
+    boxShadow: ACTIVE_RING,
   },
   disabled: {
     opacity: 0.5,

package/src/popover.tsx

@@ -254,8 +254,17 @@ export function PopoverContent(props: PopoverContentProps) {
 
     return () => {
       cancelAnimationFrame(focusFrame);
-      const target = returnFocusRef.current;
+      const prior = returnFocusRef.current;
       returnFocusRef.current = null;
+      // Return focus to the TRIGGER (WAI-ARIA: focus returns to the element that
+      // invoked the popup). `previouslyFocused` is an unreliable proxy — RN-Web's
+      // Pressable triggers don't take focus on mouse press, so for a mouse-opened
+      // popover (a Picker/InlineSelect/menu) it is <body>; restoring there strands
+      // focus and the next Tab jumps to the page's first focusable. Fall back to
+      // the prior element only if the trigger is gone (e.g. a hover-revealed menu
+      // button that unmounted under the overlay).
+      const trigger = triggerRef.current;
+      const target = trigger && trigger.isConnected ? trigger : prior;
       if (target && typeof target.focus === "function") {
         target.focus();
       }

package/src/pressable_row.tsx

@@ -55,7 +55,10 @@ export function PressableRow(props: PressableRowProps) {
   return (
     <Pressable
       onPress={onPress}
-      focusable={false}
+      // Non-focusable surface: tabIndex, NOT focusable — RN-Web's Pressable
+      // ignores `focusable` and writes its own tabIndex (the keyboard target is
+      // the nested "Open …" button, not this row).
+      tabIndex={-1}
       {...mouseProps}
       style={({ pressed }) => [
         styles.row,

package/src/radio_picker.tsx

@@ -128,7 +128,9 @@ function RadioOption<T extends string | number | symbol>(
       accessibilityLabel={description ? `${label}, ${description}` : label}
       aria-checked={selected}
       // Roving tabindex: exactly one radio is the tab-stop. Arrow keys cycle.
-      focusable={isTabStop}
+      // tabIndex, NOT focusable — RN-Web's Pressable ignores `focusable` and
+      // writes its own tabIndex.
+      tabIndex={isTabStop ? 0 : -1}
       onKeyDown={onKeyDown}
     >
       <View

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/segmented_control.tsx

@@ -152,8 +152,9 @@ function Segment<T extends string>(props: SegmentProps<T>) {
       aria-checked={selected}
       aria-disabled={disabled}
       // Roving tabindex: only the selected segment (or the fallback) is a tab
-      // stop; the rest are reached with arrow keys.
-      focusable={isTabStop && !disabled}
+      // stop; the rest are reached with arrow keys. tabIndex, NOT focusable —
+      // RN-Web's Pressable ignores `focusable` and writes its own tabIndex.
+      tabIndex={isTabStop && !disabled ? 0 : -1}
     >
       {(state) => {
         const hovered = (state as { hovered?: boolean }).hovered;

package/src/tabs.tsx

@@ -125,8 +125,10 @@ function TabButton<T extends string>(props: TabButtonProps<T>) {
       // Roving tabindex: the selected tab is the tab-stop, others are reachable
       // via arrow keys. When no tab matches the current selection (props.value
       // is stale), the first tab is the fallback so the group stays keyboard-
-      // reachable.
-      focusable={isTabStop}
+      // reachable. Drive it with tabIndex, NOT focusable: RN-Web's Pressable
+      // ignores `focusable` (it writes its own tabIndex), so a focusable-based
+      // roving model silently leaves every tab a tab-stop.
+      tabIndex={isTabStop ? 0 : -1}
     >
       {(state) => {
         const { pressed } = state;