@lotics/ui 12.1.1 → 13.7.0

package/src/badge.tsx

@@ -9,15 +9,16 @@ interface BadgeProps {
   label?: string;
   color?: ColorName;
   /**
-   * The status-indicator weight:
-   * - "tonal" (default): a filled pill — a record's prominent STATUS field (a
-   *   register's Status column, a drawer header). For categorical status, not
-   *   a metric value: a percentage/amount is a number, never a chip.
-   * - "dot": pill-less — a colored dot + label, the LIGHT indicator for
-   *   legends, secondary/inline status, or a metric's quality cue (a
-   *   healthy-vs-thin margin) where a filled chip would be too heavy.
-   * (StatusGrid/StatusLegend keep their own dot — their color is raw hex,
-   * coupled to the grid cells' tint, a separate data-viz concern.)
+   * The status-indicator weight — DEFAULT to `dot`:
+   * - "dot": pill-less — a colored dot + label. The everyday status indicator:
+   *   legends, register cells, inline/secondary status, a metric's quality cue.
+   *   Light enough to sit anywhere without shouting. Reach for this by default.
+   * - "tonal": a filled pill — HEAVY, and easy to overuse into clutter. Reserve
+   *   it for the ONE prominent status of a surface (a drawer header, a register's
+   *   primary Status column). One per view, a deliberate choice — not sprinkled
+   *   through rows or option lists. If in doubt, use `dot`.
+   * (StatusGrid/StatusLegend keep their own dot — raw hex coupled to the grid
+   * cells' tint, a separate data-viz concern.)
    */
   variant?: "tonal" | "dot";
   style?: StyleProp<ViewStyle>;
@@ -25,8 +26,23 @@ interface BadgeProps {
   userSelect?: "none" | "auto";
 }
 
+/**
+ * A STATUS indicator — a lifecycle state, a risk level, a quality cue — that reads at a
+ * GLANCE. That is the ONLY thing a Badge is for; keep the vocabulary scarce so a colored
+ * chip always MEANS state.
+ *
+ * NOT for a type / category / attribute / count (a party's type, a document kind, a city,
+ * "3 files") — that is not a status, and a pill for it is noise. Render it as inline TEXT
+ * (a muted metadata line; a taller row is fine). If you're adding a Badge "to show more
+ * info" in a row or an option list, STOP — that's text, not a badge.
+ *
+ * Default `variant="dot"`; `tonal` is the heavy exception (see the prop doc).
+ */
+
 export function Badge(props: BadgeProps) {
-  const { label, color, variant = "tonal", style, tooltip, userSelect = "none" } = props;
+  // Default `dot` (the light indicator) — `tonal` is the heavy pill you opt INTO
+  // deliberately, so a bare <Badge> never silently clutters a row with a filled chip.
+  const { label, color, variant = "dot", style, tooltip, userSelect = "none" } = props;
   const tooltipProps = useTooltip(tooltip);
   const hue = color && colors[color] ? colors[color] : null;
 

package/src/checklist.tsx

@@ -21,7 +21,7 @@ import { ActionMenu, type ActionMenuItem } from "./action_menu";
 //     <ChecklistRow control={<CheckCircle …/>} trailing={<InlineMemberSelect …/>}
 //                   menu={{ items: [{ key: "delete", label: "Delete task", danger: true, … }],
 //                           accessibilityLabel: "Task options: …" }}>
-//       <InlineTextInput background="transparent" struck={done} … />
+//       <InlineTextInput variant="cell" struck={done} … />
 //     </ChecklistRow>
 //     <SuggestionChip label="Verify the tax ID" onAdd={materialize} onDismiss={dismiss} />
 //     <CaptureRow … />

package/src/choice_list.tsx

@@ -1,8 +1,10 @@
-import { StyleSheet, View } from "react-native";
+import { Pressable, View } from "react-native";
 import { colors } from "./colors";
 import { Text } from "./text";
 import { Icon } from "./icon";
-import { CardSelectItem } from "./card_select_item";
+import { Divider } from "./divider";
+import { useFocusRing } from "./use_focus_ring";
+import { FOCUS_RING } from "./control_surface";
 
 export interface ChoiceOption {
   label: string;
@@ -18,46 +20,55 @@ export interface ChoiceListProps {
   onSelect: (value: string) => void;
 }
 
+/** One selectable option — a role-less-free `Pressable` (its own accessible name
+ *  + selected state), hover wash + focus ring, no border. */
+function ChoiceRow({ option, selected, onSelect }: { option: ChoiceOption; selected: boolean; onSelect: (value: string) => void }) {
+  const { focusVisible, focusProps } = useFocusRing();
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={option.label}
+      accessibilityState={{ selected }}
+      onPress={() => onSelect(option.value)}
+      {...focusProps}
+      style={({ hovered, pressed }) => [
+        { flexDirection: "row", alignItems: "center", gap: 12, paddingVertical: 14, paddingHorizontal: 6, borderRadius: 8 },
+        hovered || pressed ? { backgroundColor: colors.zinc[50] } : null,
+        focusVisible ? { boxShadow: FOCUS_RING } : null,
+      ]}
+    >
+      <View style={{ flex: 1, gap: 3, minWidth: 0 }}>
+        <Text size="sm" weight={selected ? "semibold" : "medium"}>
+          {option.label}
+        </Text>
+        {option.description ? (
+          <Text size="xs" color="muted">
+            {option.description}
+          </Text>
+        ) : null}
+      </View>
+      {selected ? <Icon name="check" size={17} color={colors.zinc[900]} /> : null}
+    </Pressable>
+  );
+}
+
 /**
- * A vertical set of selectable answer options — bordered cards with the global
- * focus/hover/selected ring (`CardSelectItem`), single-select and freely
- * switchable (pick a different option any time). The chosen card shows a check.
- * The agent's quick-reply surface (`Clarify` uses it) and any "pick one"
+ * A vertical set of selectable answer options — divider-separated rows (no
+ * bordered cards), each with its own focus ring + hover wash, single-select and
+ * freely switchable (pick a different option any time). The chosen row shows a
+ * check. The agent's quick-reply surface (`Clarify` uses it) and any "pick one"
  * question.
  */
 export function ChoiceList(props: ChoiceListProps) {
   const { options, value, onSelect } = props;
   return (
-    <View style={{ gap: 8 }}>
-      {options.map((o) => {
-        const selected = value === o.value;
-        return (
-          <CardSelectItem
-            key={o.value}
-            selected={selected}
-            onPress={() => onSelect(o.value)}
-            accessibilityLabel={o.label}
-            style={styles.item}
-          >
-            <View style={styles.text}>
-              <Text size="sm" weight="medium">
-                {o.label}
-              </Text>
-              {o.description ? (
-                <Text size="xs" color="muted">
-                  {o.description}
-                </Text>
-              ) : null}
-            </View>
-            {selected ? <Icon name="check" size={16} color={colors.zinc[900]} /> : null}
-          </CardSelectItem>
-        );
-      })}
+    <View>
+      {options.map((o, i) => (
+        <View key={o.value}>
+          {i > 0 ? <Divider /> : null}
+          <ChoiceRow option={o} selected={value === o.value} onSelect={onSelect} />
+        </View>
+      ))}
     </View>
   );
 }
-
-const styles = StyleSheet.create({
-  item: { flexDirection: "row", alignItems: "center", gap: 10, paddingVertical: 11, paddingHorizontal: 14 },
-  text: { flex: 1, gap: 2 },
-});

package/src/clarify.tsx

@@ -1,5 +1,4 @@
-import { StyleSheet, View } from "react-native";
-import { colors } from "./colors";
+import { View } from "react-native";
 import { Text } from "./text";
 import { ChoiceList, type ChoiceOption } from "./choice_list";
 
@@ -16,33 +15,24 @@ export interface ClarifyProps {
 }
 
 /**
- * The agent asks BACK — a question with selectable answer options (`ChoiceList`)
- * the human picks before the run continues, freely switchable until committed.
+ * The agent asks BACK — a question with selectable answer options the human picks
+ * before the run continues, freely switchable until committed. A borderless block
+ * (no card): the question, then divider-separated option rows (`ChoiceList`).
  * Human-in-the-loop input: when the agent is unsure, it clarifies instead of
- * guessing wrong. The run pauses on this and `onAnswer` resumes it. Pair with
- * `AgentRun` / `AgentProgress`.
+ * guessing wrong. Pair with `AgentRun` / `AgentProgress`.
  */
 export function Clarify(props: ClarifyProps) {
   return (
-    <View style={styles.card}>
-      <Text size="xs" color="muted" weight="medium">
-        Question
-      </Text>
-      <Text size="sm" weight="medium">
-        {props.question}
-      </Text>
+    <View style={{ gap: 14 }}>
+      <View style={{ gap: 4 }}>
+        <Text size="xs" color="muted" weight="medium">
+          Question
+        </Text>
+        <Text size="sm" weight="medium">
+          {props.question}
+        </Text>
+      </View>
       <ChoiceList options={props.options} value={props.answer} onSelect={props.onAnswer} />
     </View>
   );
 }
-
-const styles = StyleSheet.create({
-  card: {
-    borderWidth: 1,
-    borderColor: colors.border,
-    backgroundColor: colors.white,
-    borderRadius: 12,
-    padding: 16,
-    gap: 12,
-  },
-});

package/src/detail_row.tsx

@@ -111,6 +111,11 @@ export interface DetailRowProps {
    *  hidden ⓘ gloss. Invalid STATE → `error` or a co-located `Callout`. Same
    *  name, same meaning as `FormField.description`. */
   description?: string;
+  /** A consequence the user should WEIGH before acting — renders in the same
+   *  annotation slot in amber (`Text color="warning"`), one tone between the
+   *  muted `description` and the danger `error`, announced on appearance. Same
+   *  name, same meaning as `FormField.warning`. */
+  warning?: string;
   /** Field-level failure, under the value in danger ink with `FormField`'s
    *  alert semantics (announced on appearance). For CONSUMER-validated state —
    *  the `Inline*` editors already render their own transient save errors;
@@ -136,13 +141,13 @@ export interface DetailRowProps {
  */
 export function DetailRow(props: DetailRowProps) {
   const table = useContext(DetailTableContext);
-  const { label, children, trailing, labelSize = "sm", description, error, flat } = props;
+  const { label, children, trailing, labelSize = "sm", description, warning, error, flat } = props;
   const labelWidth = props.labelWidth ?? table?.labelWidth;
   const minHeight = props.minHeight ?? table?.minHeight ?? 28;
   const form = labelWidth != null;
-  // Annotations (description / error) live UNDER THE VALUE — the row grows,
-  // so the label + trailing center against the CONTROL LINE, not the block.
-  const annotated = description != null || error != null;
+  // Annotations (description / warning / error) live UNDER THE VALUE — the row
+  // grows, so the label + trailing center against the CONTROL LINE, not the block.
+  const annotated = description != null || warning != null || error != null;
   // A FLAT value (no painted chip) centers its text in the control band,
   // leaving invisible slack below it — tuck the annotations up by that slack
   // so the perceived gap matches a chip row's. Horizontal mode only (stacked
@@ -155,9 +160,10 @@ export function DetailRow(props: DetailRowProps) {
       </Text>
     </View>
   );
-  // Error first (adjacent to the control that failed, FormField's alert
-  // semantics), then the guidance. Indented to the inline chip's OWN text
-  // inset (paddingHorizontal 8), so annotations align with the value's text.
+  // Severity descending from the control: error first (adjacent to the control
+  // that failed, FormField's alert semantics), then warning, then the guidance.
+  // Indented to the inline chip's OWN text inset (paddingHorizontal 8), so
+  // annotations align with the value's text.
   const annotations = annotated ? (
     <>
       {error != null ? (
@@ -165,6 +171,11 @@ export function DetailRow(props: DetailRowProps) {
           {error}
         </Text>
       ) : null}
+      {warning != null ? (
+        <Text size="xs" color="warning" accessibilityRole="alert" aria-live="polite" style={styles.annotation}>
+          {warning}
+        </Text>
+      ) : null}
       {description != null ? (
         <Text size="xs" color="muted" style={styles.annotation}>
           {description}
@@ -184,12 +195,17 @@ export function DetailRow(props: DetailRowProps) {
           {label}
         </Text>
         {/* stacked wears the FORM grammar exactly: label · description ·
-            control · error (the `FormField` order) */}
+            control · warning · error (the `FormField` order) */}
         {description != null ? <Text color="muted">{description}</Text> : null}
         <View style={[styles.stackedValueRow, { minHeight }]}>
           <View style={styles.value}>{children}</View>
           {trailing != null ? trailing : null}
         </View>
+        {warning != null ? (
+          <Text size="xs" color="warning" accessibilityRole="alert" aria-live="polite">
+            {warning}
+          </Text>
+        ) : null}
         {error != null ? (
           <Text size="xs" color="danger" accessibilityRole="alert" aria-live="polite">
             {error}

package/src/form_date_picker.tsx

@@ -8,12 +8,13 @@ export interface FormDatePickerProps
 /** `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;
+  const { label, description, warning, optional, optionalLabel, error, ...datePickerProps } = props;
 
   return (
     <FormField
       label={label}
       description={description}
+      warning={warning}
       error={error}
       optional={optional}
       optionalLabel={optionalLabel}

package/src/form_field.tsx

@@ -8,6 +8,10 @@ export interface FormFieldProps {
   label: string;
   optional?: boolean;
   description?: string;
+  /** A consequence the user should WEIGH before acting — amber, one tone between
+   *  the muted `description` and the danger `error`. Same name/meaning on
+   *  `DetailRow`. */
+  warning?: string;
   error?: string;
   style?: StyleProp<ViewStyle>;
   /** Label shown next to `label` when `optional` is true. Defaults to the locale
@@ -18,12 +22,13 @@ export interface FormFieldProps {
 /**
  * Binding emitted by `FormField` to the single input it wraps. Descendants
  * that call `useFormField()` apply these props to the native input so screen
- * readers know the label, error, and description apply to it.
+ * readers know the label, description, warning, and error apply to it.
  */
 export interface FormFieldBinding {
   inputId: string;
   labelId: string;
   descriptionId: string | undefined;
+  warningId: string | undefined;
   errorId: string | undefined;
   invalid: boolean;
 }
@@ -33,7 +38,7 @@ const FormFieldContext = createContext<FormFieldBinding | null>(null);
 /**
  * Returns the association IDs set by the nearest enclosing `FormField`.
  * Inputs spread the returned props onto their underlying element so label,
- * description, and error are announced together. Returns `null` when the
+ * description, warning, and error are announced together. Returns `null` when the
  * input is used outside a `FormField` — callers should then provide their
  * own `accessibilityLabel`.
  */
@@ -42,18 +47,20 @@ export function useFormField(): FormFieldBinding | null {
 }
 
 export function FormField(props: FormFieldProps & { children: React.ReactNode }) {
-  const { label, description, error, optional, style, children, optionalLabel } = props;
+  const { label, description, warning, error, optional, style, children, optionalLabel } = props;
   const resolvedOptionalLabel = optionalLabel ?? useLoticsLocale().formField.optional;
 
   const inputId = useId();
   const labelId = `${inputId}-label`;
   const descriptionId = description ? `${inputId}-description` : undefined;
+  const warningId = warning ? `${inputId}-warning` : undefined;
   const errorId = error ? `${inputId}-error` : undefined;
 
   const binding: FormFieldBinding = {
     inputId,
     labelId,
     descriptionId,
+    warningId,
     errorId,
     invalid: !!error,
   };
@@ -86,6 +93,19 @@ export function FormField(props: FormFieldProps & { children: React.ReactNode })
         )}
         <Spacer size={8} />
         <View>{children}</View>
+        {warning && (
+          <>
+            <Spacer size={8} />
+            {/*
+              Below the control, above the error — the three tones read
+              description · warning · error, ascending severity. `role="alert"`
+              + `aria-live="polite"` announce it politely on appearance.
+            */}
+            <Text nativeID={warningId} color="warning" accessibilityRole="alert" aria-live="polite">
+              {warning}
+            </Text>
+          </>
+        )}
         {error && (
           <>
             <Spacer size={8} />

package/src/form_picker.tsx

@@ -5,12 +5,13 @@ import { Picker, PickerProps } from "./picker";
 export function FormPicker<T extends string>(
   props: PickerProps<T> & FormFieldProps,
 ) {
-  const { label, description, optional, optionalLabel, error, ...pickerProps } = props;
+  const { label, description, warning, optional, optionalLabel, error, ...pickerProps } = props;
 
   return (
     <FormField
       label={label}
       description={description}
+      warning={warning}
       error={error}
       optional={optional}
       optionalLabel={optionalLabel}

package/src/form_switch.tsx

@@ -7,10 +7,11 @@ import { Spacer } from "./spacer";
 
 export interface FormSwitchProps extends Omit<FormFieldProps, "optional">, SwitchProps {}
 
-/** A labeled on/off toggle — a `Switch` + clickable label + optional `description`/`error`. */
+/** A labeled on/off toggle — a `Switch` + clickable label + optional `description`/`warning`/`error`. */
 export function FormSwitch(props: FormSwitchProps) {
-  const { label, description, error, value, onChange } = props;
+  const { label, description, warning, error, value, onChange } = props;
   const labelId = useId();
+  const warningId = warning ? `${labelId}-warning` : undefined;
   const errorId = error ? `${labelId}-error` : undefined;
 
   return (
@@ -44,6 +45,19 @@ export function FormSwitch(props: FormSwitchProps) {
         </View>
       </View>
 
+      {!!warning && (
+        <>
+          <Spacer size={8} />
+          <Text
+            nativeID={warningId}
+            color="warning"
+            accessibilityRole="alert"
+            aria-live="polite"
+          >
+            {warning}
+          </Text>
+        </>
+      )}
       {!!error && (
         <>
           <Spacer size={8} />

package/src/form_text_input.tsx

@@ -4,13 +4,13 @@ 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. */
+/** `FormField` (label / description / warning / 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;
+  const { label, description, warning, optional, error, ...textInputProps } = props;
 
   return (
-    <FormField label={label} description={description} error={error} optional={optional}>
+    <FormField label={label} description={description} warning={warning} error={error} optional={optional}>
       <TextInputField {...textInputProps} />
     </FormField>
   );

package/src/inline_date_picker.tsx

@@ -9,7 +9,8 @@ import { DateField } from "./date_field";
 import { isoHasTime, resolveDateCommit } from "./date_picker_value";
 import { formatDate } from "./format_date";
 import { ActivityIndicator } from "./activity_indicator";
-import { type InlineEditBackground, InlineEditView } from "./inline_edit";
+import { type InlineEditVariant, InlineEditView } from "./inline_edit";
+import { type TextColor } from "./text_utils";
 import { useLoticsLocale } from "./locale";
 import { getInteractionModality } from "./interaction_modality";
 import { shouldOpenOnFocus, shouldRestoreFocusOnClose } from "./inline_focus";
@@ -34,8 +35,11 @@ export interface InlineDatePickerProps {
   locale?: string;
   disabled?: boolean;
   accessibilityLabel?: string;
-  /** Resting surface — "tint" (default, the zinc-50 chip) or "transparent". */
-  background?: InlineEditBackground;
+  /** Form field (default) or grid cell — see `InlineEditVariant`. */
+  variant?: InlineEditVariant;
+  /** Colour the resting date by urgency — overdue red, soon-due amber (the caller owns
+   *  the rule; e.g. a task's `dueTone`). Applies to a set value only. */
+  tone?: TextColor;
 }
 
 /**
@@ -54,7 +58,7 @@ export interface InlineDatePickerProps {
  * The row never changes height in either mode.
  */
 export function InlineDatePicker(props: InlineDatePickerProps) {
-  const { value, onSave, onClear, format = "date", optionalTime, placeholder, locale, disabled, accessibilityLabel , background } = props;
+  const { value, onSave, onClear, format = "date", optionalTime, placeholder, locale, disabled, accessibilityLabel , variant, tone } = props;
   const locales = useLoticsLocale();
   const inlineLabels = locales.inline;
   const dateLabels = locales.datePicker;
@@ -228,6 +232,11 @@ export function InlineDatePicker(props: InlineDatePickerProps) {
   ) : (
     <Icon name={format === "datetime" ? "calendar-clock" : "calendar"} size={18} color={colors.zinc[400]} />
   );
+  // The resting calendar glyph is a FORM affordance (marks an empty field as a date
+  // control). A `cell` lives in a grid where the column header already says "Due" and
+  // every cell edits — the repeated glyph is noise, so it reads value-first (the saving
+  // spinner still shows). The typed-edit field keeps its glyph — that's the open-picker button.
+  const restTrailing = variant === "cell" && !saving ? undefined : trailing;
 
   return (
     <View>
@@ -254,17 +263,18 @@ export function InlineDatePicker(props: InlineDatePickerProps) {
         ) : (
           <PopoverTrigger>
             <InlineEditView
-              background={background}
+              variant={variant}
+              tone={tone}
               display={display}
               placeholder={placeholder}
               disabled={disabled}
               active={open && !disabled}
               accessibilityLabel={accessibilityLabel}
               onFocus={handleViewFocus}
-              // A rest affordance (like the select's chevron): a calendar glyph marks
-              // the field as a tappable date control even when empty — no hover / pointer
-              // cursor needed, so it reads as interactive on touch.
-              trailing={trailing}
+              // A rest affordance (like the select's chevron): in a FORM a calendar glyph
+              // marks the field as a tappable date control even when empty; a grid CELL
+              // drops it (see restTrailing) to read value-first.
+              trailing={restTrailing}
             />
           </PopoverTrigger>
         )}