@lotics/ui 1.3.1 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -30,6 +30,7 @@
     "./menu_list_item": "./src/menu_list_item.tsx",
     "./pressable_highlight": "./src/pressable_highlight.tsx",
     "./icon_button": "./src/icon_button.tsx",
+    "./info_popover": "./src/info_popover.tsx",
     "./badge": "./src/badge.tsx",
     "./divider": "./src/divider.tsx",
     "./spacer": "./src/spacer.tsx",
@@ -83,6 +84,7 @@
       "default": "./src/wave_avatar.web.tsx"
     },
     "./use_async_fn": "./src/use_async_fn.ts",
+    "./use_form": "./src/use_form.ts",
     "./hover_action": "./src/hover_action.tsx",
     "./scroll_to_bottom": "./src/scroll_to_bottom.tsx",
     "./animation_fade_in": "./src/animation_fade_in.tsx",

package/src/icon_button.tsx

@@ -13,6 +13,8 @@ export interface IconButtonProps {
   iconColor?: string;
   tooltip?: string;
   tooltipSide?: TooltipSide;
+  /** Accessible name for the button. Falls back to `tooltip` when omitted. */
+  accessibilityLabel?: string;
   onPress?: (event: GestureResponderEvent) => void;
   style?: StyleProp<ViewStyle>;
   disabled?: boolean;
@@ -28,6 +30,7 @@ export function IconButton(props: IconButtonProps) {
     color = "none",
     tooltip,
     tooltipSide,
+    accessibilityLabel,
     disabled,
     style,
   } = props;
@@ -45,6 +48,8 @@ export function IconButton(props: IconButtonProps) {
       testID={testID}
       tooltip={tooltip}
       tooltipSide={tooltipSide}
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel ?? tooltip}
       style={[styles.button, styles[color], disabled && styles.disabled, style]}
       onPress={handlePress}
       disabled={disabled}

package/src/info_popover.tsx

@@ -0,0 +1,49 @@
+import { StyleSheet } from "react-native";
+import { Popover, PopoverTrigger, PopoverContent } from "./popover";
+import type { PopoverSide, PopoverAlign } from "./popover";
+import { IconButton } from "./icon_button";
+import { Text } from "./text";
+import { colors } from "./colors";
+
+export interface InfoPopoverProps {
+  /** Explanatory text shown when the popover opens. */
+  text: string;
+  /** Accessible name for the trigger button. */
+  accessibilityLabel?: string;
+  /** Popover placement relative to the trigger. */
+  side?: PopoverSide;
+  /** Popover alignment along the trigger edge. */
+  align?: PopoverAlign;
+}
+
+/**
+ * A "?" icon button that opens a popover explaining something — a metric, a
+ * field, a setting. The middle ground between Tooltip (a short hover label)
+ * and composing Popover directly (rich, interactive content): a labeled,
+ * keyboard-accessible help affordance for a sentence or two of text.
+ */
+export function InfoPopover(props: InfoPopoverProps) {
+  const { text, accessibilityLabel = "More information", side = "bottom", align = "end" } = props;
+  return (
+    <Popover side={side} align={align}>
+      <PopoverTrigger>
+        <IconButton
+          icon="message-circle-question-mark"
+          iconColor={colors.zinc[500]}
+          accessibilityLabel={accessibilityLabel}
+        />
+      </PopoverTrigger>
+      <PopoverContent style={styles.content} disableBodyScroll>
+        <Text size="sm" color="muted">
+          {text}
+        </Text>
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+const styles = StyleSheet.create({
+  content: {
+    width: 280,
+  },
+});

package/src/use_form.ts

@@ -0,0 +1,285 @@
+import { useCallback, useMemo, useReducer, useRef } from "react";
+
+export interface UseFormProps<T> {
+  initialValues: T;
+  validate?: (
+    values: T,
+  ) =>
+    | FormErrors<T>
+    | Promise<FormErrors<T>>
+    | undefined
+    | Promise<undefined>
+    | void
+    | Promise<void>;
+  onSubmit?: (values: T, helpers: FormSetters<T>) => Promise<void> | void;
+  onChange?: (values: T) => Promise<void> | void;
+}
+
+export interface FormHandler<T> extends FormSetters<T> {
+  submit: () => Promise<void>;
+  reset: () => void;
+  validate: () => void;
+  values: T;
+  errors: FormErrors<T>;
+  changes: FormChanged<T>;
+  submitting: boolean;
+  submitCount: number;
+  changed: boolean;
+}
+
+export interface FormSetters<T> {
+  setFieldError: (field: keyof T, message?: string) => void;
+  setFieldValue: {
+    (field: keyof T): (value: T[keyof T]) => void;
+    (field: keyof T, value: T[keyof T]): void;
+  };
+  setValues: (values: Partial<T>) => void;
+  setSubmitting: (submitting: boolean) => void;
+  setErrors: (errors: FormErrors<T>) => void;
+  reset: () => void;
+}
+
+interface FormState<T> {
+  edits: Partial<T>;
+  errors: FormErrors<T>;
+  submitting: boolean;
+  submitCount: number;
+}
+
+export type FormErrors<T> = { [key in keyof T]?: string };
+export type FormChanged<T> = { [key in keyof T]?: boolean };
+
+type Action<T> =
+  | {
+      type: "SET_FIELD_VALUE";
+      field: keyof T;
+      value: T[keyof T];
+    }
+  | {
+      type: "SET_VALUES";
+      values: Partial<T>;
+    }
+  | {
+      type: "SET_FIELD_ERROR";
+      field: keyof T;
+      message?: string;
+    }
+  | {
+      type: "SET_ERRORS";
+      errors: FormErrors<T>;
+    }
+  | {
+      type: "SUBMIT";
+    }
+  | {
+      type: "SET_SUBMITTING";
+      submitting: boolean;
+    }
+  | {
+      type: "RESET";
+    };
+
+function reducer<T>(prevState: FormState<T>, action: Action<T>): FormState<T> {
+  switch (action.type) {
+    case "SET_FIELD_VALUE": {
+      const errors = { ...prevState.errors };
+      delete errors[action.field];
+      return {
+        ...prevState,
+        edits: { ...prevState.edits, [action.field]: action.value },
+        errors,
+      };
+    }
+    case "SET_VALUES": {
+      const errors = { ...prevState.errors };
+      for (const key of Object.keys(action.values)) {
+        delete errors[key as keyof T];
+      }
+      return {
+        ...prevState,
+        edits: { ...prevState.edits, ...action.values },
+        errors,
+      };
+    }
+    case "SET_ERRORS":
+      return { ...prevState, errors: { ...action.errors } };
+    case "SET_FIELD_ERROR": {
+      const errors = { ...prevState.errors };
+      if (action.message === undefined) {
+        delete errors[action.field];
+      } else {
+        errors[action.field] = action.message;
+      }
+      return { ...prevState, errors };
+    }
+    case "SET_SUBMITTING":
+      if (prevState.submitting === action.submitting) return prevState;
+      return { ...prevState, submitting: action.submitting };
+    case "SUBMIT":
+      return {
+        ...prevState,
+        errors: {},
+        submitting: false,
+        submitCount: prevState.submitCount + 1,
+      };
+    case "RESET":
+      return { edits: {}, errors: {}, submitting: false, submitCount: 0 };
+    default:
+      throw new Error("Action type not resolved");
+  }
+}
+
+function createEmptyState<T>(): FormState<T> {
+  return { edits: {}, errors: {}, submitting: false, submitCount: 0 };
+}
+
+export function useForm<T>(props: UseFormProps<T>): FormHandler<T> {
+  const { initialValues, validate, onSubmit, onChange } = props;
+  const [state, dispatch] = useReducer(reducer<T>, null, createEmptyState<T>);
+  const submittingRef = useRef(false);
+
+  // Values derived from props + user edits. When initialValues changes
+  // (e.g. SWR revalidation), non-edited fields automatically reflect
+  // the new server data. No synchronization needed.
+  const values = useMemo(
+    (): T => ({ ...initialValues, ...state.edits }),
+    [initialValues, state.edits],
+  );
+
+  const { errors, submitting, submitCount } = state;
+
+  const changes = useMemo((): FormChanged<T> => {
+    const result: FormChanged<T> = {};
+    for (const key of Object.keys(state.edits)) {
+      result[key as keyof T] = true;
+    }
+    return result;
+  }, [state.edits]);
+
+  const changed = Object.keys(state.edits).length > 0;
+
+  const setErrors = useCallback((nextErrors: FormErrors<T>) => {
+    dispatch({ type: "SET_ERRORS", errors: nextErrors });
+  }, []);
+
+  const setFieldError = useCallback((field: keyof T, message?: string): void => {
+    dispatch({ type: "SET_FIELD_ERROR", field, message });
+  }, []);
+
+  const setSubmitting = useCallback((newSubmitting: boolean) => {
+    dispatch({ type: "SET_SUBMITTING", submitting: newSubmitting });
+  }, []);
+
+  const setFieldValue = useCallback(
+    ((...args: [field: keyof T, value?: T[keyof T]]) => {
+      const [field, value] = args;
+
+      if (args.length === 1) {
+        return (val: T[keyof T]) => {
+          dispatch({ type: "SET_FIELD_VALUE", field, value: val });
+          onChange?.({ ...values, [field]: val });
+        };
+      } else {
+        dispatch({
+          type: "SET_FIELD_VALUE",
+          field,
+          value: value as T[keyof T],
+        });
+        onChange?.({ ...values, [field]: value });
+      }
+    }) as {
+      (field: keyof T): (value: T[keyof T]) => void;
+      (field: keyof T, value: T[keyof T]): void;
+    },
+    [onChange, values],
+  );
+
+  const setValues = useCallback(
+    (newValues: Partial<T>) => {
+      dispatch({ type: "SET_VALUES", values: newValues });
+      onChange?.({ ...values, ...newValues });
+    },
+    [onChange, values],
+  );
+
+  const reset = useCallback(() => {
+    dispatch({ type: "RESET" });
+  }, []);
+
+  const handleValidate = useCallback(async () => {
+    if (validate !== undefined) {
+      setErrors((await validate(values)) || {});
+    }
+  }, [validate, values, setErrors]);
+
+  const formHelpers = useMemo(
+    (): FormSetters<T> => ({
+      setFieldError,
+      setFieldValue,
+      setValues,
+      setErrors,
+      setSubmitting,
+      reset,
+    }),
+    [setValues, setFieldError, setFieldValue, setErrors, setSubmitting, reset],
+  );
+
+  const submit = useCallback(async () => {
+    if (!onSubmit) return;
+    if (submittingRef.current) return;
+
+    if (validate !== undefined) {
+      const nextErrors = await validate(values);
+
+      if (nextErrors && Object.keys(nextErrors).length) {
+        setErrors(nextErrors);
+        return;
+      }
+    }
+
+    submittingRef.current = true;
+    dispatch({ type: "SET_SUBMITTING", submitting: true });
+    try {
+      await onSubmit(values, formHelpers);
+      dispatch({ type: "SUBMIT" });
+    } finally {
+      submittingRef.current = false;
+      dispatch({ type: "SET_SUBMITTING", submitting: false });
+    }
+  }, [onSubmit, validate, setErrors, values, formHelpers]);
+
+  return useMemo(
+    () => ({
+      setValues,
+      setFieldValue,
+      setFieldError,
+      setErrors,
+      setSubmitting,
+      submit,
+      reset,
+      values,
+      errors,
+      changes,
+      submitting,
+      validate: handleValidate,
+      submitCount,
+      changed,
+    }),
+    [
+      setValues,
+      setFieldValue,
+      setFieldError,
+      setErrors,
+      setSubmitting,
+      submit,
+      reset,
+      values,
+      errors,
+      changes,
+      submitting,
+      handleValidate,
+      submitCount,
+      changed,
+    ],
+  );
+}